============== 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.