2 * This source file is documented using Doxygen markup.
3 * See http://www.stack.nl/~dimitri/doxygen/
7 * This copyright notice applies to this header file:
9 * Copyright (c) 2008 NVIDIA Corporation
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
20 * The above copyright notice and this permission notice shall be
21 * included in all copies or substantial portions of the Software.
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.
34 * \mainpage Video Decode and Presentation API for Unix
36 * \section intro Introduction
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.
44 * \section api_partitioning API Partitioning
46 * VDPAU is split into two distinct modules:
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.
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
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.
66 * \section objects Object Types
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
74 * \subsection device_type Device Type
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.
81 * \subsection surface_types Surface Types
83 * A surface stores pixel information. Various types of surfaces
84 * existing for different purposes:
86 * - \ref VdpVideoSurface "VdpVideoSurface"s store decompressed
87 * YCbCr video frames in an implementation-defined internal
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
97 * \subsection transfer_types Transfer Types
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:
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.
112 * \section data_flow Data Flow
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.
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.
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".
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.
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".
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".
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.
158 * Finally, the resultant \ref VdpOutputSurface
159 * "VdpOutputSurface" must be displayed on screen. This is the job
160 * of the \ref VdpPresentationQueue "VdpPresentationQueue" object.
162 * \image html vdpau_data_flow.png
164 * \section entry_point_retrieval Entry Point Retrieval
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.
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
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.
182 * \subsection entry_point_philosophy Philosophy
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.
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.
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.
209 * \section threading Multi-threading
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.
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.
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.
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.
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.
239 * In a multi-threaded application, threads may need to be
240 * synchronized. For example, consider the situation where:
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.
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
256 * Queue<VdpVideoSurface> q_full_surfaces;
257 * Queue<VdpVideoSurface> q_empty_surfaces;
261 * VdpVideoSurface s = q_empty_surfaces.get();
262 * // Parse compressed stream here
263 * VdpDecoderRender(s, ...);
264 * q_full_surfaces.put(s);
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.
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, ...);
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.
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.
298 * \section endianness Surface Endianness
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
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.
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
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.
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:
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.
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.
344 * \section video_mixer_usage Video Mixer Usage
346 * \subsection video_surface_content VdpVideoSurface Content
348 * Each \ref VdpVideoSurface "VdpVideoSurface" is expected to
349 * contain an entire frame's-worth of data, irrespective of
350 * whether an interlaced of progressive sequence is being
353 * Depending on the exact encoding structure of the compressed
354 * video stream, the application may need to call \ref
355 * VdpDecoderRender twice to fill a single \ref VdpVideoSurface
356 * "VdpVideoSurface". When the stream contains an encoded
357 * progressive frame, or a "frame coded" interlaced field-pair,
358 * a single \ref VdpDecoderRender call will fill the entire
359 * surface. When the stream contains separately encoded
360 * interlaced fields, two \ref VdpDecoderRender calls will be
361 * required; one for the top field, and one for the bottom
364 * Implementation note: When \ref VdpDecoderRender renders an
365 * interlaced field, this operation must not disturb the content
366 * of the other field in the surface.
368 * \subsection vm_render_surfaces VdpVideoMixerRender surface list
370 * The \ref VdpVideoMixerRender API receives \ref VdpVideoSurface
371 * "VdpVideoSurface" IDs for any number of fields/frames. The
372 * application should strive to provide as many fields/frames as
373 * practical, to enable advanced video processing
374 * algorithms. At a minimum, the current field/frame must be
375 * provided. It is recommended that at least 2 past and 1 future
376 * frame be provided in all cases.
378 * Note that it is entirely possible, in general, for any of the
379 * \ref VdpVideoMixer "VdpVideoMixer" post-processing steps to
380 * require access to multiple input fields/frames.
382 * It is legal for an application not to provide some or all of
383 * the surfaces other than the "current" surface. Note that this
384 * may cause degraded operation of the \ref VdpVideoMixer
385 * "VdpVideoMixer" algorithms. However, this may be required in
386 * the case of temporary file or network read errors, decode
389 * When an application chooses not to provide a particular
390 * surface to \ref VdpVideoMixerRender, then this "slot" in the
391 * surface list must be filled with the special value \ref
392 * VDP_INVALID_HANDLE, to explicitly indicate that the picture
393 * is missing; do not simply shuffle other surfaces together to
396 * The \ref VdpVideoMixerRender parameter \b
397 * current_picture_structure applies to \b
398 * video_surface_current. The picture structure for the other
399 * surfaces will be automatically derived from that for the
400 * current picture as detailed below.
402 * If \b current_picture_structure is \ref
403 * VDP_VIDEO_MIXER_PICTURE_STRUCTURE_FRAME, then all surfaces are
404 * assumed to be frames. Otherwise, the picture structure is
405 * assumed to alternate between top and bottom field, anchored
406 * against \b current_picture_structure and \b
407 * video_surface_current.
409 * \subsection deinterlacing Applying de-interlacing
411 * Note that \ref VdpVideoMixerRender disables de-interlacing
412 * when \b current_picture_structure is \ref
413 * VDP_VIDEO_MIXER_PICTURE_STRUCTURE_FRAME; frames by definition
414 * need no de-interlacing.
416 * Weave de-interlacing may be obtained by giving the video
417 * mixer a surface containing two interlaced fields, but
418 * informing the \ref VdpVideoMixer "VdpVideoMixer" that the
419 * surface has \ref VDP_VIDEO_MIXER_PICTURE_STRUCTURE_FRAME.
421 * Bob de-interlacing is the default for interlaced content.
422 * More advanced de-interlacing techniques may be available,
423 * depending on the implementation. Such features need to be
424 * requested when creating the \ref VdpVideoMixer "VdpVideoMixer",
425 * and subsequently enabled.
427 * If the source material is marked progressive, two options are
428 * available for \ref VdpVideoMixerRender usage:
430 * -# Simply pass the allegedly progressive frames through the
431 * mixer, marking them as progressive. This equates to a
432 * so-called "flag following" mode.
433 * -# Apply any pulldown flags in the stream, yielding a higher
434 * rate stream of interlaced fields. These should then be
435 * passed through the mixer, marked as fields, with
436 * de-interlacing enabled, and inverse telecine optionally
437 * enabled. This should allow for so-called "bad edit"
438 * detection. However, it requires more processing power from
441 * If the source material is marked interlaced, the decoded
442 * interlaced fields should always be marked as fields when
443 * processing them with the mixer. Some de-interlacing
444 * algorithm is then always applied. Inverse telecine may be
445 * useful in cases where some portions, or all of, the
446 * interlaced stream is telecined film.
448 * \section extending Extending the API
450 * \subsection extend_enums Enumerations and Other Constants
452 * VDPAU defines a number of enumeration types.
454 * When modifying VDPAU, existing enumeration constants must
455 * continue to exist (although they may be deprecated), and do
456 * so in the existing order.
458 * The above discussion naturally applies to "manually" defined
459 * enumerations, using pre-processor macros, too.
461 * \subsection extend_structs Structures
463 * In most case, VDPAU includes no provision for modifying existing
464 * structure definitions, although they may be deprecated.
466 * New structures may be created, together with new API entry
467 * points or feature/attribute/parameter values, to expose new
470 * A few structures are considered plausible candidates for future extension.
471 * Such structures include a version number as the first field, indicating the
472 * exact layout of the client-provided data. Such structures may only be
473 * modified by adding new fields to the end of the structure, so that the
474 * original structure definition is completely compatible with a leading
475 * subset of fields of the extended structure.
477 * \subsection extend_functions Functions
479 * Existing functions may not be modified, although they may be
482 * New functions may be added at will. Note the enumeration
483 * requirements when modifying the enumeration that defines the
484 * list of entry points.
486 * \section preemption_note Display Preemption
488 * Please note that the display may be preempted away from
489 * VDPAU at any time. See \ref display_preemption for more
492 * \subsection trademarks Trademarks
494 * VDPAU is a trademark of NVIDIA Corporation. You may freely use the
495 * VDPAU trademark, as long as trademark ownership is attributed to
496 * NVIDIA Corporation.
501 * \brief The Core API
503 * This file contains the \ref api_core "Core API".
516 * \defgroup api_core Core API
518 * The core API encompasses all VDPAU functionality that operates
519 * in the same fashion across all Window Systems.
525 * \defgroup base_types Basic Types
527 * VDPAU primarily uses ISO C99 types from \c stdint.h.
532 /** \brief A true \ref VdpBool value */
534 /** \brief A false \ref VdpBool value */
537 * \brief A boolean value, holding \ref VDP_TRUE or \ref
545 * \defgroup misc_types Miscellaneous Types
551 * \brief An invalid object handle value.
553 * This value may be used to represent an invalid, or
554 * non-existent, object (\ref VdpDevice "VdpDevice",
555 * \ref VdpVideoSurface "VdpVideoSurface", etc.)
557 * Note that most APIs require valid object handles in all
558 * cases, and will fail when presented with this value.
560 #define VDP_INVALID_HANDLE 0xffffffffU
563 * \brief The set of all chroma formats for \ref VdpVideoSurface
564 * "VdpVideoSurface"s.
566 typedef uint32_t VdpChromaType;
568 /** \hideinitializer \brief 4:2:0 chroma format. */
569 #define VDP_CHROMA_TYPE_420 (VdpChromaType)0
570 /** \hideinitializer \brief 4:2:2 chroma format. */
571 #define VDP_CHROMA_TYPE_422 (VdpChromaType)1
572 /** \hideinitializer \brief 4:4:4 chroma format. */
573 #define VDP_CHROMA_TYPE_444 (VdpChromaType)2
576 * \brief The set of all known YCbCr surface formats.
578 typedef uint32_t VdpYCbCrFormat;
582 * \brief The "NV12" YCbCr surface format.
584 * This format has a two planes, a Y plane and a UV plane.
586 * The Y plane is an array of byte-sized Y components.
587 * Applications should access this data via a uint8_t pointer.
589 * The UV plane is an array of interleaved byte-sized U and V
590 * components, in the order U, V, U, V. Applications should
591 * access this data via a uint8_t pointer.
593 #define VDP_YCBCR_FORMAT_NV12 (VdpYCbCrFormat)0
596 * \brief The "YV12" YCbCr surface format.
598 * This format has a three planes, a Y plane, a U plane, and a V
601 * Each of the planes is an array of byte-sized components.
603 * Applications should access this data via a uint8_t pointer.
605 #define VDP_YCBCR_FORMAT_YV12 (VdpYCbCrFormat)1
608 * \brief The "UYVY" YCbCr surface format.
610 * This format may also be known as Y422, UYNV, HDYC.
612 * This format has a single plane.
614 * This plane is an array of interleaved byte-sized Y, U, and V
615 * components, in the order U, Y, V, Y, U, Y, V, Y.
617 * Applications should access this data via a uint8_t pointer.
619 #define VDP_YCBCR_FORMAT_UYVY (VdpYCbCrFormat)2
622 * \brief The "YUYV" YCbCr surface format.
624 * This format may also be known as YUY2, YUNV, V422.
626 * This format has a single plane.
628 * This plane is an array of interleaved byte-sized Y, U, and V
629 * components, in the order Y, U, Y, V, Y, U, Y, V.
631 * Applications should access this data via a uint8_t pointer.
633 #define VDP_YCBCR_FORMAT_YUYV (VdpYCbCrFormat)3
636 * \brief A packed YCbCr format.
638 * This format has a single plane.
640 * This plane is an array packed 32-bit pixel data. Within each
641 * 32-bit pixel, bits [31:24] contain A, bits [23:16] contain V,
642 * bits [15:8] contain U, and bits [7:0] contain Y.
644 * Applications should access this data via a uint32_t pointer.
646 #define VDP_YCBCR_FORMAT_Y8U8V8A8 (VdpYCbCrFormat)4
649 * \brief A packed YCbCr format.
651 * This format has a single plane.
653 * This plane is an array packed 32-bit pixel data. Within each
654 * 32-bit pixel, bits [31:24] contain A, bits [23:16] contain Y,
655 * bits [15:8] contain U, and bits [7:0] contain V.
657 * Applications should access this data via a uint32_t pointer.
659 #define VDP_YCBCR_FORMAT_V8U8Y8A8 (VdpYCbCrFormat)5
662 * \brief The set of all known RGB surface formats.
664 typedef uint32_t VdpRGBAFormat;
668 * \brief A packed RGB format.
670 * This format has a single plane.
672 * This plane is an array packed 32-bit pixel data. Within each
673 * 32-bit pixel, bits [31:24] contain A, bits [23:16] contain R,
674 * bits [15:8] contain G, and bits [7:0] contain B.
676 * Applications should access this data via a uint32_t pointer.
678 #define VDP_RGBA_FORMAT_B8G8R8A8 (VdpRGBAFormat)0
681 * \brief A packed RGB format.
683 * This format has a single plane.
685 * This plane is an array packed 32-bit pixel data. Within each
686 * 32-bit pixel, bits [31:24] contain A, bits [23:16] contain B,
687 * bits [15:8] contain G, and bits [7:0] contain R.
689 * Applications should access this data via a uint32_t pointer.
691 #define VDP_RGBA_FORMAT_R8G8B8A8 (VdpRGBAFormat)1
694 * \brief A packed RGB format.
696 * This format has a single plane.
698 * This plane is an array packed 32-bit pixel data. Within each
699 * 32-bit pixel, bits [31:30] contain A, bits [29:20] contain B,
700 * bits [19:10] contain G, and bits [9:0] contain R.
702 * Applications should access this data via a uint32_t pointer.
704 #define VDP_RGBA_FORMAT_R10G10B10A2 (VdpRGBAFormat)2
707 * \brief A packed RGB format.
709 * This format has a single plane.
711 * This plane is an array packed 32-bit pixel data. Within each
712 * 32-bit pixel, bits [31:30] contain A, bits [29:20] contain R,
713 * bits [19:10] contain G, and bits [9:0] contain B.
715 * Applications should access this data via a uint32_t pointer.
717 #define VDP_RGBA_FORMAT_B10G10R10A2 (VdpRGBAFormat)3
720 * \brief An alpha-only surface format.
722 * This format has a single plane.
724 * This plane is an array of byte-sized components.
726 * Applications should access this data via a uint8_t pointer.
728 #define VDP_RGBA_FORMAT_A8 (VdpRGBAFormat)4
731 * \brief The set of all known indexed surface formats.
733 typedef uint32_t VdpIndexedFormat;
737 * \brief A 4-bit indexed format, with alpha.
739 * This format has a single plane.
741 * This plane is an array of byte-sized components. Within each
742 * byte, bits [7:4] contain I (index), and bits [3:0] contain A.
744 * Applications should access this data via a uint8_t pointer.
746 #define VDP_INDEXED_FORMAT_A4I4 (VdpIndexedFormat)0
749 * \brief A 4-bit indexed format, with alpha.
751 * This format has a single plane.
753 * This plane is an array of byte-sized components. Within each
754 * byte, bits [7:4] contain A, and bits [3:0] contain I (index).
756 * Applications should access this data via a uint8_t pointer.
758 #define VDP_INDEXED_FORMAT_I4A4 (VdpIndexedFormat)1
761 * \brief A 8-bit indexed format, with alpha.
763 * This format has a single plane.
765 * This plane is an array of interleaved byte-sized A and I
766 * (index) components, in the order A, I, A, I.
768 * Applications should access this data via a uint8_t pointer.
770 #define VDP_INDEXED_FORMAT_A8I8 (VdpIndexedFormat)2
773 * \brief A 8-bit indexed format, with alpha.
775 * This format has a single plane.
777 * This plane is an array of interleaved byte-sized A and I
778 * (index) components, in the order I, A, I, A.
780 * Applications should access this data via a uint8_t pointer.
782 #define VDP_INDEXED_FORMAT_I8A8 (VdpIndexedFormat)3
785 * \brief A location within a surface.
787 * The VDPAU co-ordinate system has its origin at the top-left
788 * of a surface, with x and y components increasing right and
792 /** X co-ordinate. */
794 /** Y co-ordinate. */
799 * \brief A rectangular region of a surface.
801 * The co-ordinates are top-left inclusive, bottom-right
804 * The VDPAU co-ordinate system has its origin at the top-left
805 * of a surface, with x and y components increasing right and
809 /** Left X co-ordinate. Inclusive. */
811 /** Top Y co-ordinate. Inclusive. */
813 /** Right X co-ordinate. Exclusive. */
815 /** Bottom Y co-ordinate. Exclusive. */
820 * A constant RGBA color.
822 * Note that the components are stored as float values in the
823 * range 0.0...1.0 rather than format-specific integer values.
824 * This allows VdpColor values to be independent from the exact
825 * surface format(s) in use.
837 * \defgroup error_handling Error Handling
844 * \brief The set of all possible error codes.
847 /** The operation completed successfully; no error. */
850 * No backend implementation could be loaded.
852 VDP_STATUS_NO_IMPLEMENTATION,
854 * The display was preempted, or a fatal error occurred.
856 * The application must re-initialize VDPAU.
858 VDP_STATUS_DISPLAY_PREEMPTED,
860 * An invalid handle value was provided.
862 * Either the handle does not exist at all, or refers to an object of an
865 VDP_STATUS_INVALID_HANDLE,
867 * An invalid pointer was provided.
869 * Typically, this means that a NULL pointer was provided for an "output"
872 VDP_STATUS_INVALID_POINTER,
874 * An invalid/unsupported \ref VdpChromaType value was supplied.
876 VDP_STATUS_INVALID_CHROMA_TYPE,
878 * An invalid/unsupported \ref VdpYCbCrFormat value was supplied.
880 VDP_STATUS_INVALID_Y_CB_CR_FORMAT,
882 * An invalid/unsupported \ref VdpRGBAFormat value was supplied.
884 VDP_STATUS_INVALID_RGBA_FORMAT,
886 * An invalid/unsupported \ref VdpIndexedFormat value was supplied.
888 VDP_STATUS_INVALID_INDEXED_FORMAT,
890 * An invalid/unsupported \ref VdpColorStandard value was supplied.
892 VDP_STATUS_INVALID_COLOR_STANDARD,
894 * An invalid/unsupported \ref VdpColorTableFormat value was supplied.
896 VDP_STATUS_INVALID_COLOR_TABLE_FORMAT,
898 * An invalid/unsupported \ref VdpOutputSurfaceRenderBlendFactor value was
901 VDP_STATUS_INVALID_BLEND_FACTOR,
903 * An invalid/unsupported \ref VdpOutputSurfaceRenderBlendEquation value
906 VDP_STATUS_INVALID_BLEND_EQUATION,
908 * An invalid/unsupported flag value/combination was supplied.
910 VDP_STATUS_INVALID_FLAG,
912 * An invalid/unsupported \ref VdpDecoderProfile value was supplied.
914 VDP_STATUS_INVALID_DECODER_PROFILE,
916 * An invalid/unsupported \ref VdpVideoMixerFeature value was supplied.
918 VDP_STATUS_INVALID_VIDEO_MIXER_FEATURE,
920 * An invalid/unsupported \ref VdpVideoMixerParameter value was supplied.
922 VDP_STATUS_INVALID_VIDEO_MIXER_PARAMETER,
924 * An invalid/unsupported \ref VdpVideoMixerAttribute value was supplied.
926 VDP_STATUS_INVALID_VIDEO_MIXER_ATTRIBUTE,
928 * An invalid/unsupported \ref VdpVideoMixerPictureStructure value was
931 VDP_STATUS_INVALID_VIDEO_MIXER_PICTURE_STRUCTURE,
933 * An invalid/unsupported \ref VdpFuncId value was supplied.
935 VDP_STATUS_INVALID_FUNC_ID,
937 * The size of a supplied object does not match the object it is being
940 * For example, a \ref VdpVideoMixer "VdpVideoMixer" is configured to
941 * process \ref VdpVideoSurface "VdpVideoSurface" objects of a specific
942 * size. If presented with a \ref VdpVideoSurface "VdpVideoSurface" of a
943 * different size, this error will be raised.
945 VDP_STATUS_INVALID_SIZE,
947 * An invalid/unsupported value was supplied.
949 * This is a catch-all error code for values of type other than those
950 * with a specific error code.
952 VDP_STATUS_INVALID_VALUE,
954 * An invalid/unsupported structure version was specified in a versioned
955 * structure. This implies that the implementation is older than the
956 * header file the application was built against.
958 VDP_STATUS_INVALID_STRUCT_VERSION,
960 * The system does not have enough resources to complete the requested
961 * operation at this time.
963 VDP_STATUS_RESOURCES,
965 * The set of handles supplied are not all related to the same VdpDevice.
967 * When performing operations that operate on multiple surfaces, such as
968 * \ref VdpOutputSurfaceRenderOutputSurface or \ref VdpVideoMixerRender,
969 * all supplied surfaces must have been created within the context of the
970 * same \ref VdpDevice "VdpDevice" object. This error is raised if they were
973 VDP_STATUS_HANDLE_DEVICE_MISMATCH,
975 * A catch-all error, used when no other error code applies.
981 * \brief Retrieve a string describing an error code.
982 * \param[in] status The error code.
983 * \return A pointer to the string. Note that this is a
984 * statically allocated read-only string. As such, the
985 * application must not free the returned pointer. The
986 * pointer is valid as long as the VDPAU implementation is
987 * present within the application's address space.
989 typedef char const * VdpGetErrorString(
996 * \defgroup versioning Versioning
1003 * \brief The VDPAU version described by this header file.
1005 * Note that VDPAU version numbers are simple integers that
1006 * increase monotonically (typically by value 1) with each VDPAU
1009 #define VDPAU_VERSION 0
1012 * \brief Retrieve the VDPAU version implemented by the backend.
1013 * \param[out] api_version The API version.
1014 * \return VdpStatus The completion status of the operation.
1016 typedef VdpStatus VdpGetApiVersion(
1017 /* output parameters follow */
1018 uint32_t * api_version
1022 * \brief Retrieve an implementation-specific string description
1023 * of the implementation. This typically includes detailed version
1025 * \param[out] information_string A pointer to the information
1026 * string. Note that this is a statically allocated
1027 * read-only string. As such, the application must not
1028 * free the returned pointer. The pointer is valid as long
1029 * as the implementation is present within the
1030 * application's address space.
1031 * \return VdpStatus The completion status of the operation.
1033 * Note that the returned string is useful for information
1034 * reporting. It is not intended that the application should
1035 * parse this string in order to determine any information about
1036 * the implementation.
1038 typedef VdpStatus VdpGetInformationString(
1039 /* output parameters follow */
1040 char const * * information_string
1046 * \defgroup VdpDevice VdpDevice; Primary API object
1048 * The VdpDevice is the root of the VDPAU object system. Using a
1049 * VdpDevice object, all other object types may be created. See
1050 * the sections describing those other object types for details
1051 * on object creation.
1053 * Note that VdpDevice objects are created using the \ref
1060 * \brief An opaque handle representing a VdpDevice object.
1062 typedef uint32_t VdpDevice;
1065 * \brief Destroy a VdpDevice.
1066 * \param[in] device The device to destroy.
1067 * \return VdpStatus The completion status of the operation.
1069 typedef VdpStatus VdpDeviceDestroy(
1076 * \defgroup VdpCSCMatrix VdpCSCMatrix; CSC Matrix Manipulation
1078 * When converting from YCbCr to RGB data formats, a color space
1079 * conversion operation must be performed. This operation is
1080 * parameterized using a "color space conversion matrix". The
1081 * VdpCSCMatrix is a data structure representing this
1088 * \brief Storage for a color space conversion matrix.
1090 * Note that the application may choose to construct the matrix
1091 * content by either:
1092 * - Directly filling in the fields of the CSC matrix
1093 * - Using the \ref VdpGenerateCSCMatrix helper function.
1095 * The color space conversion equation is as follows:
1098 * \left( \begin{array}{c} R \\ G \\ B \end{array} \right)
1100 * \left( \begin{array}{cccc}
1101 * m_{0,0} & m_{0,1} & m_{0,2} & m_{0,3} \\
1102 * m_{1,0} & m_{1,1} & m_{1,2} & m_{1,3} \\
1103 * m_{2,0} & m_{2,1} & m_{2,2} & m_{2,3}
1107 * \left( \begin{array}{c} Y \\ Cb \\ Cr \\ 1.0 \end{array}
1111 typedef float VdpCSCMatrix[3][4];
1113 #define VDP_PROCAMP_VERSION 0
1116 * \brief Procamp operation parameterization data.
1118 * When performing a color space conversion operation, various
1119 * adjustments can be performed at the same time, such as
1120 * brightness and contrast. This structure defines the level of
1121 * adjustments to make.
1125 * This field must be filled with VDP_PROCAMP_VERSION
1127 uint32_t struct_version;
1129 * Brightness adjustment amount. A value clamped between
1130 * -1.0 and 1.0. 0.0 represents no modification.
1134 * Contrast adjustment amount. A value clamped between
1135 * 0.0 and 10.0. 1.0 represents no modification.
1139 * Saturation adjustment amount. A value clamped between 0.0 and
1140 * 10.0. 1.0 represents no modification.
1144 * Hue adjustment amount. A value clamped between
1145 * -PI and PI. 0.0 represents no modification.
1151 * \brief YCbCr color space specification.
1153 * A number of YCbCr color spaces exist. This enumeration
1154 * defines the specifications known to VDPAU.
1156 typedef uint32_t VdpColorStandard;
1158 /** \hideinitializer \brief ITU-R BT.601 */
1159 #define VDP_COLOR_STANDARD_ITUR_BT_601 (VdpColorStandard)0
1160 /** \hideinitializer \brief ITU-R BT.709 */
1161 #define VDP_COLOR_STANDARD_ITUR_BT_709 (VdpColorStandard)1
1162 /** \hideinitializer \brief SMPTE-240M */
1163 #define VDP_COLOR_STANDARD_SMPTE_240M (VdpColorStandard)2
1166 * \brief Generate a color space conversion matrix
1167 * \param[in] procamp The procamp adjustments to make. If NULL,
1168 * no adjustments will be made.
1169 * \param[in] standard The YCbCr color space to convert from.
1170 * \param[out] csc_matrix The CSC matrix to initialize.
1171 * \return VdpStatus The completion status of the operation.
1173 typedef VdpStatus VdpGenerateCSCMatrix(
1174 VdpProcamp * procamp,
1175 VdpColorStandard standard,
1176 /* output parameters follow */
1177 VdpCSCMatrix * csc_matrix
1183 * \defgroup VdpVideoSurface VdpVideoSurface; Video Surface object
1185 * A VdpVideoSurface stores YCbCr data in an internal format,
1186 * with a variety of possible chroma sub-sampling options.
1188 * A VdpVideoSurface may be filled with:
1189 * - Data provided by the CPU via \ref
1190 * VdpVideoSurfacePutBitsYCbCr (i.e. software decode.)
1191 * - The result of applying a \ref VdpDecoder "VdpDecoder" to
1192 * compressed video data.
1194 * VdpVideoSurface content may be accessed by:
1195 * - The application via \ref VdpVideoSurfaceGetBitsYCbCr
1196 * - The Hardware that implements \ref VdpOutputSurface
1197 * "VdpOutputSurface" \ref VdpOutputSurfaceRender
1198 * "rendering functionality".
1199 * - The Hardware the implements \ref VdpVideoMixer
1200 * "VdpVideoMixer" functionality.
1202 * VdpVideoSurfaces are not directly displayable. They must be
1203 * converted into a displayable format using \ref VdpVideoMixer
1204 * "VdpVideoMixer" objects.
1206 * See \ref video_mixer_usage for additional information.
1212 * \brief Query the implementation's VdpVideoSurface
1214 * \param[in] device The device to query.
1215 * \param[in] surface_chroma_type The type of chroma type for
1216 * which information is requested.
1217 * \param[out] is_supported Is this chroma type supported?
1218 * \param[out] max_width The maximum supported surface width for
1220 * \param[out] max_height The maximum supported surface height
1221 * for this chroma type.
1222 * \return VdpStatus The completion status of the operation.
1224 typedef VdpStatus VdpVideoSurfaceQueryCapabilities(
1226 VdpChromaType surface_chroma_type,
1227 /* output parameters follow */
1228 VdpBool * is_supported,
1229 uint32_t * max_width,
1230 uint32_t * max_height
1234 * \brief Query the implementation's VdpVideoSurface
1235 * GetBits/PutBits capabilities.
1236 * \param[in] device The device to query.
1237 * \param[in] surface_chroma_type The type of chroma type for
1238 * which information is requested.
1239 * \param[in] bits_ycbcr_format The format of application "bits"
1240 * buffer for which information is requested.
1241 * \param[out] is_supported Is this chroma type supported?
1242 * \return VdpStatus The completion status of the operation.
1244 typedef VdpStatus VdpVideoSurfaceQueryGetPutBitsYCbCrCapabilities(
1246 VdpChromaType surface_chroma_type,
1247 VdpYCbCrFormat bits_ycbcr_format,
1248 /* output parameters follow */
1249 VdpBool * is_supported
1253 * \brief An opaque handle representing a VdpVideoSurface
1256 typedef uint32_t VdpVideoSurface;
1259 * \brief Create a VdpVideoSurface.
1260 * \param[in] device The device that will contain the surface.
1261 * \param[in] chroma_type The chroma type of the new surface.
1262 * \param[in] width The width of the new surface.
1263 * \param[in] height The height of the new surface.
1264 * \param[out] surface The new surface's handle.
1265 * \return VdpStatus The completion status of the operation.
1267 * The memory backing the surface may not be initialized during
1268 * creation. Applications are expected to initialize any region
1269 * that they use, via \ref VdpDecoderRender or \ref
1270 * VdpVideoSurfacePutBitsYCbCr.
1272 typedef VdpStatus VdpVideoSurfaceCreate(
1274 VdpChromaType chroma_type,
1277 /* output parameters follow */
1278 VdpVideoSurface * surface
1282 * \brief Destroy a VdpVideoSurface.
1283 * \param[in] surface The surface's handle.
1284 * \return VdpStatus The completion status of the operation.
1286 typedef VdpStatus VdpVideoSurfaceDestroy(
1287 VdpVideoSurface surface
1291 * \brief Retrieve the parameters used to create a
1293 * \param[in] surface The surface's handle.
1294 * \param[out] chroma_type The chroma type of the surface.
1295 * \param[out] width The width of the surface.
1296 * \param[out] height The height of the surface.
1297 * \return VdpStatus The completion status of the operation.
1299 typedef VdpStatus VdpVideoSurfaceGetParameters(
1300 VdpVideoSurface surface,
1301 /* output parameters follow */
1302 VdpChromaType * chroma_type,
1308 * \brief Copy image data from a VdpVideoSurface to application
1309 * memory in a specified YCbCr format.
1310 * \param[in] surface The surface's handle.
1311 * \param[in] destination_ycbcr_format The format of the
1312 * application's data buffers.
1313 * \param[in] destination_data Pointers to the application data
1314 * buffers into which the image data will be written. Note
1315 * that this is an array of pointers, one per plane. The
1316 * destination_format parameter will define how many
1317 * planes are required.
1318 * \param[in] destination_pitches Pointers to the pitch values
1319 * for the application data buffers. Note that this is an
1320 * array of pointers, one per plane. The
1321 * destination_format parameter will define how many
1322 * planes are required.
1323 * \return VdpStatus The completion status of the operation.
1325 typedef VdpStatus VdpVideoSurfaceGetBitsYCbCr(
1326 VdpVideoSurface surface,
1327 VdpYCbCrFormat destination_ycbcr_format,
1328 void * const * destination_data,
1329 uint32_t const * destination_pitches
1333 * \brief Copy image data from application memory in a specific
1334 * YCbCr format to a VdpVideoSurface.
1335 * \param[in] surface The surface's handle.
1336 * \param[in] source_ycbcr_format The format of the
1337 * application's data buffers.
1338 * \param[in] source_data Pointers to the application data
1339 * buffers from which the image data will be copied. Note
1340 * that this is an array of pointers, one per plane. The
1341 * source_format parameter will define how many
1342 * planes are required.
1343 * \param[in] source_pitches Pointers to the pitch values
1344 * for the application data buffers. Note that this is an
1345 * array of pointers, one per plane. The
1346 * source_format parameter will define how many
1347 * planes are required.
1348 * \return VdpStatus The completion status of the operation.
1350 typedef VdpStatus VdpVideoSurfacePutBitsYCbCr(
1351 VdpVideoSurface surface,
1352 VdpYCbCrFormat source_ycbcr_format,
1353 void const * const * source_data,
1354 uint32_t const * source_pitches
1360 * \defgroup VdpOutputSurface VdpOutputSurface; Output Surface \
1363 * A VdpOutputSurface stores RGBA data in a defined format.
1365 * A VdpOutputSurface may be filled with:
1366 * - Data provided by the CPU via the various
1367 * VdpOutputSurfacePutBits functions.
1368 * - Using the VdpOutputSurface \ref VdpOutputSurfaceRender
1369 * "rendering functionality".
1370 * - Using a \ref VdpVideoMixer "VdpVideoMixer" object.
1372 * VdpOutputSurface content may be accessed by:
1373 * - The application via the various VdpOutputSurfaceGetBits
1375 * - The Hardware that implements VdpOutputSurface
1376 * \ref VdpOutputSurfaceRender "rendering functionality".
1377 * - The Hardware the implements \ref VdpVideoMixer
1378 * "VdpVideoMixer" functionality.
1379 * - The Hardware that implements \ref VdpPresentationQueue
1380 * "VdpPresentationQueue" functionality,
1382 * VdpVideoSurfaces are directly displayable using a \ref
1383 * VdpPresentationQueue "VdpPresentationQueue" object.
1389 * \brief The set of all known color table formats, for use with
1390 * \ref VdpOutputSurfacePutBitsIndexed.
1392 typedef uint32_t VdpColorTableFormat;
1396 * \brief 8-bit per component packed into 32-bits
1398 * This format is an array of packed 32-bit RGB color values.
1399 * Bits [31:24] are unused, bits [23:16] contain R, bits [15:8]
1400 * contain G, and bits [7:0] contain B. Note: The format is
1401 * physically an array of uint32_t values, and should be accessed
1402 * as such by the application in order to avoid endianness
1405 #define VDP_COLOR_TABLE_FORMAT_B8G8R8X8 (VdpColorTableFormat)0
1408 * \brief Query the implementation's VdpOutputSurface
1410 * \param[in] device The device to query.
1411 * \param[in] surface_rgba_format The surface format for
1412 * which information is requested.
1413 * \param[out] is_supported Is this surface format supported?
1414 * \param[out] max_width The maximum supported surface width for
1416 * \param[out] max_height The maximum supported surface height
1417 * for this chroma type.
1418 * \return VdpStatus The completion status of the operation.
1420 typedef VdpStatus VdpOutputSurfaceQueryCapabilities(
1422 VdpRGBAFormat surface_rgba_format,
1423 /* output parameters follow */
1424 VdpBool * is_supported,
1425 uint32_t * max_width,
1426 uint32_t * max_height
1430 * \brief Query the implementation's capability to perform a
1431 * PutBits operation using application data matching the
1433 * \param[in] device The device to query.
1434 * \param[in] surface_rgba_format The surface format for
1435 * which information is requested.
1436 * \param[out] is_supported Is this surface format supported?
1437 * \return VdpStatus The completion status of the operation.
1439 typedef VdpStatus VdpOutputSurfaceQueryGetPutBitsNativeCapabilities(
1441 VdpRGBAFormat surface_rgba_format,
1442 /* output parameters follow */
1443 VdpBool * is_supported
1447 * \brief Query the implementation's capability to perform a
1448 * PutBits operation using application data in a specific
1450 * \param[in] device The device to query.
1451 * \param[in] surface_rgba_format The surface format for
1452 * which information is requested.
1453 * \param[in] bits_indexed_format The format of the application
1455 * \param[in] color_table_format The format of the color lookup
1457 * \param[out] is_supported Is this surface format supported?
1458 * \return VdpStatus The completion status of the operation.
1460 typedef VdpStatus VdpOutputSurfaceQueryPutBitsIndexedCapabilities(
1462 VdpRGBAFormat surface_rgba_format,
1463 VdpIndexedFormat bits_indexed_format,
1464 VdpColorTableFormat color_table_format,
1465 /* output parameters follow */
1466 VdpBool * is_supported
1470 * \brief Query the implementation's capability to perform a
1471 * PutBits operation using application data in a specific
1473 * \param[in] device The device to query.
1474 * \param[in] surface_rgba_format The surface format for which
1475 * information is requested.
1476 * \param[in] bits_ycbcr_format The format of the application
1478 * \param[out] is_supported Is this surface format supported?
1479 * \return VdpStatus The completion status of the operation.
1481 typedef VdpStatus VdpOutputSurfaceQueryPutBitsYCbCrCapabilities(
1483 VdpRGBAFormat surface_rgba_format,
1484 VdpYCbCrFormat bits_ycbcr_format,
1485 /* output parameters follow */
1486 VdpBool * is_supported
1490 * \brief An opaque handle representing a VdpOutputSurface
1493 typedef uint32_t VdpOutputSurface;
1496 * \brief Create a VdpOutputSurface.
1497 * \param[in] device The device that will contain the surface.
1498 * \param[in] rgba_format The format of the new surface.
1499 * \param[in] width The width of the new surface.
1500 * \param[in] height The height of the new surface.
1501 * \param[out] surface The new surface's handle.
1502 * \return VdpStatus The completion status of the operation.
1504 * The memory backing the surface will be initialized to 0 color
1505 * and 0 alpha (i.e. black.)
1507 typedef VdpStatus VdpOutputSurfaceCreate(
1509 VdpRGBAFormat rgba_format,
1512 /* output parameters follow */
1513 VdpOutputSurface * surface
1517 * \brief Destroy a VdpOutputSurface.
1518 * \param[in] surface The surface's handle.
1519 * \return VdpStatus The completion status of the operation.
1521 typedef VdpStatus VdpOutputSurfaceDestroy(
1522 VdpOutputSurface surface
1526 * \brief Retrieve the parameters used to create a
1528 * \param[in] surface The surface's handle.
1529 * \param[out] rgba_format The format of the surface.
1530 * \param[out] width The width of the surface.
1531 * \param[out] height The height of the surface.
1532 * \return VdpStatus The completion status of the operation.
1534 typedef VdpStatus VdpOutputSurfaceGetParameters(
1535 VdpOutputSurface surface,
1536 /* output parameters follow */
1537 VdpRGBAFormat * rgba_format,
1543 * \brief Copy image data from a VdpOutputSurface to application
1544 * memory in the surface's native format.
1545 * \param[in] surface The surface's handle.
1546 * \param[in] source_rect The sub-rectangle of the source
1547 * surface to copy. If NULL, the entire surface will be
1549 * \param[in] destination_data Pointers to the application data
1550 * buffers into which the image data will be written. Note
1551 * that this is an array of pointers, one per plane. The
1552 * destination_format parameter will define how many
1553 * planes are required.
1554 * \param[in] destination_pitches Pointers to the pitch values
1555 * for the application data buffers. Note that this is an
1556 * array of pointers, one per plane. The
1557 * destination_format parameter will define how many
1558 * planes are required.
1559 * \return VdpStatus The completion status of the operation.
1561 typedef VdpStatus VdpOutputSurfaceGetBitsNative(
1562 VdpOutputSurface surface,
1563 VdpRect const * source_rect,
1564 void * const * destination_data,
1565 uint32_t const * destination_pitches
1569 * \brief Copy image data from application memory in the
1570 * surface's native format to a VdpOutputSurface.
1571 * \param[in] surface The surface's handle.
1572 * \param[in] source_data Pointers to the application data
1573 * buffers from which the image data will be copied. Note
1574 * that this is an array of pointers, one per plane. The
1575 * source_format parameter will define how many
1576 * planes are required.
1577 * \param[in] source_pitches Pointers to the pitch values
1578 * for the application data buffers. Note that this is an
1579 * array of pointers, one per plane. The
1580 * source_format parameter will define how many
1581 * planes are required.
1582 * \param[in] destination_rect The sub-rectangle of the surface
1583 * to fill with application data. If NULL, the entire
1584 * surface will be updated.
1585 * \return VdpStatus The completion status of the operation.
1587 typedef VdpStatus VdpOutputSurfacePutBitsNative(
1588 VdpOutputSurface surface,
1589 void const * const * source_data,
1590 uint32_t const * source_pitches,
1591 VdpRect const * destination_rect
1595 * \brief Copy image data from application memory in a specific
1596 * indexed format to a VdpOutputSurface.
1597 * \param[in] surface The surface's handle.
1598 * \param[in] source_indexed_format The format of the
1599 * application's data buffers.
1600 * \param[in] source_data Pointers to the application data
1601 * buffers from which the image data will be copied. Note
1602 * that this is an array of pointers, one per plane. The
1603 * source_indexed_format parameter will define how many
1604 * planes are required.
1605 * \param[in] source_pitches Pointers to the pitch values
1606 * for the application data buffers. Note that this is an
1607 * array of pointers, one per plane. The
1608 * source_indexed_format parameter will define how many
1609 * planes are required.
1610 * \param[in] destination_rect The sub-rectangle of the surface
1611 * to fill with application data. If NULL, the entire
1612 * surface will be updated.
1613 * \param[in] color_table_format The format of the color_table.
1614 * \param[in] color_table A table that maps between source index
1615 * and target color data. See \ref VdpColorTableFormat for
1616 * details regarding the memory layout.
1617 * \return VdpStatus The completion status of the operation.
1619 typedef VdpStatus VdpOutputSurfacePutBitsIndexed(
1620 VdpOutputSurface surface,
1621 VdpIndexedFormat source_indexed_format,
1622 void const * const * source_data,
1623 uint32_t const * source_pitch,
1624 VdpRect const * destination_rect,
1625 VdpColorTableFormat color_table_format,
1626 void const * color_table
1630 * \brief Copy image data from application memory in a specific
1631 * YCbCr format to a VdpOutputSurface.
1632 * \param[in] surface The surface's handle.
1633 * \param[in] source_ycbcr_format The format of the
1634 * application's data buffers.
1635 * \param[in] source_data Pointers to the application data
1636 * buffers from which the image data will be copied. Note
1637 * that this is an array of pointers, one per plane. The
1638 * source_ycbcr_format parameter will define how many
1639 * planes are required.
1640 * \param[in] source_pitches Pointers to the pitch values
1641 * for the application data buffers. Note that this is an
1642 * array of pointers, one per plane. The
1643 * source_ycbcr_format parameter will define how many
1644 * planes are required.
1645 * \param[in] destination_rect The sub-rectangle of the surface
1646 * to fill with application data. If NULL, the entire
1647 * surface will be updated.
1648 * \param[in] csc_matrix The color space conversion matrix used
1649 * by the copy operation. If NULL, a default matrix will
1650 * be used internally. Th default matrix is equivalent to
1651 * ITU-R BT.601 with no procamp changes.
1652 * \return VdpStatus The completion status of the operation.
1654 typedef VdpStatus VdpOutputSurfacePutBitsYCbCr(
1655 VdpOutputSurface surface,
1656 VdpYCbCrFormat source_ycbcr_format,
1657 void const * const * source_data,
1658 uint32_t const * source_pitches,
1659 VdpRect const * destination_rect,
1660 VdpCSCMatrix const * csc_matrix
1666 * \defgroup VdpBitmapSurface VdpBitmapSurface; Bitmap Surface \
1669 * A VdpBitmapSurface stores RGBA data in a defined format.
1671 * A VdpBitmapSurface may be filled with:
1672 * - Data provided by the CPU via the \ref
1673 * VdpBitmapSurfacePutBitsNative function.
1675 * VdpBitmapSurface content may be accessed by:
1676 * - The Hardware that implements \ref VdpOutputSurface
1677 * "VdpOutputSurface" \ref VdpOutputSurfaceRender
1678 * "rendering functionality"
1680 * VdpBitmapSurface objects are intended to store static read-only data, such
1681 * as font glyphs, and the bitmaps used to compose an applications'
1684 * The primary differences between VdpBitmapSurfaces and
1685 * \ref VdpOutputSurface "VdpOutputSurface"s are:
1687 * - You cannot render to a VdpBitmapSurface, just upload native data via
1690 * - The read-only nature of a VdpBitmapSurface gives the implementation more
1691 * flexibility in its choice of data storage location for the bitmap data.
1692 * For example, some implementations may choose to store some/all
1693 * VdpBitmapSurface objects in system memory to relieve GPU memory pressure.
1695 * - VdpBitmapSurface and VdpOutputSurface may support different subsets of all
1696 * known RGBA formats.
1702 * \brief Query the implementation's VdpBitmapSurface
1704 * \param[in] device The device to query.
1705 * \param[in] surface_rgba_format The surface format for
1706 * which information is requested.
1707 * \param[out] is_supported Is this surface format supported?
1708 * \param[out] max_width The maximum supported surface width for
1710 * \param[out] max_height The maximum supported surface height
1711 * for this chroma type.
1712 * \return VdpStatus The completion status of the operation.
1714 typedef VdpStatus VdpBitmapSurfaceQueryCapabilities(
1716 VdpRGBAFormat surface_rgba_format,
1717 /* output parameters follow */
1718 VdpBool * is_supported,
1719 uint32_t * max_width,
1720 uint32_t * max_height
1724 * \brief An opaque handle representing a VdpBitmapSurface
1727 typedef uint32_t VdpBitmapSurface;
1730 * \brief Create a VdpBitmapSurface.
1731 * \param[in] device The device that will contain the surface.
1732 * \param[in] rgba_format The format of the new surface.
1733 * \param[in] width The width of the new surface.
1734 * \param[in] height The height of the new surface.
1735 * \param[in] frequently_accessed Is this bitmap used
1736 * frequently, or infrequently, by compositing options?
1737 * Implementations may use this as a hint to determine how
1738 * to allocate the underlying storage for the surface.
1739 * \param[out] surface The new surface's handle.
1740 * \return VdpStatus The completion status of the operation.
1742 * The memory backing the surface may not be initialized
1743 * during creation. Applications are expected initialize any
1744 * region that they use, via \ref VdpBitmapSurfacePutBitsNative.
1746 typedef VdpStatus VdpBitmapSurfaceCreate(
1748 VdpRGBAFormat rgba_format,
1751 VdpBool frequently_accessed,
1752 /* output parameters follow */
1753 VdpBitmapSurface * surface
1757 * \brief Destroy a VdpBitmapSurface.
1758 * \param[in] surface The surface's handle.
1759 * \return VdpStatus The completion status of the operation.
1761 typedef VdpStatus VdpBitmapSurfaceDestroy(
1762 VdpBitmapSurface surface
1766 * \brief Retrieve the parameters used to create a
1768 * \param[in] surface The surface's handle.
1769 * \param[out] rgba_format The format of the surface.
1770 * \param[out] width The width of the surface.
1771 * \param[out] height The height of the surface.
1772 * \param[out] frequently_accessed The frequently_accessed state
1774 * \return VdpStatus The completion status of the operation.
1776 typedef VdpStatus VdpBitmapSurfaceGetParameters(
1777 VdpBitmapSurface surface,
1778 /* output parameters follow */
1779 VdpRGBAFormat * rgba_format,
1782 VdpBool * frequently_accessed
1786 * \brief Copy image data from application memory in the
1787 * surface's native format to a VdpBitmapSurface.
1788 * \param[in] surface The surface's handle.
1789 * \param[in] source_data Pointers to the application data
1790 * buffers from which the image data will be copied. Note
1791 * that this is an array of pointers, one per plane. The
1792 * source_format parameter will define how many
1793 * planes are required.
1794 * \param[in] source_pitches Pointers to the pitch values
1795 * for the application data buffers. Note that this is an
1796 * array of pointers, one per plane. The
1797 * source_format parameter will define how many
1798 * planes are required.
1799 * \param[in] destination_rect The sub-rectangle of the surface
1800 * to fill with application data. If NULL, the entire
1801 * surface will be updated.
1802 * \return VdpStatus The completion status of the operation.
1804 typedef VdpStatus VdpBitmapSurfacePutBitsNative(
1805 VdpBitmapSurface surface,
1806 void const * const * source_data,
1807 uint32_t const * source_pitches,
1808 VdpRect const * destination_rect
1814 * \defgroup VdpOutputSurfaceRender VdpOutputSurface Rendering \
1817 * \ref VdpOutputSurface "VdpOutputSurface" objects
1818 * directly provide some rendering/compositing operations. These
1819 * are described below.
1826 * \brief The blending equation factors.
1829 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ZERO = 0,
1830 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE = 1,
1831 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_SRC_COLOR = 2,
1832 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_SRC_COLOR = 3,
1833 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_SRC_ALPHA = 4,
1834 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA = 5,
1835 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_DST_ALPHA = 6,
1836 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_DST_ALPHA = 7,
1837 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_DST_COLOR = 8,
1838 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_DST_COLOR = 9,
1839 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_SRC_ALPHA_SATURATE = 10,
1840 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_CONSTANT_COLOR = 11,
1841 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR = 12,
1842 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_CONSTANT_ALPHA = 13,
1843 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA = 14,
1844 } VdpOutputSurfaceRenderBlendFactor;
1848 * \brief The blending equations.
1851 VDP_OUTPUT_SURFACE_RENDER_BLEND_EQUATION_SUBTRACT = 0,
1852 VDP_OUTPUT_SURFACE_RENDER_BLEND_EQUATION_REVERSE_SUBTRACT = 1,
1853 VDP_OUTPUT_SURFACE_RENDER_BLEND_EQUATION_ADD = 2,
1854 VDP_OUTPUT_SURFACE_RENDER_BLEND_EQUATION_MIN = 3,
1855 VDP_OUTPUT_SURFACE_RENDER_BLEND_EQUATION_MAX = 4,
1856 } VdpOutputSurfaceRenderBlendEquation;
1858 #define VDP_OUTPUT_SURFACE_RENDER_BLEND_STATE_VERSION 0
1861 * \brief Complete blending operation definition.
1865 * This field must be filled with VDP_OUTPUT_SURFACE_RENDER_BLEND_STATE_VERSIION
1867 uint32_t struct_version;
1868 VdpOutputSurfaceRenderBlendFactor blend_factor_source_color;
1869 VdpOutputSurfaceRenderBlendFactor blend_factor_destination_color;
1870 VdpOutputSurfaceRenderBlendFactor blend_factor_source_alpha;
1871 VdpOutputSurfaceRenderBlendFactor blend_factor_destination_alpha;
1872 VdpOutputSurfaceRenderBlendEquation blend_equation_color;
1873 VdpOutputSurfaceRenderBlendEquation blend_equation_alpha;
1874 VdpColor blend_constant;
1875 } VdpOutputSurfaceRenderBlendState;
1879 * \brief Do not rotate source_surface prior to compositing.
1881 #define VDP_OUTPUT_SURFACE_RENDER_ROTATE_0 0
1885 * \brief Rotate source_surface 90 degrees clockwise prior to
1888 #define VDP_OUTPUT_SURFACE_RENDER_ROTATE_90 1
1892 * \brief Rotate source_surface 180 degrees prior to
1895 #define VDP_OUTPUT_SURFACE_RENDER_ROTATE_180 2
1899 * \brief Rotate source_surface 270 degrees clockwise prior to
1902 #define VDP_OUTPUT_SURFACE_RENDER_ROTATE_270 3
1906 * \brief A separate color is used for each vertex of the
1907 * smooth-shaded quad. Hence, colors array contains 4
1908 * elements rather than 1. See description of colors
1911 #define VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX (1 << 2)
1914 * \brief Composite a sub-rectangle of a \ref VdpOutputSurface
1915 * "VdpOutputSurface" into a sub-rectangle of another
1916 * \ref VdpOutputSurface VdpOutputSurface.
1917 * \param[in] destination_surface The destination surface of the
1918 * compositing operation.
1919 * \param[in] destination_rect The sub-rectangle of the
1920 * destination surface to update. If NULL, the entire
1921 * destination surface will be updated.
1922 * \param[in] source_surface The source surface for the
1923 * compositing operation. The surface is treated as having
1924 * four components: red, green, blue and alpha. Any
1925 * missing components are treated as 1.0. For example, for
1926 * an A8 VdpOutputSurface, alpha will come from the surface
1927 * but red, green and blue will be treated as 1.0. If
1928 * source_surface is NULL, all components will be treated
1929 * as 1.0. Note that destination_surface and
1930 * source_surface must have been allocated via the same
1931 * \ref VdpDevice "VdpDevice".
1932 * \param[in] source_rect The sub-rectangle of the source
1933 * surface to read from. If NULL, the entire
1934 * source_surface will be read. Left/right ot top/bottom
1935 * co-ordinates may be swapped to flip the source. Any
1936 * flip occurs prior to any requested rotation. Values
1937 * from outside the source surface are valid and samples
1938 * at those locations will be taken from the nearest edge.
1939 * \param[in] colors A pointer to an array of \ref VdpColor
1940 * "VdpColor" objects. If the flag
1941 * VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX is set,
1942 * VDPAU will four entries from the array, and treat them
1943 * as the colors corresponding to the upper-left,
1944 * upper-right, lower-right and lower-left corners of the
1945 * post-rotation source (i.e. indices 0, 1, 2 and 3 run
1946 * clockwise from the upper left corner). If the flag
1947 * VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX is not
1948 * set, VDPAU will use the single VdpColor for all four
1949 * corners. If colors is NULL then red, green, blue and
1950 * alpha values of 1.0 will be used.
1951 * \param[in] blend_state If a blend state is provided, the
1952 * blend state will be used for the composite operation. If
1953 * NULL, blending is effectively disabled, which is
1954 * equivalent to a blend equation of ADD, source blend
1955 * factors of ONE and destination blend factors of ZERO. The
1956 * blend math is the familiar OpenGL blend math:
1958 * dst.a = equation(blendFactorDstAlpha*dst.a,
1959 * blendFactorSrcAlpha*src.a);
1962 * dst.rgb = equation(blendFactorDstColor*dst.rgb,
1963 * blendFactorSrcColor*src.rgb);
1965 * \param[in] flags A set of flags influencing how the
1966 * compositing operation works.
1967 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_0
1968 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_90
1969 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_180
1970 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_270
1971 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX
1972 * \return VdpStatus The completion status of the operation.
1974 * The general compositing pipeline is as follows.
1976 * -# Extract source_rect from source_surface.
1978 * -# The extracted source is rotated 0, 90, 180 or 270 degrees
1979 * according to the flags.
1981 * -# The rotated source is component-wise multiplied by a
1982 * smooth-shaded quad with a (potentially) different color at
1985 * -# The resulting rotated, smooth-shaded quad is scaled to the
1986 * size of destination_rect and composited with
1987 * destination_surface using the provided blend state.
1990 typedef VdpStatus VdpOutputSurfaceRenderOutputSurface(
1991 VdpOutputSurface destination_surface,
1992 VdpRect const * destination_rect,
1993 VdpOutputSurface source_surface,
1994 VdpRect const * source_rect,
1995 VdpColor const * colors,
1996 VdpOutputSurfaceRenderBlendState const * blend_state,
2001 * \brief Composite a sub-rectangle of a \ref VdpBitmapSurface
2002 * "VdpBitmapSurface" into a sub-rectangle of a
2003 * \ref VdpOutputSurface VdpOutputSurface.
2004 * \param[in] destination_surface The destination surface of the
2005 * compositing operation.
2006 * \param[in] destination_rect The sub-rectangle of the
2007 * destination surface to update. If NULL, the entire
2008 * destination surface will be updated.
2009 * \param[in] source_surface The source surface for the
2010 * compositing operation. The surface is treated as having
2011 * four components: red, green, blue and alpha. Any
2012 * missing components are treated as 1.0. For example, for
2013 * an A8 VdpBitmapSurface, alpha will come from the surface
2014 * but red, green and blue will be treated as 1.0. If
2015 * source_surface is NULL, all components will be treated
2016 * as 1.0. Note that destination_surface and
2017 * source_surface must have been allocated via the same
2018 * \ref VdpDevice "VdpDevice".
2019 * \param[in] source_rect The sub-rectangle of the source
2020 * surface to read from. If NULL, the entire
2021 * source_surface will be read. Left/right ot top/bottom
2022 * co-ordinates may be swapped to flip the source. Any
2023 * flip occurs prior to any requested rotation. Values
2024 * from outside the source surface are valid and samples
2025 * at those locations will be taken from the nearest edge.
2026 * \param[in] colors A pointer to an array of \ref VdpColor
2027 * "VdpColor" objects. If the flag
2028 * VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX is set,
2029 * VDPAU will four entries from the array, and treat them
2030 * as the colors corresponding to the upper-left,
2031 * upper-right, lower-right and lower-left corners of the
2032 * post-rotation source (i.e. indices 0, 1, 2 and 3 run
2033 * clockwise from the upper left corner). If the flag
2034 * VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX is not
2035 * set, VDPAU will use the single VdpColor for all four
2036 * corners. If colors is NULL then red, green, blue and
2037 * alpha values of 1.0 will be used.
2038 * \param[in] blend_state If a blend state is provided, the
2039 * blend state will be used for the composite operation. If
2040 * NULL, blending is effectively disabled, which is
2041 * equivalent to a blend equation of ADD, source blend
2042 * factors of ONE and destination blend factors of ZERO. The
2043 * blend math is the familiar OpenGL blend math:
2045 * dst.a = equation(blendFactorDstAlpha*dst.a,
2046 * blendFactorSrcAlpha*src.a);
2049 * dst.rgb = equation(blendFactorDstColor*dst.rgb,
2050 * blendFactorSrcColor*src.rgb);
2052 * \param[in] flags A set of flags influencing how the
2053 * compositing operation works.
2054 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_0
2055 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_90
2056 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_180
2057 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_270
2058 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX
2059 * \return VdpStatus The completion status of the operation.
2061 * The general compositing pipeline is as follows.
2063 * -# Extract source_rect from source_surface.
2065 * -# The extracted source is rotated 0, 90, 180 or 270 degrees
2066 * according to the flags.
2068 * -# The rotated source is component-wise multiplied by a
2069 * smooth-shaded quad with a (potentially) different color at
2072 * -# The resulting rotated, smooth-shaded quad is scaled to the
2073 * size of destination_rect and composited with
2074 * destination_surface using the provided blend state.
2077 typedef VdpStatus VdpOutputSurfaceRenderBitmapSurface(
2078 VdpOutputSurface destination_surface,
2079 VdpRect const * destination_rect,
2080 VdpBitmapSurface source_surface,
2081 VdpRect const * source_rect,
2082 VdpColor const * colors,
2083 VdpOutputSurfaceRenderBlendState const * blend_state,
2090 * \defgroup VdpDecoder VdpDecoder; Video Decoding object
2092 * The VdpDecoder object decodes compressed video data, writing
2093 * the results to a \ref VdpVideoSurface "VdpVideoSurface".
2095 * A specific VDPAU implementation may support decoding multiple
2096 * types of compressed video data. However, VdpDecoder objects
2097 * are able to decode a specific type of compressed video data.
2098 * This type must be specified during creation.
2104 * \brief The set of all known compressed video formats, and
2105 * associated profiles, that may be decoded.
2107 typedef uint32_t VdpDecoderProfile;
2109 /** \hideinitializer */
2110 #define VDP_DECODER_PROFILE_MPEG1 (VdpDecoderProfile)0
2111 /** \hideinitializer */
2112 #define VDP_DECODER_PROFILE_MPEG2_SIMPLE (VdpDecoderProfile)1
2113 /** \hideinitializer */
2114 #define VDP_DECODER_PROFILE_MPEG2_MAIN (VdpDecoderProfile)2
2115 /** \hideinitializer */
2116 /** \brief MPEG 4 part 10 == H.264 == AVC */
2117 #define VDP_DECODER_PROFILE_H264_BASELINE (VdpDecoderProfile)6
2118 /** \hideinitializer */
2119 #define VDP_DECODER_PROFILE_H264_MAIN (VdpDecoderProfile)7
2120 /** \hideinitializer */
2121 #define VDP_DECODER_PROFILE_H264_HIGH (VdpDecoderProfile)8
2122 /** \hideinitializer */
2123 #define VDP_DECODER_PROFILE_VC1_SIMPLE (VdpDecoderProfile)9
2124 /** \hideinitializer */
2125 #define VDP_DECODER_PROFILE_VC1_MAIN (VdpDecoderProfile)10
2126 /** \hideinitializer */
2127 #define VDP_DECODER_PROFILE_VC1_ADVANCED (VdpDecoderProfile)11
2129 /** \hideinitializer */
2130 #define VDP_DECODER_LEVEL_MPEG1_NA 0
2132 /** \hideinitializer */
2133 #define VDP_DECODER_LEVEL_MPEG2_LL 0
2134 /** \hideinitializer */
2135 #define VDP_DECODER_LEVEL_MPEG2_ML 1
2136 /** \hideinitializer */
2137 #define VDP_DECODER_LEVEL_MPEG2_HL14 2
2138 /** \hideinitializer */
2139 #define VDP_DECODER_LEVEL_MPEG2_HL 3
2141 /** \hideinitializer */
2142 #define VDP_DECODER_LEVEL_H264_1 10
2143 /** \hideinitializer */
2144 #define VDP_DECODER_LEVEL_H264_1b 9
2145 /** \hideinitializer */
2146 #define VDP_DECODER_LEVEL_H264_1_1 11
2147 /** \hideinitializer */
2148 #define VDP_DECODER_LEVEL_H264_1_2 12
2149 /** \hideinitializer */
2150 #define VDP_DECODER_LEVEL_H264_1_3 13
2151 /** \hideinitializer */
2152 #define VDP_DECODER_LEVEL_H264_2 20
2153 /** \hideinitializer */
2154 #define VDP_DECODER_LEVEL_H264_2_1 21
2155 /** \hideinitializer */
2156 #define VDP_DECODER_LEVEL_H264_2_2 22
2157 /** \hideinitializer */
2158 #define VDP_DECODER_LEVEL_H264_3 30
2159 /** \hideinitializer */
2160 #define VDP_DECODER_LEVEL_H264_3_1 31
2161 /** \hideinitializer */
2162 #define VDP_DECODER_LEVEL_H264_3_2 32
2163 /** \hideinitializer */
2164 #define VDP_DECODER_LEVEL_H264_4 40
2165 /** \hideinitializer */
2166 #define VDP_DECODER_LEVEL_H264_4_1 41
2167 /** \hideinitializer */
2168 #define VDP_DECODER_LEVEL_H264_4_2 42
2169 /** \hideinitializer */
2170 #define VDP_DECODER_LEVEL_H264_5 50
2171 /** \hideinitializer */
2172 #define VDP_DECODER_LEVEL_H264_5_1 51
2174 /** \hideinitializer */
2175 #define VDP_DECODER_LEVEL_VC1_SIMPLE_LOW 0
2176 /** \hideinitializer */
2177 #define VDP_DECODER_LEVEL_VC1_SIMPLE_MEDIUM 1
2179 /** \hideinitializer */
2180 #define VDP_DECODER_LEVEL_VC1_MAIN_LOW 0
2181 /** \hideinitializer */
2182 #define VDP_DECODER_LEVEL_VC1_MAIN_MEDIUM 1
2183 /** \hideinitializer */
2184 #define VDP_DECODER_LEVEL_VC1_MAIN_HIGH 2
2186 /** \hideinitializer */
2187 #define VDP_DECODER_LEVEL_VC1_ADVANCED_L0 0
2188 /** \hideinitializer */
2189 #define VDP_DECODER_LEVEL_VC1_ADVANCED_L1 1
2190 /** \hideinitializer */
2191 #define VDP_DECODER_LEVEL_VC1_ADVANCED_L2 2
2192 /** \hideinitializer */
2193 #define VDP_DECODER_LEVEL_VC1_ADVANCED_L3 3
2194 /** \hideinitializer */
2195 #define VDP_DECODER_LEVEL_VC1_ADVANCED_L4 4
2198 * \brief Query the implementation's VdpDecoder capabilities.
2199 * \param[in] device The device to query.
2200 * \param[in] profile The decoder profile for which information is requested.
2201 * \param[out] is_supported Is this profile supported?
2202 * \param[out] max_level The maximum specification level supported for this
2204 * \param[out] max_macroblocks The maximum supported surface size in
2205 * macroblocks. Note that this could be greater than that dictated by
2206 * the maximum level.
2207 * \param[out] max_width The maximum supported surface width for this profile.
2208 * Note that this could be greater than that dictated by the maximum
2210 * \param[out] max_height The maximum supported surface height for this
2211 * profile. Note that this could be greater than that dictated by the
2213 * \return VdpStatus The completion status of the operation.
2215 typedef VdpStatus VdpDecoderQueryCapabilities(
2217 VdpDecoderProfile profile,
2218 /* output parameters follow */
2219 VdpBool * is_supported,
2220 uint32_t * max_level,
2221 uint32_t * max_macroblocks,
2222 uint32_t * max_width,
2223 uint32_t * max_height
2227 * \brief An opaque handle representing a VdpDecoder object.
2229 typedef uint32_t VdpDecoder;
2232 * \brief Create a VdpDecoder.
2233 * \param[in] device The device that will contain the surface.
2234 * \param[in] profile The video format the decoder will decode.
2235 * \param[in] width The width of the new surface.
2236 * \param[in] height The height of the new surface.
2237 * \param[in] max_references The maximum number of references that may be
2238 * used by a single frame in the stream to be decoded. This parameter
2239 * exists mainly for formats such as H.264, where different streams
2240 * may use a different number of references. Requesting too many
2241 * references may waste memory, but decoding should still operate
2242 * correctly. Requesting too few references will cause decoding to
2244 * \param[out] decoder The new decoder's handle.
2245 * \return VdpStatus The completion status of the operation.
2247 typedef VdpStatus VdpDecoderCreate(
2249 VdpDecoderProfile profile,
2252 uint32_t max_references,
2253 /* output parameters follow */
2254 VdpDecoder * decoder
2258 * \brief Destroy a VdpDecoder.
2259 * \param[in] surface The decoder's handle.
2260 * \return VdpStatus The completion status of the operation.
2262 typedef VdpStatus VdpDecoderDestroy(
2267 * \brief Retrieve the parameters used to create a
2269 * \param[in] surface The surface's handle.
2270 * \param[out] profile The video format used to create the
2272 * \param[out] width The width of surfaces decode by the
2274 * \param[out] height The height of surfaces decode by the
2276 * \return VdpStatus The completion status of the operation.
2278 typedef VdpStatus VdpDecoderGetParameters(
2280 /* output parameters follow */
2281 VdpDecoderProfile * profile,
2286 #define VDP_BITSTREAM_BUFFER_VERSION 0
2289 * \brief Application data buffer containing compressed video
2294 * This field must be filled with VDP_BITSTREAM_BUFFER_VERSION
2296 uint32_t struct_version;
2297 /** A pointer to the bitstream data bytes */
2298 void const * bitstream;
2299 /** The number of data bytes */
2300 uint32_t bitstream_bytes;
2301 } VdpBitstreamBuffer;
2304 * \brief A generic "picture information" pointer type.
2306 * This type serves solely to document the expected usage of a
2307 * generic (void *) function parameter. In actual usage, the
2308 * application is expected to physically provide a pointer to an
2309 * instance of one of the "real" VdpPictureInfo* structures,
2310 * picking the type appropriate for the decoder object in
2313 typedef void * VdpPictureInfo;
2316 * \brief Picture parameter information for an MPEG 1 or MPEG 2
2319 * Note: References to "copy of bitstream field" in the field descriptions
2320 * may refer to data literally parsed from the bitstream, or derived from
2321 * the bitstream using a mechanism described in the specification.
2325 * Reference used by B and P frames.
2326 * Set to VDP_INVALID_HANDLE when not used.
2328 VdpVideoSurface forward_reference;
2330 * Reference used by B frames.
2331 * Set to VDP_INVALID_HANDLE when not used.
2333 VdpVideoSurface backward_reference;
2334 /** Number of slices in the bitstream provided. */
2335 uint32_t slice_count;
2337 /** Copy of the MPEG bitstream field. */
2338 uint8_t picture_structure;
2339 /** Copy of the MPEG bitstream field. */
2340 uint8_t picture_coding_type;
2341 /** Copy of the MPEG bitstream field. */
2342 uint8_t intra_dc_precision;
2343 /** Copy of the MPEG bitstream field. */
2344 uint8_t frame_pred_frame_dct;
2345 /** Copy of the MPEG bitstream field. */
2346 uint8_t concealment_motion_vectors;
2347 /** Copy of the MPEG bitstream field. */
2348 uint8_t intra_vlc_format;
2349 /** Copy of the MPEG bitstream field. */
2350 uint8_t alternate_scan;
2351 /** Copy of the MPEG bitstream field. */
2352 uint8_t q_scale_type;
2353 /** Copy of the MPEG bitstream field. */
2354 uint8_t top_field_first;
2355 /** Copy of the MPEG-1 bitstream field. For MPEG-2, set to 0. */
2356 uint8_t full_pel_forward_vector;
2357 /** Copy of the MPEG-1 bitstream field. For MPEG-2, set to 0. */
2358 uint8_t full_pel_backward_vector;
2360 * Copy of the MPEG bitstream field.
2361 * For MPEG-1, fill both horizontal and vertical entries.
2363 uint8_t f_code[2][2];
2364 /** Copy of the MPEG bitstream field, converted to raster order. */
2365 uint8_t intra_quantizer_matrix[64];
2366 /** Copy of the MPEG bitstream field, converted to raster order. */
2367 uint8_t non_intra_quantizer_matrix[64];
2368 } VdpPictureInfoMPEG1Or2;
2371 * \brief Information about an H.264 reference frame
2373 * Note: References to "copy of bitstream field" in the field descriptions
2374 * may refer to data literally parsed from the bitstream, or derived from
2375 * the bitstream using a mechanism described in the specification.
2379 * The surface that contains the reference image.
2380 * Set to VDP_INVALID_HANDLE for unused entries.
2382 VdpVideoSurface surface;
2383 /** Is this a long term reference (else short term). */
2384 VdpBool is_long_term;
2386 * Is the top field used as a reference.
2387 * Set to VDP_FALSE for unused entries.
2389 VdpBool top_is_reference;
2391 * Is the bottom field used as a reference.
2392 * Set to VDP_FALSE for unused entries.
2394 VdpBool bottom_is_reference;
2395 /** [0]: top, [1]: bottom */
2396 int32_t field_order_cnt[2];
2398 * Copy of the H.264 bitstream field:
2399 * frame_num from slice_header for short-term references,
2400 * LongTermPicNum from decoding algorithm for long-term references.
2403 } VdpReferenceFrameH264;
2406 * \brief Picture parameter information for an H.264 picture.
2408 * Note: The \ref referenceFrames array must contain the "DPB" as
2409 * defined by the H.264 specification. In particular, once a
2410 * reference frame has been decoded to a surface, that surface must
2411 * continue to appear in the DPB until no longer required to predict
2412 * any future frame. Once a surface is removed from the DPB, it can
2413 * no longer be used as a reference, unless decoded again.
2415 * Also note that only surfaces previously generated using \ref
2416 * VdpDecoderRender may be used as reference frames. In particular,
2417 * surfaces filled using any "put bits" API will not work.
2419 * Note: References to "copy of bitstream field" in the field descriptions
2420 * may refer to data literally parsed from the bitstream, or derived from
2421 * the bitstream using a mechanism described in the specification.
2424 /** Number of slices in the bitstream provided. */
2425 uint32_t slice_count;
2426 /** [0]: top, [1]: bottom */
2427 int32_t field_order_cnt[2];
2428 /** Will the decoded frame be used as a reference later. */
2429 VdpBool is_reference;
2431 /** Copy of the H.264 bitstream field. */
2433 /** Copy of the H.264 bitstream field. */
2434 uint8_t field_pic_flag;
2435 /** Copy of the H.264 bitstream field. */
2436 uint8_t bottom_field_flag;
2437 /** Copy of the H.264 bitstream field. */
2438 uint8_t num_ref_frames;
2439 /** Copy of the H.264 bitstream field. */
2440 uint8_t mb_adaptive_frame_field_flag;
2441 /** Copy of the H.264 bitstream field. */
2442 uint8_t constrained_intra_pred_flag;
2443 /** Copy of the H.264 bitstream field. */
2444 uint8_t weighted_pred_flag;
2445 /** Copy of the H.264 bitstream field. */
2446 uint8_t weighted_bipred_idc;
2447 /** Copy of the H.264 bitstream field. */
2448 uint8_t frame_mbs_only_flag;
2449 /** Copy of the H.264 bitstream field. */
2450 uint8_t transform_8x8_mode_flag;
2451 /** Copy of the H.264 bitstream field. */
2452 int8_t chroma_qp_index_offset;
2453 /** Copy of the H.264 bitstream field. */
2454 int8_t second_chroma_qp_index_offset;
2455 /** Copy of the H.264 bitstream field. */
2456 int8_t pic_init_qp_minus26;
2457 /** Copy of the H.264 bitstream field. */
2458 uint8_t num_ref_idx_l0_active_minus1;
2459 /** Copy of the H.264 bitstream field. */
2460 uint8_t num_ref_idx_l1_active_minus1;
2461 /** Copy of the H.264 bitstream field. */
2462 uint8_t log2_max_frame_num_minus4;
2463 /** Copy of the H.264 bitstream field. */
2464 uint8_t pic_order_cnt_type;
2465 /** Copy of the H.264 bitstream field. */
2466 uint8_t log2_max_pic_order_cnt_lsb_minus4;
2467 /** Copy of the H.264 bitstream field. */
2468 uint8_t delta_pic_order_always_zero_flag;
2469 /** Copy of the H.264 bitstream field. */
2470 uint8_t direct_8x8_inference_flag;
2471 /** Copy of the H.264 bitstream field. */
2472 uint8_t entropy_coding_mode_flag;
2473 /** Copy of the H.264 bitstream field. */
2474 uint8_t pic_order_present_flag;
2475 /** Copy of the H.264 bitstream field. */
2476 uint8_t deblocking_filter_control_present_flag;
2477 /** Copy of the H.264 bitstream field. */
2478 uint8_t redundant_pic_cnt_present_flag;
2480 /** Copy of the H.264 bitstream field, converted to raster order. */
2481 uint8_t scaling_lists_4x4[6][16];
2482 /** Copy of the H.264 bitstream field, converted to raster order. */
2483 uint8_t scaling_lists_8x8[2][64];
2485 /** See \ref VdpPictureInfoH264 for instructions regarding this field. */
2486 VdpReferenceFrameH264 referenceFrames[16];
2487 } VdpPictureInfoH264;
2490 * \brief Picture parameter information for a VC1 picture.
2492 * Note: References to "copy of bitstream field" in the field descriptions
2493 * may refer to data literally parsed from the bitstream, or derived from
2494 * the bitstream using a mechanism described in the specification.
2498 * Reference used by B and P frames.
2499 * Set to VDP_INVALID_HANDLE when not used.
2501 VdpVideoSurface forward_reference;
2503 * Reference used by B frames.
2504 * Set to VDP_INVALID_HANDLE when not used.
2506 VdpVideoSurface backward_reference;
2508 /** Number of slices in the bitstream provided. */
2509 uint32_t slice_count;
2510 /** I=0, P=1, B=3, BI=4 from 7.1.1.4. */
2511 uint8_t picture_type;
2512 /** Progressive=0, Frame-interlace=2, Field-interlace=3; see VC-1 7.1.1.15. */
2513 uint8_t frame_coding_mode;
2515 /** Copy of the VC-1 bitstream field. See VC-1 6.1.5. */
2516 uint8_t postprocflag;
2517 /** Copy of the VC-1 bitstream field. See VC-1 6.1.8. */
2519 /** Copy of the VC-1 bitstream field. See VC-1 6.1.9. */
2521 /** Copy of the VC-1 bitstream field. See VC-1 6.1.10. */
2523 /** Copy of the VC-1 bitstream field. See VC-1 6.1.11. */
2524 uint8_t finterpflag;
2525 /** Copy of the VC-1 bitstream field. See VC-1 6.1.3. */
2527 /** Copy of the VC-1 bitstream field. See VC-1 6.2.8. */
2529 /** Copy of the VC-1 bitstream field. See VC-1 6.2.3. */
2530 uint8_t panscan_flag;
2531 /** Copy of the VC-1 bitstream field. See VC-1 6.2.4. */
2532 uint8_t refdist_flag;
2533 /** Copy of the VC-1 bitstream field. See VC-1 6.2.11. */
2535 /** Copy of the VC-1 bitstream field. See VC-1 6.2.7. */
2536 uint8_t extended_mv;
2537 /** Copy of the VC-1 bitstream field. See VC-1 6.2.14. */
2538 uint8_t extended_dmv;
2539 /** Copy of the VC-1 bitstream field. See VC-1 6.2.10. */
2541 /** Copy of the VC-1 bitstream field. See VC-1 6.2.9. */
2542 uint8_t vstransform;
2543 /** Copy of the VC-1 bitstream field. See VC-1 6.2.5. */
2545 /** Copy of the VC-1 bitstream field. See VC-1 6.2.6. */
2547 /** Copy of the VC-1 bitstream field. See VC-1 6.12.15. */
2548 uint8_t range_mapy_flag;
2549 /** Copy of the VC-1 bitstream field. */
2551 /** Copy of the VC-1 bitstream field. See VC-1 6.2.16. */
2552 uint8_t range_mapuv_flag;
2553 /** Copy of the VC-1 bitstream field. */
2554 uint8_t range_mapuv;
2557 * Copy of the VC-1 bitstream field. See VC-1 J.1.10.
2558 * Only used by simple and main profiles.
2562 * Copy of the VC-1 bitstream field. See VC-1 J.1.16.
2563 * Only used by simple and main profiles.
2567 * Copy of the VC-1 bitstream field. See VC-1 J.1.17.
2568 * Only used by simple and main profiles.
2572 * Copy of the VC-1 bitstream field. See VC-1 J.1.17.
2573 * Only used by simple and main profiles.
2578 * Out-of-loop deblocking enable.
2579 * Bit 0 of POSTPROC from VC-1 7.1.1.27
2580 * Note that bit 1 of POSTPROC (dering enable) should not be included.
2582 uint8_t deblockEnable;
2584 * Parameter used by VC-1 Annex H deblocking algorithm. Note that VDPAU
2585 * implementations may choose which deblocking algorithm to use.
2589 } VdpPictureInfoVC1;
2592 * \brief Decode a compressed field/frame and render the result
2593 * into a \ref VdpVideoSurface "VdpVideoSurface".
2594 * \param[in] decoder The decoder object that will perform the
2596 * \param[in] target The video surface to render to.
2597 * \param[in] picture_info A (pointer to a) structure containing
2598 * information about the picture to be decoded. Note that
2599 * the appropriate type of VdpPictureInfo* structure must
2600 * be provided to match to profile that the decoder was
2602 * \param[in] bitstream_buffer_count The number of bitstream
2603 * buffers containing compressed data for this picture.
2604 * \param[in] bitstream_buffers An array of bitstream buffers.
2605 * \return VdpStatus The completion status of the operation.
2607 * See \ref video_mixer_usage for additional information.
2609 typedef VdpStatus VdpDecoderRender(
2611 VdpVideoSurface target,
2612 VdpPictureInfo const * picture_info,
2613 uint32_t bitstream_buffer_count,
2614 VdpBitstreamBuffer const * bitstream_buffers
2620 * \defgroup VdpVideoMixer VdpVideoMixer; Video Post-processing \
2621 * and Compositing object
2623 * VdpVideoMixer can perform some subset of the following
2624 * post-processing steps on video:
2626 * - Various types, with or without inverse telecine
2628 * - Sharpness adjustment
2629 * - Color space conversion to RGB
2630 * - Chroma format upscaling to 4:4:4
2632 * A VdpVideoMixer takes a source \ref VdpVideoSurface
2633 * "VdpVideoSurface" VdpVideoSurface and performs various video
2634 * processing steps on it (potentially using information from
2635 * past or future video surfaces). It scales the video and
2636 * converts it to RGB, then optionally composites it with
2637 * multiple auxiliary \ref VdpOutputSurface "VdpOutputSurface"s
2638 * before writing the result to the destination \ref
2639 * VdpOutputSurface "VdpOutputSurface".
2641 * The video mixer compositing model is as follows:
2643 * - A rectangle will be rendered on an output surface. No
2644 * pixels will be rendered outside of this output rectangle.
2645 * The contents of this rectangle will be a composite of many
2648 * - The first layer is the background color. The background
2649 * color will fill the entire rectangle.
2651 * - The second layer is the processed video which has been
2652 * converted to RGB. These pixels will overwrite the
2653 * background color of the first layer except where the second
2654 * layer's rectangle does not completely cover the output
2655 * rectangle. In those regions the background color will
2656 * continue to show. If any portion of the second layer's
2657 * output rectangle is outside of the output rectangle, those
2658 * portions will be clipped.
2660 * - The third layer contains some number of auxiliary layers
2661 * (in the form of \ref VdpOutputSurface "VdpOutputSurface"s)
2662 * which will be composited using the alpha value from the
2663 * those surfaces. The compositing operations are equivalent
2664 * to rendering with \ref VdpOutputSurfaceRenderOutputSurface
2665 * using a source blend factor of SOURCE_ALPHA, a destination
2666 * blend factor of ONE_MINUS_SOURCE_ALPHA and an equation of
2673 * \brief A VdpVideoMixer feature that must be requested at
2674 * creation time to be used.
2676 * Certain advanced VdpVideoMixer features are optional, and the
2677 * ability to use those features at all must be requested when
2678 * the VdpVideoMixer object is created. Each feature is named via
2679 * a specific VdpVideoMixerFeature value.
2681 * Once requested, these features are permanently available
2682 * within that specific VdpVideoMixer object. All features that
2683 * are not explicitly requested at creation time default to
2684 * being permanently unavailable.
2686 * Even when requested, all features default to being initially
2687 * disabled. However, applications can subsequently enable and
2688 * disable features at any time. See \ref
2689 * VdpVideoMixerSetFeatureEnables.
2691 * Some features allow configuration of their operation. Each
2692 * configurable item is an \ref VdpVideoMixerAttribute. These
2693 * attributes may be manipulated at any time using \ref
2694 * VdpVideoMixerSetAttributeValues.
2696 typedef uint32_t VdpVideoMixerFeature;
2700 * \brief A VdpVideoMixerFeature.
2702 * When requested and enabled, motion adaptive temporal
2703 * deinterlacing will be used on interlaced content.
2705 * When multiple de-interlacing options are requested and
2706 * enabled, the back-end implementation chooses the best
2707 * algorithm to apply.
2709 #define VDP_VIDEO_MIXER_FEATURE_DEINTERLACE_TEMPORAL (VdpVideoMixerFeature)0
2712 * \brief A VdpVideoMixerFeature.
2714 * When requested and enabled, this enables a more advanced
2715 * version of temporal de-interlacing, that additionally uses
2716 * edge-guided spatial interpolation.
2718 * When multiple de-interlacing options are requested and
2719 * enabled, the back-end implementation chooses the best
2720 * algorithm to apply.
2722 #define VDP_VIDEO_MIXER_FEATURE_DEINTERLACE_TEMPORAL_SPATIAL (VdpVideoMixerFeature)1
2725 * \brief A VdpVideoMixerFeature.
2727 * When requested and enabled, cadence detection will be enabled
2728 * on interlaced content and the video mixer will try to extract
2729 * progressive frames from pull-down material.
2731 #define VDP_VIDEO_MIXER_FEATURE_INVERSE_TELECINE (VdpVideoMixerFeature)2
2734 * \brief A VdpVideoMixerFeature.
2736 * When requested and enabled, a noise reduction algorithm will
2737 * be applied to the video.
2739 #define VDP_VIDEO_MIXER_FEATURE_NOISE_REDUCTION (VdpVideoMixerFeature)3
2742 * \brief A VdpVideoMixerFeature.
2744 * When requested and enabled, a sharpening algorithm will be
2745 * applied to the video.
2747 #define VDP_VIDEO_MIXER_FEATURE_SHARPNESS (VdpVideoMixerFeature)4
2750 * \brief A VdpVideoMixerFeature.
2752 * When requested and enabled, the alpha of the rendered
2753 * surface, which is normally set to the alpha of the background
2754 * color, will be forced to 0.0 on pixels corresponding to
2755 * source video surface luminance values in the range specified
2756 * by attributes \ref VDP_VIDEO_MIXER_ATTRIBUTE_LUMA_KEY_MIN_LUMA
2757 * to \ref VDP_VIDEO_MIXER_ATTRIBUTE_LUMA_KEY_MAX_LUMA. This
2758 * keying is performed after scaling and de-interlacing.
2760 #define VDP_VIDEO_MIXER_FEATURE_LUMA_KEY (VdpVideoMixerFeature)5
2763 * \brief A VdpVideoMixer creation parameter.
2765 * When a VdpVideoMixer is created, certain parameters may be
2766 * supplied. Each parameter is named via a specific
2767 * VdpVideoMixerParameter value.
2769 * Each parameter has a specific type, and specific default
2770 * value if not specified at VdpVideoMixer creation time. The
2771 * application may query the legal supported range for some
2774 typedef uint32_t VdpVideoMixerParameter;
2778 * \brief The exact width of input video surfaces.
2780 * This attribute's type is uint32_t.
2782 * This parameter defaults to 0 if not specified, which entails
2783 * that it must be specified.
2785 * The application may query this parameter's supported
2788 #define VDP_VIDEO_MIXER_PARAMETER_VIDEO_SURFACE_WIDTH (VdpVideoMixerParameter)0
2791 * \brief The exact height of input video surfaces.
2793 * This attribute's type is uint32_t.
2795 * This parameter defaults to 0 if not specified, which entails
2796 * that it must be specified.
2798 * The application may query this parameter's supported
2801 #define VDP_VIDEO_MIXER_PARAMETER_VIDEO_SURFACE_HEIGHT (VdpVideoMixerParameter)1
2804 * \brief The chroma type of the input video surfaces the will
2807 * This attribute's type is VdpChromaType.
2809 * If not specified, this parameter defaults to
2810 * VDP_CHROMA_TYPE_420.
2812 * The application may not query this application's supported
2813 * range, since it is a potentially disjoint enumeration.
2815 #define VDP_VIDEO_MIXER_PARAMETER_CHROMA_TYPE (VdpVideoMixerParameter)2
2818 * \brief The number of auxiliary layers in the mixer's
2819 * compositing model.
2821 * Note that this indicates the maximum number of layers that
2822 * may be processed by a given \ref VdpVideoMixer "VdpVideoMixer"
2823 * object. Each individual \ref VdpVideoMixerRender invocation
2824 * may choose to use a different number of actual layers, from 0
2827 * This attribute's type is uint32_t.
2829 * If not specified, this parameter defaults to 0.
2831 * The application may query this parameter's supported
2834 #define VDP_VIDEO_MIXER_PARAMETER_LAYERS (VdpVideoMixerParameter)3
2837 * \brief An adjustable attribute of VdpVideoMixer operation.
2839 * Various attributes of VdpVideoMixer operation may be adjusted
2840 * at any time. Each attribute is named via a specific
2841 * VdpVideoMixerAttribute value.
2843 * Each attribute has a specific type, and specific default
2844 * value if not specified at VdpVideoMixer creation time. The
2845 * application may query the legal supported range for some
2848 typedef uint32_t VdpVideoMixerAttribute;
2852 * \brief The background color in the VdpVideoMixer's compositing
2855 * This attribute's type is VdpColor.
2857 * This parameter defaults to black (all color components 0.0
2860 * The application may not query this parameter's supported
2861 * range, since the type is not scalar.
2863 #define VDP_VIDEO_MIXER_ATTRIBUTE_BACKGROUND_COLOR (VdpVideoMixerAttribute)0
2866 * \brief The color-space conversion matrix used by the
2869 * This attribute's type is \ref VdpCSCMatrix.
2871 * Note: When using \ref VdpVideoMixerGetAttributeValues to retrieve the
2872 * current CSC matrix, the attribute_values array must contain a pointer to
2873 * a pointer a VdpCSCMatrix (VdpCSCMatrix** as a void *). The get function will
2874 * either initialize the referenced CSC matrix to the current value, *or*
2875 * clear the supplied pointer to NULL, if the previous set call supplied a
2876 * value of NULL in parameter_values, to request the default matrix.
2879 * VdpCSCMatrix matrix;
2880 * VdpCSCMatrix * matrix_ptr;
2881 * void * attribute_values[] = {&matrix_ptr};
2882 * VdpStatus st = vdp_video_mixer_get_attribute_values(..., attribute_values, ...);
2885 * This parameter defaults to a matrix suitable for ITU-R BT.601
2886 * input surfaces, with no procamp adjustments.
2888 * The application may not query this parameter's supported
2889 * range, since the type is not scalar.
2891 #define VDP_VIDEO_MIXER_ATTRIBUTE_CSC_MATRIX (VdpVideoMixerAttribute)1
2894 * \brief The amount of noise reduction algorithm to apply.
2896 * This attribute's type is float.
2898 * This parameter defaults to 0.0, which equates to no noise
2901 * The application may query this parameter's supported range.
2902 * However, the range is fixed as 0.0...1.0.
2904 #define VDP_VIDEO_MIXER_ATTRIBUTE_NOISE_REDUCTION_LEVEL (VdpVideoMixerAttribute)2
2907 * \brief The amount of sharpening, or blurring, to apply.
2909 * This attribute's type is float.
2911 * This parameter defaults to 0.0, which equates to no
2914 * Positive values request sharpening. Negative values request
2917 * The application may query this parameter's supported range.
2918 * However, the range is fixed as -1.0...1.0.
2920 #define VDP_VIDEO_MIXER_ATTRIBUTE_SHARPNESS_LEVEL (VdpVideoMixerAttribute)3
2923 * \brief The minimum luma value for the luma key algorithm.
2925 * This attribute's type is float.
2927 * This parameter defaults to 0.0.
2929 * The application may query this parameter's supported range.
2930 * However, the range is fixed as 0.0...1.0.
2932 #define VDP_VIDEO_MIXER_ATTRIBUTE_LUMA_KEY_MIN_LUMA (VdpVideoMixerAttribute)4
2935 * \brief The maximum luma value for the luma key algorithm.
2937 * This attribute's type is float.
2939 * This parameter defaults to 1.0.
2941 * The application may query this parameter's supported range.
2942 * However, the range is fixed as 0.0...1.0.
2944 #define VDP_VIDEO_MIXER_ATTRIBUTE_LUMA_KEY_MAX_LUMA (VdpVideoMixerAttribute)5
2947 * \brief Query the implementation's support for a specific
2949 * \param[in] device The device to query.
2950 * \param[in] feature The feature for which support is to be
2952 * \param[out] is_supported Is the specified feature supported?
2953 * \return VdpStatus The completion status of the operation.
2955 typedef VdpStatus VdpVideoMixerQueryFeatureSupport(
2957 VdpVideoMixerFeature feature,
2958 /* output parameters follow */
2959 VdpBool * is_supported
2963 * \brief Query the implementation's support for a specific
2965 * \param[in] device The device to query.
2966 * \param[in] parameter The parameter for which support is to be
2968 * \param[out] is_supported Is the specified parameter
2970 * \return VdpStatus The completion status of the operation.
2972 typedef VdpStatus VdpVideoMixerQueryParameterSupport(
2974 VdpVideoMixerParameter parameter,
2975 /* output parameters follow */
2976 VdpBool * is_supported
2980 * \brief Query the implementation's support for a specific
2982 * \param[in] device The device to query.
2983 * \param[in] feature The feature for which support is to be
2985 * \param[out] is_supported Is the specified feature supported?
2986 * \return VdpStatus The completion status of the operation.
2988 typedef VdpStatus VdpVideoMixerQueryAttributeSupport(
2990 VdpVideoMixerAttribute attribute,
2991 /* output parameters follow */
2992 VdpBool * is_supported
2996 * \brief Query the implementation's supported for a specific
2998 * \param[in] device The device to query.
2999 * \param[in] parameter The parameter for which support is to be
3001 * \param[out] min_value The minimum supported value.
3002 * \param[out] max_value The maximum supported value.
3003 * \return VdpStatus The completion status of the operation.
3005 typedef VdpStatus VdpVideoMixerQueryParameterValueRange(
3007 VdpVideoMixerParameter parameter,
3008 /* output parameters follow */
3014 * \brief Query the implementation's supported for a specific
3016 * \param[in] device The device to query.
3017 * \param[in] attribute The attribute for which support is to be
3019 * \param[out] min_value The minimum supported value.
3020 * \param[out] max_value The maximum supported value.
3021 * \return VdpStatus The completion status of the operation.
3023 typedef VdpStatus VdpVideoMixerQueryAttributeValueRange(
3025 VdpVideoMixerAttribute attribute,
3026 /* output parameters follow */
3032 * \brief An opaque handle representing a VdpVideoMixer object.
3034 typedef uint32_t VdpVideoMixer;
3037 * \brief Create a VdpVideoMixer.
3038 * \param[in] device The device that will contain the mixer.
3039 * \param[in] feature_count The number of features to request.
3040 * \param[in] features The list of features to request.
3041 * \param[in] parameter_count The number of parameters to set.
3042 * \param[in] parameters The list of parameters to set.
3043 * \param[in] parameter_values The values for the parameters. Note that each
3044 * entry in the value array is a pointer to the actual value. In other
3045 * words, the values themselves are not cast to "void *" and passed
3046 * "inside" the array.
3047 * \param[out] mixer The new mixer's handle.
3048 * \return VdpStatus The completion status of the operation.
3050 * Initially, all requested features will be disabled. They can
3051 * be enabled using \ref VdpVideoMixerSetFeatureEnables.
3053 * Initially, all attributes will have default values. Values
3054 * can be changed using \ref VdpVideoMixerSetAttributeValues.
3056 typedef VdpStatus VdpVideoMixerCreate(
3058 // The set of features to request
3059 uint32_t feature_count,
3060 VdpVideoMixerFeature const * features,
3061 // The parameters used during creation
3062 uint32_t parameter_count,
3063 VdpVideoMixerParameter const * parameters,
3064 void const * const * parameter_values,
3065 /* output parameters follow */
3066 VdpVideoMixer * mixer
3070 * \brief Enable or disable features.
3071 * \param[in] mixer The mixer to manipulate.
3072 * \param[in] feature_count The number of features to
3074 * \param[in] features The list of features to enable/disable.
3075 * \param[in] feature_enables The list of new feature enable
3077 * \return VdpStatus The completion status of the operation.
3079 typedef VdpStatus VdpVideoMixerSetFeatureEnables(
3080 VdpVideoMixer mixer,
3081 uint32_t feature_count,
3082 VdpVideoMixerFeature const * features,
3083 VdpBool const * feature_enables
3087 * \brief Set attribute values
3088 * \param[in] mixer The mixer to manipulate.
3089 * \param[in] attribute_count The number of attributes to set.
3090 * \param[in] attributes The list of attributes to set.
3091 * \param[in] attribute_values The values for the attributes. Note that each
3092 * entry in the value array is a pointer to the actual value. In other
3093 * words, the values themselves are not cast to "void *" and passed
3094 * "inside" the array. A NULL pointer requests that the default value be
3095 * set for that attribute.
3096 * \return VdpStatus The completion status of the operation.
3098 typedef VdpStatus VdpVideoMixerSetAttributeValues(
3099 VdpVideoMixer mixer,
3100 uint32_t attribute_count,
3101 VdpVideoMixerAttribute const * attributes,
3102 void const * const * attribute_values
3106 * \brief Retrieve whether features were requested at creation
3108 * \param[in] mixer The mixer to query.
3109 * \param[in] feature_count The number of features to query.
3110 * \param[in] features The list of features to query.
3111 * \param[out] feature_supported A list of values indicating
3112 * whether the feature was requested, and hence is
3114 * \return VdpStatus The completion status of the operation.
3116 typedef VdpStatus VdpVideoMixerGetFeatureSupport(
3117 VdpVideoMixer mixer,
3118 uint32_t feature_count,
3119 VdpVideoMixerFeature const * features,
3120 /* output parameters follow */
3121 VdpBool * feature_supports
3125 * \brief Retrieve whether features are enabled.
3126 * \param[in] mixer The mixer to manipulate.
3127 * \param[in] feature_count The number of features to query.
3128 * \param[in] features The list of features to query.
3129 * \param[out] feature_enabled A list of values indicating
3130 * whether the feature is enabled.
3131 * \return VdpStatus The completion status of the operation.
3133 typedef VdpStatus VdpVideoMixerGetFeatureEnables(
3134 VdpVideoMixer mixer,
3135 uint32_t feature_count,
3136 VdpVideoMixerFeature const * features,
3137 /* output parameters follow */
3138 VdpBool * feature_enables
3142 * \brief Retrieve parameter values given at creation time.
3143 * \param[in] mixer The mixer to manipulate.
3144 * \param[in] parameter_count The number of parameters to query.
3145 * \param[in] parameters The list of parameters to query.
3146 * \param[out] parameter_values The list of current values for
3147 * the parameters. Note that each entry in the value array is a pointer to
3148 * storage that will receive the actual value. If the attribute's type is
3149 * a pointer itself, please closely read the documentation for that
3150 * attribute type for any other data passing requirements.
3151 * \return VdpStatus The completion status of the operation.
3153 typedef VdpStatus VdpVideoMixerGetParameterValues(
3154 VdpVideoMixer mixer,
3155 uint32_t parameter_count,
3156 VdpVideoMixerParameter const * parameters,
3157 /* output parameters follow */
3158 void * const * parameter_values
3162 * \brief Retrieve current attribute values.
3163 * \param[in] mixer The mixer to manipulate.
3164 * \param[in] attribute_count The number of attributes to query.
3165 * \param[in] attributes The list of attributes to query.
3166 * \param[out] attribute_values The list of current values for
3167 * the attributes. Note that each entry in the value array is a pointer to
3168 * storage that will receive the actual value. If the attribute's type is
3169 * a pointer itself, please closely read the documentation for that
3170 * attribute type for any other data passing requirements.
3171 * \return VdpStatus The completion status of the operation.
3173 typedef VdpStatus VdpVideoMixerGetAttributeValues(
3174 VdpVideoMixer mixer,
3175 uint32_t attribute_count,
3176 VdpVideoMixerAttribute const * attributes,
3177 /* output parameters follow */
3178 void * const * attribute_values
3182 * \brief Destroy a VdpVideoMixer.
3183 * \param[in] device The device to destroy.
3184 * \return VdpStatus The completion status of the operation.
3186 typedef VdpStatus VdpVideoMixerDestroy(
3192 * \brief The structure of the picture present in a \ref
3193 * VdpVideoSurface "VdpVideoSurface".
3197 * The picture is a field, and is the top field of the surface.
3199 VDP_VIDEO_MIXER_PICTURE_STRUCTURE_TOP_FIELD,
3201 * The picture is a field, and is the bottom field of the
3204 VDP_VIDEO_MIXER_PICTURE_STRUCTURE_BOTTOM_FIELD,
3206 * The picture is a frame, and hence is the entire surface.
3208 VDP_VIDEO_MIXER_PICTURE_STRUCTURE_FRAME,
3209 } VdpVideoMixerPictureStructure;
3211 #define VDP_LAYER_VERSION 0
3214 * \brief Definition of an additional \ref VdpOutputSurface
3215 * "VdpOutputSurface" layer in the composting model.
3219 * This field must be filled with VDP_LAYER_VERSION
3221 uint32_t struct_version;
3223 * The surface to composite from.
3225 VdpOutputSurface source_surface;
3227 * The sub-rectangle of the source surface to use. If NULL, the
3228 * entire source surface will be used.
3230 VdpRect const * source_rect;
3232 * The sub-rectangle of the destination surface to map
3233 * this layer into. This rectangle is relative to the entire
3234 * destination surface. This rectangle will be clipped by \ref
3235 * VdpVideoMixerRender's \b destination_rect. If NULL, the
3236 * destination rectangle will be sized to match the source
3237 * rectangle, and will be located at the origin.
3239 VdpRect const * destination_rect;
3243 * \brief Perform a video post-processing and compositing
3245 * \param[in] mixer The mixer object that will perform the
3246 * mixing/rendering operation.
3247 * \param[in] background_surface A background image. If set to any value other
3248 * than VDP_INVALID_HANDLE, the specific surface will be used instead of
3249 * the background color as the first layer in the mixer's compositing
3251 * \param[in] background_source_rect When background_surface is specified,
3252 * this parameter indicates the portion of background_surface that will
3253 * be used as the background layer. The specified region will be
3254 * extracted and scaled to match the size of destination_rect. If NULL,
3255 * the entire background_surface will be used.
3256 * \param[in] current_picture_structure The picture structure of
3257 * the field/frame to be processed. This field/frame is
3258 * presented in the \b video_surface_current parameter. If
3259 * frame, then all \b video_surface_* parameters are
3260 * assumed to be frames. If field, then all
3261 * video_surface_* parameters are assumed to be fields,
3262 * with alternating top/bottom-ness derived from
3263 * video_surface_current.
3264 * \param[in] video_surfaces_past_count The number of provided
3265 * fields/frames prior to the current picture.
3266 * \param[in] video_surfaces_past The fields/frames prior to the
3267 * current field/frame. Note that array index 0 is the
3268 * field/frame temporally nearest to the current
3269 * field/frame, with increasing array indices used for
3270 * older frames. Unavailable entries may be set to
3271 * \ref VDP_INVALID_HANDLE.
3272 * \param[in] video_surface_current The field/frame to be
3274 * \param[in] video_surfaces_future_count The number of provided
3275 * fields/frames following the current picture.
3276 * \param[in] video_surfaces_future The fields/frames that
3277 * follow the current field/frame. Note that array index 0
3278 * is the field/frame temporally nearest to the current
3279 * field/frame, with increasing array indices used for
3280 * newer frames. Unavailable entries may be set to \ref
3281 * VDP_INVALID_HANDLE.
3282 * \param[in] video_source_rect The sub-rectangle of the source
3283 * video surface to extract and process. If NULL, the
3284 * entire surface will be used.
3285 * \param[in] destination_surface
3286 * \param[in] destination_rect The sub-rectangle of the
3287 * destination surface to modify. Note that rectangle clips
3288 * all other actions.
3289 * \param[in] destination_video_rect The sub-rectangle of the
3290 * destination surface that will contain the processed
3291 * video. This rectangle is relative to the entire
3292 * destination surface. This rectangle is clipped by \b
3293 * destination_rect. If NULL, the destination rectangle
3294 * will be sized to match the source rectangle, and will
3295 * be located at the origin.
3296 * \param[in] layer_count The number of additional layers to
3297 * composite above the video.
3298 * \param[in] layers The array of additional layers to composite
3300 * \return VdpStatus The completion status of the operation.
3302 * For a complete discussion of how to use this API, please see
3303 * \ref video_mixer_usage.
3305 typedef VdpStatus VdpVideoMixerRender(
3306 VdpVideoMixer mixer,
3307 VdpOutputSurface background_surface,
3308 VdpRect const * background_source_rect,
3309 VdpVideoMixerPictureStructure current_picture_structure,
3310 uint32_t video_surface_past_count,
3311 VdpVideoSurface const * video_surface_past,
3312 VdpVideoSurface video_surface_current,
3313 uint32_t video_surface_future_count,
3314 VdpVideoSurface const * video_surface_future,
3315 VdpRect const * video_source_rect,
3316 VdpOutputSurface destination_surface,
3317 VdpRect const * destination_rect,
3318 VdpRect const * destination_video_rect,
3319 uint32_t layer_count,
3320 VdpLayer const * layers
3326 * \defgroup VdpPresentationQueue VdpPresentationQueue; Video \
3327 * presentation (display) object
3329 * The VdpPresentationQueue manages a queue of surfaces and
3330 * associated timestamps. For each surface in the queue, once
3331 * the associated timestamp is reached, the surface is displayed
3332 * to the user. This timestamp-based approach yields high
3333 * quality video delivery.
3335 * The exact location of the displayed content is Window System
3336 * specific. For this reason, the \ref api_winsys provides an
3337 * API to create a \ref VdpPresentationQueueTarget object (e.g.
3338 * via \ref VdpPresentationQueueTargetCreateX11) which
3339 * encapsulates this information.
3341 * Note that the presentation queue performs no scaling of
3342 * surfaces to match the display target's size, aspect ratio,
3345 * Surfaces that are too large to fit into the display target
3346 * will be clipped. Surfaces that are too small to fill the
3347 * display target will be aligned to the top-left corner of the
3348 * display target, with the balance of the display target being
3349 * filled with a constant configurable "background" color.
3351 * Note that the presentation queue operates in a manner that is
3352 * semantically equivalent to an overlay surface, with any
3353 * required color key painting hidden internally. However,
3354 * implementations are free to use whatever semantically
3355 * equivalent technique they wish. Note that implementations
3356 * that actually use color-keyed overlays will typically use
3357 * the "background" color as the overlay color key value, so
3358 * this color should be chosen with care.
3364 * \brief The representation of a point in time.
3366 * VdpTime timestamps are intended to be a high-precision timing
3367 * system, potentially independent from any other time domain in
3370 * Time is represented in units of nanoseconds. The origin
3371 * (i.e. the time represented by a value of 0) is implementation
3374 typedef uint64_t VdpTime;
3377 * \brief An opaque handle representing the location where
3378 * video will be presented.
3380 * VdpPresentationQueueTarget are created using a \ref api_winsys
3381 * specific API, such as \ref
3382 * VdpPresentationQueueTargetCreateX11.
3384 typedef uint32_t VdpPresentationQueueTarget;
3387 * \brief Destroy a VdpPresentationQueueTarget.
3388 * \param[in] presentation_queue_target The target to destroy.
3389 * \return VdpStatus The completion status of the operation.
3391 typedef VdpStatus VdpPresentationQueueTargetDestroy(
3392 VdpPresentationQueueTarget presentation_queue_target
3396 * \brief An opaque handle representing a presentation queue
3399 typedef uint32_t VdpPresentationQueue;
3402 * \brief Create a VdpPresentationQueue.
3403 * \param[in] device The device that will contain the queue.
3404 * \param[in] presentation_queue_target The location to display
3406 * \param[out] presentation_queue The new queue's handle.
3407 * \return VdpStatus The completion status of the operation.
3409 * Note: The initial value for the background color will be set to
3410 * an implementation-defined value.
3412 typedef VdpStatus VdpPresentationQueueCreate(
3414 VdpPresentationQueueTarget presentation_queue_target,
3415 /* output parameters follow */
3416 VdpPresentationQueue * presentation_queue
3420 * \brief Destroy a VdpPresentationQueue.
3421 * \param[in] presentation_queue The queue to destroy.
3422 * \return VdpStatus The completion status of the operation.
3424 typedef VdpStatus VdpPresentationQueueDestroy(
3425 VdpPresentationQueue presentation_queue
3429 * \brief Configure the background color setting.
3430 * \param[in] presentation_queue The queue to manipulate.
3431 * \param[in] background_color The new background color.
3433 * Note: Implementations may choose whether to apply the
3434 * new background color value immediately, or defer it until
3435 * the next surface is presented.
3437 typedef VdpStatus VdpPresentationQueueSetBackgroundColor(
3438 VdpPresentationQueue presentation_queue,
3439 VdpColor * const background_color
3443 * \brief Retrieve the current background color setting.
3444 * \param[in] presentation_queue The queue to query.
3445 * \param[out] background_color The current background color.
3447 typedef VdpStatus VdpPresentationQueueGetBackgroundColor(
3448 VdpPresentationQueue presentation_queue,
3449 VdpColor * background_color
3453 * \brief Retrieve the presentation queue's "current" time.
3454 * \param[in] presentation_queue The queue to query.
3455 * \param[out] current_time The current time, which may
3456 * represent a point between display VSYNC events.
3457 * \return VdpStatus The completion status of the operation.
3459 typedef VdpStatus VdpPresentationQueueGetTime(
3460 VdpPresentationQueue presentation_queue,
3461 /* output parameters follow */
3462 VdpTime * current_time
3466 * \brief Enter a surface into the presentation queue.
3467 * \param[in] presentation_queue The queue to query.
3468 * \param[in] surface The surface to enter into the queue.
3469 * \param[in] clip_width If set to a non-zero value, the presentation queue
3470 * will display only clip_width pixels of the surface (anchored to the
3471 * top-left corner of the surface.
3472 * \param[in] clip_height If set to a non-zero value, the presentation queue
3473 * will display only clip_height lines of the surface (anchored to the
3474 * top-left corner of the surface.
3475 * \param[in] earliest_presentation_time The timestamp
3476 * associated with the surface. The presentation queue
3477 * will not display the surface until the presentation
3478 * queue's current time is at least this value.
3479 * \return VdpStatus The completion status of the operation.
3481 * Applications may choose to allow resizing of the presentation queue target
3482 * (which may be e.g. a regular Window when using an X11-based
3485 * \b clip_width and \b clip_height may be used to limit the size of the
3486 * displayed region of a surface, in order to match the specific region that
3489 * In turn, this allows the application to allocate over-sized (e.g.
3490 * screen-sized) surfaces, but render to a region that matches the current
3491 * size of the video window.
3493 * Using this technique, an application's response to window resizing may
3494 * simply be to render to, and display, a different region of the surface,
3495 * rather than de-/re-allocation of surfaces to match the updated window size.
3497 typedef VdpStatus VdpPresentationQueueDisplay(
3498 VdpPresentationQueue presentation_queue,
3499 VdpOutputSurface surface,
3500 uint32_t clip_width,
3501 uint32_t clip_height,
3502 VdpTime earliest_presentation_time
3506 * \brief Wait for a surface to finish being displayed.
3507 * \param[in] presentation_queue The queue to query.
3508 * \param[in] surface The surface to wait for.
3509 * \param[out] first_presentation_time The timestamp of the
3510 * VSYNC at which this surface was first displayed. Note
3511 * that 0 means the surface was never displayed.
3512 * \return VdpStatus The completion status of the operation.
3514 * Note that this API will block indefinitely if queried about
3515 * the surface most recently added to a presentation queue,
3516 * since there is no other surface that could possibly replace
3517 * the queried surface.
3519 typedef VdpStatus VdpPresentationQueueBlockUntilSurfaceIdle(
3520 VdpPresentationQueue presentation_queue,
3521 VdpOutputSurface surface,
3522 /* output parameters follow */
3523 VdpTime * first_presentation_time
3528 * \brief The status of a surface within a presentation queue.
3531 /** The surface is no queued or currently visible. */
3532 VDP_PRESENTATION_QUEUE_STATUS_IDLE,
3533 /** The surface is in the queue, and not currently visible. */
3534 VDP_PRESENTATION_QUEUE_STATUS_QUEUED,
3535 /** The surface is the currently visible surface. */
3536 VDP_PRESENTATION_QUEUE_STATUS_VISIBLE,
3537 } VdpPresentationQueueStatus;
3540 * \brief Poll the current queue status of a surface.
3541 * \param[in] presentation_queue The queue to query.
3542 * \param[in] surface The surface to query.
3543 * \param[out] status The current status of the surface within
3545 * \param[out] first_presentation_time The timestamp of the
3546 * VSYNC at which this surface was first displayed. Note
3547 * that 0 means the surface was never displayed.
3548 * \return VdpStatus The completion status of the operation.
3550 typedef VdpStatus VdpPresentationQueueQuerySurfaceStatus(
3551 VdpPresentationQueue presentation_queue,
3552 VdpOutputSurface surface,
3553 /* output parameters follow */
3554 VdpPresentationQueueStatus * status,
3555 VdpTime * first_presentation_time
3561 * \defgroup display_preemption Display Preemption
3563 * The Window System may operate within a frame-work (such as
3564 * Linux's VT switching) where the display is shared between the
3565 * Window System (e.g. X) and some other output mechanism (e.g.
3566 * the VT.) Given this scenario, the Window System's control of
3567 * the display could be preempted, and restored, at any time.
3569 * VDPAU does not mandate that implementations hide such
3570 * preemptions from VDPAU client applications; doing so may
3571 * impose extreme burdens upon VDPAU implementations. Equally,
3572 * however, implementations are free to hide such preemptions
3573 * from client applications.
3575 * VDPAU allows implementations to inform the client application
3576 * when such a preemption has occurred, and then refuse to
3577 * continue further operation.
3579 * Similarly, some form of fatal hardware error could prevent further
3580 * operation of the VDPAU implementation, without a complete
3581 * re-initialization.
3583 * The following discusses the behavior of implementations that
3584 * choose not to hide preemption from client applications.
3586 * When preemption occurs, VDPAU internally destroys all
3587 * objects; the client application need not do this. However, if
3588 * the client application wishes to continue operation, it must
3589 * recreate all objects that it uses. It is probable that this
3590 * recreation will not succeed until the display ownership is
3591 * restored to the Window System.
3593 * Once preemption has occurred, all VDPAU entry points will
3594 * return the specific error code \ref
3595 * VDP_STATUS_DISPLAY_PREEMPTED.
3597 * VDPAU client applications may also be notified of such
3598 * preemptions and fatal errors via a callback. See \ref
3599 * VdpPreemptionCallbackRegister for more details.
3605 * \brief A callback to notify the client application that a
3606 * device's display has been preempted.
3607 * \param[in] device The device that had its display preempted.
3608 * \param[in] context The client-supplied callback context
3610 * \return void No return value
3612 typedef void VdpPreemptionCallback(
3618 * \brief Configure the display preemption callback.
3619 * \param[in] device The device to be monitored for preemption.
3620 * \param[in] callback The client application's callback
3621 * function. If NULL, the callback is unregistered.
3622 * \param[in] context The client-supplied callback context
3623 * information. This information will be passed to the
3624 * callback function if/when invoked.
3625 * \return VdpStatus The completion status of the operation.
3627 typedef VdpStatus VdpPreemptionCallbackRegister(
3629 VdpPreemptionCallback callback,
3636 * \defgroup get_proc_address Entry Point Retrieval
3638 * In order to facilitate multiple implementations of VDPAU
3639 * co-existing within a single process, all functionality is
3640 * available via function pointers. The mechanism to retrieve
3641 * those function pointers is described below.
3647 * \brief A type suitable for \ref VdpGetProcAddress
3648 * "VdpGetProcAddress"'s \b function_id parameter.
3650 typedef uint32_t VdpFuncId;
3652 /** \hideinitializer */
3653 #define VDP_FUNC_ID_GET_ERROR_STRING (VdpFuncId)0
3654 /** \hideinitializer */
3655 #define VDP_FUNC_ID_GET_PROC_ADDRESS (VdpFuncId)1
3656 /** \hideinitializer */
3657 #define VDP_FUNC_ID_GET_API_VERSION (VdpFuncId)2
3658 /** \hideinitializer */
3659 #define VDP_FUNC_ID_GET_INFORMATION_STRING (VdpFuncId)4
3660 /** \hideinitializer */
3661 #define VDP_FUNC_ID_DEVICE_DESTROY (VdpFuncId)5
3662 /** \hideinitializer */
3663 #define VDP_FUNC_ID_GENERATE_CSC_MATRIX (VdpFuncId)6
3664 /** \hideinitializer */
3665 #define VDP_FUNC_ID_VIDEO_SURFACE_QUERY_CAPABILITIES (VdpFuncId)7
3666 /** \hideinitializer */
3667 #define VDP_FUNC_ID_VIDEO_SURFACE_QUERY_GET_PUT_BITS_Y_CB_CR_CAPABILITIES (VdpFuncId)8
3668 /** \hideinitializer */
3669 #define VDP_FUNC_ID_VIDEO_SURFACE_CREATE (VdpFuncId)9
3670 /** \hideinitializer */
3671 #define VDP_FUNC_ID_VIDEO_SURFACE_DESTROY (VdpFuncId)10
3672 /** \hideinitializer */
3673 #define VDP_FUNC_ID_VIDEO_SURFACE_GET_PARAMETERS (VdpFuncId)11
3674 /** \hideinitializer */
3675 #define VDP_FUNC_ID_VIDEO_SURFACE_GET_BITS_Y_CB_CR (VdpFuncId)12
3676 /** \hideinitializer */
3677 #define VDP_FUNC_ID_VIDEO_SURFACE_PUT_BITS_Y_CB_CR (VdpFuncId)13
3678 /** \hideinitializer */
3679 #define VDP_FUNC_ID_OUTPUT_SURFACE_QUERY_CAPABILITIES (VdpFuncId)14
3680 /** \hideinitializer */
3681 #define VDP_FUNC_ID_OUTPUT_SURFACE_QUERY_GET_PUT_BITS_NATIVE_CAPABILITIES (VdpFuncId)15
3682 /** \hideinitializer */
3683 #define VDP_FUNC_ID_OUTPUT_SURFACE_QUERY_PUT_BITS_INDEXED_CAPABILITIES (VdpFuncId)16
3684 /** \hideinitializer */
3685 #define VDP_FUNC_ID_OUTPUT_SURFACE_QUERY_PUT_BITS_Y_CB_CR_CAPABILITIES (VdpFuncId)17
3686 /** \hideinitializer */
3687 #define VDP_FUNC_ID_OUTPUT_SURFACE_CREATE (VdpFuncId)18
3688 /** \hideinitializer */
3689 #define VDP_FUNC_ID_OUTPUT_SURFACE_DESTROY (VdpFuncId)19
3690 /** \hideinitializer */
3691 #define VDP_FUNC_ID_OUTPUT_SURFACE_GET_PARAMETERS (VdpFuncId)20
3692 /** \hideinitializer */
3693 #define VDP_FUNC_ID_OUTPUT_SURFACE_GET_BITS_NATIVE (VdpFuncId)21
3694 /** \hideinitializer */
3695 #define VDP_FUNC_ID_OUTPUT_SURFACE_PUT_BITS_NATIVE (VdpFuncId)22
3696 /** \hideinitializer */
3697 #define VDP_FUNC_ID_OUTPUT_SURFACE_PUT_BITS_INDEXED (VdpFuncId)23
3698 /** \hideinitializer */
3699 #define VDP_FUNC_ID_OUTPUT_SURFACE_PUT_BITS_Y_CB_CR (VdpFuncId)24
3700 /** \hideinitializer */
3701 #define VDP_FUNC_ID_BITMAP_SURFACE_QUERY_CAPABILITIES (VdpFuncId)25
3702 /** \hideinitializer */
3703 #define VDP_FUNC_ID_BITMAP_SURFACE_CREATE (VdpFuncId)26
3704 /** \hideinitializer */
3705 #define VDP_FUNC_ID_BITMAP_SURFACE_DESTROY (VdpFuncId)27
3706 /** \hideinitializer */
3707 #define VDP_FUNC_ID_BITMAP_SURFACE_GET_PARAMETERS (VdpFuncId)28
3708 /** \hideinitializer */
3709 #define VDP_FUNC_ID_BITMAP_SURFACE_PUT_BITS_NATIVE (VdpFuncId)29
3710 /** \hideinitializer */
3711 #define VDP_FUNC_ID_OUTPUT_SURFACE_RENDER_OUTPUT_SURFACE (VdpFuncId)33
3712 /** \hideinitializer */
3713 #define VDP_FUNC_ID_OUTPUT_SURFACE_RENDER_BITMAP_SURFACE (VdpFuncId)34
3714 /** \hideinitializer */
3715 #define VDP_FUNC_ID_OUTPUT_SURFACE_RENDER_VIDEO_SURFACE_LUMA (VdpFuncId)35
3716 /** \hideinitializer */
3717 #define VDP_FUNC_ID_DECODER_QUERY_CAPABILITIES (VdpFuncId)36
3718 /** \hideinitializer */
3719 #define VDP_FUNC_ID_DECODER_CREATE (VdpFuncId)37
3720 /** \hideinitializer */
3721 #define VDP_FUNC_ID_DECODER_DESTROY (VdpFuncId)38
3722 /** \hideinitializer */
3723 #define VDP_FUNC_ID_DECODER_GET_PARAMETERS (VdpFuncId)39
3724 /** \hideinitializer */
3725 #define VDP_FUNC_ID_DECODER_RENDER (VdpFuncId)40
3726 /** \hideinitializer */
3727 #define VDP_FUNC_ID_VIDEO_MIXER_QUERY_FEATURE_SUPPORT (VdpFuncId)41
3728 /** \hideinitializer */
3729 #define VDP_FUNC_ID_VIDEO_MIXER_QUERY_PARAMETER_SUPPORT (VdpFuncId)42
3730 /** \hideinitializer */
3731 #define VDP_FUNC_ID_VIDEO_MIXER_QUERY_ATTRIBUTE_SUPPORT (VdpFuncId)43
3732 /** \hideinitializer */
3733 #define VDP_FUNC_ID_VIDEO_MIXER_QUERY_PARAMETER_VALUE_RANGE (VdpFuncId)44
3734 /** \hideinitializer */
3735 #define VDP_FUNC_ID_VIDEO_MIXER_QUERY_ATTRIBUTE_VALUE_RANGE (VdpFuncId)45
3736 /** \hideinitializer */
3737 #define VDP_FUNC_ID_VIDEO_MIXER_CREATE (VdpFuncId)46
3738 /** \hideinitializer */
3739 #define VDP_FUNC_ID_VIDEO_MIXER_SET_FEATURE_ENABLES (VdpFuncId)47
3740 /** \hideinitializer */
3741 #define VDP_FUNC_ID_VIDEO_MIXER_SET_ATTRIBUTE_VALUES (VdpFuncId)48
3742 /** \hideinitializer */
3743 #define VDP_FUNC_ID_VIDEO_MIXER_GET_FEATURE_SUPPORT (VdpFuncId)49
3744 /** \hideinitializer */
3745 #define VDP_FUNC_ID_VIDEO_MIXER_GET_FEATURE_ENABLES (VdpFuncId)50
3746 /** \hideinitializer */
3747 #define VDP_FUNC_ID_VIDEO_MIXER_GET_PARAMETER_VALUES (VdpFuncId)51
3748 /** \hideinitializer */
3749 #define VDP_FUNC_ID_VIDEO_MIXER_GET_ATTRIBUTE_VALUES (VdpFuncId)52
3750 /** \hideinitializer */
3751 #define VDP_FUNC_ID_VIDEO_MIXER_DESTROY (VdpFuncId)53
3752 /** \hideinitializer */
3753 #define VDP_FUNC_ID_VIDEO_MIXER_RENDER (VdpFuncId)54
3754 /** \hideinitializer */
3755 #define VDP_FUNC_ID_PRESENTATION_QUEUE_TARGET_DESTROY (VdpFuncId)55
3756 /** \hideinitializer */
3757 #define VDP_FUNC_ID_PRESENTATION_QUEUE_CREATE (VdpFuncId)56
3758 /** \hideinitializer */
3759 #define VDP_FUNC_ID_PRESENTATION_QUEUE_DESTROY (VdpFuncId)57
3760 /** \hideinitializer */
3761 #define VDP_FUNC_ID_PRESENTATION_QUEUE_SET_BACKGROUND_COLOR (VdpFuncId)58
3762 /** \hideinitializer */
3763 #define VDP_FUNC_ID_PRESENTATION_QUEUE_GET_BACKGROUND_COLOR (VdpFuncId)59
3764 /** \hideinitializer */
3765 #define VDP_FUNC_ID_PRESENTATION_QUEUE_GET_TIME (VdpFuncId)62
3766 /** \hideinitializer */
3767 #define VDP_FUNC_ID_PRESENTATION_QUEUE_DISPLAY (VdpFuncId)63
3768 /** \hideinitializer */
3769 #define VDP_FUNC_ID_PRESENTATION_QUEUE_BLOCK_UNTIL_SURFACE_IDLE (VdpFuncId)64
3770 /** \hideinitializer */
3771 #define VDP_FUNC_ID_PRESENTATION_QUEUE_QUERY_SURFACE_STATUS (VdpFuncId)65
3772 /** \hideinitializer */
3773 #define VDP_FUNC_ID_PREEMPTION_CALLBACK_REGISTER (VdpFuncId)66
3775 #define VDP_FUNC_ID_BASE_WINSYS 0x1000
3778 * \brief Retrieve a VDPAU function pointer.
3779 * \param[in] device The device that the function will operate
3781 * \param[in] function_id The specific function to retrieve.
3782 * \param[out] function_pointer The actual pointer for the
3783 * application to call.
3784 * \return VdpStatus The completion status of the operation.
3786 typedef VdpStatus VdpGetProcAddress(
3788 VdpFuncId function_id,
3789 /* output parameters follow */
3790 void * * function_pointer
3797 * \defgroup api_winsys Window System Integration Layer
3799 * The set of VDPAU functionality specific to an individual