Documentation/media/uapi/dvb/video_types.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _video_types:
   4
   5 ****************
   6 Video Data Types
   7 ****************
   8
   9
  10 .. _video-format-t:
  11
  12 video_format_t
  13 ==============
  14
  15 The ``video_format_t`` data type defined by
  16
  17
  18 .. code-block:: c
  19
  20     typedef enum {
  21         VIDEO_FORMAT_4_3,     /* Select 4:3 format */
  22         VIDEO_FORMAT_16_9,    /* Select 16:9 format. */
  23         VIDEO_FORMAT_221_1    /* 2.21:1 */
  24     } video_format_t;
  25
  26 is used in the VIDEO_SET_FORMAT function (??) to tell the driver which
  27 aspect ratio the output hardware (e.g. TV) has. It is also used in the
  28 data structures video_status (??) returned by VIDEO_GET_STATUS (??)
  29 and video_event (??) returned by VIDEO_GET_EVENT (??) which report
  30 about the display format of the current video stream.
  31
  32
  33 .. _video-displayformat-t:
  34
  35 video_displayformat_t
  36 =====================
  37
  38 In case the display format of the video stream and of the display
  39 hardware differ the application has to specify how to handle the
  40 cropping of the picture. This can be done using the
  41 VIDEO_SET_DISPLAY_FORMAT call (??) which accepts
  42
  43
  44 .. code-block:: c
  45
  46     typedef enum {
  47         VIDEO_PAN_SCAN,       /* use pan and scan format */
  48         VIDEO_LETTER_BOX,     /* use letterbox format */
  49         VIDEO_CENTER_CUT_OUT  /* use center cut out format */
  50     } video_displayformat_t;
  51
  52 as argument.
  53
  54
  55 .. _video-stream-source-t:
  56
  57 video_stream_source_t
  58 =====================
  59
  60 The video stream source is set through the VIDEO_SELECT_SOURCE call
  61 and can take the following values, depending on whether we are replaying
  62 from an internal (demuxer) or external (user write) source.
  63
  64
  65 .. code-block:: c
  66
  67     typedef enum {
  68         VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */
  69         VIDEO_SOURCE_MEMORY /* If this source is selected, the stream
  70                        comes from the user through the write
  71                        system call */
  72     } video_stream_source_t;
  73
  74 VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the
  75 frontend or the DVR device) as the source of the video stream. If
  76 VIDEO_SOURCE_MEMORY is selected the stream comes from the application
  77 through the **write()** system call.
  78
  79
  80 .. _video-play-state-t:
  81
  82 video_play_state_t
  83 ==================
  84
  85 The following values can be returned by the VIDEO_GET_STATUS call
  86 representing the state of video playback.
  87
  88
  89 .. code-block:: c
  90
  91     typedef enum {
  92         VIDEO_STOPPED, /* Video is stopped */
  93         VIDEO_PLAYING, /* Video is currently playing */
  94         VIDEO_FREEZED  /* Video is freezed */
  95     } video_play_state_t;
  96
  97
  98 .. c:type:: video_command
  99
 100 struct video_command
 101 ====================
 102
 103 The structure must be zeroed before use by the application This ensures
 104 it can be extended safely in the future.
 105
 106
 107 .. code-block:: c
 108
 109     struct video_command {
 110         __u32 cmd;
 111         __u32 flags;
 112         union {
 113             struct {
 114                 __u64 pts;
 115             } stop;
 116
 117             struct {
 118                 /* 0 or 1000 specifies normal speed,
 119                    1 specifies forward single stepping,
 120                    -1 specifies backward single stepping,
 121                    >>1: playback at speed/1000 of the normal speed,
 122                    <-1: reverse playback at (-speed/1000) of the normal speed. */
 123                 __s32 speed;
 124                 __u32 format;
 125             } play;
 126
 127             struct {
 128                 __u32 data[16];
 129             } raw;
 130         };
 131     };
 132
 133
 134 .. _video-size-t:
 135
 136 video_size_t
 137 ============
 138
 139
 140 .. code-block:: c
 141
 142     typedef struct {
 143         int w;
 144         int h;
 145         video_format_t aspect_ratio;
 146     } video_size_t;
 147
 148
 149 .. c:type:: video_event
 150
 151 struct video_event
 152 ==================
 153
 154 The following is the structure of a video event as it is returned by the
 155 VIDEO_GET_EVENT call.
 156
 157
 158 .. code-block:: c
 159
 160     struct video_event {
 161         __s32 type;
 162     #define VIDEO_EVENT_SIZE_CHANGED    1
 163     #define VIDEO_EVENT_FRAME_RATE_CHANGED  2
 164     #define VIDEO_EVENT_DECODER_STOPPED     3
 165     #define VIDEO_EVENT_VSYNC       4
 166         __kernel_time_t timestamp;
 167         union {
 168             video_size_t size;
 169             unsigned int frame_rate;    /* in frames per 1000sec */
 170             unsigned char vsync_field;  /* unknown/odd/even/progressive */
 171         } u;
 172     };
 173
 174
 175 .. c:type:: video_status
 176
 177 struct video_status
 178 ===================
 179
 180 The VIDEO_GET_STATUS call returns the following structure informing
 181 about various states of the playback operation.
 182
 183
 184 .. code-block:: c
 185
 186     struct video_status {
 187         int                   video_blank;   /* blank video on freeze? */
 188         video_play_state_t    play_state;    /* current state of playback */
 189         video_stream_source_t stream_source; /* current source (demux/memory) */
 190         video_format_t        video_format;  /* current aspect ratio of stream */
 191         video_displayformat_t display_format;/* selected cropping mode */
 192     };
 193
 194 If video_blank is set video will be blanked out if the channel is
 195 changed or if playback is stopped. Otherwise, the last picture will be
 196 displayed. play_state indicates if the video is currently frozen,
 197 stopped, or being played back. The stream_source corresponds to the
 198 seleted source for the video stream. It can come either from the
 199 demultiplexer or from memory. The video_format indicates the aspect
 200 ratio (one of 4:3 or 16:9) of the currently played video stream.
 201 Finally, display_format corresponds to the selected cropping mode in
 202 case the source video format is not the same as the format of the output
 203 device.
 204
 205
 206 .. c:type:: video_still_picture
 207
 208 struct video_still_picture
 209 ==========================
 210
 211 An I-frame displayed via the VIDEO_STILLPICTURE call is passed on
 212 within the following structure.
 213
 214
 215 .. code-block:: c
 216
 217     /* pointer to and size of a single iframe in memory */
 218     struct video_still_picture {
 219         char *iFrame;        /* pointer to a single iframe in memory */
 220         int32_t size;
 221     };
 222
 223
 224 .. _video_caps:
 225
 226 video capabilities
 227 ==================
 228
 229 A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the
 230 following bits set according to the hardwares capabilities.
 231
 232
 233 .. code-block:: c
 234
 235      /* bit definitions for capabilities: */
 236      /* can the hardware decode MPEG1 and/or MPEG2? */
 237      #define VIDEO_CAP_MPEG1   1
 238      #define VIDEO_CAP_MPEG2   2
 239      /* can you send a system and/or program stream to video device?
 240         (you still have to open the video and the audio device but only
 241          send the stream to the video device) */
 242      #define VIDEO_CAP_SYS     4
 243      #define VIDEO_CAP_PROG    8
 244      /* can the driver also handle SPU, NAVI and CSS encoded data?
 245         (CSS API is not present yet) */
 246      #define VIDEO_CAP_SPU    16
 247      #define VIDEO_CAP_NAVI   32
 248      #define VIDEO_CAP_CSS    64
 249
 250
 251 .. _video-system:
 252
 253 video_system_t
 254 ==============
 255
 256 A call to VIDEO_SET_SYSTEM sets the desired video system for TV
 257 output. The following system types can be set:
 258
 259
 260 .. code-block:: c
 261
 262     typedef enum {
 263          VIDEO_SYSTEM_PAL,
 264          VIDEO_SYSTEM_NTSC,
 265          VIDEO_SYSTEM_PALN,
 266          VIDEO_SYSTEM_PALNc,
 267          VIDEO_SYSTEM_PALM,
 268          VIDEO_SYSTEM_NTSC60,
 269          VIDEO_SYSTEM_PAL60,
 270          VIDEO_SYSTEM_PALM60
 271     } video_system_t;
 272
 273
 274 .. c:type:: video_highlight
 275
 276 struct video_highlight
 277 ======================
 278
 279 Calling the ioctl VIDEO_SET_HIGHLIGHTS posts the SPU highlight
 280 information. The call expects the following format for that information:
 281
 282
 283 .. code-block:: c
 284
 285      typedef
 286      struct video_highlight {
 287          boolean active;      /*    1=show highlight, 0=hide highlight */
 288          uint8_t contrast1;   /*    7- 4  Pattern pixel contrast */
 289                       /*    3- 0  Background pixel contrast */
 290          uint8_t contrast2;   /*    7- 4  Emphasis pixel-2 contrast */
 291                       /*    3- 0  Emphasis pixel-1 contrast */
 292          uint8_t color1;      /*    7- 4  Pattern pixel color */
 293                       /*    3- 0  Background pixel color */
 294          uint8_t color2;      /*    7- 4  Emphasis pixel-2 color */
 295                       /*    3- 0  Emphasis pixel-1 color */
 296          uint32_t ypos;       /*   23-22  auto action mode */
 297                       /*   21-12  start y */
 298                       /*    9- 0  end y */
 299          uint32_t xpos;       /*   23-22  button color number */
 300                       /*   21-12  start x */
 301                       /*    9- 0  end x */
 302      } video_highlight_t;
 303
 304
 305 .. c:type:: video_spu
 306
 307 struct video_spu
 308 ================
 309
 310 Calling VIDEO_SET_SPU deactivates or activates SPU decoding, according
 311 to the following format:
 312
 313
 314 .. code-block:: c
 315
 316      typedef
 317      struct video_spu {
 318          boolean active;
 319          int stream_id;
 320      } video_spu_t;
 321
 322
 323 .. c:type:: video_spu_palette
 324
 325 struct video_spu_palette
 326 ========================
 327
 328 The following structure is used to set the SPU palette by calling
 329 VIDEO_SPU_PALETTE:
 330
 331
 332 .. code-block:: c
 333
 334      typedef
 335      struct video_spu_palette {
 336          int length;
 337          uint8_t *palette;
 338      } video_spu_palette_t;
 339
 340
 341 .. c:type:: video_navi_pack
 342
 343 struct video_navi_pack
 344 ======================
 345
 346 In order to get the navigational data the following structure has to be
 347 passed to the ioctl VIDEO_GET_NAVI:
 348
 349
 350 .. code-block:: c
 351
 352      typedef
 353      struct video_navi_pack {
 354          int length;         /* 0 ... 1024 */
 355          uint8_t data[1024];
 356      } video_navi_pack_t;
 357
 358
 359 .. _video-attributes-t:
 360
 361 video_attributes_t
 362 ==================
 363
 364 The following attributes can be set by a call to VIDEO_SET_ATTRIBUTES:
 365
 366
 367 .. code-block:: c
 368
 369      typedef uint16_t video_attributes_t;
 370      /*   bits: descr. */
 371      /*   15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) */
 372      /*   13-12 TV system (0=525/60, 1=625/50) */
 373      /*   11-10 Aspect ratio (0=4:3, 3=16:9) */
 374      /*    9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca */
 375      /*    7    line 21-1 data present in GOP (1=yes, 0=no) */
 376      /*    6    line 21-2 data present in GOP (1=yes, 0=no) */
 377      /*    5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 */
 378      /*    2    source letterboxed (1=yes, 0=no) */
 379      /*    0    film/camera mode (0=camera, 1=film (625/50 only)) */