Documentation/media/uapi/dvb/video_types.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _video_types:
  11
  12 ****************
  13 Video Data Types
  14 ****************
  15
  16
  17 .. _video-format-t:
  18
  19 video_format_t
  20 ==============
  21
  22 The ``video_format_t`` data type defined by
  23
  24
  25 .. code-block:: c
  26
  27     typedef enum {
  28         VIDEO_FORMAT_4_3,     /* Select 4:3 format */
  29         VIDEO_FORMAT_16_9,    /* Select 16:9 format. */
  30         VIDEO_FORMAT_221_1    /* 2.21:1 */
  31     } video_format_t;
  32
  33 is used in the VIDEO_SET_FORMAT function (??) to tell the driver which
  34 aspect ratio the output hardware (e.g. TV) has. It is also used in the
  35 data structures video_status (??) returned by VIDEO_GET_STATUS (??)
  36 and video_event (??) returned by VIDEO_GET_EVENT (??) which report
  37 about the display format of the current video stream.
  38
  39
  40 .. _video-displayformat-t:
  41
  42 video_displayformat_t
  43 =====================
  44
  45 In case the display format of the video stream and of the display
  46 hardware differ the application has to specify how to handle the
  47 cropping of the picture. This can be done using the
  48 VIDEO_SET_DISPLAY_FORMAT call (??) which accepts
  49
  50
  51 .. code-block:: c
  52
  53     typedef enum {
  54         VIDEO_PAN_SCAN,       /* use pan and scan format */
  55         VIDEO_LETTER_BOX,     /* use letterbox format */
  56         VIDEO_CENTER_CUT_OUT  /* use center cut out format */
  57     } video_displayformat_t;
  58
  59 as argument.
  60
  61
  62 .. _video-stream-source-t:
  63
  64 video_stream_source_t
  65 =====================
  66
  67 The video stream source is set through the VIDEO_SELECT_SOURCE call
  68 and can take the following values, depending on whether we are replaying
  69 from an internal (demuxer) or external (user write) source.
  70
  71
  72 .. code-block:: c
  73
  74     typedef enum {
  75         VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */
  76         VIDEO_SOURCE_MEMORY /* If this source is selected, the stream
  77                        comes from the user through the write
  78                        system call */
  79     } video_stream_source_t;
  80
  81 VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the
  82 frontend or the DVR device) as the source of the video stream. If
  83 VIDEO_SOURCE_MEMORY is selected the stream comes from the application
  84 through the **write()** system call.
  85
  86
  87 .. _video-play-state-t:
  88
  89 video_play_state_t
  90 ==================
  91
  92 The following values can be returned by the VIDEO_GET_STATUS call
  93 representing the state of video playback.
  94
  95
  96 .. code-block:: c
  97
  98     typedef enum {
  99         VIDEO_STOPPED, /* Video is stopped */
 100         VIDEO_PLAYING, /* Video is currently playing */
 101         VIDEO_FREEZED  /* Video is freezed */
 102     } video_play_state_t;
 103
 104
 105 .. c:type:: video_command
 106
 107 struct video_command
 108 ====================
 109
 110 The structure must be zeroed before use by the application This ensures
 111 it can be extended safely in the future.
 112
 113
 114 .. code-block:: c
 115
 116     struct video_command {
 117         __u32 cmd;
 118         __u32 flags;
 119         union {
 120             struct {
 121                 __u64 pts;
 122             } stop;
 123
 124             struct {
 125                 /* 0 or 1000 specifies normal speed,
 126                    1 specifies forward single stepping,
 127                    -1 specifies backward single stepping,
 128                    >>1: playback at speed/1000 of the normal speed,
 129                    <-1: reverse playback at (-speed/1000) of the normal speed. */
 130                 __s32 speed;
 131                 __u32 format;
 132             } play;
 133
 134             struct {
 135                 __u32 data[16];
 136             } raw;
 137         };
 138     };
 139
 140
 141 .. _video-size-t:
 142
 143 video_size_t
 144 ============
 145
 146
 147 .. code-block:: c
 148
 149     typedef struct {
 150         int w;
 151         int h;
 152         video_format_t aspect_ratio;
 153     } video_size_t;
 154
 155
 156 .. c:type:: video_event
 157
 158 struct video_event
 159 ==================
 160
 161 The following is the structure of a video event as it is returned by the
 162 VIDEO_GET_EVENT call.
 163
 164
 165 .. code-block:: c
 166
 167     struct video_event {
 168         __s32 type;
 169     #define VIDEO_EVENT_SIZE_CHANGED    1
 170     #define VIDEO_EVENT_FRAME_RATE_CHANGED  2
 171     #define VIDEO_EVENT_DECODER_STOPPED     3
 172     #define VIDEO_EVENT_VSYNC       4
 173         __kernel_time_t timestamp;
 174         union {
 175             video_size_t size;
 176             unsigned int frame_rate;    /* in frames per 1000sec */
 177             unsigned char vsync_field;  /* unknown/odd/even/progressive */
 178         } u;
 179     };
 180
 181
 182 .. c:type:: video_status
 183
 184 struct video_status
 185 ===================
 186
 187 The VIDEO_GET_STATUS call returns the following structure informing
 188 about various states of the playback operation.
 189
 190
 191 .. code-block:: c
 192
 193     struct video_status {
 194         int                   video_blank;   /* blank video on freeze? */
 195         video_play_state_t    play_state;    /* current state of playback */
 196         video_stream_source_t stream_source; /* current source (demux/memory) */
 197         video_format_t        video_format;  /* current aspect ratio of stream */
 198         video_displayformat_t display_format;/* selected cropping mode */
 199     };
 200
 201 If video_blank is set video will be blanked out if the channel is
 202 changed or if playback is stopped. Otherwise, the last picture will be
 203 displayed. play_state indicates if the video is currently frozen,
 204 stopped, or being played back. The stream_source corresponds to the
 205 seleted source for the video stream. It can come either from the
 206 demultiplexer or from memory. The video_format indicates the aspect
 207 ratio (one of 4:3 or 16:9) of the currently played video stream.
 208 Finally, display_format corresponds to the selected cropping mode in
 209 case the source video format is not the same as the format of the output
 210 device.
 211
 212
 213 .. c:type:: video_still_picture
 214
 215 struct video_still_picture
 216 ==========================
 217
 218 An I-frame displayed via the VIDEO_STILLPICTURE call is passed on
 219 within the following structure.
 220
 221
 222 .. code-block:: c
 223
 224     /* pointer to and size of a single iframe in memory */
 225     struct video_still_picture {
 226         char *iFrame;        /* pointer to a single iframe in memory */
 227         int32_t size;
 228     };
 229
 230
 231 .. _video_caps:
 232
 233 video capabilities
 234 ==================
 235
 236 A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the
 237 following bits set according to the hardwares capabilities.
 238
 239
 240 .. code-block:: c
 241
 242      /* bit definitions for capabilities: */
 243      /* can the hardware decode MPEG1 and/or MPEG2? */
 244      #define VIDEO_CAP_MPEG1   1
 245      #define VIDEO_CAP_MPEG2   2
 246      /* can you send a system and/or program stream to video device?
 247         (you still have to open the video and the audio device but only
 248          send the stream to the video device) */
 249      #define VIDEO_CAP_SYS     4
 250      #define VIDEO_CAP_PROG    8
 251      /* can the driver also handle SPU, NAVI and CSS encoded data?
 252         (CSS API is not present yet) */
 253      #define VIDEO_CAP_SPU    16
 254      #define VIDEO_CAP_NAVI   32
 255      #define VIDEO_CAP_CSS    64