Documentation/userspace-api/media/dvb/video_types.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   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         long 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 selected 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