Google Git
Sign in
android-kvm / linux / refs/heads/master / . / Documentation / userspace-api / media / dvb / legacy_dvb_osd.rst
blob: 179b66a8016a1bbffe14622accb13a623315e5d3 [file] [log] [blame]
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0
.. c:namespace:: dtv.legacy.osd
.. _dvb_osd:
==============
DVB OSD Device
==============
.. attention:: Do **not** use in new drivers!
See: :ref:`legacy_dvb_decoder_notes`
The DVB OSD device controls the OnScreen-Display of the AV7110 based
DVB-cards with hardware MPEG2 decoder. It can be accessed through
``/dev/dvb/adapter?/osd0``.
Data types and ioctl definitions can be accessed by including
``linux/dvb/osd.h`` in your application.
The OSD is not a frame-buffer like on many other cards.
It is a kind of canvas one can draw on.
The color-depth is limited depending on the memory size installed.
An appropriate palette of colors has to be set up.
The installed memory size can be identified with the `OSD_GET_CAPABILITY`_
ioctl.
OSD Data Types
==============
OSD_Command
-----------
Synopsis
~~~~~~~~
.. code-block:: c
typedef enum {
/* All functions return -2 on "not open" */
OSD_Close = 1,
OSD_Open,
OSD_Show,
OSD_Hide,
OSD_Clear,
OSD_Fill,
OSD_SetColor,
OSD_SetPalette,
OSD_SetTrans,
OSD_SetPixel,
OSD_GetPixel,
OSD_SetRow,
OSD_SetBlock,
OSD_FillRow,
OSD_FillBlock,
OSD_Line,
OSD_Query,
OSD_Test,
OSD_Text,
OSD_SetWindow,
OSD_MoveWindow,
OSD_OpenRaw,
} OSD_Command;
Commands
~~~~~~~~
.. note:: All functions return -2 on "not open"
.. flat-table::
:header-rows: 1
:stub-columns: 0
- ..
- Command
- | Used variables of ``struct`` `osd_cmd_t`_.
| Usage{variable} if alternative use.
- :cspan:`2` Description
- ..
- ``OSD_Close``
- -
- | Disables OSD and releases the buffers.
| Returns 0 on success.
- ..
- ``OSD_Open``
- | x0,y0,x1,y1,
| BitPerPixel[2/4/8]{color&0x0F},
| mix[0..15]{color&0xF0}
- | Opens OSD with this size and bit depth
| Returns 0 on success,
| -1 on DRAM allocation error,
| -2 on "already open".
- ..
- ``OSD_Show``
- -
- | Enables OSD mode.
| Returns 0 on success.
- ..
- ``OSD_Hide``
- -
- | Disables OSD mode.
| Returns 0 on success.
- ..
- ``OSD_Clear``
- -
- | Sets all pixel to color 0.
| Returns 0 on success.
- ..
- ``OSD_Fill``
- color
- | Sets all pixel to color <color>.
| Returns 0 on success.
- ..
- ``OSD_SetColor``
- | color,
| R{x0},G{y0},B{x1},
| opacity{y1}
- | Set palette entry <num> to <r,g,b>, <mix> and <trans> apply
| R,G,B: 0..255
| R=Red, G=Green, B=Blue
| opacity=0: pixel opacity 0% (only video pixel shows)
| opacity=1..254: pixel opacity as specified in header
| opacity=255: pixel opacity 100% (only OSD pixel shows)
| Returns 0 on success, -1 on error.
- ..
- ``OSD_SetPalette``
- | firstcolor{color},
| lastcolor{x0},data
- | Set a number of entries in the palette.
| Sets the entries "firstcolor" through "lastcolor" from the
array "data".
| Data has 4 byte for each color:
| R,G,B, and a opacity value: 0->transparent, 1..254->mix,
255->pixel
- ..
- ``OSD_SetTrans``
- transparency{color}
- | Sets transparency of mixed pixel (0..15).
| Returns 0 on success.
- ..
- ``OSD_SetPixel``
- x0,y0,color
- | Sets pixel <x>,<y> to color number <color>.
| Returns 0 on success, -1 on error.
- ..
- ``OSD_GetPixel``
- x0,y0
- | Returns color number of pixel <x>,<y>, or -1.
| Command currently not supported by the AV7110!
- ..
- ``OSD_SetRow``
- x0,y0,x1,data
- | Fills pixels x0,y through x1,y with the content of data[].
| Returns 0 on success, -1 on clipping all pixel (no pixel
drawn).
- ..
- ``OSD_SetBlock``
- | x0,y0,x1,y1,
| increment{color},
| data
- | Fills pixels x0,y0 through x1,y1 with the content of data[].
| Inc contains the width of one line in the data block,
| inc<=0 uses block width as line width.
| Returns 0 on success, -1 on clipping all pixel.
- ..
- ``OSD_FillRow``
- x0,y0,x1,color
- | Fills pixels x0,y through x1,y with the color <color>.
| Returns 0 on success, -1 on clipping all pixel.
- ..
- ``OSD_FillBlock``
- x0,y0,x1,y1,color
- | Fills pixels x0,y0 through x1,y1 with the color <color>.
| Returns 0 on success, -1 on clipping all pixel.
- ..
- ``OSD_Line``
- x0,y0,x1,y1,color
- | Draw a line from x0,y0 to x1,y1 with the color <color>.
| Returns 0 on success.
- ..
- ``OSD_Query``
- | x0,y0,x1,y1,
| xasp{color}; yasp=11
- | Fills parameters with the picture dimensions and the pixel
aspect ratio.
| Returns 0 on success.
| Command currently not supported by the AV7110!
- ..
- ``OSD_Test``
- -
- | Draws a test picture.
| For debugging purposes only.
| Returns 0 on success.
- ..
- ``OSD_Text``
- x0,y0,size,color,text
- Draws a text at position x0,y0 with the color <color>.
- ..
- ``OSD_SetWindow``
- x0
- Set window with number 0<x0<8 as current.
- ..
- ``OSD_MoveWindow``
- x0,y0
- Move current window to (x0, y0).
- ..
- ``OSD_OpenRaw``
- | x0,y0,x1,y1,
| `osd_raw_window_t`_ {color}
- Open other types of OSD windows.
Description
~~~~~~~~~~~
The ``OSD_Command`` data type is used with the `OSD_SEND_CMD`_ ioctl to
tell the driver which OSD_Command to execute.
-----
osd_cmd_t
---------
Synopsis
~~~~~~~~
.. code-block:: c
typedef struct osd_cmd_s {
OSD_Command cmd;
int x0;
int y0;
int x1;
int y1;
int color;
void __user *data;
} osd_cmd_t;
Variables
~~~~~~~~~
.. flat-table::
:header-rows: 0
:stub-columns: 0
- ..
- ``OSD_Command cmd``
- `OSD_Command`_ to be executed.
- ..
- ``int x0``
- First horizontal position.
- ..
- ``int y0``
- First vertical position.
- ..
- ``int x1``
- Second horizontal position.
- ..
- ``int y1``
- Second vertical position.
- ..
- ``int color``
- Number of the color in the palette.
- ..
- ``void __user *data``
- Command specific Data.
Description
~~~~~~~~~~~
The ``osd_cmd_t`` data type is used with the `OSD_SEND_CMD`_ ioctl.
It contains the data for the OSD_Command and the `OSD_Command`_ itself.
The structure has to be passed to the driver and the components may be
modified by it.
-----
osd_raw_window_t
----------------
Synopsis
~~~~~~~~
.. code-block:: c
typedef enum {
OSD_BITMAP1,
OSD_BITMAP2,
OSD_BITMAP4,
OSD_BITMAP8,
OSD_BITMAP1HR,
OSD_BITMAP2HR,
OSD_BITMAP4HR,
OSD_BITMAP8HR,
OSD_YCRCB422,
OSD_YCRCB444,
OSD_YCRCB444HR,
OSD_VIDEOTSIZE,
OSD_VIDEOHSIZE,
OSD_VIDEOQSIZE,
OSD_VIDEODSIZE,
OSD_VIDEOTHSIZE,
OSD_VIDEOTQSIZE,
OSD_VIDEOTDSIZE,
OSD_VIDEONSIZE,
OSD_CURSOR
} osd_raw_window_t;
Constants
~~~~~~~~~
.. flat-table::
:header-rows: 0
:stub-columns: 0
- ..
- ``OSD_BITMAP1``
- :cspan:`1` 1 bit bitmap
- ..
- ``OSD_BITMAP2``
- 2 bit bitmap
- ..
- ``OSD_BITMAP4``
- 4 bit bitmap
- ..
- ``OSD_BITMAP8``
- 8 bit bitmap
- ..
- ``OSD_BITMAP1HR``
- 1 Bit bitmap half resolution
- ..
- ``OSD_BITMAP2HR``
- 2 Bit bitmap half resolution
- ..
- ``OSD_BITMAP4HR``
- 4 Bit bitmap half resolution
- ..
- ``OSD_BITMAP8HR``
- 8 Bit bitmap half resolution
- ..
- ``OSD_YCRCB422``
- 4:2:2 YCRCB Graphic Display
- ..
- ``OSD_YCRCB444``
- 4:4:4 YCRCB Graphic Display
- ..
- ``OSD_YCRCB444HR``
- 4:4:4 YCRCB graphic half resolution
- ..
- ``OSD_VIDEOTSIZE``
- True Size Normal MPEG Video Display
- ..
- ``OSD_VIDEOHSIZE``
- MPEG Video Display Half Resolution
- ..
- ``OSD_VIDEOQSIZE``
- MPEG Video Display Quarter Resolution
- ..
- ``OSD_VIDEODSIZE``
- MPEG Video Display Double Resolution
- ..
- ``OSD_VIDEOTHSIZE``
- True Size MPEG Video Display Half Resolution
- ..
- ``OSD_VIDEOTQSIZE``
- True Size MPEG Video Display Quarter Resolution
- ..
- ``OSD_VIDEOTDSIZE``
- True Size MPEG Video Display Double Resolution
- ..
- ``OSD_VIDEONSIZE``
- Full Size MPEG Video Display
- ..
- ``OSD_CURSOR``
- Cursor
Description
~~~~~~~~~~~
The ``osd_raw_window_t`` data type is used with the `OSD_Command`_
OSD_OpenRaw to tell the driver which type of OSD to open.
-----
osd_cap_t
---------
Synopsis
~~~~~~~~
.. code-block:: c
typedef struct osd_cap_s {
int cmd;
#define OSD_CAP_MEMSIZE 1
long val;
} osd_cap_t;
Variables
~~~~~~~~~
.. flat-table::
:header-rows: 0
:stub-columns: 0
- ..
- ``int cmd``
- Capability to query.
- ..
- ``long val``
- Used to store the Data.
Supported capabilities
~~~~~~~~~~~~~~~~~~~~~~
.. flat-table::
:header-rows: 0
:stub-columns: 0
- ..
- ``OSD_CAP_MEMSIZE``
- Memory size installed on the card.
Description
~~~~~~~~~~~
This structure of data used with the `OSD_GET_CAPABILITY`_ call.
-----
OSD Function Calls
==================
OSD_SEND_CMD
------------
Synopsis
~~~~~~~~
.. c:macro:: OSD_SEND_CMD
.. code-block:: c
int ioctl(int fd, int request = OSD_SEND_CMD, enum osd_cmd_t *cmd)
Arguments
~~~~~~~~~
.. flat-table::
:header-rows: 0
:stub-columns: 0
- ..
- ``int fd``
- :cspan:`1` File descriptor returned by a previous call
to `open()`_.
- ..
- ``int request``
- Pointer to the location of the structure `osd_cmd_t`_ for this
command.
Description
~~~~~~~~~~~
.. attention:: Do **not** use in new drivers!
See: :ref:`legacy_dvb_decoder_notes`
This ioctl sends the `OSD_Command`_ to the card.
Return Value
~~~~~~~~~~~~
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. flat-table::
:header-rows: 0
:stub-columns: 0
- ..
- ``EINVAL``
- Command is out of range.
-----
OSD_GET_CAPABILITY
------------------
Synopsis
~~~~~~~~
.. c:macro:: OSD_GET_CAPABILITY
.. code-block:: c
int ioctl(int fd, int request = OSD_GET_CAPABILITY,
struct osd_cap_t *cap)
Arguments
~~~~~~~~~
.. flat-table::
:header-rows: 0
:stub-columns: 0
- ..
- ``int fd``
- :cspan:`1` File descriptor returned by a previous call
to `open()`_.
- ..
- ``int request``
- Equals ``OSD_GET_CAPABILITY`` for this command.
- ..
- ``unsigned int *cap``
- Pointer to the location of the structure `osd_cap_t`_ for this
command.
Description
~~~~~~~~~~~
.. attention:: Do **not** use in new drivers!
See: :ref:`legacy_dvb_decoder_notes`
This ioctl is used to get the capabilities of the OSD of the AV7110 based
DVB-decoder-card in use.
.. note::
The structure osd_cap_t has to be setup by the user and passed to the
driver.
Return Value
~~~~~~~~~~~~
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. flat-table::
:header-rows: 0
:stub-columns: 0
- ..
- ``EINVAL``
- Unsupported capability.
-----
open()
------
Synopsis
~~~~~~~~
.. code-block:: c
#include <fcntl.h>
.. c:function:: int open(const char *deviceName, int flags)
Arguments
~~~~~~~~~
.. flat-table::
:header-rows: 0
:stub-columns: 0
- ..
- ``const char *deviceName``
- Name of specific OSD device.
- ..
- :rspan:`3` ``int flags``
- :cspan:`1` A bit-wise OR of the following flags:
- ..
- ``O_RDONLY``
- read-only access
- ..
- ``O_RDWR``
- read/write access
- ..
- ``O_NONBLOCK``
- | Open in non-blocking mode
| (blocking mode is the default)
Description
~~~~~~~~~~~
This system call opens a named OSD device (e.g.
``/dev/dvb/adapter?/osd0``) for subsequent use.
Return Value
~~~~~~~~~~~~
.. flat-table::
:header-rows: 0
:stub-columns: 0
- ..
- ``ENODEV``
- Device driver not loaded/available.
- ..
- ``EINTERNAL``
- Internal error.
- ..
- ``EBUSY``
- Device or resource busy.
- ..
- ``EINVAL``
- Invalid argument.
-----
close()
-------
Synopsis
~~~~~~~~
.. c:function:: int close(int fd)
Arguments
~~~~~~~~~
.. flat-table::
:header-rows: 0
:stub-columns: 0
- ..
- ``int fd``
- :cspan:`1` File descriptor returned by a previous call
to `open()`_ .
Description
~~~~~~~~~~~
This system call closes a previously opened OSD device.
Return Value
~~~~~~~~~~~~
.. flat-table::
:header-rows: 0
:stub-columns: 0
- ..
- ``EBADF``
- fd is not a valid open file descriptor.