1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0 2 3.. c:namespace:: dtv.legacy.osd 4 5.. _dvb_osd: 6 7============== 8DVB OSD Device 9============== 10 11.. attention:: Do **not** use in new drivers! 12 See: :ref:`legacy_dvb_decoder_notes` 13 14The DVB OSD device controls the OnScreen-Display of the AV7110 based 15DVB-cards with hardware MPEG2 decoder. It can be accessed through 16``/dev/dvb/adapter?/osd0``. 17Data types and ioctl definitions can be accessed by including 18``linux/dvb/osd.h`` in your application. 19 20The OSD is not a frame-buffer like on many other cards. 21It is a kind of canvas one can draw on. 22The color-depth is limited depending on the memory size installed. 23An appropriate palette of colors has to be set up. 24The installed memory size can be identified with the `OSD_GET_CAPABILITY`_ 25ioctl. 26 27OSD Data Types 28============== 29 30OSD_Command 31----------- 32 33Synopsis 34~~~~~~~~ 35 36.. code-block:: c 37 38 typedef enum { 39 /* All functions return -2 on "not open" */ 40 OSD_Close = 1, 41 OSD_Open, 42 OSD_Show, 43 OSD_Hide, 44 OSD_Clear, 45 OSD_Fill, 46 OSD_SetColor, 47 OSD_SetPalette, 48 OSD_SetTrans, 49 OSD_SetPixel, 50 OSD_GetPixel, 51 OSD_SetRow, 52 OSD_SetBlock, 53 OSD_FillRow, 54 OSD_FillBlock, 55 OSD_Line, 56 OSD_Query, 57 OSD_Test, 58 OSD_Text, 59 OSD_SetWindow, 60 OSD_MoveWindow, 61 OSD_OpenRaw, 62 } OSD_Command; 63 64Commands 65~~~~~~~~ 66 67.. note:: All functions return -2 on "not open" 68 69.. flat-table:: 70 :header-rows: 1 71 :stub-columns: 0 72 73 - .. 74 75 - Command 76 77 - | Used variables of ``struct`` `osd_cmd_t`_. 78 | Usage{variable} if alternative use. 79 80 - :cspan:`2` Description 81 82 83 84 - .. 85 86 - ``OSD_Close`` 87 88 - - 89 90 - | Disables OSD and releases the buffers. 91 | Returns 0 on success. 92 93 - .. 94 95 - ``OSD_Open`` 96 97 - | x0,y0,x1,y1, 98 | BitPerPixel[2/4/8]{color&0x0F}, 99 | mix[0..15]{color&0xF0} 100 101 - | Opens OSD with this size and bit depth 102 | Returns 0 on success, 103 | -1 on DRAM allocation error, 104 | -2 on "already open". 105 106 - .. 107 108 - ``OSD_Show`` 109 110 - - 111 112 - | Enables OSD mode. 113 | Returns 0 on success. 114 115 - .. 116 117 - ``OSD_Hide`` 118 119 - - 120 121 - | Disables OSD mode. 122 | Returns 0 on success. 123 124 - .. 125 126 - ``OSD_Clear`` 127 128 - - 129 130 - | Sets all pixel to color 0. 131 | Returns 0 on success. 132 133 - .. 134 135 - ``OSD_Fill`` 136 137 - color 138 139 - | Sets all pixel to color <color>. 140 | Returns 0 on success. 141 142 - .. 143 144 - ``OSD_SetColor`` 145 146 - | color, 147 | R{x0},G{y0},B{x1}, 148 | opacity{y1} 149 150 - | Set palette entry <num> to <r,g,b>, <mix> and <trans> apply 151 | R,G,B: 0..255 152 | R=Red, G=Green, B=Blue 153 | opacity=0: pixel opacity 0% (only video pixel shows) 154 | opacity=1..254: pixel opacity as specified in header 155 | opacity=255: pixel opacity 100% (only OSD pixel shows) 156 | Returns 0 on success, -1 on error. 157 158 - .. 159 160 - ``OSD_SetPalette`` 161 162 - | firstcolor{color}, 163 | lastcolor{x0},data 164 165 - | Set a number of entries in the palette. 166 | Sets the entries "firstcolor" through "lastcolor" from the 167 array "data". 168 | Data has 4 byte for each color: 169 | R,G,B, and a opacity value: 0->transparent, 1..254->mix, 170 255->pixel 171 172 - .. 173 174 - ``OSD_SetTrans`` 175 176 - transparency{color} 177 178 - | Sets transparency of mixed pixel (0..15). 179 | Returns 0 on success. 180 181 - .. 182 183 - ``OSD_SetPixel`` 184 185 - x0,y0,color 186 187 - | Sets pixel <x>,<y> to color number <color>. 188 | Returns 0 on success, -1 on error. 189 190 - .. 191 192 - ``OSD_GetPixel`` 193 194 - x0,y0 195 196 - | Returns color number of pixel <x>,<y>, or -1. 197 | Command currently not supported by the AV7110! 198 199 - .. 200 201 - ``OSD_SetRow`` 202 203 - x0,y0,x1,data 204 205 - | Fills pixels x0,y through x1,y with the content of data[]. 206 | Returns 0 on success, -1 on clipping all pixel (no pixel 207 drawn). 208 209 - .. 210 211 - ``OSD_SetBlock`` 212 213 - | x0,y0,x1,y1, 214 | increment{color}, 215 | data 216 217 - | Fills pixels x0,y0 through x1,y1 with the content of data[]. 218 | Inc contains the width of one line in the data block, 219 | inc<=0 uses block width as line width. 220 | Returns 0 on success, -1 on clipping all pixel. 221 222 - .. 223 224 - ``OSD_FillRow`` 225 226 - x0,y0,x1,color 227 228 - | Fills pixels x0,y through x1,y with the color <color>. 229 | Returns 0 on success, -1 on clipping all pixel. 230 231 - .. 232 233 - ``OSD_FillBlock`` 234 235 - x0,y0,x1,y1,color 236 237 - | Fills pixels x0,y0 through x1,y1 with the color <color>. 238 | Returns 0 on success, -1 on clipping all pixel. 239 240 - .. 241 242 - ``OSD_Line`` 243 244 - x0,y0,x1,y1,color 245 246 - | Draw a line from x0,y0 to x1,y1 with the color <color>. 247 | Returns 0 on success. 248 249 - .. 250 251 - ``OSD_Query`` 252 253 - | x0,y0,x1,y1, 254 | xasp{color}; yasp=11 255 256 - | Fills parameters with the picture dimensions and the pixel 257 aspect ratio. 258 | Returns 0 on success. 259 | Command currently not supported by the AV7110! 260 261 - .. 262 263 - ``OSD_Test`` 264 265 - - 266 267 - | Draws a test picture. 268 | For debugging purposes only. 269 | Returns 0 on success. 270 - .. 271 272 - ``OSD_Text`` 273 274 - x0,y0,size,color,text 275 276 - Draws a text at position x0,y0 with the color <color>. 277 278 - .. 279 280 - ``OSD_SetWindow`` 281 282 - x0 283 284 - Set window with number 0<x0<8 as current. 285 286 - .. 287 288 - ``OSD_MoveWindow`` 289 290 - x0,y0 291 292 - Move current window to (x0, y0). 293 294 - .. 295 296 - ``OSD_OpenRaw`` 297 298 - | x0,y0,x1,y1, 299 | `osd_raw_window_t`_ {color} 300 301 - Open other types of OSD windows. 302 303Description 304~~~~~~~~~~~ 305 306The ``OSD_Command`` data type is used with the `OSD_SEND_CMD`_ ioctl to 307tell the driver which OSD_Command to execute. 308 309 310----- 311 312osd_cmd_t 313--------- 314 315Synopsis 316~~~~~~~~ 317 318.. code-block:: c 319 320 typedef struct osd_cmd_s { 321 OSD_Command cmd; 322 int x0; 323 int y0; 324 int x1; 325 int y1; 326 int color; 327 void __user *data; 328 } osd_cmd_t; 329 330Variables 331~~~~~~~~~ 332 333.. flat-table:: 334 :header-rows: 0 335 :stub-columns: 0 336 337 - .. 338 339 - ``OSD_Command cmd`` 340 341 - `OSD_Command`_ to be executed. 342 343 - .. 344 345 - ``int x0`` 346 347 - First horizontal position. 348 349 - .. 350 351 - ``int y0`` 352 353 - First vertical position. 354 355 - .. 356 357 - ``int x1`` 358 359 - Second horizontal position. 360 361 - .. 362 363 - ``int y1`` 364 365 - Second vertical position. 366 367 - .. 368 369 - ``int color`` 370 371 - Number of the color in the palette. 372 373 - .. 374 375 - ``void __user *data`` 376 377 - Command specific Data. 378 379Description 380~~~~~~~~~~~ 381 382The ``osd_cmd_t`` data type is used with the `OSD_SEND_CMD`_ ioctl. 383It contains the data for the OSD_Command and the `OSD_Command`_ itself. 384The structure has to be passed to the driver and the components may be 385modified by it. 386 387 388----- 389 390 391osd_raw_window_t 392---------------- 393 394Synopsis 395~~~~~~~~ 396 397.. code-block:: c 398 399 typedef enum { 400 OSD_BITMAP1, 401 OSD_BITMAP2, 402 OSD_BITMAP4, 403 OSD_BITMAP8, 404 OSD_BITMAP1HR, 405 OSD_BITMAP2HR, 406 OSD_BITMAP4HR, 407 OSD_BITMAP8HR, 408 OSD_YCRCB422, 409 OSD_YCRCB444, 410 OSD_YCRCB444HR, 411 OSD_VIDEOTSIZE, 412 OSD_VIDEOHSIZE, 413 OSD_VIDEOQSIZE, 414 OSD_VIDEODSIZE, 415 OSD_VIDEOTHSIZE, 416 OSD_VIDEOTQSIZE, 417 OSD_VIDEOTDSIZE, 418 OSD_VIDEONSIZE, 419 OSD_CURSOR 420 } osd_raw_window_t; 421 422Constants 423~~~~~~~~~ 424 425.. flat-table:: 426 :header-rows: 0 427 :stub-columns: 0 428 429 - .. 430 431 - ``OSD_BITMAP1`` 432 433 - :cspan:`1` 1 bit bitmap 434 435 - .. 436 437 - ``OSD_BITMAP2`` 438 439 - 2 bit bitmap 440 441 - .. 442 443 - ``OSD_BITMAP4`` 444 445 - 4 bit bitmap 446 447 - .. 448 449 - ``OSD_BITMAP8`` 450 451 - 8 bit bitmap 452 453 - .. 454 455 - ``OSD_BITMAP1HR`` 456 457 - 1 Bit bitmap half resolution 458 459 - .. 460 461 - ``OSD_BITMAP2HR`` 462 463 - 2 Bit bitmap half resolution 464 465 - .. 466 467 - ``OSD_BITMAP4HR`` 468 469 - 4 Bit bitmap half resolution 470 471 - .. 472 473 - ``OSD_BITMAP8HR`` 474 475 - 8 Bit bitmap half resolution 476 477 - .. 478 479 - ``OSD_YCRCB422`` 480 481 - 4:2:2 YCRCB Graphic Display 482 483 - .. 484 485 - ``OSD_YCRCB444`` 486 487 - 4:4:4 YCRCB Graphic Display 488 489 - .. 490 491 - ``OSD_YCRCB444HR`` 492 493 - 4:4:4 YCRCB graphic half resolution 494 495 - .. 496 497 - ``OSD_VIDEOTSIZE`` 498 499 - True Size Normal MPEG Video Display 500 501 - .. 502 503 - ``OSD_VIDEOHSIZE`` 504 505 - MPEG Video Display Half Resolution 506 507 - .. 508 509 - ``OSD_VIDEOQSIZE`` 510 511 - MPEG Video Display Quarter Resolution 512 513 - .. 514 515 - ``OSD_VIDEODSIZE`` 516 517 - MPEG Video Display Double Resolution 518 519 - .. 520 521 - ``OSD_VIDEOTHSIZE`` 522 523 - True Size MPEG Video Display Half Resolution 524 525 - .. 526 527 - ``OSD_VIDEOTQSIZE`` 528 529 - True Size MPEG Video Display Quarter Resolution 530 531 - .. 532 533 - ``OSD_VIDEOTDSIZE`` 534 535 - True Size MPEG Video Display Double Resolution 536 537 - .. 538 539 - ``OSD_VIDEONSIZE`` 540 541 - Full Size MPEG Video Display 542 543 - .. 544 545 - ``OSD_CURSOR`` 546 547 - Cursor 548 549Description 550~~~~~~~~~~~ 551 552The ``osd_raw_window_t`` data type is used with the `OSD_Command`_ 553OSD_OpenRaw to tell the driver which type of OSD to open. 554 555 556----- 557 558 559osd_cap_t 560--------- 561 562Synopsis 563~~~~~~~~ 564 565.. code-block:: c 566 567 typedef struct osd_cap_s { 568 int cmd; 569 #define OSD_CAP_MEMSIZE 1 570 long val; 571 } osd_cap_t; 572 573Variables 574~~~~~~~~~ 575 576.. flat-table:: 577 :header-rows: 0 578 :stub-columns: 0 579 580 - .. 581 582 - ``int cmd`` 583 584 - Capability to query. 585 586 - .. 587 588 - ``long val`` 589 590 - Used to store the Data. 591 592Supported capabilities 593~~~~~~~~~~~~~~~~~~~~~~ 594 595.. flat-table:: 596 :header-rows: 0 597 :stub-columns: 0 598 599 - .. 600 601 - ``OSD_CAP_MEMSIZE`` 602 603 - Memory size installed on the card. 604 605Description 606~~~~~~~~~~~ 607 608This structure of data used with the `OSD_GET_CAPABILITY`_ call. 609 610 611----- 612 613 614OSD Function Calls 615================== 616 617OSD_SEND_CMD 618------------ 619 620Synopsis 621~~~~~~~~ 622 623.. c:macro:: OSD_SEND_CMD 624 625.. code-block:: c 626 627 int ioctl(int fd, int request = OSD_SEND_CMD, enum osd_cmd_t *cmd) 628 629 630Arguments 631~~~~~~~~~ 632 633.. flat-table:: 634 :header-rows: 0 635 :stub-columns: 0 636 637 - .. 638 639 - ``int fd`` 640 641 - :cspan:`1` File descriptor returned by a previous call 642 to `open()`_. 643 644 - .. 645 646 - ``int request`` 647 648 - Pointer to the location of the structure `osd_cmd_t`_ for this 649 command. 650 651Description 652~~~~~~~~~~~ 653 654.. attention:: Do **not** use in new drivers! 655 See: :ref:`legacy_dvb_decoder_notes` 656 657This ioctl sends the `OSD_Command`_ to the card. 658 659Return Value 660~~~~~~~~~~~~ 661 662On success 0 is returned, on error -1 and the ``errno`` variable is set 663appropriately. The generic error codes are described at the 664:ref:`Generic Error Codes <gen-errors>` chapter. 665 666.. flat-table:: 667 :header-rows: 0 668 :stub-columns: 0 669 670 - .. 671 672 - ``EINVAL`` 673 674 - Command is out of range. 675 676 677----- 678 679 680OSD_GET_CAPABILITY 681------------------ 682 683Synopsis 684~~~~~~~~ 685 686.. c:macro:: OSD_GET_CAPABILITY 687 688.. code-block:: c 689 690 int ioctl(int fd, int request = OSD_GET_CAPABILITY, 691 struct osd_cap_t *cap) 692 693Arguments 694~~~~~~~~~ 695 696.. flat-table:: 697 :header-rows: 0 698 :stub-columns: 0 699 700 - .. 701 702 - ``int fd`` 703 704 - :cspan:`1` File descriptor returned by a previous call 705 to `open()`_. 706 707 - .. 708 709 - ``int request`` 710 711 - Equals ``OSD_GET_CAPABILITY`` for this command. 712 713 - .. 714 715 - ``unsigned int *cap`` 716 717 - Pointer to the location of the structure `osd_cap_t`_ for this 718 command. 719 720Description 721~~~~~~~~~~~ 722 723.. attention:: Do **not** use in new drivers! 724 See: :ref:`legacy_dvb_decoder_notes` 725 726This ioctl is used to get the capabilities of the OSD of the AV7110 based 727DVB-decoder-card in use. 728 729.. note:: 730 The structure osd_cap_t has to be setup by the user and passed to the 731 driver. 732 733Return Value 734~~~~~~~~~~~~ 735 736On success 0 is returned, on error -1 and the ``errno`` variable is set 737appropriately. The generic error codes are described at the 738:ref:`Generic Error Codes <gen-errors>` chapter. 739 740.. flat-table:: 741 :header-rows: 0 742 :stub-columns: 0 743 744 745 - .. 746 747 - ``EINVAL`` 748 749 - Unsupported capability. 750 751 752----- 753 754 755open() 756------ 757 758Synopsis 759~~~~~~~~ 760 761.. code-block:: c 762 763 #include <fcntl.h> 764 765.. c:function:: int open(const char *deviceName, int flags) 766 767Arguments 768~~~~~~~~~ 769 770.. flat-table:: 771 :header-rows: 0 772 :stub-columns: 0 773 774 - .. 775 776 - ``const char *deviceName`` 777 778 - Name of specific OSD device. 779 780 - .. 781 782 - :rspan:`3` ``int flags`` 783 784 - :cspan:`1` A bit-wise OR of the following flags: 785 786 - .. 787 788 - ``O_RDONLY`` 789 790 - read-only access 791 792 - .. 793 794 - ``O_RDWR`` 795 796 - read/write access 797 798 - .. 799 800 - ``O_NONBLOCK`` 801 - | Open in non-blocking mode 802 | (blocking mode is the default) 803 804Description 805~~~~~~~~~~~ 806 807This system call opens a named OSD device (e.g. 808``/dev/dvb/adapter?/osd0``) for subsequent use. 809 810Return Value 811~~~~~~~~~~~~ 812 813.. flat-table:: 814 :header-rows: 0 815 :stub-columns: 0 816 817 - .. 818 819 - ``ENODEV`` 820 821 - Device driver not loaded/available. 822 823 - .. 824 825 - ``EINTERNAL`` 826 827 - Internal error. 828 829 - .. 830 831 - ``EBUSY`` 832 833 - Device or resource busy. 834 835 - .. 836 837 - ``EINVAL`` 838 839 - Invalid argument. 840 841 842----- 843 844 845close() 846------- 847 848Synopsis 849~~~~~~~~ 850 851.. c:function:: int close(int fd) 852 853Arguments 854~~~~~~~~~ 855 856.. flat-table:: 857 :header-rows: 0 858 :stub-columns: 0 859 860 - .. 861 862 - ``int fd`` 863 864 - :cspan:`1` File descriptor returned by a previous call 865 to `open()`_ . 866 867Description 868~~~~~~~~~~~ 869 870This system call closes a previously opened OSD device. 871 872Return Value 873~~~~~~~~~~~~ 874 875.. flat-table:: 876 :header-rows: 0 877 :stub-columns: 0 878 879 - .. 880 881 - ``EBADF`` 882 883 - fd is not a valid open file descriptor. 884