1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _video_types:
4
5****************
6Video Data Types
7****************
8
9
10.. _video-format-t:
11
12video_format_t
13==============
14
15The ``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
26is used in the VIDEO_SET_FORMAT function (??) to tell the driver which
27aspect ratio the output hardware (e.g. TV) has. It is also used in the
28data structures video_status (??) returned by VIDEO_GET_STATUS (??)
29and video_event (??) returned by VIDEO_GET_EVENT (??) which report
30about the display format of the current video stream.
31
32
33.. _video-displayformat-t:
34
35video_displayformat_t
36=====================
37
38In case the display format of the video stream and of the display
39hardware differ the application has to specify how to handle the
40cropping of the picture. This can be done using the
41VIDEO_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
52as argument.
53
54
55.. _video-stream-source-t:
56
57video_stream_source_t
58=====================
59
60The video stream source is set through the VIDEO_SELECT_SOURCE call
61and can take the following values, depending on whether we are replaying
62from 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
74VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the
75frontend or the DVR device) as the source of the video stream. If
76VIDEO_SOURCE_MEMORY is selected the stream comes from the application
77through the **write()** system call.
78
79
80.. _video-play-state-t:
81
82video_play_state_t
83==================
84
85The following values can be returned by the VIDEO_GET_STATUS call
86representing 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
100struct video_command
101====================
102
103The structure must be zeroed before use by the application This ensures
104it 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
136video_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
151struct video_event
152==================
153
154The following is the structure of a video event as it is returned by the
155VIDEO_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
177struct video_status
178===================
179
180The VIDEO_GET_STATUS call returns the following structure informing
181about 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
194If video_blank is set video will be blanked out if the channel is
195changed or if playback is stopped. Otherwise, the last picture will be
196displayed. play_state indicates if the video is currently frozen,
197stopped, or being played back. The stream_source corresponds to the
198selected source for the video stream. It can come either from the
199demultiplexer or from memory. The video_format indicates the aspect
200ratio (one of 4:3 or 16:9) of the currently played video stream.
201Finally, display_format corresponds to the selected cropping mode in
202case the source video format is not the same as the format of the output
203device.
204
205
206.. c:type:: video_still_picture
207
208struct video_still_picture
209==========================
210
211An I-frame displayed via the VIDEO_STILLPICTURE call is passed on
212within 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
226video capabilities
227==================
228
229A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the
230following 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