« back to all changes in this revision
Viewing changes to debian/include/vdpau/vdpau.h
- browse files at revision 7
- compare with another revision
- download diff
- download tarball
- view history from revision 7
- Committer: Bazaar Package Importer
- Author(s): Reinhard Tartler
- Date: 2010-01-17 09:34:54 UTC
- Revision ID: james.westby@ubuntu.com-20100117093454-nizyo2zidkw0gipk
Tags: 4:0.5+svn20090706-5ubuntu1
merge from 'ubuntu' branch
- files added:
- debian/README.source
- files removed:
- debian/include
- debian/include/vdpau
- files modified:
- debian/changelog
added
removed
debian/include/vdpau/vdpau.h
1
/*
2
* This source file is documented using Doxygen markup.
3
* See http://www.stack.nl/~dimitri/doxygen/
4
*/
5
6
/*
7
* This copyright notice applies to this header file:
8
*
9
* Copyright (c) 2008 NVIDIA Corporation
10
*
11
* Permission is hereby granted, free of charge, to any person
12
* obtaining a copy of this software and associated documentation
13
* files (the "Software"), to deal in the Software without
14
* restriction, including without limitation the rights to use,
15
* copy, modify, merge, publish, distribute, sublicense, and/or sell
16
* copies of the Software, and to permit persons to whom the
17
* Software is furnished to do so, subject to the following
18
* conditions:
19
*
20
* The above copyright notice and this permission notice shall be
21
* included in all copies or substantial portions of the Software.
22
*
23
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
24
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
25
* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
26
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
27
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
28
* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
29
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
30
* OTHER DEALINGS IN THE SOFTWARE.
31
*/
32
33
/**
34
* \mainpage Video Decode and Presentation API for Unix
35
*
36
* \section intro Introduction
37
*
38
* The Video Decode and Presentation API for Unix (VDPAU) provides
39
* a complete solution for decoding, post-processing, compositing,
40
* and displaying compressed or uncompressed video streams. These
41
* video streams may be combined (composited) with bitmap content,
42
* to implement OSDs and other application user interfaces.
43
*
44
* \section api_partitioning API Partitioning
45
*
46
* VDPAU is split into two distinct modules:
47
* - \ref api_core
48
* - \ref api_winsys
49
*
50
* The intent is that most VDPAU functionality exists and
51
* operates identically across all possible Windowing Systems.
52
* This functionality is the \ref api_core.
53
*
54
* However, a small amount of functionality must be included that
55
* is tightly coupled to the underlying Windowing System. This
56
* functionality is the \ref api_winsys. Possibly examples
57
* include:
58
* - Creation of the initial VDPAU \ref VdpDevice "VdpDevice"
59
* handle, since this act requires intimate knowledge of the
60
* underlying Window System, such as specific display handle or
61
* driver identification.
62
* - Conversion of VDPAU surfaces to/from underlying Window
63
* System surface types, e.g. to allow manipulation of
64
* VDPAU-generated surfaces via native Window System APIs.
65
*
66
* \section objects Object Types
67
*
68
* VDPAU is roughly object oriented; most functionality is
69
* exposed by creating an object (handle) of a certain class
70
* (type), then executing various functions against that handle.
71
* The set of object classes supported, and their purpose, is
72
* discussed below.
73
*
74
* \subsection device_type Device Type
75
*
76
* A \ref VdpDevice "VdpDevice" is the root object in VDPAU's
77
* object system. The \ref api_winsys allows creation of a \ref
78
* VdpDevice "VdpDevice" object handle, from which all other API
79
* entry points can be retrieved and invoked.
80
*
81
* \subsection surface_types Surface Types
82
*
83
* A surface stores pixel information. Various types of surfaces
84
* existing for different purposes:
85
*
86
* - \ref VdpVideoSurface "VdpVideoSurface"s store decompressed
87
* YCbCr video frames in an implementation-defined internal
88
* format.
89
* - \ref VdpOutputSurface "VdpOutputSurface"s store RGB 4:4:4
90
* data. They are legal render targets for video
91
* post-processing and compositing operations.
92
* - \ref VdpBitmapSurface "VdpBitmapSurface"s store RGB 4:4:4
93
* data. These surfaces are designed to contain read-only
94
* bitmap data, to be used for OSD or application UI
95
* compositing.
96
*
97
* \subsection transfer_types Transfer Types
98
*
99
* A data transfer object reads data from a surface (or
100
* surfaces), processes it, and writes the result to another
101
* surface. Various types of processing are possible:
102
*
103
* - \ref VdpDecoder "VdpDecoder" objects process compressed video
104
* data, and generate decompressed images.
105
* - \ref VdpOutputSurface "VdpOutputSurface"s have their own \ref
106
* VdpOutputSurfaceRender "rendering functionality".
107
* - \ref VdpVideoMixer "VdpVideoMixer" objects perform video
108
* post-processing, de-interlacing, and compositing.
109
* - \ref VdpPresentationQueue "VdpPresentationQueue" is
110
* responsible for timestamp-based display of surfaces.
111
*
112
* \section data_flow Data Flow
113
*
114
* Compressed video data originates in the application's memory
115
* space. This memory is typically obtained using \c malloc, and
116
* filled via regular file or network read system calls.
117
* Alternatively, the application may \c mmap a file.
118
*
119
* The compressed data is then processed using a \ref VdpDecoder
120
* "VdpDecoder", which will decompress the field or frame,
121
* and write the result into a \ref VdpVideoSurface
122
* "VdpVideoSurface". This action may require reading pixel data
123
* from some number of other \ref VdpVideoSurface "VdpVideoSurface"
124
* objects, depending on the type of compressed data and
125
* field/frame in question.
126
*
127
* If the application wishes to display any form of OSD or
128
* user-interface, this must be created in a \ref
129
* VdpOutputSurface "VdpOutputSurface".
130
*
131
* This process begins with the creation of \ref VdpBitmapSurface
132
* "VdpBitmapSurface" objects to contain the OSD/UI's static data,
133
* such as individual glyphs.
134
*
135
* \ref VdpOutputSurface "VdpOutputSurface" \ref
136
* VdpOutputSurfaceRender "rendering functionality" may be used
137
* to composite together various \ref VdpBitmapSurface
138
* "VdpBitmapSurface"s and \ref VdpOutputSurface
139
* "VdpOutputSurface"s, into another VdpOutputSurface
140
* "VdpOutputSurface".
141
*
142
* Once video has been decoded, it must be post-processed. This
143
* involves various steps such as color space conversion,
144
* de-interlacing, and other video adjustments. This step is
145
* performed using an \ref VdpVideoMixer "VdpVideoMixer" object.
146
* This object can not only perform the aforementioned video
147
* post-processing, but also composite the video with a number of
148
* \ref VdpOutputSurface "VdpOutputSurface"s, thus allowing complex
149
* user interfaces to be built. The final result is written into
150
* another \ref VdpOutputSurface "VdpOutputSurface".
151
*
152
* Note that at this point, the resultant \ref VdpOutputSurface
153
* "VdpOutputSurface" may be fed back through the above path,
154
* either using \ref VdpOutputSurface "VdpOutputSurface" \ref
155
* VdpOutputSurfaceRender "rendering functionality",
156
* or as input to the \ref VdpVideoMixer "VdpVideoMixer" object.
157
*
158
* Finally, the resultant \ref VdpOutputSurface
159
* "VdpOutputSurface" must be displayed on screen. This is the job
160
* of the \ref VdpPresentationQueue "VdpPresentationQueue" object.
161
*
162
* \image html vdpau_data_flow.png
163
*
164
* \section entry_point_retrieval Entry Point Retrieval
165
*
166
* VDPAU is designed so that multiple implementations can be
167
* used without application changes. For example, VDPAU could be
168
* hosted on X11, or via direct GPU access.
169
*
170
* The key technology behind this is the use of function
171
* pointers and a "get proc address" style API for all entry
172
* points. Put another way, functions are not called directly
173
* via global symbols set up by the linker, but rather through
174
* pointers.
175
*
176
* In practical terms, the \ref api_winsys provides factory
177
* functions which not only create and return \ref VdpDevice
178
* "VdpDevice" objects, but also a function pointer to a \ref
179
* VdpGetProcAddress function, through which all entry point
180
* function pointers will be retrieved.
181
*
182
* \subsection entry_point_philosophy Philosophy
183
*
184
* It is entirely possible to envisage a simpler scheme whereby
185
* such function pointers are hidden. That is, the application
186
* would link against a wrapper library that exposed "real"
187
* functions. The application would then call such functions
188
* directly, by symbol, like any other function. The wrapper
189
* library would handle loading the appropriate back-end, and
190
* implementing a similar "get proc address" scheme internally.
191
*
192
* However, the above scheme does not work well in the context
193
* of separated \ref api_core and \ref api_winsys. In this
194
* scenario, one would require a separate wrapper library per
195
* Window System, since each Window System would have a
196
* different function name and prototype for the main factory
197
* function. If an application then wanted to be Window System
198
* agnostic (making final determination at run-time via some
199
* form of plugin), it may then need to link against two
200
* wrapper libraries, which would cause conflicts for all
201
* symbols other than the main factory function.
202
*
203
* Another disadvantage of the wrapper library approach is the
204
* extra level of function call required; the wrapper library
205
* would internally implement the existing "get proc address"
206
* and "function pointer" style dispatch anyway. Exposing this
207
* directly to the application is slightly more efficient.
208
*
209
* \section threading Multi-threading
210
*
211
* All VDPAU functionality is fully thread-safe; any number of
212
* threads may call into any VDPAU functions at any time. VDPAU
213
* may not be called from signal-handlers.
214
*
215
* Note, however, that this simply guarantees that internal
216
* VDPAU state will not be corrupted by thread usage, and that
217
* crashes and deadlocks will not occur. Completely arbitrary
218
* thread usage may not generate the results that an application
219
* desires. In particular, care must be taken when multiple
220
* threads are performing operations on the same VDPAU objects.
221
*
222
* VDPAU implementations guarantee correct flow of surface
223
* content through the rendering pipeline, but only when
224
* function calls that read from or write to a surface return to
225
* the caller prior to any thread calling any other function(s)
226
* that read from or write to the surface. Invoking multiple
227
* reads from a surface in parallel is OK.
228
*
229
* Note that this restriction is placed upon VDPAU function
230
* invocations, and specifically not upon any back-end
231
* hardware's physical rendering operations. VDPAU
232
* implementations are expected to internally synchronize such
233
* hardware operations.
234
*
235
* In a single-threaded application, the above restriction comes
236
* naturally; each function call completes before it is possible
237
* to begin a new function call.
238
*
239
* In a multi-threaded application, threads may need to be
240
* synchronized. For example, consider the situation where:
241
*
242
* - Thread 1 is parsing compressed video data, passing them
243
* through a \ref VdpDecoder "VdpDecoder" object, and filling a
244
* ring-buffer of \ref VdpVideoSurface "VdpVideoSurface"s
245
* - Thread 2 is consuming those \ref VdpVideoSurface
246
* "VdpVideoSurface"s, and using a \ref VdpVideoMixer
247
* "VdpVideoMixer" to process them and composite them with UI.
248
*
249
* In this case, the threads must synchronize to ensure that
250
* thread 1's call to \ref VdpDecoderRender has returned prior to
251
* thread 2's call(s) to \ref VdpVideoMixerRender that use that
252
* specific surface. This could be achieved using the following
253
* pseudo-code:
254
*
255
* \code
256
* Queue<VdpVideoSurface> q_full_surfaces;
257
* Queue<VdpVideoSurface> q_empty_surfaces;
258
*
259
* thread_1() {
260
* for (;;) {
261
* VdpVideoSurface s = q_empty_surfaces.get();
262
* // Parse compressed stream here
263
* VdpDecoderRender(s, ...);
264
* q_full_surfaces.put(s);
265
* }
266
* }
267
*
268
* // This would need to be more complex if
269
* // VdpVideoMixerRender were to be provided with more
270
* // than one field/frame at a time.
271
* thread_1() {
272
* for (;;) {
273
* // Possibly, other rendering operations to mixer
274
* // layer surfaces here.
275
* VdpOutputSurface t = ...;
276
* VdpPresentationQueueBlockUntilSurfaceIdle(t);
277
* VdpVideoSurface s = q_full_surfaces.get();
278
* VdpVideoMixerRender(s, t, ...);
279
* q_empty_surfaces.put(s);
280
* // Possibly, other rendering operations to "t" here
281
* VdpPresentationQueueDisplay(t, ...);
282
* }
283
* }
284
* \endcode
285
*
286
* Finally, note that VDPAU makes no guarantees regarding any
287
* level of parallelism in any given implementation. Put another
288
* way, use of multi-threading is not guaranteed to yield any
289
* performance gain, and in theory could even slightly reduce
290
* performance due to threading/synchronization overhead.
291
*
292
* However, the intent of the threading requirements is to allow
293
* for e.g. video decoding and video mixer operations to proceed
294
* in parallel in hardware. Given a (presumably multi-threaded)
295
* application that kept each portion of the hardware busy, this
296
* would yield a performance increase.
297
*
298
* \section endianness Surface Endianness
299
*
300
* When dealing with surface content, i.e. the input/output of
301
* Put/GetBits functions, applications must take care to access
302
* memory in the correct fashion, so as to avoid endianness
303
* issues.
304
*
305
* By established convention in the 3D graphics world, RGBA data
306
* is defined to be an array of 32-bit pixels containing packed
307
* RGBA components, not as an array of bytes or interleaved RGBA
308
* components. VDPAU follows this convention. As such,
309
* applications are expected to access such surfaces as arrays
310
* of 32-bit components (i.e. using a 32-bit pointer), and not
311
* as interleaved arrays of 8-bit components (i.e. using an
312
* 8-bit pointer.) Deviation from this convention will lead to
313
* endianness issues, unless appropriate care is taken.
314
*
315
* The same convention is followed for some packed YCbCr formats
316
* such as \ref VDP_YCBCR_FORMAT_Y8U8V8A8; i.e. they are
317
* considered arrays of 32-bit pixels, and hence should be
318
* accessed as such.
319
*
320
* For YCbCr formats with chroma decimation and/or planar
321
* formats, however, this convention is awkward. Therefore,
322
* formats such as \ref VDP_YCBCR_FORMAT_NV12 are defined as
323
* arrays of (potentially interleaved) byte-sized components.
324
* Hence, applications should manipulate such data 8-bits at a
325
* time, using 8-bit pointers.
326
*
327
* Note that one common usage for the input/output of
328
* Put/GetBits APIs is file I/O. Typical file I/O APIs treat all
329
* memory as a simple array of 8-bit values. This violates the
330
* rule requiring surface data to be accessed in its true native
331
* format. As such, applications may be required to solve
332
* endianness issues. Possible solutions include:
333
*
334
* - Authoring static UI data files according to the endianness
335
* of the target execution platform.
336
* - Conditionally byte-swapping Put/GetBits data buffers at
337
* run-time based on execution platform.
338
*
339
* Note: Complete details regarding each surface format's
340
* precise pixel layout is included with the documentation of
341
* each surface type. For example, see \ref
342
* VDP_RGBA_FORMAT_B8G8R8A8.
343
*
344
* \section video_mixer_usage Video Mixer Usage
345
*
346
* \subsection video_surface_content VdpVideoSurface Content
347
*
348
* Each \ref VdpVideoSurface "VdpVideoSurface" is expected to contain an
349
* entire frame's-worth of data, irrespective of whether an interlaced of
350
* progressive sequence is being decoded.
351
*
352
* Depending on the exact encoding structure of the compressed video stream,
353
* the application may need to call \ref VdpDecoderRender twice to fill a
354
* single \ref VdpVideoSurface "VdpVideoSurface". When the stream contains an
355
* encoded progressive frame, or a "frame coded" interlaced field-pair, a
356
* single \ref VdpDecoderRender call will fill the entire surface. When the
357
* stream contains separately encoded interlaced fields, two
358
* \ref VdpDecoderRender calls will be required; one for the top field, and
359
* one for the bottom field.
360
*
361
* Implementation note: When \ref VdpDecoderRender renders an interlaced
362
* field, this operation must not disturb the content of the other field in
363
* the surface.
364
*
365
* \subsection vm_surf_list VdpVideoMixer Surface List
366
*
367
* An video stream is logically composed of a sequence of fields. An
368
* example is shown below, in display order, assuming top field first:
369
*
370
* <pre>t0 b0 t1 b1 t2 b2 t3 b3 t4 b4 t5 b5 t6 b6 t7 b7 t8 b8 t9 b9</pre>
371
*
372
* The canonical usage is to call \ref VdpVideoMixerRender once for decoded
373
* field, in display order, to yield one post-processed frame for display.
374
*
375
* For each call to \ref VdpVideoMixerRender, the field to be processed should
376
* be provided as the \b video_surface_current parameter.
377
*
378
* To enable operation of advanced de-interlacing algorithms and/or
379
* post-processing algorithms, some past and/or future surfaces should be
380
* provided as context. These are provided in the \b video_surface_past and
381
* \b video_surface_future lists. In general, these lists may contain any
382
* number of surfaces. Specific implementations may have specific requirements
383
* determining the minimum required number of surfaces for optimal operation,
384
* and the maximum number of useful surfaces, beyond which surfaces are not
385
* used. It is recommended that in all cases other than plain bob/weave, at
386
* least 2 past and 1 future frame be provided.
387
*
388
* Note that it is entirely possible, in general, for any of the
389
* \ref VdpVideoMixer "VdpVideoMixer" post-processing steps other than
390
* de-interlacing to require access to multiple input fields/frames. For
391
* example, an motion-sensitive noise-reduction algorithm.
392
*
393
* For example, when processing field t4, the \ref VdpVideoMixerRender
394
* parameters may contain the following values, if the application chose to
395
* provide 3 fields of context for both the past and future:
396
*
397
* <pre>
398
* current_picture_structure: VDP_VIDEO_MIXER_PICTURE_STRUCTURE_TOP_FIELD
399
* past: [b3, t3, b2]
400
* current: t4
401
* future: [b4, t5, b5]
402
* </pre>
403
*
404
* Note that for both the past/future lists, array index 0 represents the
405
* field temporally closest to current, in display order.
406
*
407
* The \ref VdpVideoMixerRender parameter \b current_picture_structure applies
408
* to \b video_surface_current. The picture structure for the other surfaces
409
* will be automatically derived from that for the current picture. The
410
* derivation algorithm is extremely simple; the concatenated list
411
* past/current/future is simply assumed to have an alternating top/bottom
412
* pattern throughout.
413
*
414
* Continuing the example above, subsequent calls to \ref VdpVideoMixerRender
415
* would provide the following sets of parameters:
416
*
417
* <pre>
418
* current_picture_structure: VDP_VIDEO_MIXER_PICTURE_STRUCTURE_BOTTOM_FIELD
419
* past: [t4, b3, t3]
420
* current: b4
421
* future: [t5, b5, t6]
422
* </pre>
423
*
424
* then:
425
*
426
* <pre>
427
* current_picture_structure: VDP_VIDEO_MIXER_PICTURE_STRUCTURE_TOP_FIELD
428
* past: [b4, t4, b3]
429
* current: t5
430
* future: [b5, t6, b7]
431
* </pre>
432
*
433
* In other words, the concatenated list of past/current/future frames simply
434
* forms a window that slides through the sequence of decoded fields.
435
*
436
* It is syntactically legal for an application to choose not to provide a
437
* particular entry in the past or future lists. In this case, the "slot" in
438
* the surface list must be filled with the special value
439
* \ref VDP_INVALID_HANDLE, to explicitly indicate that the picture is
440
* missing; do not simply shuffle other surfaces together to fill in the gap.
441
* Note that entries should only be omitted under special circumstances, such
442
* as failed decode due to bitstream error during picture header parsing,
443
* since missing entries will typically cause advanced de-interlacing
444
* algorithms to experience significantly degraded operation.
445
*
446
* Specific examples for different de-interlacing types are presented below.
447
*
448
* \subsection deint_weave Weave De-interlacing
449
*
450
* Weave de-interlacing is the act of interleaving the lines of two temporally
451
* adjacent fields to form a frame for display.
452
*
453
* To disable de-interlacing for progressive streams, simply specify
454
* \b current_picture_structure as \ref VDP_VIDEO_MIXER_PICTURE_STRUCTURE_FRAME;
455
* no de-interlacing will be applied.
456
*
457
* Weave de-interlacing for interlaced streams is identical to disabling
458
* de-interlacing, as describe immediately above, because each
459
* \ref VdpVideoSurface already contains an entire frame's worth (i.e. two
460
* fields) of picture data.
461
*
462
* Inverse telecine is disabled when using weave de-interlacing.
463
*
464
* Weave de-interlacing produces one output frame for each input frame. The
465
* application should make one \ref VdpVideoMixerRender call per pair of
466
* decoded fields, or per decoded frame.
467
*
468
* Weave de-interlacing requires no entries in the past/future lists.
469
*
470
* All implementations must support weave de-interlacing.
471
*
472
* \subsection deint_bob Bob De-interlacing
473
*
474
* Bob de-interlacing is the act of vertically scaling a single field to the
475
* size of a single frame.
476
*
477
* To achieve bob de-interlacing, simply provide a single field as
478
* \b video_surface_current, and set \b current_picture_structure
479
* appropriately, to indicate whether a top or bottom field was provided.
480
*
481
* Inverse telecine is disabled when using bob de-interlacing.
482
*
483
* Bob de-interlacing produces one output frame for each input field. The
484
* application should make one \ref VdpVideoMixerRender call per decoded
485
* field.
486
*
487
* Bob de-interlacing requires no entries in the past/future lists.
488
*
489
* Bob de-interlacing is the default when no advanced method is requested and
490
* enabled. Advanced de-interlacing algorithms may fall back to bob e.g. when
491
* required past/future fields are missing.
492
*
493
* All implementations must support bob de-interlacing.
494
*
495
* \subsection deint_adv Advanced De-interlacing
496
*
497
* Operation of both temporal and temporal-spatial de-interlacing is
498
* identical; the only difference is the internal processing the algorithm
499
* performs in generating the output frame.
500
*
501
* These algorithms use various advanced processing on the pixels of both the
502
* current and various past/future fields in order to determine how best to
503
* de-interlacing individual portions of the image.
504
*
505
* Inverse telecine may be enabled when using advanced de-interlacing.
506
*
507
* Advanced de-interlacing produces one output frame for each input field. The
508
* application should make one \ref VdpVideoMixerRender call per decoded
509
* field.
510
*
511
* Advanced de-interlacing requires entries in the past/future lists.
512
*
513
* Availability of advanced de-interlacing algorithms is implementation
514
* dependent.
515
*
516
* \subsection deint_rate De-interlacing Rate
517
*
518
* For all de-interlacing algorithms except weave, a choice may be made to
519
* call \ref VdpVideoMixerRender for either each decoded field, or every
520
* second decoded field.
521
*
522
* If \ref VdpVideoMixerRender is called for every decoded field, the
523
* generated post-processed frame rate is equal to the decoded field rate.
524
* Put another way, the generated post-processed nominal field rate is equal
525
* to 2x the decoded field rate. This is standard practice.
526
*
527
* If \ref VdpVideoMixerRender is called for every second decoded field (say
528
* every top field), the generated post-processed frame rate is half to the
529
* decoded field rate. This mode of operation is thus referred to as
530
* "half-rate".
531
*
532
* Implementations may choose whether to support half-rate de-interlacing mode
533
* or not. Regular de-interlacing mode should be supported to any supported
534
* advanced de-interlacing algorithm.
535
*
536
* The descriptions of de-interlacing algorithms above assume that regular
537
* (not half-rate) operation is being performed, when detailing the number of
538
"half-rate" de-interlacing is used.deoMixerRender calls.
539
*
540
* Recall that the concatenation of past/current/future surface lists simply
541
* forms a window into the stream of decoded fields. To achieve standard
542
* de-interlacing, the window is slid through the list of decoded fields one
543
* field at a time, and a call is made to \ref VdpVideoMixerRender for each
544
* movement of the window. To achieve half-rate de-interlacing, the window is
545
* slid through the* list of decoded fields two fields at a time, and a
546
* call is made to \ref VdpVideoMixerRender for each movement of the window.
547
*
548
* \subsection invtc Inverse Telecine
549
*
550
* Assuming the implementation supports it, inverse telecine may be enabled
551
* alongside any advanced de-interlacing algorithm. Inverse telecine is never
552
* active for bob or weave.
553
*
554
* Operation of \ref VdpVideoMixerRender with inverse telecine active is
555
* identical to the basic operation mechanisms describe above in every way;
556
* all inverse telecine processing is performed internally to the
557
* \ref VdpVideoMixer "VdpVideoMixer".
558
*
559
* In particular, there is no provision way for \ref VdpVideoMixerRender to
560
* indicate when identical input fields have been observed, and consequently
561
* identical output frames may have been produced.
562
*
563
* De-interlacing (and inverse telecine) may be applied to streams that are
564
* marked as being progressive. This will allow detection of, and correct
565
* de-interlacing of, mixed interlace/progressive streams, bad edits, etc.
566
* To implement de-interlacing/inverse-telecine on progressive material,
567
* simply treat the stream of decoded frames as a stream of decoded fields,
568
* apply any telecine flags (see the next section), and then apply
569
* de-interlacing to those fields as described above.
570
*
571
* Implementations are free to determine whether inverse telecine operates
572
* in conjunction with half-rate de-interlacing or not. It should always
573
* operate with regular de-interlacing, when advertized.
574
*
575
* \subsection tcflags Telecine (Pull-Down) Flags
576
*
577
* Some media delivery formats, e.g. DVD-Video, include flags that are
578
* intended to modify the decoded field sequence before display. This allows
579
* e.g. 24p content to be encoded at 48i, which saves space relative to a 60i
580
* encoded stream, but still displayed at 60i, to match target consumer
581
* display equipment.
582
*
583
* If the inverse telecine option is not activated in the
584
* \ref VdpVideoMixer "VdpVideoMixer", these flags should be ignored, and the
585
* decoded fields passed directly to \ref VdpVideoMixerRender as detailed
586
* above.
587
*
588
* However, to make full use of the inverse telecine feature, these flags
589
* should be applied to the field stream, yielding another field stream with
590
* some repeated fields, before passing the field stream to
591
* \ref VdpVideoMixerRender. In this scenario, the sliding window mentioned
592
* in the descriptions above applies to the field stream after application of
593
* flags.
594
*
595
* \section extending Extending the API
596
*
597
* \subsection extend_enums Enumerations and Other Constants
598
*
599
* VDPAU defines a number of enumeration types.
600
*
601
* When modifying VDPAU, existing enumeration constants must
602
* continue to exist (although they may be deprecated), and do
603
* so in the existing order.
604
*
605
* The above discussion naturally applies to "manually" defined
606
* enumerations, using pre-processor macros, too.
607
*
608
* \subsection extend_structs Structures
609
*
610
* In most case, VDPAU includes no provision for modifying existing
611
* structure definitions, although they may be deprecated.
612
*
613
* New structures may be created, together with new API entry
614
* points or feature/attribute/parameter values, to expose new
615
* functionality.
616
*
617
* A few structures are considered plausible candidates for future extension.
618
* Such structures include a version number as the first field, indicating the
619
* exact layout of the client-provided data. Such structures may only be
620
* modified by adding new fields to the end of the structure, so that the
621
* original structure definition is completely compatible with a leading
622
* subset of fields of the extended structure.
623
*
624
* \subsection extend_functions Functions
625
*
626
* Existing functions may not be modified, although they may be
627
* deprecated.
628
*
629
* New functions may be added at will. Note the enumeration
630
* requirements when modifying the enumeration that defines the
631
* list of entry points.
632
*
633
* \section preemption_note Display Preemption
634
*
635
* Please note that the display may be preempted away from
636
* VDPAU at any time. See \ref display_preemption for more
637
* details.
638
*
639
* \subsection trademarks Trademarks
640
*
641
* VDPAU is a trademark of NVIDIA Corporation. You may freely use the
642
* VDPAU trademark, as long as trademark ownership is attributed to
643
* NVIDIA Corporation.
644
*/
645
646
/**
647
* \file vdpau.h
648
* \brief The Core API
649
*
650
* This file contains the \ref api_core "Core API".
651
*/
652
653
#ifndef _VDPAU_H
654
#define _VDPAU_H
655
656
#include <stdint.h>
657
658
#ifdef __cplusplus
659
extern "C" {
660
#endif
661
662
/**
663
* \defgroup api_core Core API
664
*
665
* The core API encompasses all VDPAU functionality that operates
666
* in the same fashion across all Window Systems.
667
*
668
* @{
669
*/
670
671
/**
672
* \defgroup base_types Basic Types
673
*
674
* VDPAU primarily uses ISO C99 types from \c stdint.h.
675
*
676
* @{
677
*/
678
679
/** \brief A true \ref VdpBool value */
680
#define VDP_TRUE 1
681
/** \brief A false \ref VdpBool value */
682
#define VDP_FALSE 0
683
/**
684
* \brief A boolean value, holding \ref VDP_TRUE or \ref
685
* VDP_FALSE.
686
*/
687
typedef int VdpBool;
688
689
/*@}*/
690
691
/**
692
* \defgroup misc_types Miscellaneous Types
693
*
694
* @{
695
*/
696
697
/**
698
* \brief An invalid object handle value.
699
*
700
* This value may be used to represent an invalid, or
701
* non-existent, object (\ref VdpDevice "VdpDevice",
702
* \ref VdpVideoSurface "VdpVideoSurface", etc.)
703
*
704
* Note that most APIs require valid object handles in all
705
* cases, and will fail when presented with this value.
706
*/
707
#define VDP_INVALID_HANDLE 0xffffffffU
708
709
/**
710
* \brief The set of all chroma formats for \ref VdpVideoSurface
711
* "VdpVideoSurface"s.
712
*/
713
typedef uint32_t VdpChromaType;
714
715
/** \hideinitializer \brief 4:2:0 chroma format. */
716
#define VDP_CHROMA_TYPE_420 (VdpChromaType)0
717
/** \hideinitializer \brief 4:2:2 chroma format. */
718
#define VDP_CHROMA_TYPE_422 (VdpChromaType)1
719
/** \hideinitializer \brief 4:4:4 chroma format. */
720
#define VDP_CHROMA_TYPE_444 (VdpChromaType)2
721
722
/**
723
* \brief The set of all known YCbCr surface formats.
724
*/
725
typedef uint32_t VdpYCbCrFormat;
726
727
/**
728
* \hideinitializer
729
* \brief The "NV12" YCbCr surface format.
730
*
731
* This format has a two planes, a Y plane and a UV plane.
732
*
733
* The Y plane is an array of byte-sized Y components.
734
* Applications should access this data via a uint8_t pointer.
735
*
736
* The UV plane is an array of interleaved byte-sized U and V
737
* components, in the order U, V, U, V. Applications should
738
* access this data via a uint8_t pointer.
739
*/
740
#define VDP_YCBCR_FORMAT_NV12 (VdpYCbCrFormat)0
741
/**
742
* \hideinitializer
743
* \brief The "YV12" YCbCr surface format.
744
*
745
* This format has a three planes, a Y plane, a U plane, and a V
746
* plane.
747
*
748
* Each of the planes is an array of byte-sized components.
749
*
750
* Applications should access this data via a uint8_t pointer.
751
*/
752
#define VDP_YCBCR_FORMAT_YV12 (VdpYCbCrFormat)1
753
/**
754
* \hideinitializer
755
* \brief The "UYVY" YCbCr surface format.
756
*
757
* This format may also be known as Y422, UYNV, HDYC.
758
*
759
* This format has a single plane.
760
*
761
* This plane is an array of interleaved byte-sized Y, U, and V
762
* components, in the order U, Y, V, Y, U, Y, V, Y.
763
*
764
* Applications should access this data via a uint8_t pointer.
765
*/
766
#define VDP_YCBCR_FORMAT_UYVY (VdpYCbCrFormat)2
767
/**
768
* \hideinitializer
769
* \brief The "YUYV" YCbCr surface format.
770
*
771
* This format may also be known as YUY2, YUNV, V422.
772
*
773
* This format has a single plane.
774
*
775
* This plane is an array of interleaved byte-sized Y, U, and V
776
* components, in the order Y, U, Y, V, Y, U, Y, V.
777
*
778
* Applications should access this data via a uint8_t pointer.
779
*/
780
#define VDP_YCBCR_FORMAT_YUYV (VdpYCbCrFormat)3
781
/**
782
* \hideinitializer
783
* \brief A packed YCbCr format.
784
*
785
* This format has a single plane.
786
*
787
* This plane is an array packed 32-bit pixel data. Within each
788
* 32-bit pixel, bits [31:24] contain A, bits [23:16] contain V,
789
* bits [15:8] contain U, and bits [7:0] contain Y.
790
*
791
* Applications should access this data via a uint32_t pointer.
792
*/
793
#define VDP_YCBCR_FORMAT_Y8U8V8A8 (VdpYCbCrFormat)4
794
/**
795
* \hideinitializer
796
* \brief A packed YCbCr format.
797
*
798
* This format has a single plane.
799
*
800
* This plane is an array packed 32-bit pixel data. Within each
801
* 32-bit pixel, bits [31:24] contain A, bits [23:16] contain Y,
802
* bits [15:8] contain U, and bits [7:0] contain V.
803
*
804
* Applications should access this data via a uint32_t pointer.
805
*/
806
#define VDP_YCBCR_FORMAT_V8U8Y8A8 (VdpYCbCrFormat)5
807
808
/**
809
* \brief The set of all known RGB surface formats.
810
*/
811
typedef uint32_t VdpRGBAFormat;
812
813
/**
814
* \hideinitializer
815
* \brief A packed RGB format.
816
*
817
* This format has a single plane.
818
*
819
* This plane is an array packed 32-bit pixel data. Within each
820
* 32-bit pixel, bits [31:24] contain A, bits [23:16] contain R,
821
* bits [15:8] contain G, and bits [7:0] contain B.
822
*
823
* Applications should access this data via a uint32_t pointer.
824
*/
825
#define VDP_RGBA_FORMAT_B8G8R8A8 (VdpRGBAFormat)0
826
/**
827
* \hideinitializer
828
* \brief A packed RGB format.
829
*
830
* This format has a single plane.
831
*
832
* This plane is an array packed 32-bit pixel data. Within each
833
* 32-bit pixel, bits [31:24] contain A, bits [23:16] contain B,
834
* bits [15:8] contain G, and bits [7:0] contain R.
835
*
836
* Applications should access this data via a uint32_t pointer.
837
*/
838
#define VDP_RGBA_FORMAT_R8G8B8A8 (VdpRGBAFormat)1
839
/**
840
* \hideinitializer
841
* \brief A packed RGB format.
842
*
843
* This format has a single plane.
844
*
845
* This plane is an array packed 32-bit pixel data. Within each
846
* 32-bit pixel, bits [31:30] contain A, bits [29:20] contain B,
847
* bits [19:10] contain G, and bits [9:0] contain R.
848
*
849
* Applications should access this data via a uint32_t pointer.
850
*/
851
#define VDP_RGBA_FORMAT_R10G10B10A2 (VdpRGBAFormat)2
852
/**
853
* \hideinitializer
854
* \brief A packed RGB format.
855
*
856
* This format has a single plane.
857
*
858
* This plane is an array packed 32-bit pixel data. Within each
859
* 32-bit pixel, bits [31:30] contain A, bits [29:20] contain R,
860
* bits [19:10] contain G, and bits [9:0] contain B.
861
*
862
* Applications should access this data via a uint32_t pointer.
863
*/
864
#define VDP_RGBA_FORMAT_B10G10R10A2 (VdpRGBAFormat)3
865
/**
866
* \hideinitializer
867
* \brief An alpha-only surface format.
868
*
869
* This format has a single plane.
870
*
871
* This plane is an array of byte-sized components.
872
*
873
* Applications should access this data via a uint8_t pointer.
874
*/
875
#define VDP_RGBA_FORMAT_A8 (VdpRGBAFormat)4
876
877
/**
878
* \brief The set of all known indexed surface formats.
879
*/
880
typedef uint32_t VdpIndexedFormat;
881
882
/**
883
* \hideinitializer
884
* \brief A 4-bit indexed format, with alpha.
885
*
886
* This format has a single plane.
887
*
888
* This plane is an array of byte-sized components. Within each
889
* byte, bits [7:4] contain I (index), and bits [3:0] contain A.
890
*
891
* Applications should access this data via a uint8_t pointer.
892
*/
893
#define VDP_INDEXED_FORMAT_A4I4 (VdpIndexedFormat)0
894
/**
895
* \hideinitializer
896
* \brief A 4-bit indexed format, with alpha.
897
*
898
* This format has a single plane.
899
*
900
* This plane is an array of byte-sized components. Within each
901
* byte, bits [7:4] contain A, and bits [3:0] contain I (index).
902
*
903
* Applications should access this data via a uint8_t pointer.
904
*/
905
#define VDP_INDEXED_FORMAT_I4A4 (VdpIndexedFormat)1
906
/**
907
* \hideinitializer
908
* \brief A 8-bit indexed format, with alpha.
909
*
910
* This format has a single plane.
911
*
912
* This plane is an array of interleaved byte-sized A and I
913
* (index) components, in the order A, I, A, I.
914
*
915
* Applications should access this data via a uint8_t pointer.
916
*/
917
#define VDP_INDEXED_FORMAT_A8I8 (VdpIndexedFormat)2
918
/**
919
* \hideinitializer
920
* \brief A 8-bit indexed format, with alpha.
921
*
922
* This format has a single plane.
923
*
924
* This plane is an array of interleaved byte-sized A and I
925
* (index) components, in the order I, A, I, A.
926
*
927
* Applications should access this data via a uint8_t pointer.
928
*/
929
#define VDP_INDEXED_FORMAT_I8A8 (VdpIndexedFormat)3
930
931
/**
932
* \brief A location within a surface.
933
*
934
* The VDPAU co-ordinate system has its origin at the top-left
935
* of a surface, with x and y components increasing right and
936
* down.
937
*/
938
typedef struct {
939
/** X co-ordinate. */
940
uint32_t x;
941
/** Y co-ordinate. */
942
uint32_t y;
943
} VdpPoint;
944
945
/**
946
* \brief A rectangular region of a surface.
947
*
948
* The co-ordinates are top-left inclusive, bottom-right
949
* exclusive.
950
*
951
* The VDPAU co-ordinate system has its origin at the top-left
952
* of a surface, with x and y components increasing right and
953
* down.
954
*/
955
typedef struct {
956
/** Left X co-ordinate. Inclusive. */
957
uint32_t x0;
958
/** Top Y co-ordinate. Inclusive. */
959
uint32_t y0;
960
/** Right X co-ordinate. Exclusive. */
961
uint32_t x1;
962
/** Bottom Y co-ordinate. Exclusive. */
963
uint32_t y1;
964
} VdpRect;
965
966
/**
967
* A constant RGBA color.
968
*
969
* Note that the components are stored as float values in the
970
* range 0.0...1.0 rather than format-specific integer values.
971
* This allows VdpColor values to be independent from the exact
972
* surface format(s) in use.
973
*/
974
typedef struct {
975
float red;
976
float green;
977
float blue;
978
float alpha;
979
} VdpColor;
980
981
/*@}*/
982
983
/**
984
* \defgroup error_handling Error Handling
985
*
986
* @{
987
*/
988
989
/**
990
* \hideinitializer
991
* \brief The set of all possible error codes.
992
*/
993
typedef enum {
994
/** The operation completed successfully; no error. */
995
VDP_STATUS_OK = 0,
996
/**
997
* No backend implementation could be loaded.
998
*/
999
VDP_STATUS_NO_IMPLEMENTATION,
1000
/**
1001
* The display was preempted, or a fatal error occurred.
1002
*
1003
* The application must re-initialize VDPAU.
1004
*/
1005
VDP_STATUS_DISPLAY_PREEMPTED,
1006
/**
1007
* An invalid handle value was provided.
1008
*
1009
* Either the handle does not exist at all, or refers to an object of an
1010
* incorrect type.
1011
*/
1012
VDP_STATUS_INVALID_HANDLE,
1013
/**
1014
* An invalid pointer was provided.
1015
*
1016
* Typically, this means that a NULL pointer was provided for an "output"
1017
* parameter.
1018
*/
1019
VDP_STATUS_INVALID_POINTER,
1020
/**
1021
* An invalid/unsupported \ref VdpChromaType value was supplied.
1022
*/
1023
VDP_STATUS_INVALID_CHROMA_TYPE,
1024
/**
1025
* An invalid/unsupported \ref VdpYCbCrFormat value was supplied.
1026
*/
1027
VDP_STATUS_INVALID_Y_CB_CR_FORMAT,
1028
/**
1029
* An invalid/unsupported \ref VdpRGBAFormat value was supplied.
1030
*/
1031
VDP_STATUS_INVALID_RGBA_FORMAT,
1032
/**
1033
* An invalid/unsupported \ref VdpIndexedFormat value was supplied.
1034
*/
1035
VDP_STATUS_INVALID_INDEXED_FORMAT,
1036
/**
1037
* An invalid/unsupported \ref VdpColorStandard value was supplied.
1038
*/
1039
VDP_STATUS_INVALID_COLOR_STANDARD,
1040
/**
1041
* An invalid/unsupported \ref VdpColorTableFormat value was supplied.
1042
*/
1043
VDP_STATUS_INVALID_COLOR_TABLE_FORMAT,
1044
/**
1045
* An invalid/unsupported \ref VdpOutputSurfaceRenderBlendFactor value was
1046
* supplied.
1047
*/
1048
VDP_STATUS_INVALID_BLEND_FACTOR,
1049
/**
1050
* An invalid/unsupported \ref VdpOutputSurfaceRenderBlendEquation value
1051
* was supplied.
1052
*/
1053
VDP_STATUS_INVALID_BLEND_EQUATION,
1054
/**
1055
* An invalid/unsupported flag value/combination was supplied.
1056
*/
1057
VDP_STATUS_INVALID_FLAG,
1058
/**
1059
* An invalid/unsupported \ref VdpDecoderProfile value was supplied.
1060
*/
1061
VDP_STATUS_INVALID_DECODER_PROFILE,
1062
/**
1063
* An invalid/unsupported \ref VdpVideoMixerFeature value was supplied.
1064
*/
1065
VDP_STATUS_INVALID_VIDEO_MIXER_FEATURE,
1066
/**
1067
* An invalid/unsupported \ref VdpVideoMixerParameter value was supplied.
1068
*/
1069
VDP_STATUS_INVALID_VIDEO_MIXER_PARAMETER,
1070
/**
1071
* An invalid/unsupported \ref VdpVideoMixerAttribute value was supplied.
1072
*/
1073
VDP_STATUS_INVALID_VIDEO_MIXER_ATTRIBUTE,
1074
/**
1075
* An invalid/unsupported \ref VdpVideoMixerPictureStructure value was
1076
* supplied.
1077
*/
1078
VDP_STATUS_INVALID_VIDEO_MIXER_PICTURE_STRUCTURE,
1079
/**
1080
* An invalid/unsupported \ref VdpFuncId value was supplied.
1081
*/
1082
VDP_STATUS_INVALID_FUNC_ID,
1083
/**
1084
* The size of a supplied object does not match the object it is being
1085
* used with.
1086
*
1087
* For example, a \ref VdpVideoMixer "VdpVideoMixer" is configured to
1088
* process \ref VdpVideoSurface "VdpVideoSurface" objects of a specific
1089
* size. If presented with a \ref VdpVideoSurface "VdpVideoSurface" of a
1090
* different size, this error will be raised.
1091
*/
1092
VDP_STATUS_INVALID_SIZE,
1093
/**
1094
* An invalid/unsupported value was supplied.
1095
*
1096
* This is a catch-all error code for values of type other than those
1097
* with a specific error code.
1098
*/
1099
VDP_STATUS_INVALID_VALUE,
1100
/**
1101
* An invalid/unsupported structure version was specified in a versioned
1102
* structure. This implies that the implementation is older than the
1103
* header file the application was built against.
1104
*/
1105
VDP_STATUS_INVALID_STRUCT_VERSION,
1106
/**
1107
* The system does not have enough resources to complete the requested
1108
* operation at this time.
1109
*/
1110
VDP_STATUS_RESOURCES,
1111
/**
1112
* The set of handles supplied are not all related to the same VdpDevice.
1113
*
1114
* When performing operations that operate on multiple surfaces, such as
1115
* \ref VdpOutputSurfaceRenderOutputSurface or \ref VdpVideoMixerRender,
1116
* all supplied surfaces must have been created within the context of the
1117
* same \ref VdpDevice "VdpDevice" object. This error is raised if they were
1118
* not.
1119
*/
1120
VDP_STATUS_HANDLE_DEVICE_MISMATCH,
1121
/**
1122
* A catch-all error, used when no other error code applies.
1123
*/
1124
VDP_STATUS_ERROR,
1125
} VdpStatus;
1126
1127
/**
1128
* \brief Retrieve a string describing an error code.
1129
* \param[in] status The error code.
1130
* \return A pointer to the string. Note that this is a
1131
* statically allocated read-only string. As such, the
1132
* application must not free the returned pointer. The
1133
* pointer is valid as long as the VDPAU implementation is
1134
* present within the application's address space.
1135
*/
1136
typedef char const * VdpGetErrorString(
1137
VdpStatus status
1138
);
1139
1140
/*@}*/
1141
1142
/**
1143
* \defgroup versioning Versioning
1144
*
1145
*
1146
* @{
1147
*/
1148
1149
/**
1150
* \brief The VDPAU version described by this header file.
1151
*
1152
* Note that VDPAU version numbers are simple integers that
1153
* increase monotonically (typically by value 1) with each VDPAU
1154
* header revision.
1155
*/
1156
#define VDPAU_VERSION 0
1157
1158
/**
1159
* \brief Retrieve the VDPAU version implemented by the backend.
1160
* \param[out] api_version The API version.
1161
* \return VdpStatus The completion status of the operation.
1162
*/
1163
typedef VdpStatus VdpGetApiVersion(
1164
/* output parameters follow */
1165
uint32_t * api_version
1166
);
1167
1168
/**
1169
* \brief Retrieve an implementation-specific string description
1170
* of the implementation. This typically includes detailed version
1171
* information.
1172
* \param[out] information_string A pointer to the information
1173
* string. Note that this is a statically allocated
1174
* read-only string. As such, the application must not
1175
* free the returned pointer. The pointer is valid as long
1176
* as the implementation is present within the
1177
* application's address space.
1178
* \return VdpStatus The completion status of the operation.
1179
*
1180
* Note that the returned string is useful for information
1181
* reporting. It is not intended that the application should
1182
* parse this string in order to determine any information about
1183
* the implementation.
1184
*/
1185
typedef VdpStatus VdpGetInformationString(
1186
/* output parameters follow */
1187
char const * * information_string
1188
);
1189
1190
/*@}*/
1191
1192
/**
1193
* \defgroup VdpDevice VdpDevice; Primary API object
1194
*
1195
* The VdpDevice is the root of the VDPAU object system. Using a
1196
* VdpDevice object, all other object types may be created. See
1197
* the sections describing those other object types for details
1198
* on object creation.
1199
*
1200
* Note that VdpDevice objects are created using the \ref
1201
* api_winsys.
1202
*
1203
* @{
1204
*/
1205
1206
/**
1207
* \brief An opaque handle representing a VdpDevice object.
1208
*/
1209
typedef uint32_t VdpDevice;
1210
1211
/**
1212
* \brief Destroy a VdpDevice.
1213
* \param[in] device The device to destroy.
1214
* \return VdpStatus The completion status of the operation.
1215
*/
1216
typedef VdpStatus VdpDeviceDestroy(
1217
VdpDevice device
1218
);
1219
1220
/*@}*/
1221
1222
/**
1223
* \defgroup VdpCSCMatrix VdpCSCMatrix; CSC Matrix Manipulation
1224
*
1225
* When converting from YCbCr to RGB data formats, a color space
1226
* conversion operation must be performed. This operation is
1227
* parameterized using a "color space conversion matrix". The
1228
* VdpCSCMatrix is a data structure representing this
1229
* information.
1230
*
1231
* @{
1232
*/
1233
1234
/**
1235
* \brief Storage for a color space conversion matrix.
1236
*
1237
* Note that the application may choose to construct the matrix
1238
* content by either:
1239
* - Directly filling in the fields of the CSC matrix
1240
* - Using the \ref VdpGenerateCSCMatrix helper function.
1241
*
1242
* The color space conversion equation is as follows:
1243
*
1244
* \f[
1245
* \left( \begin{array}{c} R \\ G \\ B \end{array} \right)
1246
* =
1247
* \left( \begin{array}{cccc}
1248
* m_{0,0} & m_{0,1} & m_{0,2} & m_{0,3} \\
1249
* m_{1,0} & m_{1,1} & m_{1,2} & m_{1,3} \\
1250
* m_{2,0} & m_{2,1} & m_{2,2} & m_{2,3}
1251
* \end{array}
1252
* \right)
1253
* *
1254
* \left( \begin{array}{c} Y \\ Cb \\ Cr \\ 1.0 \end{array}
1255
* \right)
1256
* \f]
1257
*/
1258
typedef float VdpCSCMatrix[3][4];
1259
1260
#define VDP_PROCAMP_VERSION 0
1261
1262
/**
1263
* \brief Procamp operation parameterization data.
1264
*
1265
* When performing a color space conversion operation, various
1266
* adjustments can be performed at the same time, such as
1267
* brightness and contrast. This structure defines the level of
1268
* adjustments to make.
1269
*/
1270
typedef struct {
1271
/**
1272
* This field must be filled with VDP_PROCAMP_VERSION
1273
*/
1274
uint32_t struct_version;
1275
/**
1276
* Brightness adjustment amount. A value clamped between
1277
* -1.0 and 1.0. 0.0 represents no modification.
1278
*/
1279
float brightness;
1280
/**
1281
* Contrast adjustment amount. A value clamped between
1282
* 0.0 and 10.0. 1.0 represents no modification.
1283
*/
1284
float contrast;
1285
/**
1286
* Saturation adjustment amount. A value clamped between 0.0 and
1287
* 10.0. 1.0 represents no modification.
1288
*/
1289
float saturation;
1290
/**
1291
* Hue adjustment amount. A value clamped between
1292
* -PI and PI. 0.0 represents no modification.
1293
*/
1294
float hue;
1295
} VdpProcamp;
1296
1297
/**
1298
* \brief YCbCr color space specification.
1299
*
1300
* A number of YCbCr color spaces exist. This enumeration
1301
* defines the specifications known to VDPAU.
1302
*/
1303
typedef uint32_t VdpColorStandard;
1304
1305
/** \hideinitializer \brief ITU-R BT.601 */
1306
#define VDP_COLOR_STANDARD_ITUR_BT_601 (VdpColorStandard)0
1307
/** \hideinitializer \brief ITU-R BT.709 */
1308
#define VDP_COLOR_STANDARD_ITUR_BT_709 (VdpColorStandard)1
1309
/** \hideinitializer \brief SMPTE-240M */
1310
#define VDP_COLOR_STANDARD_SMPTE_240M (VdpColorStandard)2
1311
1312
/**
1313
* \brief Generate a color space conversion matrix
1314
* \param[in] procamp The procamp adjustments to make. If NULL,
1315
* no adjustments will be made.
1316
* \param[in] standard The YCbCr color space to convert from.
1317
* \param[out] csc_matrix The CSC matrix to initialize.
1318
* \return VdpStatus The completion status of the operation.
1319
*/
1320
typedef VdpStatus VdpGenerateCSCMatrix(
1321
VdpProcamp * procamp,
1322
VdpColorStandard standard,
1323
/* output parameters follow */
1324
VdpCSCMatrix * csc_matrix
1325
);
1326
1327
/*@}*/
1328
1329
/**
1330
* \defgroup VdpVideoSurface VdpVideoSurface; Video Surface object
1331
*
1332
* A VdpVideoSurface stores YCbCr data in an internal format,
1333
* with a variety of possible chroma sub-sampling options.
1334
*
1335
* A VdpVideoSurface may be filled with:
1336
* - Data provided by the CPU via \ref
1337
* VdpVideoSurfacePutBitsYCbCr (i.e. software decode.)
1338
* - The result of applying a \ref VdpDecoder "VdpDecoder" to
1339
* compressed video data.
1340
*
1341
* VdpVideoSurface content may be accessed by:
1342
* - The application via \ref VdpVideoSurfaceGetBitsYCbCr
1343
* - The Hardware that implements \ref VdpOutputSurface
1344
* "VdpOutputSurface" \ref VdpOutputSurfaceRender
1345
* "rendering functionality".
1346
* - The Hardware the implements \ref VdpVideoMixer
1347
* "VdpVideoMixer" functionality.
1348
*
1349
* VdpVideoSurfaces are not directly displayable. They must be
1350
* converted into a displayable format using \ref VdpVideoMixer
1351
* "VdpVideoMixer" objects.
1352
*
1353
* See \ref video_mixer_usage for additional information.
1354
*
1355
* @{
1356
*/
1357
1358
/**
1359
* \brief Query the implementation's VdpVideoSurface
1360
* capabilities.
1361
* \param[in] device The device to query.
1362
* \param[in] surface_chroma_type The type of chroma type for
1363
* which information is requested.
1364
* \param[out] is_supported Is this chroma type supported?
1365
* \param[out] max_width The maximum supported surface width for
1366
* this chroma type.
1367
* \param[out] max_height The maximum supported surface height
1368
* for this chroma type.
1369
* \return VdpStatus The completion status of the operation.
1370
*/
1371
typedef VdpStatus VdpVideoSurfaceQueryCapabilities(
1372
VdpDevice device,
1373
VdpChromaType surface_chroma_type,
1374
/* output parameters follow */
1375
VdpBool * is_supported,
1376
uint32_t * max_width,
1377
uint32_t * max_height
1378
);
1379
1380
/**
1381
* \brief Query the implementation's VdpVideoSurface
1382
* GetBits/PutBits capabilities.
1383
* \param[in] device The device to query.
1384
* \param[in] surface_chroma_type The type of chroma type for
1385
* which information is requested.
1386
* \param[in] bits_ycbcr_format The format of application "bits"
1387
* buffer for which information is requested.
1388
* \param[out] is_supported Is this chroma type supported?
1389
* \return VdpStatus The completion status of the operation.
1390
*/
1391
typedef VdpStatus VdpVideoSurfaceQueryGetPutBitsYCbCrCapabilities(
1392
VdpDevice device,
1393
VdpChromaType surface_chroma_type,
1394
VdpYCbCrFormat bits_ycbcr_format,
1395
/* output parameters follow */
1396
VdpBool * is_supported
1397
);
1398
1399
/**
1400
* \brief An opaque handle representing a VdpVideoSurface
1401
* object.
1402
*/
1403
typedef uint32_t VdpVideoSurface;
1404
1405
/**
1406
* \brief Create a VdpVideoSurface.
1407
* \param[in] device The device that will contain the surface.
1408
* \param[in] chroma_type The chroma type of the new surface.
1409
* \param[in] width The width of the new surface.
1410
* \param[in] height The height of the new surface.
1411
* \param[out] surface The new surface's handle.
1412
* \return VdpStatus The completion status of the operation.
1413
*
1414
* The memory backing the surface may not be initialized during
1415
* creation. Applications are expected to initialize any region
1416
* that they use, via \ref VdpDecoderRender or \ref
1417
* VdpVideoSurfacePutBitsYCbCr.
1418
*/
1419
typedef VdpStatus VdpVideoSurfaceCreate(
1420
VdpDevice device,
1421
VdpChromaType chroma_type,
1422
uint32_t width,
1423
uint32_t height,
1424
/* output parameters follow */
1425
VdpVideoSurface * surface
1426
);
1427
1428
/**
1429
* \brief Destroy a VdpVideoSurface.
1430
* \param[in] surface The surface's handle.
1431
* \return VdpStatus The completion status of the operation.
1432
*/
1433
typedef VdpStatus VdpVideoSurfaceDestroy(
1434
VdpVideoSurface surface
1435
);
1436
1437
/**
1438
* \brief Retrieve the parameters used to create a
1439
* VdpVideoSurface.
1440
* \param[in] surface The surface's handle.
1441
* \param[out] chroma_type The chroma type of the surface.
1442
* \param[out] width The width of the surface.
1443
* \param[out] height The height of the surface.
1444
* \return VdpStatus The completion status of the operation.
1445
*/
1446
typedef VdpStatus VdpVideoSurfaceGetParameters(
1447
VdpVideoSurface surface,
1448
/* output parameters follow */
1449
VdpChromaType * chroma_type,
1450
uint32_t * width,
1451
uint32_t * height
1452
);
1453
1454
/**
1455
* \brief Copy image data from a VdpVideoSurface to application
1456
* memory in a specified YCbCr format.
1457
* \param[in] surface The surface's handle.
1458
* \param[in] destination_ycbcr_format The format of the
1459
* application's data buffers.
1460
* \param[in] destination_data Pointers to the application data
1461
* buffers into which the image data will be written. Note
1462
* that this is an array of pointers, one per plane. The
1463
* destination_format parameter will define how many
1464
* planes are required.
1465
* \param[in] destination_pitches Pointers to the pitch values
1466
* for the application data buffers. Note that this is an
1467
* array of pointers, one per plane. The
1468
* destination_format parameter will define how many
1469
* planes are required.
1470
* \return VdpStatus The completion status of the operation.
1471
*/
1472
typedef VdpStatus VdpVideoSurfaceGetBitsYCbCr(
1473
VdpVideoSurface surface,
1474
VdpYCbCrFormat destination_ycbcr_format,
1475
void * const * destination_data,
1476
uint32_t const * destination_pitches
1477
);
1478
1479
/**
1480
* \brief Copy image data from application memory in a specific
1481
* YCbCr format to a VdpVideoSurface.
1482
* \param[in] surface The surface's handle.
1483
* \param[in] source_ycbcr_format The format of the
1484
* application's data buffers.
1485
* \param[in] source_data Pointers to the application data
1486
* buffers from which the image data will be copied. Note
1487
* that this is an array of pointers, one per plane. The
1488
* source_format parameter will define how many
1489
* planes are required.
1490
* \param[in] source_pitches Pointers to the pitch values
1491
* for the application data buffers. Note that this is an
1492
* array of pointers, one per plane. The
1493
* source_format parameter will define how many
1494
* planes are required.
1495
* \return VdpStatus The completion status of the operation.
1496
*/
1497
typedef VdpStatus VdpVideoSurfacePutBitsYCbCr(
1498
VdpVideoSurface surface,
1499
VdpYCbCrFormat source_ycbcr_format,
1500
void const * const * source_data,
1501
uint32_t const * source_pitches
1502
);
1503
1504
/*@}*/
1505
1506
/**
1507
* \defgroup VdpOutputSurface VdpOutputSurface; Output Surface \
1508
* object
1509
*
1510
* A VdpOutputSurface stores RGBA data in a defined format.
1511
*
1512
* A VdpOutputSurface may be filled with:
1513
* - Data provided by the CPU via the various
1514
* VdpOutputSurfacePutBits functions.
1515
* - Using the VdpOutputSurface \ref VdpOutputSurfaceRender
1516
* "rendering functionality".
1517
* - Using a \ref VdpVideoMixer "VdpVideoMixer" object.
1518
*
1519
* VdpOutputSurface content may be accessed by:
1520
* - The application via the various VdpOutputSurfaceGetBits
1521
* functions.
1522
* - The Hardware that implements VdpOutputSurface
1523
* \ref VdpOutputSurfaceRender "rendering functionality".
1524
* - The Hardware the implements \ref VdpVideoMixer
1525
* "VdpVideoMixer" functionality.
1526
* - The Hardware that implements \ref VdpPresentationQueue
1527
* "VdpPresentationQueue" functionality,
1528
*
1529
* VdpVideoSurfaces are directly displayable using a \ref
1530
* VdpPresentationQueue "VdpPresentationQueue" object.
1531
*
1532
* @{
1533
*/
1534
1535
/**
1536
* \brief The set of all known color table formats, for use with
1537
* \ref VdpOutputSurfacePutBitsIndexed.
1538
*/
1539
typedef uint32_t VdpColorTableFormat;
1540
1541
/**
1542
* \hideinitializer
1543
* \brief 8-bit per component packed into 32-bits
1544
*
1545
* This format is an array of packed 32-bit RGB color values.
1546
* Bits [31:24] are unused, bits [23:16] contain R, bits [15:8]
1547
* contain G, and bits [7:0] contain B. Note: The format is
1548
* physically an array of uint32_t values, and should be accessed
1549
* as such by the application in order to avoid endianness
1550
* issues.
1551
*/
1552
#define VDP_COLOR_TABLE_FORMAT_B8G8R8X8 (VdpColorTableFormat)0
1553
1554
/**
1555
* \brief Query the implementation's VdpOutputSurface
1556
* capabilities.
1557
* \param[in] device The device to query.
1558
* \param[in] surface_rgba_format The surface format for
1559
* which information is requested.
1560
* \param[out] is_supported Is this surface format supported?
1561
* \param[out] max_width The maximum supported surface width for
1562
* this chroma type.
1563
* \param[out] max_height The maximum supported surface height
1564
* for this chroma type.
1565
* \return VdpStatus The completion status of the operation.
1566
*/
1567
typedef VdpStatus VdpOutputSurfaceQueryCapabilities(
1568
VdpDevice device,
1569
VdpRGBAFormat surface_rgba_format,
1570
/* output parameters follow */
1571
VdpBool * is_supported,
1572
uint32_t * max_width,
1573
uint32_t * max_height
1574
);
1575
1576
/**
1577
* \brief Query the implementation's capability to perform a
1578
* PutBits operation using application data matching the
1579
* surface's format.
1580
* \param[in] device The device to query.
1581
* \param[in] surface_rgba_format The surface format for
1582
* which information is requested.
1583
* \param[out] is_supported Is this surface format supported?
1584
* \return VdpStatus The completion status of the operation.
1585
*/
1586
typedef VdpStatus VdpOutputSurfaceQueryGetPutBitsNativeCapabilities(
1587
VdpDevice device,
1588
VdpRGBAFormat surface_rgba_format,
1589
/* output parameters follow */
1590
VdpBool * is_supported
1591
);
1592
1593
/**
1594
* \brief Query the implementation's capability to perform a
1595
* PutBits operation using application data in a specific
1596
* indexed format.
1597
* \param[in] device The device to query.
1598
* \param[in] surface_rgba_format The surface format for
1599
* which information is requested.
1600
* \param[in] bits_indexed_format The format of the application
1601
* data buffer.
1602
* \param[in] color_table_format The format of the color lookup
1603
* table.
1604
* \param[out] is_supported Is this surface format supported?
1605
* \return VdpStatus The completion status of the operation.
1606
*/
1607
typedef VdpStatus VdpOutputSurfaceQueryPutBitsIndexedCapabilities(
1608
VdpDevice device,
1609
VdpRGBAFormat surface_rgba_format,
1610
VdpIndexedFormat bits_indexed_format,
1611
VdpColorTableFormat color_table_format,
1612
/* output parameters follow */
1613
VdpBool * is_supported
1614
);
1615
1616
/**
1617
* \brief Query the implementation's capability to perform a
1618
* PutBits operation using application data in a specific
1619
* YCbCr/YUB format.
1620
* \param[in] device The device to query.
1621
* \param[in] surface_rgba_format The surface format for which
1622
* information is requested.
1623
* \param[in] bits_ycbcr_format The format of the application
1624
* data buffer.
1625
* \param[out] is_supported Is this surface format supported?
1626
* \return VdpStatus The completion status of the operation.
1627
*/
1628
typedef VdpStatus VdpOutputSurfaceQueryPutBitsYCbCrCapabilities(
1629
VdpDevice device,
1630
VdpRGBAFormat surface_rgba_format,
1631
VdpYCbCrFormat bits_ycbcr_format,
1632
/* output parameters follow */
1633
VdpBool * is_supported
1634
);
1635
1636
/**
1637
* \brief An opaque handle representing a VdpOutputSurface
1638
* object.
1639
*/
1640
typedef uint32_t VdpOutputSurface;
1641
1642
/**
1643
* \brief Create a VdpOutputSurface.
1644
* \param[in] device The device that will contain the surface.
1645
* \param[in] rgba_format The format of the new surface.
1646
* \param[in] width The width of the new surface.
1647
* \param[in] height The height of the new surface.
1648
* \param[out] surface The new surface's handle.
1649
* \return VdpStatus The completion status of the operation.
1650
*
1651
* The memory backing the surface will be initialized to 0 color
1652
* and 0 alpha (i.e. black.)
1653
*/
1654
typedef VdpStatus VdpOutputSurfaceCreate(
1655
VdpDevice device,
1656
VdpRGBAFormat rgba_format,
1657
uint32_t width,
1658
uint32_t height,
1659
/* output parameters follow */
1660
VdpOutputSurface * surface
1661
);
1662
1663
/**
1664
* \brief Destroy a VdpOutputSurface.
1665
* \param[in] surface The surface's handle.
1666
* \return VdpStatus The completion status of the operation.
1667
*/
1668
typedef VdpStatus VdpOutputSurfaceDestroy(
1669
VdpOutputSurface surface
1670
);
1671
1672
/**
1673
* \brief Retrieve the parameters used to create a
1674
* VdpOutputSurface.
1675
* \param[in] surface The surface's handle.
1676
* \param[out] rgba_format The format of the surface.
1677
* \param[out] width The width of the surface.
1678
* \param[out] height The height of the surface.
1679
* \return VdpStatus The completion status of the operation.
1680
*/
1681
typedef VdpStatus VdpOutputSurfaceGetParameters(
1682
VdpOutputSurface surface,
1683
/* output parameters follow */
1684
VdpRGBAFormat * rgba_format,
1685
uint32_t * width,
1686
uint32_t * height
1687
);
1688
1689
/**
1690
* \brief Copy image data from a VdpOutputSurface to application
1691
* memory in the surface's native format.
1692
* \param[in] surface The surface's handle.
1693
* \param[in] source_rect The sub-rectangle of the source
1694
* surface to copy. If NULL, the entire surface will be
1695
* retrieved.
1696
* \param[in] destination_data Pointers to the application data
1697
* buffers into which the image data will be written. Note
1698
* that this is an array of pointers, one per plane. The
1699
* destination_format parameter will define how many
1700
* planes are required.
1701
* \param[in] destination_pitches Pointers to the pitch values
1702
* for the application data buffers. Note that this is an
1703
* array of pointers, one per plane. The
1704
* destination_format parameter will define how many
1705
* planes are required.
1706
* \return VdpStatus The completion status of the operation.
1707
*/
1708
typedef VdpStatus VdpOutputSurfaceGetBitsNative(
1709
VdpOutputSurface surface,
1710
VdpRect const * source_rect,
1711
void * const * destination_data,
1712
uint32_t const * destination_pitches
1713
);
1714
1715
/**
1716
* \brief Copy image data from application memory in the
1717
* surface's native format to a VdpOutputSurface.
1718
* \param[in] surface The surface's handle.
1719
* \param[in] source_data Pointers to the application data
1720
* buffers from which the image data will be copied. Note
1721
* that this is an array of pointers, one per plane. The
1722
* source_format parameter will define how many
1723
* planes are required.
1724
* \param[in] source_pitches Pointers to the pitch values
1725
* for the application data buffers. Note that this is an
1726
* array of pointers, one per plane. The
1727
* source_format parameter will define how many
1728
* planes are required.
1729
* \param[in] destination_rect The sub-rectangle of the surface
1730
* to fill with application data. If NULL, the entire
1731
* surface will be updated.
1732
* \return VdpStatus The completion status of the operation.
1733
*/
1734
typedef VdpStatus VdpOutputSurfacePutBitsNative(
1735
VdpOutputSurface surface,
1736
void const * const * source_data,
1737
uint32_t const * source_pitches,
1738
VdpRect const * destination_rect
1739
);
1740
1741
/**
1742
* \brief Copy image data from application memory in a specific
1743
* indexed format to a VdpOutputSurface.
1744
* \param[in] surface The surface's handle.
1745
* \param[in] source_indexed_format The format of the
1746
* application's data buffers.
1747
* \param[in] source_data Pointers to the application data
1748
* buffers from which the image data will be copied. Note
1749
* that this is an array of pointers, one per plane. The
1750
* source_indexed_format parameter will define how many
1751
* planes are required.
1752
* \param[in] source_pitches Pointers to the pitch values
1753
* for the application data buffers. Note that this is an
1754
* array of pointers, one per plane. The
1755
* source_indexed_format parameter will define how many
1756
* planes are required.
1757
* \param[in] destination_rect The sub-rectangle of the surface
1758
* to fill with application data. If NULL, the entire
1759
* surface will be updated.
1760
* \param[in] color_table_format The format of the color_table.
1761
* \param[in] color_table A table that maps between source index
1762
* and target color data. See \ref VdpColorTableFormat for
1763
* details regarding the memory layout.
1764
* \return VdpStatus The completion status of the operation.
1765
*/
1766
typedef VdpStatus VdpOutputSurfacePutBitsIndexed(
1767
VdpOutputSurface surface,
1768
VdpIndexedFormat source_indexed_format,
1769
void const * const * source_data,
1770
uint32_t const * source_pitch,
1771
VdpRect const * destination_rect,
1772
VdpColorTableFormat color_table_format,
1773
void const * color_table
1774
);
1775
1776
/**
1777
* \brief Copy image data from application memory in a specific
1778
* YCbCr format to a VdpOutputSurface.
1779
* \param[in] surface The surface's handle.
1780
* \param[in] source_ycbcr_format The format of the
1781
* application's data buffers.
1782
* \param[in] source_data Pointers to the application data
1783
* buffers from which the image data will be copied. Note
1784
* that this is an array of pointers, one per plane. The
1785
* source_ycbcr_format parameter will define how many
1786
* planes are required.
1787
* \param[in] source_pitches Pointers to the pitch values
1788
* for the application data buffers. Note that this is an
1789
* array of pointers, one per plane. The
1790
* source_ycbcr_format parameter will define how many
1791
* planes are required.
1792
* \param[in] destination_rect The sub-rectangle of the surface
1793
* to fill with application data. If NULL, the entire
1794
* surface will be updated.
1795
* \param[in] csc_matrix The color space conversion matrix used
1796
* by the copy operation. If NULL, a default matrix will
1797
* be used internally. Th default matrix is equivalent to
1798
* ITU-R BT.601 with no procamp changes.
1799
* \return VdpStatus The completion status of the operation.
1800
*/
1801
typedef VdpStatus VdpOutputSurfacePutBitsYCbCr(
1802
VdpOutputSurface surface,
1803
VdpYCbCrFormat source_ycbcr_format,
1804
void const * const * source_data,
1805
uint32_t const * source_pitches,
1806
VdpRect const * destination_rect,
1807
VdpCSCMatrix const * csc_matrix
1808
);
1809
1810
/*@}*/
1811
1812
/**
1813
* \defgroup VdpBitmapSurface VdpBitmapSurface; Bitmap Surface \
1814
* object
1815
*
1816
* A VdpBitmapSurface stores RGBA data in a defined format.
1817
*
1818
* A VdpBitmapSurface may be filled with:
1819
* - Data provided by the CPU via the \ref
1820
* VdpBitmapSurfacePutBitsNative function.
1821
*
1822
* VdpBitmapSurface content may be accessed by:
1823
* - The Hardware that implements \ref VdpOutputSurface
1824
* "VdpOutputSurface" \ref VdpOutputSurfaceRender
1825
* "rendering functionality"
1826
*
1827
* VdpBitmapSurface objects are intended to store static read-only data, such
1828
* as font glyphs, and the bitmaps used to compose an applications'
1829
* user-interface.
1830
*
1831
* The primary differences between VdpBitmapSurfaces and
1832
* \ref VdpOutputSurface "VdpOutputSurface"s are:
1833
*
1834
* - You cannot render to a VdpBitmapSurface, just upload native data via
1835
* the PutBits API.
1836
*
1837
* - The read-only nature of a VdpBitmapSurface gives the implementation more
1838
* flexibility in its choice of data storage location for the bitmap data.
1839
* For example, some implementations may choose to store some/all
1840
* VdpBitmapSurface objects in system memory to relieve GPU memory pressure.
1841
*
1842
* - VdpBitmapSurface and VdpOutputSurface may support different subsets of all
1843
* known RGBA formats.
1844
*
1845
* @{
1846
*/
1847
1848
/**
1849
* \brief Query the implementation's VdpBitmapSurface
1850
* capabilities.
1851
* \param[in] device The device to query.
1852
* \param[in] surface_rgba_format The surface format for
1853
* which information is requested.
1854
* \param[out] is_supported Is this surface format supported?
1855
* \param[out] max_width The maximum supported surface width for
1856
* this chroma type.
1857
* \param[out] max_height The maximum supported surface height
1858
* for this chroma type.
1859
* \return VdpStatus The completion status of the operation.
1860
*/
1861
typedef VdpStatus VdpBitmapSurfaceQueryCapabilities(
1862
VdpDevice device,
1863
VdpRGBAFormat surface_rgba_format,
1864
/* output parameters follow */
1865
VdpBool * is_supported,
1866
uint32_t * max_width,
1867
uint32_t * max_height
1868
);
1869
1870
/**
1871
* \brief An opaque handle representing a VdpBitmapSurface
1872
* object.
1873
*/
1874
typedef uint32_t VdpBitmapSurface;
1875
1876
/**
1877
* \brief Create a VdpBitmapSurface.
1878
* \param[in] device The device that will contain the surface.
1879
* \param[in] rgba_format The format of the new surface.
1880
* \param[in] width The width of the new surface.
1881
* \param[in] height The height of the new surface.
1882
* \param[in] frequently_accessed Is this bitmap used
1883
* frequently, or infrequently, by compositing options?
1884
* Implementations may use this as a hint to determine how
1885
* to allocate the underlying storage for the surface.
1886
* \param[out] surface The new surface's handle.
1887
* \return VdpStatus The completion status of the operation.
1888
*
1889
* The memory backing the surface may not be initialized
1890
* during creation. Applications are expected initialize any
1891
* region that they use, via \ref VdpBitmapSurfacePutBitsNative.
1892
*/
1893
typedef VdpStatus VdpBitmapSurfaceCreate(
1894
VdpDevice device,
1895
VdpRGBAFormat rgba_format,
1896
uint32_t width,
1897
uint32_t height,
1898
VdpBool frequently_accessed,
1899
/* output parameters follow */
1900
VdpBitmapSurface * surface
1901
);
1902
1903
/**
1904
* \brief Destroy a VdpBitmapSurface.
1905
* \param[in] surface The surface's handle.
1906
* \return VdpStatus The completion status of the operation.
1907
*/
1908
typedef VdpStatus VdpBitmapSurfaceDestroy(
1909
VdpBitmapSurface surface
1910
);
1911
1912
/**
1913
* \brief Retrieve the parameters used to create a
1914
* VdpBitmapSurface.
1915
* \param[in] surface The surface's handle.
1916
* \param[out] rgba_format The format of the surface.
1917
* \param[out] width The width of the surface.
1918
* \param[out] height The height of the surface.
1919
* \param[out] frequently_accessed The frequently_accessed state
1920
* of the surface.
1921
* \return VdpStatus The completion status of the operation.
1922
*/
1923
typedef VdpStatus VdpBitmapSurfaceGetParameters(
1924
VdpBitmapSurface surface,
1925
/* output parameters follow */
1926
VdpRGBAFormat * rgba_format,
1927
uint32_t * width,
1928
uint32_t * height,
1929
VdpBool * frequently_accessed
1930
);
1931
1932
/**
1933
* \brief Copy image data from application memory in the
1934
* surface's native format to a VdpBitmapSurface.
1935
* \param[in] surface The surface's handle.
1936
* \param[in] source_data Pointers to the application data
1937
* buffers from which the image data will be copied. Note
1938
* that this is an array of pointers, one per plane. The
1939
* source_format parameter will define how many
1940
* planes are required.
1941
* \param[in] source_pitches Pointers to the pitch values
1942
* for the application data buffers. Note that this is an
1943
* array of pointers, one per plane. The
1944
* source_format parameter will define how many
1945
* planes are required.
1946
* \param[in] destination_rect The sub-rectangle of the surface
1947
* to fill with application data. If NULL, the entire
1948
* surface will be updated.
1949
* \return VdpStatus The completion status of the operation.
1950
*/
1951
typedef VdpStatus VdpBitmapSurfacePutBitsNative(
1952
VdpBitmapSurface surface,
1953
void const * const * source_data,
1954
uint32_t const * source_pitches,
1955
VdpRect const * destination_rect
1956
);
1957
1958
/*@}*/
1959
1960
/**
1961
* \defgroup VdpOutputSurfaceRender VdpOutputSurface Rendering \
1962
* Functionality
1963
*
1964
* \ref VdpOutputSurface "VdpOutputSurface" objects
1965
* directly provide some rendering/compositing operations. These
1966
* are described below.
1967
*
1968
* @{
1969
*/
1970
1971
/**
1972
* \hideinitializer
1973
* \brief The blending equation factors.
1974
*/
1975
typedef enum {
1976
VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ZERO = 0,
1977
VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE = 1,
1978
VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_SRC_COLOR = 2,
1979
VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_SRC_COLOR = 3,
1980
VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_SRC_ALPHA = 4,
1981
VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA = 5,
1982
VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_DST_ALPHA = 6,
1983
VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_DST_ALPHA = 7,
1984
VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_DST_COLOR = 8,
1985
VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_DST_COLOR = 9,
1986
VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_SRC_ALPHA_SATURATE = 10,
1987
VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_CONSTANT_COLOR = 11,
1988
VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR = 12,
1989
VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_CONSTANT_ALPHA = 13,
1990
VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA = 14,
1991
} VdpOutputSurfaceRenderBlendFactor;
1992
1993
/**
1994
* \hideinitializer
1995
* \brief The blending equations.
1996
*/
1997
typedef enum {
1998
VDP_OUTPUT_SURFACE_RENDER_BLEND_EQUATION_SUBTRACT = 0,
1999
VDP_OUTPUT_SURFACE_RENDER_BLEND_EQUATION_REVERSE_SUBTRACT = 1,
2000
VDP_OUTPUT_SURFACE_RENDER_BLEND_EQUATION_ADD = 2,
2001
VDP_OUTPUT_SURFACE_RENDER_BLEND_EQUATION_MIN = 3,
2002
VDP_OUTPUT_SURFACE_RENDER_BLEND_EQUATION_MAX = 4,
2003
} VdpOutputSurfaceRenderBlendEquation;
2004
2005
#define VDP_OUTPUT_SURFACE_RENDER_BLEND_STATE_VERSION 0
2006
2007
/**
2008
* \brief Complete blending operation definition.
2009
*/
2010
typedef struct {
2011
/**
2012
* This field must be filled with VDP_OUTPUT_SURFACE_RENDER_BLEND_STATE_VERSIION
2013
*/
2014
uint32_t struct_version;
2015
VdpOutputSurfaceRenderBlendFactor blend_factor_source_color;
2016
VdpOutputSurfaceRenderBlendFactor blend_factor_destination_color;
2017
VdpOutputSurfaceRenderBlendFactor blend_factor_source_alpha;
2018
VdpOutputSurfaceRenderBlendFactor blend_factor_destination_alpha;
2019
VdpOutputSurfaceRenderBlendEquation blend_equation_color;
2020
VdpOutputSurfaceRenderBlendEquation blend_equation_alpha;
2021
VdpColor blend_constant;
2022
} VdpOutputSurfaceRenderBlendState;
2023
2024
/**
2025
* \hideinitializer
2026
* \brief Do not rotate source_surface prior to compositing.
2027
*/
2028
#define VDP_OUTPUT_SURFACE_RENDER_ROTATE_0 0
2029
2030
/**
2031
* \hideinitializer
2032
* \brief Rotate source_surface 90 degrees clockwise prior to
2033
* compositing.
2034
*/
2035
#define VDP_OUTPUT_SURFACE_RENDER_ROTATE_90 1
2036
2037
/**
2038
* \hideinitializer
2039
* \brief Rotate source_surface 180 degrees prior to
2040
* compositing.
2041
*/
2042
#define VDP_OUTPUT_SURFACE_RENDER_ROTATE_180 2
2043
2044
/**
2045
* \hideinitializer
2046
* \brief Rotate source_surface 270 degrees clockwise prior to
2047
* compositing.
2048
*/
2049
#define VDP_OUTPUT_SURFACE_RENDER_ROTATE_270 3
2050
2051
/**
2052
* \hideinitializer
2053
* \brief A separate color is used for each vertex of the
2054
* smooth-shaded quad. Hence, colors array contains 4
2055
* elements rather than 1. See description of colors
2056
* array.
2057
*/
2058
#define VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX (1 << 2)
2059
2060
/**
2061
* \brief Composite a sub-rectangle of a \ref VdpOutputSurface
2062
* "VdpOutputSurface" into a sub-rectangle of another
2063
* \ref VdpOutputSurface VdpOutputSurface.
2064
* \param[in] destination_surface The destination surface of the
2065
* compositing operation.
2066
* \param[in] destination_rect The sub-rectangle of the
2067
* destination surface to update. If NULL, the entire
2068
* destination surface will be updated.
2069
* \param[in] source_surface The source surface for the
2070
* compositing operation. The surface is treated as having
2071
* four components: red, green, blue and alpha. Any
2072
* missing components are treated as 1.0. For example, for
2073
* an A8 VdpOutputSurface, alpha will come from the surface
2074
* but red, green and blue will be treated as 1.0. If
2075
* source_surface is NULL, all components will be treated
2076
* as 1.0. Note that destination_surface and
2077
* source_surface must have been allocated via the same
2078
* \ref VdpDevice "VdpDevice".
2079
* \param[in] source_rect The sub-rectangle of the source
2080
* surface to read from. If NULL, the entire
2081
* source_surface will be read. Left/right ot top/bottom
2082
* co-ordinates may be swapped to flip the source. Any
2083
* flip occurs prior to any requested rotation. Values
2084
* from outside the source surface are valid and samples
2085
* at those locations will be taken from the nearest edge.
2086
* \param[in] colors A pointer to an array of \ref VdpColor
2087
* "VdpColor" objects. If the flag
2088
* VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX is set,
2089
* VDPAU will four entries from the array, and treat them
2090
* as the colors corresponding to the upper-left,
2091
* upper-right, lower-right and lower-left corners of the
2092
* post-rotation source (i.e. indices 0, 1, 2 and 3 run
2093
* clockwise from the upper left corner). If the flag
2094
* VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX is not
2095
* set, VDPAU will use the single VdpColor for all four
2096
* corners. If colors is NULL then red, green, blue and
2097
* alpha values of 1.0 will be used.
2098
* \param[in] blend_state If a blend state is provided, the
2099
* blend state will be used for the composite operation. If
2100
* NULL, blending is effectively disabled, which is
2101
* equivalent to a blend equation of ADD, source blend
2102
* factors of ONE and destination blend factors of ZERO. The
2103
* blend math is the familiar OpenGL blend math:
2104
* \f[
2105
* dst.a = equation(blendFactorDstAlpha*dst.a,
2106
* blendFactorSrcAlpha*src.a);
2107
* \f]
2108
* \f[
2109
* dst.rgb = equation(blendFactorDstColor*dst.rgb,
2110
* blendFactorSrcColor*src.rgb);
2111
* \f]
2112
* \param[in] flags A set of flags influencing how the
2113
* compositing operation works.
2114
* \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_0
2115
* \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_90
2116
* \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_180
2117
* \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_270
2118
* \arg \ref VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX
2119
* \return VdpStatus The completion status of the operation.
2120
*
2121
* The general compositing pipeline is as follows.
2122
*
2123
* -# Extract source_rect from source_surface.
2124
*
2125
* -# The extracted source is rotated 0, 90, 180 or 270 degrees
2126
* according to the flags.
2127
*
2128
* -# The rotated source is component-wise multiplied by a
2129
* smooth-shaded quad with a (potentially) different color at
2130
* each vertex.
2131
*
2132
* -# The resulting rotated, smooth-shaded quad is scaled to the
2133
* size of destination_rect and composited with
2134
* destination_surface using the provided blend state.
2135
*
2136
*/
2137
typedef VdpStatus VdpOutputSurfaceRenderOutputSurface(
2138
VdpOutputSurface destination_surface,
2139
VdpRect const * destination_rect,
2140
VdpOutputSurface source_surface,
2141
VdpRect const * source_rect,
2142
VdpColor const * colors,
2143
VdpOutputSurfaceRenderBlendState const * blend_state,
2144
uint32_t flags
2145
);
2146
2147
/**
2148
* \brief Composite a sub-rectangle of a \ref VdpBitmapSurface
2149
* "VdpBitmapSurface" into a sub-rectangle of a
2150
* \ref VdpOutputSurface VdpOutputSurface.
2151
* \param[in] destination_surface The destination surface of the
2152
* compositing operation.
2153
* \param[in] destination_rect The sub-rectangle of the
2154
* destination surface to update. If NULL, the entire
2155
* destination surface will be updated.
2156
* \param[in] source_surface The source surface for the
2157
* compositing operation. The surface is treated as having
2158
* four components: red, green, blue and alpha. Any
2159
* missing components are treated as 1.0. For example, for
2160
* an A8 VdpBitmapSurface, alpha will come from the surface
2161
* but red, green and blue will be treated as 1.0. If
2162
* source_surface is NULL, all components will be treated
2163
* as 1.0. Note that destination_surface and
2164
* source_surface must have been allocated via the same
2165
* \ref VdpDevice "VdpDevice".
2166
* \param[in] source_rect The sub-rectangle of the source
2167
* surface to read from. If NULL, the entire
2168
* source_surface will be read. Left/right ot top/bottom
2169
* co-ordinates may be swapped to flip the source. Any
2170
* flip occurs prior to any requested rotation. Values
2171
* from outside the source surface are valid and samples
2172
* at those locations will be taken from the nearest edge.
2173
* \param[in] colors A pointer to an array of \ref VdpColor
2174
* "VdpColor" objects. If the flag
2175
* VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX is set,
2176
* VDPAU will four entries from the array, and treat them
2177
* as the colors corresponding to the upper-left,
2178
* upper-right, lower-right and lower-left corners of the
2179
* post-rotation source (i.e. indices 0, 1, 2 and 3 run
2180
* clockwise from the upper left corner). If the flag
2181
* VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX is not
2182
* set, VDPAU will use the single VdpColor for all four
2183
* corners. If colors is NULL then red, green, blue and
2184
* alpha values of 1.0 will be used.
2185
* \param[in] blend_state If a blend state is provided, the
2186
* blend state will be used for the composite operation. If
2187
* NULL, blending is effectively disabled, which is
2188
* equivalent to a blend equation of ADD, source blend
2189
* factors of ONE and destination blend factors of ZERO. The
2190
* blend math is the familiar OpenGL blend math:
2191
* \f[
2192
* dst.a = equation(blendFactorDstAlpha*dst.a,
2193
* blendFactorSrcAlpha*src.a);
2194
* \f]
2195
* \f[
2196
* dst.rgb = equation(blendFactorDstColor*dst.rgb,
2197
* blendFactorSrcColor*src.rgb);
2198
* \f]
2199
* \param[in] flags A set of flags influencing how the
2200
* compositing operation works.
2201
* \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_0
2202
* \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_90
2203
* \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_180
2204
* \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_270
2205
* \arg \ref VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX
2206
* \return VdpStatus The completion status of the operation.
2207
*
2208
* The general compositing pipeline is as follows.
2209
*
2210
* -# Extract source_rect from source_surface.
2211
*
2212
* -# The extracted source is rotated 0, 90, 180 or 270 degrees
2213
* according to the flags.
2214
*
2215
* -# The rotated source is component-wise multiplied by a
2216
* smooth-shaded quad with a (potentially) different color at
2217
* each vertex.
2218
*
2219
* -# The resulting rotated, smooth-shaded quad is scaled to the
2220
* size of destination_rect and composited with
2221
* destination_surface using the provided blend state.
2222
*
2223
*/
2224
typedef VdpStatus VdpOutputSurfaceRenderBitmapSurface(
2225
VdpOutputSurface destination_surface,
2226
VdpRect const * destination_rect,
2227
VdpBitmapSurface source_surface,
2228
VdpRect const * source_rect,
2229
VdpColor const * colors,
2230
VdpOutputSurfaceRenderBlendState const * blend_state,
2231
uint32_t flags
2232
);
2233
2234
/*@}*/
2235
2236
/**
2237
* \defgroup VdpDecoder VdpDecoder; Video Decoding object
2238
*
2239
* The VdpDecoder object decodes compressed video data, writing
2240
* the results to a \ref VdpVideoSurface "VdpVideoSurface".
2241
*
2242
* A specific VDPAU implementation may support decoding multiple
2243
* types of compressed video data. However, VdpDecoder objects
2244
* are able to decode a specific type of compressed video data.
2245
* This type must be specified during creation.
2246
*
2247
* @{
2248
*/
2249
2250
/**
2251
* \brief The set of all known compressed video formats, and
2252
* associated profiles, that may be decoded.
2253
*/
2254
typedef uint32_t VdpDecoderProfile;
2255
2256
/** \hideinitializer */
2257
#define VDP_DECODER_PROFILE_MPEG1 (VdpDecoderProfile)0
2258
/** \hideinitializer */
2259
#define VDP_DECODER_PROFILE_MPEG2_SIMPLE (VdpDecoderProfile)1
2260
/** \hideinitializer */
2261
#define VDP_DECODER_PROFILE_MPEG2_MAIN (VdpDecoderProfile)2
2262
/** \hideinitializer */
2263
/** \brief MPEG 4 part 10 == H.264 == AVC */
2264
#define VDP_DECODER_PROFILE_H264_BASELINE (VdpDecoderProfile)6
2265
/** \hideinitializer */
2266
#define VDP_DECODER_PROFILE_H264_MAIN (VdpDecoderProfile)7
2267
/** \hideinitializer */
2268
#define VDP_DECODER_PROFILE_H264_HIGH (VdpDecoderProfile)8
2269
/** \hideinitializer */
2270
#define VDP_DECODER_PROFILE_VC1_SIMPLE (VdpDecoderProfile)9
2271
/** \hideinitializer */
2272
#define VDP_DECODER_PROFILE_VC1_MAIN (VdpDecoderProfile)10
2273
/** \hideinitializer */
2274
#define VDP_DECODER_PROFILE_VC1_ADVANCED (VdpDecoderProfile)11
2275
2276
/** \hideinitializer */
2277
#define VDP_DECODER_LEVEL_MPEG1_NA 0
2278
2279
/** \hideinitializer */
2280
#define VDP_DECODER_LEVEL_MPEG2_LL 0
2281
/** \hideinitializer */
2282
#define VDP_DECODER_LEVEL_MPEG2_ML 1
2283
/** \hideinitializer */
2284
#define VDP_DECODER_LEVEL_MPEG2_HL14 2
2285
/** \hideinitializer */
2286
#define VDP_DECODER_LEVEL_MPEG2_HL 3
2287
2288
/** \hideinitializer */
2289
#define VDP_DECODER_LEVEL_H264_1 10
2290
/** \hideinitializer */
2291
#define VDP_DECODER_LEVEL_H264_1b 9
2292
/** \hideinitializer */
2293
#define VDP_DECODER_LEVEL_H264_1_1 11
2294
/** \hideinitializer */
2295
#define VDP_DECODER_LEVEL_H264_1_2 12
2296
/** \hideinitializer */
2297
#define VDP_DECODER_LEVEL_H264_1_3 13
2298
/** \hideinitializer */
2299
#define VDP_DECODER_LEVEL_H264_2 20
2300
/** \hideinitializer */
2301
#define VDP_DECODER_LEVEL_H264_2_1 21
2302
/** \hideinitializer */
2303
#define VDP_DECODER_LEVEL_H264_2_2 22
2304
/** \hideinitializer */
2305
#define VDP_DECODER_LEVEL_H264_3 30
2306
/** \hideinitializer */
2307
#define VDP_DECODER_LEVEL_H264_3_1 31
2308
/** \hideinitializer */
2309
#define VDP_DECODER_LEVEL_H264_3_2 32
2310
/** \hideinitializer */
2311
#define VDP_DECODER_LEVEL_H264_4 40
2312
/** \hideinitializer */
2313
#define VDP_DECODER_LEVEL_H264_4_1 41
2314
/** \hideinitializer */
2315
#define VDP_DECODER_LEVEL_H264_4_2 42
2316
/** \hideinitializer */
2317
#define VDP_DECODER_LEVEL_H264_5 50
2318
/** \hideinitializer */
2319
#define VDP_DECODER_LEVEL_H264_5_1 51
2320
2321
/** \hideinitializer */
2322
#define VDP_DECODER_LEVEL_VC1_SIMPLE_LOW 0
2323
/** \hideinitializer */
2324
#define VDP_DECODER_LEVEL_VC1_SIMPLE_MEDIUM 1
2325
2326
/** \hideinitializer */
2327
#define VDP_DECODER_LEVEL_VC1_MAIN_LOW 0
2328
/** \hideinitializer */
2329
#define VDP_DECODER_LEVEL_VC1_MAIN_MEDIUM 1
2330
/** \hideinitializer */
2331
#define VDP_DECODER_LEVEL_VC1_MAIN_HIGH 2
2332
2333
/** \hideinitializer */
2334
#define VDP_DECODER_LEVEL_VC1_ADVANCED_L0 0
2335
/** \hideinitializer */
2336
#define VDP_DECODER_LEVEL_VC1_ADVANCED_L1 1
2337
/** \hideinitializer */
2338
#define VDP_DECODER_LEVEL_VC1_ADVANCED_L2 2
2339
/** \hideinitializer */
2340
#define VDP_DECODER_LEVEL_VC1_ADVANCED_L3 3
2341
/** \hideinitializer */
2342
#define VDP_DECODER_LEVEL_VC1_ADVANCED_L4 4
2343
2344
/**
2345
* \brief Query the implementation's VdpDecoder capabilities.
2346
* \param[in] device The device to query.
2347
* \param[in] profile The decoder profile for which information is requested.
2348
* \param[out] is_supported Is this profile supported?
2349
* \param[out] max_level The maximum specification level supported for this
2350
* profile.
2351
* \param[out] max_macroblocks The maximum supported surface size in
2352
* macroblocks. Note that this could be greater than that dictated by
2353
* the maximum level.
2354
* \param[out] max_width The maximum supported surface width for this profile.
2355
* Note that this could be greater than that dictated by the maximum
2356
* level.
2357
* \param[out] max_height The maximum supported surface height for this
2358
* profile. Note that this could be greater than that dictated by the
2359
* maximum level.
2360
* \return VdpStatus The completion status of the operation.
2361
*/
2362
typedef VdpStatus VdpDecoderQueryCapabilities(
2363
VdpDevice device,
2364
VdpDecoderProfile profile,
2365
/* output parameters follow */
2366
VdpBool * is_supported,
2367
uint32_t * max_level,
2368
uint32_t * max_macroblocks,
2369
uint32_t * max_width,
2370
uint32_t * max_height
2371
);
2372
2373
/**
2374
* \brief An opaque handle representing a VdpDecoder object.
2375
*/
2376
typedef uint32_t VdpDecoder;
2377
2378
/**
2379
* \brief Create a VdpDecoder.
2380
* \param[in] device The device that will contain the surface.
2381
* \param[in] profile The video format the decoder will decode.
2382
* \param[in] width The width of the new surface.
2383
* \param[in] height The height of the new surface.
2384
* \param[in] max_references The maximum number of references that may be
2385
* used by a single frame in the stream to be decoded. This parameter
2386
* exists mainly for formats such as H.264, where different streams
2387
* may use a different number of references. Requesting too many
2388
* references may waste memory, but decoding should still operate
2389
* correctly. Requesting too few references will cause decoding to
2390
* fail.
2391
* \param[out] decoder The new decoder's handle.
2392
* \return VdpStatus The completion status of the operation.
2393
*/
2394
typedef VdpStatus VdpDecoderCreate(
2395
VdpDevice device,
2396
VdpDecoderProfile profile,
2397
uint32_t width,
2398
uint32_t height,
2399
uint32_t max_references,
2400
/* output parameters follow */
2401
VdpDecoder * decoder
2402
);
2403
2404
/**
2405
* \brief Destroy a VdpDecoder.
2406
* \param[in] surface The decoder's handle.
2407
* \return VdpStatus The completion status of the operation.
2408
*/
2409
typedef VdpStatus VdpDecoderDestroy(
2410
VdpDecoder decoder
2411
);
2412
2413
/**
2414
* \brief Retrieve the parameters used to create a
2415
* VdpDecoder.
2416
* \param[in] surface The surface's handle.
2417
* \param[out] profile The video format used to create the
2418
* decoder.
2419
* \param[out] width The width of surfaces decode by the
2420
* decoder.
2421
* \param[out] height The height of surfaces decode by the
2422
* decoder
2423
* \return VdpStatus The completion status of the operation.
2424
*/
2425
typedef VdpStatus VdpDecoderGetParameters(
2426
VdpDecoder decoder,
2427
/* output parameters follow */
2428
VdpDecoderProfile * profile,
2429
uint32_t * width,
2430
uint32_t * height
2431
);
2432
2433
#define VDP_BITSTREAM_BUFFER_VERSION 0
2434
2435
/**
2436
* \brief Application data buffer containing compressed video
2437
* data.
2438
*/
2439
typedef struct {
2440
/**
2441
* This field must be filled with VDP_BITSTREAM_BUFFER_VERSION
2442
*/
2443
uint32_t struct_version;
2444
/** A pointer to the bitstream data bytes */
2445
void const * bitstream;
2446
/** The number of data bytes */
2447
uint32_t bitstream_bytes;
2448
} VdpBitstreamBuffer;
2449
2450
/**
2451
* \brief A generic "picture information" pointer type.
2452
*
2453
* This type serves solely to document the expected usage of a
2454
* generic (void *) function parameter. In actual usage, the
2455
* application is expected to physically provide a pointer to an
2456
* instance of one of the "real" VdpPictureInfo* structures,
2457
* picking the type appropriate for the decoder object in
2458
* question.
2459
*/
2460
typedef void * VdpPictureInfo;
2461
2462
/**
2463
* \brief Picture parameter information for an MPEG 1 or MPEG 2
2464
* picture.
2465
*
2466
* Note: References to "copy of bitstream field" in the field descriptions
2467
* may refer to data literally parsed from the bitstream, or derived from
2468
* the bitstream using a mechanism described in the specification.
2469
*/
2470
typedef struct {
2471
/**
2472
* Reference used by B and P frames.
2473
* Set to VDP_INVALID_HANDLE when not used.
2474
*/
2475
VdpVideoSurface forward_reference;
2476
/**
2477
* Reference used by B frames.
2478
* Set to VDP_INVALID_HANDLE when not used.
2479
*/
2480
VdpVideoSurface backward_reference;
2481
/** Number of slices in the bitstream provided. */
2482
uint32_t slice_count;
2483
2484
/** Copy of the MPEG bitstream field. */
2485
uint8_t picture_structure;
2486
/** Copy of the MPEG bitstream field. */
2487
uint8_t picture_coding_type;
2488
/** Copy of the MPEG bitstream field. */
2489
uint8_t intra_dc_precision;
2490
/** Copy of the MPEG bitstream field. */
2491
uint8_t frame_pred_frame_dct;
2492
/** Copy of the MPEG bitstream field. */
2493
uint8_t concealment_motion_vectors;
2494
/** Copy of the MPEG bitstream field. */
2495
uint8_t intra_vlc_format;
2496
/** Copy of the MPEG bitstream field. */
2497
uint8_t alternate_scan;
2498
/** Copy of the MPEG bitstream field. */
2499
uint8_t q_scale_type;
2500
/** Copy of the MPEG bitstream field. */
2501
uint8_t top_field_first;
2502
/** Copy of the MPEG-1 bitstream field. For MPEG-2, set to 0. */
2503
uint8_t full_pel_forward_vector;
2504
/** Copy of the MPEG-1 bitstream field. For MPEG-2, set to 0. */
2505
uint8_t full_pel_backward_vector;
2506
/**
2507
* Copy of the MPEG bitstream field.
2508
* For MPEG-1, fill both horizontal and vertical entries.
2509
*/
2510
uint8_t f_code[2][2];
2511
/** Copy of the MPEG bitstream field, converted to raster order. */
2512
uint8_t intra_quantizer_matrix[64];
2513
/** Copy of the MPEG bitstream field, converted to raster order. */
2514
uint8_t non_intra_quantizer_matrix[64];
2515
} VdpPictureInfoMPEG1Or2;
2516
2517
/**
2518
* \brief Information about an H.264 reference frame
2519
*
2520
* Note: References to "copy of bitstream field" in the field descriptions
2521
* may refer to data literally parsed from the bitstream, or derived from
2522
* the bitstream using a mechanism described in the specification.
2523
*/
2524
typedef struct {
2525
/**
2526
* The surface that contains the reference image.
2527
* Set to VDP_INVALID_HANDLE for unused entries.
2528
*/
2529
VdpVideoSurface surface;
2530
/** Is this a long term reference (else short term). */
2531
VdpBool is_long_term;
2532
/**
2533
* Is the top field used as a reference.
2534
* Set to VDP_FALSE for unused entries.
2535
*/
2536
VdpBool top_is_reference;
2537
/**
2538
* Is the bottom field used as a reference.
2539
* Set to VDP_FALSE for unused entries.
2540
*/
2541
VdpBool bottom_is_reference;
2542
/** [0]: top, [1]: bottom */
2543
int32_t field_order_cnt[2];
2544
/**
2545
* Copy of the H.264 bitstream field:
2546
* frame_num from slice_header for short-term references,
2547
* LongTermPicNum from decoding algorithm for long-term references.
2548
*/
2549
uint16_t frame_idx;
2550
} VdpReferenceFrameH264;
2551
2552
/**
2553
* \brief Picture parameter information for an H.264 picture.
2554
*
2555
* Note: The \ref referenceFrames array must contain the "DPB" as
2556
* defined by the H.264 specification. In particular, once a
2557
* reference frame has been decoded to a surface, that surface must
2558
* continue to appear in the DPB until no longer required to predict
2559
* any future frame. Once a surface is removed from the DPB, it can
2560
* no longer be used as a reference, unless decoded again.
2561
*
2562
* Also note that only surfaces previously generated using \ref
2563
* VdpDecoderRender may be used as reference frames. In particular,
2564
* surfaces filled using any "put bits" API will not work.
2565
*
2566
* Note: References to "copy of bitstream field" in the field descriptions
2567
* may refer to data literally parsed from the bitstream, or derived from
2568
* the bitstream using a mechanism described in the specification.
2569
*/
2570
typedef struct {
2571
/** Number of slices in the bitstream provided. */
2572
uint32_t slice_count;
2573
/** [0]: top, [1]: bottom */
2574
int32_t field_order_cnt[2];
2575
/** Will the decoded frame be used as a reference later. */
2576
VdpBool is_reference;
2577
2578
/** Copy of the H.264 bitstream field. */
2579
uint16_t frame_num;
2580
/** Copy of the H.264 bitstream field. */
2581
uint8_t field_pic_flag;
2582
/** Copy of the H.264 bitstream field. */
2583
uint8_t bottom_field_flag;
2584
/** Copy of the H.264 bitstream field. */
2585
uint8_t num_ref_frames;
2586
/** Copy of the H.264 bitstream field. */
2587
uint8_t mb_adaptive_frame_field_flag;
2588
/** Copy of the H.264 bitstream field. */
2589
uint8_t constrained_intra_pred_flag;
2590
/** Copy of the H.264 bitstream field. */
2591
uint8_t weighted_pred_flag;
2592
/** Copy of the H.264 bitstream field. */
2593
uint8_t weighted_bipred_idc;
2594
/** Copy of the H.264 bitstream field. */
2595
uint8_t frame_mbs_only_flag;
2596
/** Copy of the H.264 bitstream field. */
2597
uint8_t transform_8x8_mode_flag;
2598
/** Copy of the H.264 bitstream field. */
2599
int8_t chroma_qp_index_offset;
2600
/** Copy of the H.264 bitstream field. */
2601
int8_t second_chroma_qp_index_offset;
2602
/** Copy of the H.264 bitstream field. */
2603
int8_t pic_init_qp_minus26;
2604
/** Copy of the H.264 bitstream field. */
2605
uint8_t num_ref_idx_l0_active_minus1;
2606
/** Copy of the H.264 bitstream field. */
2607
uint8_t num_ref_idx_l1_active_minus1;
2608
/** Copy of the H.264 bitstream field. */
2609
uint8_t log2_max_frame_num_minus4;
2610
/** Copy of the H.264 bitstream field. */
2611
uint8_t pic_order_cnt_type;
2612
/** Copy of the H.264 bitstream field. */
2613
uint8_t log2_max_pic_order_cnt_lsb_minus4;
2614
/** Copy of the H.264 bitstream field. */
2615
uint8_t delta_pic_order_always_zero_flag;
2616
/** Copy of the H.264 bitstream field. */
2617
uint8_t direct_8x8_inference_flag;
2618
/** Copy of the H.264 bitstream field. */
2619
uint8_t entropy_coding_mode_flag;
2620
/** Copy of the H.264 bitstream field. */
2621
uint8_t pic_order_present_flag;
2622
/** Copy of the H.264 bitstream field. */
2623
uint8_t deblocking_filter_control_present_flag;
2624
/** Copy of the H.264 bitstream field. */
2625
uint8_t redundant_pic_cnt_present_flag;
2626
2627
/** Copy of the H.264 bitstream field, converted to raster order. */
2628
uint8_t scaling_lists_4x4[6][16];
2629
/** Copy of the H.264 bitstream field, converted to raster order. */
2630
uint8_t scaling_lists_8x8[2][64];
2631
2632
/** See \ref VdpPictureInfoH264 for instructions regarding this field. */
2633
VdpReferenceFrameH264 referenceFrames[16];
2634
} VdpPictureInfoH264;
2635
2636
/**
2637
* \brief Picture parameter information for a VC1 picture.
2638
*
2639
* Note: References to "copy of bitstream field" in the field descriptions
2640
* may refer to data literally parsed from the bitstream, or derived from
2641
* the bitstream using a mechanism described in the specification.
2642
*/
2643
typedef struct {
2644
/**
2645
* Reference used by B and P frames.
2646
* Set to VDP_INVALID_HANDLE when not used.
2647
*/
2648
VdpVideoSurface forward_reference;
2649
/**
2650
* Reference used by B frames.
2651
* Set to VDP_INVALID_HANDLE when not used.
2652
*/
2653
VdpVideoSurface backward_reference;
2654
2655
/** Number of slices in the bitstream provided. */
2656
uint32_t slice_count;
2657
/** I=0, P=1, B=3, BI=4 from 7.1.1.4. */
2658
uint8_t picture_type;
2659
/** Progressive=0, Frame-interlace=2, Field-interlace=3; see VC-1 7.1.1.15. */
2660
uint8_t frame_coding_mode;
2661
2662
/** Copy of the VC-1 bitstream field. See VC-1 6.1.5. */
2663
uint8_t postprocflag;
2664
/** Copy of the VC-1 bitstream field. See VC-1 6.1.8. */
2665
uint8_t pulldown;
2666
/** Copy of the VC-1 bitstream field. See VC-1 6.1.9. */
2667
uint8_t interlace;
2668
/** Copy of the VC-1 bitstream field. See VC-1 6.1.10. */
2669
uint8_t tfcntrflag;
2670
/** Copy of the VC-1 bitstream field. See VC-1 6.1.11. */
2671
uint8_t finterpflag;
2672
/** Copy of the VC-1 bitstream field. See VC-1 6.1.3. */
2673
uint8_t psf;
2674
/** Copy of the VC-1 bitstream field. See VC-1 6.2.8. */
2675
uint8_t dquant;
2676
/** Copy of the VC-1 bitstream field. See VC-1 6.2.3. */
2677
uint8_t panscan_flag;
2678
/** Copy of the VC-1 bitstream field. See VC-1 6.2.4. */
2679
uint8_t refdist_flag;
2680
/** Copy of the VC-1 bitstream field. See VC-1 6.2.11. */
2681
uint8_t quantizer;
2682
/** Copy of the VC-1 bitstream field. See VC-1 6.2.7. */
2683
uint8_t extended_mv;
2684
/** Copy of the VC-1 bitstream field. See VC-1 6.2.14. */
2685
uint8_t extended_dmv;
2686
/** Copy of the VC-1 bitstream field. See VC-1 6.2.10. */
2687
uint8_t overlap;
2688
/** Copy of the VC-1 bitstream field. See VC-1 6.2.9. */
2689
uint8_t vstransform;
2690
/** Copy of the VC-1 bitstream field. See VC-1 6.2.5. */
2691
uint8_t loopfilter;
2692
/** Copy of the VC-1 bitstream field. See VC-1 6.2.6. */
2693
uint8_t fastuvmc;
2694
/** Copy of the VC-1 bitstream field. See VC-1 6.12.15. */
2695
uint8_t range_mapy_flag;
2696
/** Copy of the VC-1 bitstream field. */
2697
uint8_t range_mapy;
2698
/** Copy of the VC-1 bitstream field. See VC-1 6.2.16. */
2699
uint8_t range_mapuv_flag;
2700
/** Copy of the VC-1 bitstream field. */
2701
uint8_t range_mapuv;
2702
2703
/**
2704
* Copy of the VC-1 bitstream field. See VC-1 J.1.10.
2705
* Only used by simple and main profiles.
2706
*/
2707
uint8_t multires;
2708
/**
2709
* Copy of the VC-1 bitstream field. See VC-1 J.1.16.
2710
* Only used by simple and main profiles.
2711
*/
2712
uint8_t syncmarker;
2713
/**
2714
* VC-1 SP/MP range reduction control.
2715
* Only used by simple and main profiles.
2716
* Bit 0: Copy of rangered VC-1 bitstream field; See VC-1 J.1.17.
2717
* Bit 1: Copy of rangeredfrm VC-1 bitstream fiels; See VC-1 7.1.13.
2718
*/
2719
uint8_t rangered;
2720
/**
2721
* Copy of the VC-1 bitstream field. See VC-1 J.1.17.
2722
* Only used by simple and main profiles.
2723
*/
2724
uint8_t maxbframes;
2725
2726
/**
2727
* Out-of-loop deblocking enable.
2728
* Bit 0 of POSTPROC from VC-1 7.1.1.27
2729
* Note that bit 1 of POSTPROC (dering enable) should not be included.
2730
*/
2731
uint8_t deblockEnable;
2732
/**
2733
* Parameter used by VC-1 Annex H deblocking algorithm. Note that VDPAU
2734
* implementations may choose which deblocking algorithm to use.
2735
* See VC-1 7.1.1.6
2736
*/
2737
uint8_t pquant;
2738
} VdpPictureInfoVC1;
2739
2740
/**
2741
* \brief Decode a compressed field/frame and render the result
2742
* into a \ref VdpVideoSurface "VdpVideoSurface".
2743
* \param[in] decoder The decoder object that will perform the
2744
* decode operation.
2745
* \param[in] target The video surface to render to.
2746
* \param[in] picture_info A (pointer to a) structure containing
2747
* information about the picture to be decoded. Note that
2748
* the appropriate type of VdpPictureInfo* structure must
2749
* be provided to match to profile that the decoder was
2750
* created for.
2751
* \param[in] bitstream_buffer_count The number of bitstream
2752
* buffers containing compressed data for this picture.
2753
* \param[in] bitstream_buffers An array of bitstream buffers.
2754
* \return VdpStatus The completion status of the operation.
2755
*
2756
* See \ref video_mixer_usage for additional information.
2757
*/
2758
typedef VdpStatus VdpDecoderRender(
2759
VdpDecoder decoder,
2760
VdpVideoSurface target,
2761
VdpPictureInfo const * picture_info,
2762
uint32_t bitstream_buffer_count,
2763
VdpBitstreamBuffer const * bitstream_buffers
2764
);
2765
2766
/*@}*/
2767
2768
/**
2769
* \defgroup VdpVideoMixer VdpVideoMixer; Video Post-processing \
2770
* and Compositing object
2771
*
2772
* VdpVideoMixer can perform some subset of the following
2773
* post-processing steps on video:
2774
* - De-interlacing
2775
* - Various types, with or without inverse telecine
2776
* - Noise-reduction
2777
* - Sharpness adjustment
2778
* - Color space conversion to RGB
2779
* - Chroma format upscaling to 4:4:4
2780
*
2781
* A VdpVideoMixer takes a source \ref VdpVideoSurface
2782
* "VdpVideoSurface" VdpVideoSurface and performs various video
2783
* processing steps on it (potentially using information from
2784
* past or future video surfaces). It scales the video and
2785
* converts it to RGB, then optionally composites it with
2786
* multiple auxiliary \ref VdpOutputSurface "VdpOutputSurface"s
2787
* before writing the result to the destination \ref
2788
* VdpOutputSurface "VdpOutputSurface".
2789
*
2790
* The video mixer compositing model is as follows:
2791
*
2792
* - A rectangle will be rendered on an output surface. No
2793
* pixels will be rendered outside of this output rectangle.
2794
* The contents of this rectangle will be a composite of many
2795
* layers.
2796
*
2797
* - The first layer is the background color. The background
2798
* color will fill the entire rectangle.
2799
*
2800
* - The second layer is the processed video which has been
2801
* converted to RGB. These pixels will overwrite the
2802
* background color of the first layer except where the second
2803
* layer's rectangle does not completely cover the output
2804
* rectangle. In those regions the background color will
2805
* continue to show. If any portion of the second layer's
2806
* output rectangle is outside of the output rectangle, those
2807
* portions will be clipped.
2808
*
2809
* - The third layer contains some number of auxiliary layers
2810
* (in the form of \ref VdpOutputSurface "VdpOutputSurface"s)
2811
* which will be composited using the alpha value from the
2812
* those surfaces. The compositing operations are equivalent
2813
* to rendering with \ref VdpOutputSurfaceRenderOutputSurface
2814
* using a source blend factor of SOURCE_ALPHA, a destination
2815
* blend factor of ONE_MINUS_SOURCE_ALPHA and an equation of
2816
* ADD.
2817
*
2818
* @{
2819
*/
2820
2821
/**
2822
* \brief A VdpVideoMixer feature that must be requested at
2823
* creation time to be used.
2824
*
2825
* Certain advanced VdpVideoMixer features are optional, and the
2826
* ability to use those features at all must be requested when
2827
* the VdpVideoMixer object is created. Each feature is named via
2828
* a specific VdpVideoMixerFeature value.
2829
*
2830
* Once requested, these features are permanently available
2831
* within that specific VdpVideoMixer object. All features that
2832
* are not explicitly requested at creation time default to
2833
* being permanently unavailable.
2834
*
2835
* Even when requested, all features default to being initially
2836
* disabled. However, applications can subsequently enable and
2837
* disable features at any time. See \ref
2838
* VdpVideoMixerSetFeatureEnables.
2839
*
2840
* Some features allow configuration of their operation. Each
2841
* configurable item is an \ref VdpVideoMixerAttribute. These
2842
* attributes may be manipulated at any time using \ref
2843
* VdpVideoMixerSetAttributeValues.
2844
*/
2845
typedef uint32_t VdpVideoMixerFeature;
2846
2847
/**
2848
* \hideinitializer
2849
* \brief A VdpVideoMixerFeature.
2850
*
2851
* When requested and enabled, motion adaptive temporal
2852
* deinterlacing will be used on interlaced content.
2853
*
2854
* When multiple de-interlacing options are requested and
2855
* enabled, the back-end implementation chooses the best
2856
* algorithm to apply.
2857
*/
2858
#define VDP_VIDEO_MIXER_FEATURE_DEINTERLACE_TEMPORAL (VdpVideoMixerFeature)0
2859
/**
2860
* \hideinitializer
2861
* \brief A VdpVideoMixerFeature.
2862
*
2863
* When requested and enabled, this enables a more advanced
2864
* version of temporal de-interlacing, that additionally uses
2865
* edge-guided spatial interpolation.
2866
*
2867
* When multiple de-interlacing options are requested and
2868
* enabled, the back-end implementation chooses the best
2869
* algorithm to apply.
2870
*/
2871
#define VDP_VIDEO_MIXER_FEATURE_DEINTERLACE_TEMPORAL_SPATIAL (VdpVideoMixerFeature)1
2872
/**
2873
* \hideinitializer
2874
* \brief A VdpVideoMixerFeature.
2875
*
2876
* When requested and enabled, cadence detection will be enabled
2877
* on interlaced content and the video mixer will try to extract
2878
* progressive frames from pull-down material.
2879
*/
2880
#define VDP_VIDEO_MIXER_FEATURE_INVERSE_TELECINE (VdpVideoMixerFeature)2
2881
/**
2882
* \hideinitializer
2883
* \brief A VdpVideoMixerFeature.
2884
*
2885
* When requested and enabled, a noise reduction algorithm will
2886
* be applied to the video.
2887
*/
2888
#define VDP_VIDEO_MIXER_FEATURE_NOISE_REDUCTION (VdpVideoMixerFeature)3
2889
/**
2890
* \hideinitializer
2891
* \brief A VdpVideoMixerFeature.
2892
*
2893
* When requested and enabled, a sharpening algorithm will be
2894
* applied to the video.
2895
*/
2896
#define VDP_VIDEO_MIXER_FEATURE_SHARPNESS (VdpVideoMixerFeature)4
2897
/**
2898
* \hideinitializer
2899
* \brief A VdpVideoMixerFeature.
2900
*
2901
* When requested and enabled, the alpha of the rendered
2902
* surface, which is normally set to the alpha of the background
2903
* color, will be forced to 0.0 on pixels corresponding to
2904
* source video surface luminance values in the range specified
2905
* by attributes \ref VDP_VIDEO_MIXER_ATTRIBUTE_LUMA_KEY_MIN_LUMA
2906
* to \ref VDP_VIDEO_MIXER_ATTRIBUTE_LUMA_KEY_MAX_LUMA. This
2907
* keying is performed after scaling and de-interlacing.
2908
*/
2909
#define VDP_VIDEO_MIXER_FEATURE_LUMA_KEY (VdpVideoMixerFeature)5
2910
2911
/**
2912
* \brief A VdpVideoMixer creation parameter.
2913
*
2914
* When a VdpVideoMixer is created, certain parameters may be
2915
* supplied. Each parameter is named via a specific
2916
* VdpVideoMixerParameter value.
2917
*
2918
* Each parameter has a specific type, and specific default
2919
* value if not specified at VdpVideoMixer creation time. The
2920
* application may query the legal supported range for some
2921
* parameters.
2922
*/
2923
typedef uint32_t VdpVideoMixerParameter;
2924
2925
/**
2926
* \hideinitializer
2927
* \brief The exact width of input video surfaces.
2928
*
2929
* This parameter's type is uint32_t.
2930
*
2931
* This parameter defaults to 0 if not specified, which entails
2932
* that it must be specified.
2933
*
2934
* The application may query this parameter's supported
2935
* range.
2936
*/
2937
#define VDP_VIDEO_MIXER_PARAMETER_VIDEO_SURFACE_WIDTH (VdpVideoMixerParameter)0
2938
/**
2939
* \hideinitializer
2940
* \brief The exact height of input video surfaces.
2941
*
2942
* This parameter's type is uint32_t.
2943
*
2944
* This parameter defaults to 0 if not specified, which entails
2945
* that it must be specified.
2946
*
2947
* The application may query this parameter's supported
2948
* range.
2949
*/
2950
#define VDP_VIDEO_MIXER_PARAMETER_VIDEO_SURFACE_HEIGHT (VdpVideoMixerParameter)1
2951
/**
2952
* \hideinitializer
2953
* \brief The chroma type of the input video surfaces the will
2954
* process.
2955
*
2956
* This parameter's type is VdpChromaType.
2957
*
2958
* If not specified, this parameter defaults to
2959
* VDP_CHROMA_TYPE_420.
2960
*
2961
* The application may not query this application's supported
2962
* range, since it is a potentially disjoint enumeration.
2963
*/
2964
#define VDP_VIDEO_MIXER_PARAMETER_CHROMA_TYPE (VdpVideoMixerParameter)2
2965
/**
2966
* \hideinitializer
2967
* \brief The number of auxiliary layers in the mixer's
2968
* compositing model.
2969
*
2970
* Note that this indicates the maximum number of layers that
2971
* may be processed by a given \ref VdpVideoMixer "VdpVideoMixer"
2972
* object. Each individual \ref VdpVideoMixerRender invocation
2973
* may choose to use a different number of actual layers, from 0
2974
* up to this limit.
2975
*
2976
* This attribute's type is uint32_t.
2977
*
2978
* If not specified, this parameter defaults to 0.
2979
*
2980
* The application may query this parameter's supported
2981
* range.
2982
*/
2983
#define VDP_VIDEO_MIXER_PARAMETER_LAYERS (VdpVideoMixerParameter)3
2984
2985
/**
2986
* \brief An adjustable attribute of VdpVideoMixer operation.
2987
*
2988
* Various attributes of VdpVideoMixer operation may be adjusted
2989
* at any time. Each attribute is named via a specific
2990
* VdpVideoMixerAttribute value.
2991
*
2992
* Each attribute has a specific type, and specific default
2993
* value if not specified at VdpVideoMixer creation time. The
2994
* application may query the legal supported range for some
2995
* attributes.
2996
*/
2997
typedef uint32_t VdpVideoMixerAttribute;
2998
2999
/**
3000
* \hideinitializer
3001
* \brief The background color in the VdpVideoMixer's compositing
3002
* model.
3003
*
3004
* This attribute's type is VdpColor.
3005
*
3006
* This parameter defaults to black (all color components 0.0
3007
* and alpha 1.0).
3008
*
3009
* The application may not query this parameter's supported
3010
* range, since the type is not scalar.
3011
*/
3012
#define VDP_VIDEO_MIXER_ATTRIBUTE_BACKGROUND_COLOR (VdpVideoMixerAttribute)0
3013
/**
3014
* \hideinitializer
3015
* \brief The color-space conversion matrix used by the
3016
* VdpVideoMixer.
3017
*
3018
* This attribute's type is \ref VdpCSCMatrix.
3019
*
3020
* Note: When using \ref VdpVideoMixerGetAttributeValues to retrieve the
3021
* current CSC matrix, the attribute_values array must contain a pointer to
3022
* a pointer a VdpCSCMatrix (VdpCSCMatrix** as a void *). The get function will
3023
* either initialize the referenced CSC matrix to the current value, *or*
3024
* clear the supplied pointer to NULL, if the previous set call supplied a
3025
* value of NULL in parameter_values, to request the default matrix.
3026
*
3027
* \code
3028
* VdpCSCMatrix matrix;
3029
* VdpCSCMatrix * matrix_ptr;
3030
* void * attribute_values[] = {&matrix_ptr};
3031
* VdpStatus st = vdp_video_mixer_get_attribute_values(..., attribute_values, ...);
3032
* \endcode
3033
*
3034
* This parameter defaults to a matrix suitable for ITU-R BT.601
3035
* input surfaces, with no procamp adjustments.
3036
*
3037
* The application may not query this parameter's supported
3038
* range, since the type is not scalar.
3039
*/
3040
#define VDP_VIDEO_MIXER_ATTRIBUTE_CSC_MATRIX (VdpVideoMixerAttribute)1
3041
/**
3042
* \hideinitializer
3043
* \brief The amount of noise reduction algorithm to apply.
3044
*
3045
* This attribute's type is float.
3046
*
3047
* This parameter defaults to 0.0, which equates to no noise
3048
* reduction.
3049
*
3050
* The application may query this parameter's supported range.
3051
* However, the range is fixed as 0.0...1.0.
3052
*/
3053
#define VDP_VIDEO_MIXER_ATTRIBUTE_NOISE_REDUCTION_LEVEL (VdpVideoMixerAttribute)2
3054
/**
3055
* \hideinitializer
3056
* \brief The amount of sharpening, or blurring, to apply.
3057
*
3058
* This attribute's type is float.
3059
*
3060
* This parameter defaults to 0.0, which equates to no
3061
* sharpening.
3062
*
3063
* Positive values request sharpening. Negative values request
3064
* blurring.
3065
*
3066
* The application may query this parameter's supported range.
3067
* However, the range is fixed as -1.0...1.0.
3068
*/
3069
#define VDP_VIDEO_MIXER_ATTRIBUTE_SHARPNESS_LEVEL (VdpVideoMixerAttribute)3
3070
/**
3071
* \hideinitializer
3072
* \brief The minimum luma value for the luma key algorithm.
3073
*
3074
* This attribute's type is float.
3075
*
3076
* This parameter defaults to 0.0.
3077
*
3078
* The application may query this parameter's supported range.
3079
* However, the range is fixed as 0.0...1.0.
3080
*/
3081
#define VDP_VIDEO_MIXER_ATTRIBUTE_LUMA_KEY_MIN_LUMA (VdpVideoMixerAttribute)4
3082
/**
3083
* \hideinitializer
3084
* \brief The maximum luma value for the luma key algorithm.
3085
*
3086
* This attribute's type is float.
3087
*
3088
* This parameter defaults to 1.0.
3089
*
3090
* The application may query this parameter's supported range.
3091
* However, the range is fixed as 0.0...1.0.
3092
*/
3093
#define VDP_VIDEO_MIXER_ATTRIBUTE_LUMA_KEY_MAX_LUMA (VdpVideoMixerAttribute)5
3094
/**
3095
* \hideinitializer
3096
* \brief Whether de-interlacers should operate solely on luma, and bob chroma.
3097
*
3098
* Note: This attribute only affects advanced de-interlacing algorithms, not
3099
* bob or weave.
3100
*
3101
* This attribute's type is uint8_t.
3102
*
3103
* This parameter defaults to 0.
3104
*
3105
* The application may query this parameter's supported range.
3106
* However, the range is fixed as 0 (no/off) ... 1 (yes/on).
3107
*/
3108
#define VDP_VIDEO_MIXER_ATTRIBUTE_SKIP_CHROMA_DEINTERLACE (VdpVideoMixerAttribute)6
3109
3110
/**
3111
* \brief Query the implementation's support for a specific
3112
* feature.
3113
* \param[in] device The device to query.
3114
* \param[in] feature The feature for which support is to be
3115
* queried.
3116
* \param[out] is_supported Is the specified feature supported?
3117
* \return VdpStatus The completion status of the operation.
3118
*/
3119
typedef VdpStatus VdpVideoMixerQueryFeatureSupport(
3120
VdpDevice device,
3121
VdpVideoMixerFeature feature,
3122
/* output parameters follow */
3123
VdpBool * is_supported
3124
);
3125
3126
/**
3127
* \brief Query the implementation's support for a specific
3128
* parameter.
3129
* \param[in] device The device to query.
3130
* \param[in] parameter The parameter for which support is to be
3131
* queried.
3132
* \param[out] is_supported Is the specified parameter
3133
* supported?
3134
* \return VdpStatus The completion status of the operation.
3135
*/
3136
typedef VdpStatus VdpVideoMixerQueryParameterSupport(
3137
VdpDevice device,
3138
VdpVideoMixerParameter parameter,
3139
/* output parameters follow */
3140
VdpBool * is_supported
3141
);
3142
3143
/**
3144
* \brief Query the implementation's support for a specific
3145
* attribute.
3146
* \param[in] device The device to query.
3147
* \param[in] feature The feature for which support is to be
3148
* queried.
3149
* \param[out] is_supported Is the specified feature supported?
3150
* \return VdpStatus The completion status of the operation.
3151
*/
3152
typedef VdpStatus VdpVideoMixerQueryAttributeSupport(
3153
VdpDevice device,
3154
VdpVideoMixerAttribute attribute,
3155
/* output parameters follow */
3156
VdpBool * is_supported
3157
);
3158
3159
/**
3160
* \brief Query the implementation's supported for a specific
3161
* parameter.
3162
* \param[in] device The device to query.
3163
* \param[in] parameter The parameter for which support is to be
3164
* queried.
3165
* \param[out] min_value The minimum supported value.
3166
* \param[out] max_value The maximum supported value.
3167
* \return VdpStatus The completion status of the operation.
3168
*/
3169
typedef VdpStatus VdpVideoMixerQueryParameterValueRange(
3170
VdpDevice device,
3171
VdpVideoMixerParameter parameter,
3172
/* output parameters follow */
3173
void * min_value,
3174
void * max_value
3175
);
3176
3177
/**
3178
* \brief Query the implementation's supported for a specific
3179
* attribute.
3180
* \param[in] device The device to query.
3181
* \param[in] attribute The attribute for which support is to be
3182
* queried.
3183
* \param[out] min_value The minimum supported value.
3184
* \param[out] max_value The maximum supported value.
3185
* \return VdpStatus The completion status of the operation.
3186
*/
3187
typedef VdpStatus VdpVideoMixerQueryAttributeValueRange(
3188
VdpDevice device,
3189
VdpVideoMixerAttribute attribute,
3190
/* output parameters follow */
3191
void * min_value,
3192
void * max_value
3193
);
3194
3195
/**
3196
* \brief An opaque handle representing a VdpVideoMixer object.
3197
*/
3198
typedef uint32_t VdpVideoMixer;
3199
3200
/**
3201
* \brief Create a VdpVideoMixer.
3202
* \param[in] device The device that will contain the mixer.
3203
* \param[in] feature_count The number of features to request.
3204
* \param[in] features The list of features to request.
3205
* \param[in] parameter_count The number of parameters to set.
3206
* \param[in] parameters The list of parameters to set.
3207
* \param[in] parameter_values The values for the parameters. Note that each
3208
* entry in the value array is a pointer to the actual value. In other
3209
* words, the values themselves are not cast to "void *" and passed
3210
* "inside" the array.
3211
* \param[out] mixer The new mixer's handle.
3212
* \return VdpStatus The completion status of the operation.
3213
*
3214
* Initially, all requested features will be disabled. They can
3215
* be enabled using \ref VdpVideoMixerSetFeatureEnables.
3216
*
3217
* Initially, all attributes will have default values. Values
3218
* can be changed using \ref VdpVideoMixerSetAttributeValues.
3219
*/
3220
typedef VdpStatus VdpVideoMixerCreate(
3221
VdpDevice device,
3222
// The set of features to request
3223
uint32_t feature_count,
3224
VdpVideoMixerFeature const * features,
3225
// The parameters used during creation
3226
uint32_t parameter_count,
3227
VdpVideoMixerParameter const * parameters,
3228
void const * const * parameter_values,
3229
/* output parameters follow */
3230
VdpVideoMixer * mixer
3231
);
3232
3233
/**
3234
* \brief Enable or disable features.
3235
* \param[in] mixer The mixer to manipulate.
3236
* \param[in] feature_count The number of features to
3237
* enable/disable.
3238
* \param[in] features The list of features to enable/disable.
3239
* \param[in] feature_enables The list of new feature enable
3240
* values.
3241
* \return VdpStatus The completion status of the operation.
3242
*/
3243
typedef VdpStatus VdpVideoMixerSetFeatureEnables(
3244
VdpVideoMixer mixer,
3245
uint32_t feature_count,
3246
VdpVideoMixerFeature const * features,
3247
VdpBool const * feature_enables
3248
);
3249
3250
/**
3251
* \brief Set attribute values
3252
* \param[in] mixer The mixer to manipulate.
3253
* \param[in] attribute_count The number of attributes to set.
3254
* \param[in] attributes The list of attributes to set.
3255
* \param[in] attribute_values The values for the attributes. Note that each
3256
* entry in the value array is a pointer to the actual value. In other
3257
* words, the values themselves are not cast to "void *" and passed
3258
* "inside" the array. A NULL pointer requests that the default value be
3259
* set for that attribute.
3260
* \return VdpStatus The completion status of the operation.
3261
*/
3262
typedef VdpStatus VdpVideoMixerSetAttributeValues(
3263
VdpVideoMixer mixer,
3264
uint32_t attribute_count,
3265
VdpVideoMixerAttribute const * attributes,
3266
void const * const * attribute_values
3267
);
3268
3269
/**
3270
* \brief Retrieve whether features were requested at creation
3271
* time.
3272
* \param[in] mixer The mixer to query.
3273
* \param[in] feature_count The number of features to query.
3274
* \param[in] features The list of features to query.
3275
* \param[out] feature_supported A list of values indicating
3276
* whether the feature was requested, and hence is
3277
* available.
3278
* \return VdpStatus The completion status of the operation.
3279
*/
3280
typedef VdpStatus VdpVideoMixerGetFeatureSupport(
3281
VdpVideoMixer mixer,
3282
uint32_t feature_count,
3283
VdpVideoMixerFeature const * features,
3284
/* output parameters follow */
3285
VdpBool * feature_supports
3286
);
3287
3288
/**
3289
* \brief Retrieve whether features are enabled.
3290
* \param[in] mixer The mixer to manipulate.
3291
* \param[in] feature_count The number of features to query.
3292
* \param[in] features The list of features to query.
3293
* \param[out] feature_enabled A list of values indicating
3294
* whether the feature is enabled.
3295
* \return VdpStatus The completion status of the operation.
3296
*/
3297
typedef VdpStatus VdpVideoMixerGetFeatureEnables(
3298
VdpVideoMixer mixer,
3299
uint32_t feature_count,
3300
VdpVideoMixerFeature const * features,
3301
/* output parameters follow */
3302
VdpBool * feature_enables
3303
);
3304
3305
/**
3306
* \brief Retrieve parameter values given at creation time.
3307
* \param[in] mixer The mixer to manipulate.
3308
* \param[in] parameter_count The number of parameters to query.
3309
* \param[in] parameters The list of parameters to query.
3310
* \param[out] parameter_values The list of current values for
3311
* the parameters. Note that each entry in the value array is a pointer to
3312
* storage that will receive the actual value. If the attribute's type is
3313
* a pointer itself, please closely read the documentation for that
3314
* attribute type for any other data passing requirements.
3315
* \return VdpStatus The completion status of the operation.
3316
*/
3317
typedef VdpStatus VdpVideoMixerGetParameterValues(
3318
VdpVideoMixer mixer,
3319
uint32_t parameter_count,
3320
VdpVideoMixerParameter const * parameters,
3321
/* output parameters follow */
3322
void * const * parameter_values
3323
);
3324
3325
/**
3326
* \brief Retrieve current attribute values.
3327
* \param[in] mixer The mixer to manipulate.
3328
* \param[in] attribute_count The number of attributes to query.
3329
* \param[in] attributes The list of attributes to query.
3330
* \param[out] attribute_values The list of current values for
3331
* the attributes. Note that each entry in the value array is a pointer to
3332
* storage that will receive the actual value. If the attribute's type is
3333
* a pointer itself, please closely read the documentation for that
3334
* attribute type for any other data passing requirements.
3335
* \return VdpStatus The completion status of the operation.
3336
*/
3337
typedef VdpStatus VdpVideoMixerGetAttributeValues(
3338
VdpVideoMixer mixer,
3339
uint32_t attribute_count,
3340
VdpVideoMixerAttribute const * attributes,
3341
/* output parameters follow */
3342
void * const * attribute_values
3343
);
3344
3345
/**
3346
* \brief Destroy a VdpVideoMixer.
3347
* \param[in] device The device to destroy.
3348
* \return VdpStatus The completion status of the operation.
3349
*/
3350
typedef VdpStatus VdpVideoMixerDestroy(
3351
VdpVideoMixer mixer
3352
);
3353
3354
/**
3355
* \hideinitializer
3356
* \brief The structure of the picture present in a \ref
3357
* VdpVideoSurface "VdpVideoSurface".
3358
*/
3359
typedef enum {
3360
/**
3361
* The picture is a field, and is the top field of the surface.
3362
*/
3363
VDP_VIDEO_MIXER_PICTURE_STRUCTURE_TOP_FIELD,
3364
/**
3365
* The picture is a field, and is the bottom field of the
3366
* surface.
3367
*/
3368
VDP_VIDEO_MIXER_PICTURE_STRUCTURE_BOTTOM_FIELD,
3369
/**
3370
* The picture is a frame, and hence is the entire surface.
3371
*/
3372
VDP_VIDEO_MIXER_PICTURE_STRUCTURE_FRAME,
3373
} VdpVideoMixerPictureStructure;
3374
3375
#define VDP_LAYER_VERSION 0
3376
3377
/**
3378
* \brief Definition of an additional \ref VdpOutputSurface
3379
* "VdpOutputSurface" layer in the composting model.
3380
*/
3381
typedef struct {
3382
/**
3383
* This field must be filled with VDP_LAYER_VERSION
3384
*/
3385
uint32_t struct_version;
3386
/**
3387
* The surface to composite from.
3388
*/
3389
VdpOutputSurface source_surface;
3390
/**
3391
* The sub-rectangle of the source surface to use. If NULL, the
3392
* entire source surface will be used.
3393
*/
3394
VdpRect const * source_rect;
3395
/**
3396
* The sub-rectangle of the destination surface to map
3397
* this layer into. This rectangle is relative to the entire
3398
* destination surface. This rectangle will be clipped by \ref
3399
* VdpVideoMixerRender's \b destination_rect. If NULL, the
3400
* destination rectangle will be sized to match the source
3401
* rectangle, and will be located at the origin.
3402
*/
3403
VdpRect const * destination_rect;
3404
} VdpLayer;
3405
3406
/**
3407
* \brief Perform a video post-processing and compositing
3408
* operation.
3409
* \param[in] mixer The mixer object that will perform the
3410
* mixing/rendering operation.
3411
* \param[in] background_surface A background image. If set to any value other
3412
* than VDP_INVALID_HANDLE, the specific surface will be used instead of
3413
* the background color as the first layer in the mixer's compositing
3414
* process.
3415
* \param[in] background_source_rect When background_surface is specified,
3416
* this parameter indicates the portion of background_surface that will
3417
* be used as the background layer. The specified region will be
3418
* extracted and scaled to match the size of destination_rect. If NULL,
3419
* the entire background_surface will be used.
3420
* \param[in] current_picture_structure The picture structure of
3421
* the field/frame to be processed. This field/frame is
3422
* presented in the \b video_surface_current parameter. If
3423
* frame, then all \b video_surface_* parameters are
3424
* assumed to be frames. If field, then all
3425
* video_surface_* parameters are assumed to be fields,
3426
* with alternating top/bottom-ness derived from
3427
* video_surface_current.
3428
* \param[in] video_surfaces_past_count The number of provided
3429
* fields/frames prior to the current picture.
3430
* \param[in] video_surfaces_past The fields/frames prior to the
3431
* current field/frame. Note that array index 0 is the
3432
* field/frame temporally nearest to the current
3433
* field/frame, with increasing array indices used for
3434
* older frames. Unavailable entries may be set to
3435
* \ref VDP_INVALID_HANDLE.
3436
* \param[in] video_surface_current The field/frame to be
3437
* processed.
3438
* \param[in] video_surfaces_future_count The number of provided
3439
* fields/frames following the current picture.
3440
* \param[in] video_surfaces_future The fields/frames that
3441
* follow the current field/frame. Note that array index 0
3442
* is the field/frame temporally nearest to the current
3443
* field/frame, with increasing array indices used for
3444
* newer frames. Unavailable entries may be set to \ref
3445
* VDP_INVALID_HANDLE.
3446
* \param[in] video_source_rect The sub-rectangle of the source
3447
* video surface to extract and process. If NULL, the
3448
* entire surface will be used.
3449
* \param[in] destination_surface
3450
* \param[in] destination_rect The sub-rectangle of the
3451
* destination surface to modify. Note that rectangle clips
3452
* all other actions.
3453
* \param[in] destination_video_rect The sub-rectangle of the
3454
* destination surface that will contain the processed
3455
* video. This rectangle is relative to the entire
3456
* destination surface. This rectangle is clipped by \b
3457
* destination_rect. If NULL, the destination rectangle
3458
* will be sized to match the source rectangle, and will
3459
* be located at the origin.
3460
* \param[in] layer_count The number of additional layers to
3461
* composite above the video.
3462
* \param[in] layers The array of additional layers to composite
3463
* above the video.
3464
* \return VdpStatus The completion status of the operation.
3465
*
3466
* For a complete discussion of how to use this API, please see
3467
* \ref video_mixer_usage.
3468
*/
3469
typedef VdpStatus VdpVideoMixerRender(
3470
VdpVideoMixer mixer,
3471
VdpOutputSurface background_surface,
3472
VdpRect const * background_source_rect,
3473
VdpVideoMixerPictureStructure current_picture_structure,
3474
uint32_t video_surface_past_count,
3475
VdpVideoSurface const * video_surface_past,
3476
VdpVideoSurface video_surface_current,
3477
uint32_t video_surface_future_count,
3478
VdpVideoSurface const * video_surface_future,
3479
VdpRect const * video_source_rect,
3480
VdpOutputSurface destination_surface,
3481
VdpRect const * destination_rect,
3482
VdpRect const * destination_video_rect,
3483
uint32_t layer_count,
3484
VdpLayer const * layers
3485
);
3486
3487
/*@}*/
3488
3489
/**
3490
* \defgroup VdpPresentationQueue VdpPresentationQueue; Video \
3491
* presentation (display) object
3492
*
3493
* The VdpPresentationQueue manages a queue of surfaces and
3494
* associated timestamps. For each surface in the queue, once
3495
* the associated timestamp is reached, the surface is displayed
3496
* to the user. This timestamp-based approach yields high
3497
* quality video delivery.
3498
*
3499
* The exact location of the displayed content is Window System
3500
* specific. For this reason, the \ref api_winsys provides an
3501
* API to create a \ref VdpPresentationQueueTarget object (e.g.
3502
* via \ref VdpPresentationQueueTargetCreateX11) which
3503
* encapsulates this information.
3504
*
3505
* Note that the presentation queue performs no scaling of
3506
* surfaces to match the display target's size, aspect ratio,
3507
* etc.
3508
*
3509
* Surfaces that are too large to fit into the display target
3510
* will be clipped. Surfaces that are too small to fill the
3511
* display target will be aligned to the top-left corner of the
3512
* display target, with the balance of the display target being
3513
* filled with a constant configurable "background" color.
3514
*
3515
* Note that the presentation queue operates in a manner that is
3516
* semantically equivalent to an overlay surface, with any
3517
* required color key painting hidden internally. However,
3518
* implementations are free to use whatever semantically
3519
* equivalent technique they wish. Note that implementations
3520
* that actually use color-keyed overlays will typically use
3521
* the "background" color as the overlay color key value, so
3522
* this color should be chosen with care.
3523
*
3524
* @{
3525
*/
3526
3527
/**
3528
* \brief The representation of a point in time.
3529
*
3530
* VdpTime timestamps are intended to be a high-precision timing
3531
* system, potentially independent from any other time domain in
3532
* the system.
3533
*
3534
* Time is represented in units of nanoseconds. The origin
3535
* (i.e. the time represented by a value of 0) is implementation
3536
* dependent.
3537
*/
3538
typedef uint64_t VdpTime;
3539
3540
/**
3541
* \brief An opaque handle representing the location where
3542
* video will be presented.
3543
*
3544
* VdpPresentationQueueTarget are created using a \ref api_winsys
3545
* specific API, such as \ref
3546
* VdpPresentationQueueTargetCreateX11.
3547
*/
3548
typedef uint32_t VdpPresentationQueueTarget;
3549
3550
/**
3551
* \brief Destroy a VdpPresentationQueueTarget.
3552
* \param[in] presentation_queue_target The target to destroy.
3553
* \return VdpStatus The completion status of the operation.
3554
*/
3555
typedef VdpStatus VdpPresentationQueueTargetDestroy(
3556
VdpPresentationQueueTarget presentation_queue_target
3557
);
3558
3559
/**
3560
* \brief An opaque handle representing a presentation queue
3561
* object.
3562
*/
3563
typedef uint32_t VdpPresentationQueue;
3564
3565
/**
3566
* \brief Create a VdpPresentationQueue.
3567
* \param[in] device The device that will contain the queue.
3568
* \param[in] presentation_queue_target The location to display
3569
* the content.
3570
* \param[out] presentation_queue The new queue's handle.
3571
* \return VdpStatus The completion status of the operation.
3572
*
3573
* Note: The initial value for the background color will be set to
3574
* an implementation-defined value.
3575
*/
3576
typedef VdpStatus VdpPresentationQueueCreate(
3577
VdpDevice device,
3578
VdpPresentationQueueTarget presentation_queue_target,
3579
/* output parameters follow */
3580
VdpPresentationQueue * presentation_queue
3581
);
3582
3583
/**
3584
* \brief Destroy a VdpPresentationQueue.
3585
* \param[in] presentation_queue The queue to destroy.
3586
* \return VdpStatus The completion status of the operation.
3587
*/
3588
typedef VdpStatus VdpPresentationQueueDestroy(
3589
VdpPresentationQueue presentation_queue
3590
);
3591
3592
/**
3593
* \brief Configure the background color setting.
3594
* \param[in] presentation_queue The queue to manipulate.
3595
* \param[in] background_color The new background color.
3596
*
3597
* Note: Implementations may choose whether to apply the
3598
* new background color value immediately, or defer it until
3599
* the next surface is presented.
3600
*/
3601
typedef VdpStatus VdpPresentationQueueSetBackgroundColor(
3602
VdpPresentationQueue presentation_queue,
3603
VdpColor * const background_color
3604
);
3605
3606
/**
3607
* \brief Retrieve the current background color setting.
3608
* \param[in] presentation_queue The queue to query.
3609
* \param[out] background_color The current background color.
3610
*/
3611
typedef VdpStatus VdpPresentationQueueGetBackgroundColor(
3612
VdpPresentationQueue presentation_queue,
3613
VdpColor * background_color
3614
);
3615
3616
/**
3617
* \brief Retrieve the presentation queue's "current" time.
3618
* \param[in] presentation_queue The queue to query.
3619
* \param[out] current_time The current time, which may
3620
* represent a point between display VSYNC events.
3621
* \return VdpStatus The completion status of the operation.
3622
*/
3623
typedef VdpStatus VdpPresentationQueueGetTime(
3624
VdpPresentationQueue presentation_queue,
3625
/* output parameters follow */
3626
VdpTime * current_time
3627
);
3628
3629
/**
3630
* \brief Enter a surface into the presentation queue.
3631
* \param[in] presentation_queue The queue to query.
3632
* \param[in] surface The surface to enter into the queue.
3633
* \param[in] clip_width If set to a non-zero value, the presentation queue
3634
* will display only clip_width pixels of the surface (anchored to the
3635
* top-left corner of the surface.
3636
* \param[in] clip_height If set to a non-zero value, the presentation queue
3637
* will display only clip_height lines of the surface (anchored to the
3638
* top-left corner of the surface.
3639
* \param[in] earliest_presentation_time The timestamp
3640
* associated with the surface. The presentation queue
3641
* will not display the surface until the presentation
3642
* queue's current time is at least this value.
3643
* \return VdpStatus The completion status of the operation.
3644
*
3645
* Applications may choose to allow resizing of the presentation queue target
3646
* (which may be e.g. a regular Window when using an X11-based
3647
* implementation).
3648
*
3649
* \b clip_width and \b clip_height may be used to limit the size of the
3650
* displayed region of a surface, in order to match the specific region that
3651
* was rendered to.
3652
*
3653
* In turn, this allows the application to allocate over-sized (e.g.
3654
* screen-sized) surfaces, but render to a region that matches the current
3655
* size of the video window.
3656
*
3657
* Using this technique, an application's response to window resizing may
3658
* simply be to render to, and display, a different region of the surface,
3659
* rather than de-/re-allocation of surfaces to match the updated window size.
3660
*/
3661
typedef VdpStatus VdpPresentationQueueDisplay(
3662
VdpPresentationQueue presentation_queue,
3663
VdpOutputSurface surface,
3664
uint32_t clip_width,
3665
uint32_t clip_height,
3666
VdpTime earliest_presentation_time
3667
);
3668
3669
/**
3670
* \brief Wait for a surface to finish being displayed.
3671
* \param[in] presentation_queue The queue to query.
3672
* \param[in] surface The surface to wait for.
3673
* \param[out] first_presentation_time The timestamp of the
3674
* VSYNC at which this surface was first displayed. Note
3675
* that 0 means the surface was never displayed.
3676
* \return VdpStatus The completion status of the operation.
3677
*
3678
* Note that this API will block indefinitely if queried about
3679
* the surface most recently added to a presentation queue,
3680
* since there is no other surface that could possibly replace
3681
* the queried surface.
3682
*/
3683
typedef VdpStatus VdpPresentationQueueBlockUntilSurfaceIdle(
3684
VdpPresentationQueue presentation_queue,
3685
VdpOutputSurface surface,
3686
/* output parameters follow */
3687
VdpTime * first_presentation_time
3688
);
3689
3690
/**
3691
* \hideinitializer
3692
* \brief The status of a surface within a presentation queue.
3693
*/
3694
typedef enum {
3695
/** The surface is no queued or currently visible. */
3696
VDP_PRESENTATION_QUEUE_STATUS_IDLE,
3697
/** The surface is in the queue, and not currently visible. */
3698
VDP_PRESENTATION_QUEUE_STATUS_QUEUED,
3699
/** The surface is the currently visible surface. */
3700
VDP_PRESENTATION_QUEUE_STATUS_VISIBLE,
3701
} VdpPresentationQueueStatus;
3702
3703
/**
3704
* \brief Poll the current queue status of a surface.
3705
* \param[in] presentation_queue The queue to query.
3706
* \param[in] surface The surface to query.
3707
* \param[out] status The current status of the surface within
3708
* the queue.
3709
* \param[out] first_presentation_time The timestamp of the
3710
* VSYNC at which this surface was first displayed. Note
3711
* that 0 means the surface was never displayed.
3712
* \return VdpStatus The completion status of the operation.
3713
*/
3714
typedef VdpStatus VdpPresentationQueueQuerySurfaceStatus(
3715
VdpPresentationQueue presentation_queue,
3716
VdpOutputSurface surface,
3717
/* output parameters follow */
3718
VdpPresentationQueueStatus * status,
3719
VdpTime * first_presentation_time
3720
);
3721
3722
/*@}*/
3723
3724
/**
3725
* \defgroup display_preemption Display Preemption
3726
*
3727
* The Window System may operate within a frame-work (such as
3728
* Linux's VT switching) where the display is shared between the
3729
* Window System (e.g. X) and some other output mechanism (e.g.
3730
* the VT.) Given this scenario, the Window System's control of
3731
* the display could be preempted, and restored, at any time.
3732
*
3733
* VDPAU does not mandate that implementations hide such
3734
* preemptions from VDPAU client applications; doing so may
3735
* impose extreme burdens upon VDPAU implementations. Equally,
3736
* however, implementations are free to hide such preemptions
3737
* from client applications.
3738
*
3739
* VDPAU allows implementations to inform the client application
3740
* when such a preemption has occurred, and then refuse to
3741
* continue further operation.
3742
*
3743
* Similarly, some form of fatal hardware error could prevent further
3744
* operation of the VDPAU implementation, without a complete
3745
* re-initialization.
3746
*
3747
* The following discusses the behavior of implementations that
3748
* choose not to hide preemption from client applications.
3749
*
3750
* When preemption occurs, VDPAU internally destroys all
3751
* objects; the client application need not do this. However, if
3752
* the client application wishes to continue operation, it must
3753
* recreate all objects that it uses. It is probable that this
3754
* recreation will not succeed until the display ownership is
3755
* restored to the Window System.
3756
*
3757
* Once preemption has occurred, all VDPAU entry points will
3758
* return the specific error code \ref
3759
* VDP_STATUS_DISPLAY_PREEMPTED.
3760
*
3761
* VDPAU client applications may also be notified of such
3762
* preemptions and fatal errors via a callback. See \ref
3763
* VdpPreemptionCallbackRegister for more details.
3764
*
3765
* @{
3766
*/
3767
3768
/**
3769
* \brief A callback to notify the client application that a
3770
* device's display has been preempted.
3771
* \param[in] device The device that had its display preempted.
3772
* \param[in] context The client-supplied callback context
3773
* information.
3774
* \return void No return value
3775
*/
3776
typedef void VdpPreemptionCallback(
3777
VdpDevice device,
3778
void * context
3779
);
3780
3781
/**
3782
* \brief Configure the display preemption callback.
3783
* \param[in] device The device to be monitored for preemption.
3784
* \param[in] callback The client application's callback
3785
* function. If NULL, the callback is unregistered.
3786
* \param[in] context The client-supplied callback context
3787
* information. This information will be passed to the
3788
* callback function if/when invoked.
3789
* \return VdpStatus The completion status of the operation.
3790
*/
3791
typedef VdpStatus VdpPreemptionCallbackRegister(
3792
VdpDevice device,
3793
VdpPreemptionCallback callback,
3794
void * context
3795
);
3796
3797
/*@}*/
3798
3799
/**
3800
* \defgroup get_proc_address Entry Point Retrieval
3801
*
3802
* In order to facilitate multiple implementations of VDPAU
3803
* co-existing within a single process, all functionality is
3804
* available via function pointers. The mechanism to retrieve
3805
* those function pointers is described below.
3806
*
3807
* @{
3808
*/
3809
3810
/**
3811
* \brief A type suitable for \ref VdpGetProcAddress
3812
* "VdpGetProcAddress"'s \b function_id parameter.
3813
*/
3814
typedef uint32_t VdpFuncId;
3815
3816
/** \hideinitializer */
3817
#define VDP_FUNC_ID_GET_ERROR_STRING (VdpFuncId)0
3818
/** \hideinitializer */
3819
#define VDP_FUNC_ID_GET_PROC_ADDRESS (VdpFuncId)1
3820
/** \hideinitializer */
3821
#define VDP_FUNC_ID_GET_API_VERSION (VdpFuncId)2
3822
/** \hideinitializer */
3823
#define VDP_FUNC_ID_GET_INFORMATION_STRING (VdpFuncId)4
3824
/** \hideinitializer */
3825
#define VDP_FUNC_ID_DEVICE_DESTROY (VdpFuncId)5
3826
/** \hideinitializer */
3827
#define VDP_FUNC_ID_GENERATE_CSC_MATRIX (VdpFuncId)6
3828
/** \hideinitializer */
3829
#define VDP_FUNC_ID_VIDEO_SURFACE_QUERY_CAPABILITIES (VdpFuncId)7
3830
/** \hideinitializer */
3831
#define VDP_FUNC_ID_VIDEO_SURFACE_QUERY_GET_PUT_BITS_Y_CB_CR_CAPABILITIES (VdpFuncId)8
3832
/** \hideinitializer */
3833
#define VDP_FUNC_ID_VIDEO_SURFACE_CREATE (VdpFuncId)9
3834
/** \hideinitializer */
3835
#define VDP_FUNC_ID_VIDEO_SURFACE_DESTROY (VdpFuncId)10
3836
/** \hideinitializer */
3837
#define VDP_FUNC_ID_VIDEO_SURFACE_GET_PARAMETERS (VdpFuncId)11
3838
/** \hideinitializer */
3839
#define VDP_FUNC_ID_VIDEO_SURFACE_GET_BITS_Y_CB_CR (VdpFuncId)12
3840
/** \hideinitializer */
3841
#define VDP_FUNC_ID_VIDEO_SURFACE_PUT_BITS_Y_CB_CR (VdpFuncId)13
3842
/** \hideinitializer */
3843
#define VDP_FUNC_ID_OUTPUT_SURFACE_QUERY_CAPABILITIES (VdpFuncId)14
3844
/** \hideinitializer */
3845
#define VDP_FUNC_ID_OUTPUT_SURFACE_QUERY_GET_PUT_BITS_NATIVE_CAPABILITIES (VdpFuncId)15
3846
/** \hideinitializer */
3847
#define VDP_FUNC_ID_OUTPUT_SURFACE_QUERY_PUT_BITS_INDEXED_CAPABILITIES (VdpFuncId)16
3848
/** \hideinitializer */
3849
#define VDP_FUNC_ID_OUTPUT_SURFACE_QUERY_PUT_BITS_Y_CB_CR_CAPABILITIES (VdpFuncId)17
3850
/** \hideinitializer */
3851
#define VDP_FUNC_ID_OUTPUT_SURFACE_CREATE (VdpFuncId)18
3852
/** \hideinitializer */
3853
#define VDP_FUNC_ID_OUTPUT_SURFACE_DESTROY (VdpFuncId)19
3854
/** \hideinitializer */
3855
#define VDP_FUNC_ID_OUTPUT_SURFACE_GET_PARAMETERS (VdpFuncId)20
3856
/** \hideinitializer */
3857
#define VDP_FUNC_ID_OUTPUT_SURFACE_GET_BITS_NATIVE (VdpFuncId)21
3858
/** \hideinitializer */
3859
#define VDP_FUNC_ID_OUTPUT_SURFACE_PUT_BITS_NATIVE (VdpFuncId)22
3860
/** \hideinitializer */
3861
#define VDP_FUNC_ID_OUTPUT_SURFACE_PUT_BITS_INDEXED (VdpFuncId)23
3862
/** \hideinitializer */
3863
#define VDP_FUNC_ID_OUTPUT_SURFACE_PUT_BITS_Y_CB_CR (VdpFuncId)24
3864
/** \hideinitializer */
3865
#define VDP_FUNC_ID_BITMAP_SURFACE_QUERY_CAPABILITIES (VdpFuncId)25
3866
/** \hideinitializer */
3867
#define VDP_FUNC_ID_BITMAP_SURFACE_CREATE (VdpFuncId)26
3868
/** \hideinitializer */
3869
#define VDP_FUNC_ID_BITMAP_SURFACE_DESTROY (VdpFuncId)27
3870
/** \hideinitializer */
3871
#define VDP_FUNC_ID_BITMAP_SURFACE_GET_PARAMETERS (VdpFuncId)28
3872
/** \hideinitializer */
3873
#define VDP_FUNC_ID_BITMAP_SURFACE_PUT_BITS_NATIVE (VdpFuncId)29
3874
/** \hideinitializer */
3875
#define VDP_FUNC_ID_OUTPUT_SURFACE_RENDER_OUTPUT_SURFACE (VdpFuncId)33
3876
/** \hideinitializer */
3877
#define VDP_FUNC_ID_OUTPUT_SURFACE_RENDER_BITMAP_SURFACE (VdpFuncId)34
3878
/** \hideinitializer */
3879
#define VDP_FUNC_ID_OUTPUT_SURFACE_RENDER_VIDEO_SURFACE_LUMA (VdpFuncId)35
3880
/** \hideinitializer */
3881
#define VDP_FUNC_ID_DECODER_QUERY_CAPABILITIES (VdpFuncId)36
3882
/** \hideinitializer */
3883
#define VDP_FUNC_ID_DECODER_CREATE (VdpFuncId)37
3884
/** \hideinitializer */
3885
#define VDP_FUNC_ID_DECODER_DESTROY (VdpFuncId)38
3886
/** \hideinitializer */
3887
#define VDP_FUNC_ID_DECODER_GET_PARAMETERS (VdpFuncId)39
3888
/** \hideinitializer */
3889
#define VDP_FUNC_ID_DECODER_RENDER (VdpFuncId)40
3890
/** \hideinitializer */
3891
#define VDP_FUNC_ID_VIDEO_MIXER_QUERY_FEATURE_SUPPORT (VdpFuncId)41
3892
/** \hideinitializer */
3893
#define VDP_FUNC_ID_VIDEO_MIXER_QUERY_PARAMETER_SUPPORT (VdpFuncId)42
3894
/** \hideinitializer */
3895
#define VDP_FUNC_ID_VIDEO_MIXER_QUERY_ATTRIBUTE_SUPPORT (VdpFuncId)43
3896
/** \hideinitializer */
3897
#define VDP_FUNC_ID_VIDEO_MIXER_QUERY_PARAMETER_VALUE_RANGE (VdpFuncId)44
3898
/** \hideinitializer */
3899
#define VDP_FUNC_ID_VIDEO_MIXER_QUERY_ATTRIBUTE_VALUE_RANGE (VdpFuncId)45
3900
/** \hideinitializer */
3901
#define VDP_FUNC_ID_VIDEO_MIXER_CREATE (VdpFuncId)46
3902
/** \hideinitializer */
3903
#define VDP_FUNC_ID_VIDEO_MIXER_SET_FEATURE_ENABLES (VdpFuncId)47
3904
/** \hideinitializer */
3905
#define VDP_FUNC_ID_VIDEO_MIXER_SET_ATTRIBUTE_VALUES (VdpFuncId)48
3906
/** \hideinitializer */
3907
#define VDP_FUNC_ID_VIDEO_MIXER_GET_FEATURE_SUPPORT (VdpFuncId)49
3908
/** \hideinitializer */
3909
#define VDP_FUNC_ID_VIDEO_MIXER_GET_FEATURE_ENABLES (VdpFuncId)50
3910
/** \hideinitializer */
3911
#define VDP_FUNC_ID_VIDEO_MIXER_GET_PARAMETER_VALUES (VdpFuncId)51
3912
/** \hideinitializer */
3913
#define VDP_FUNC_ID_VIDEO_MIXER_GET_ATTRIBUTE_VALUES (VdpFuncId)52
3914
/** \hideinitializer */
3915
#define VDP_FUNC_ID_VIDEO_MIXER_DESTROY (VdpFuncId)53
3916
/** \hideinitializer */
3917
#define VDP_FUNC_ID_VIDEO_MIXER_RENDER (VdpFuncId)54
3918
/** \hideinitializer */
3919
#define VDP_FUNC_ID_PRESENTATION_QUEUE_TARGET_DESTROY (VdpFuncId)55
3920
/** \hideinitializer */
3921
#define VDP_FUNC_ID_PRESENTATION_QUEUE_CREATE (VdpFuncId)56
3922
/** \hideinitializer */
3923
#define VDP_FUNC_ID_PRESENTATION_QUEUE_DESTROY (VdpFuncId)57
3924
/** \hideinitializer */
3925
#define VDP_FUNC_ID_PRESENTATION_QUEUE_SET_BACKGROUND_COLOR (VdpFuncId)58
3926
/** \hideinitializer */
3927
#define VDP_FUNC_ID_PRESENTATION_QUEUE_GET_BACKGROUND_COLOR (VdpFuncId)59
3928
/** \hideinitializer */
3929
#define VDP_FUNC_ID_PRESENTATION_QUEUE_GET_TIME (VdpFuncId)62
3930
/** \hideinitializer */
3931
#define VDP_FUNC_ID_PRESENTATION_QUEUE_DISPLAY (VdpFuncId)63
3932
/** \hideinitializer */
3933
#define VDP_FUNC_ID_PRESENTATION_QUEUE_BLOCK_UNTIL_SURFACE_IDLE (VdpFuncId)64
3934
/** \hideinitializer */
3935
#define VDP_FUNC_ID_PRESENTATION_QUEUE_QUERY_SURFACE_STATUS (VdpFuncId)65
3936
/** \hideinitializer */
3937
#define VDP_FUNC_ID_PREEMPTION_CALLBACK_REGISTER (VdpFuncId)66
3938
3939
#define VDP_FUNC_ID_BASE_WINSYS 0x1000
3940
3941
/**
3942
* \brief Retrieve a VDPAU function pointer.
3943
* \param[in] device The device that the function will operate
3944
* against.
3945
* \param[in] function_id The specific function to retrieve.
3946
* \param[out] function_pointer The actual pointer for the
3947
* application to call.
3948
* \return VdpStatus The completion status of the operation.
3949
*/
3950
typedef VdpStatus VdpGetProcAddress(
3951
VdpDevice device,
3952
VdpFuncId function_id,
3953
/* output parameters follow */
3954
void * * function_pointer
3955
);
3956
3957
/*@}*/
3958
/*@}*/
3959
3960
/**
3961
* \defgroup api_winsys Window System Integration Layer
3962
*
3963
* The set of VDPAU functionality specific to an individual
3964
* Windowing System.
3965
*/
3966
3967
#ifdef __cplusplus
3968
}
3969
#endif
3970
3971
#endif
3972
Loggerhead is a web-based interface for Breezy
Version: 2.0.1