1 /* 2 * This source file is documented using Doxygen markup. 3 * See http://www.stack.nl/~dimitri/doxygen/ 4 */ 5 6 /* 7 * This copyright notice applies to this header file: 8 * 9 * Copyright (c) 2008-2015 NVIDIA Corporation 10 * 11 * Permission is hereby granted, free of charge, to any person 12 * obtaining a copy of this software and associated documentation 13 * files (the "Software"), to deal in the Software without 14 * restriction, including without limitation the rights to use, 15 * copy, modify, merge, publish, distribute, sublicense, and/or sell 16 * copies of the Software, and to permit persons to whom the 17 * Software is furnished to do so, subject to the following 18 * conditions: 19 * 20 * The above copyright notice and this permission notice shall be 21 * included in all copies or substantial portions of the Software. 22 * 23 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 24 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 25 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 26 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 27 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 28 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 29 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 30 * OTHER DEALINGS IN THE SOFTWARE. 31 */ 32 33 /** 34 * \mainpage Video Decode and Presentation API for Unix 35 * 36 * \section intro Introduction 37 * 38 * The Video Decode and Presentation API for Unix (VDPAU) provides 39 * a complete solution for decoding, post-processing, compositing, 40 * and displaying compressed or uncompressed video streams. These 41 * video streams may be combined (composited) with bitmap content, 42 * to implement OSDs and other application user interfaces. 43 * 44 * \section api_partitioning API Partitioning 45 * 46 * VDPAU is split into two distinct modules: 47 * - \ref api_core 48 * - \ref api_winsys 49 * 50 * The intent is that most VDPAU functionality exists and 51 * operates identically across all possible Windowing Systems. 52 * This functionality is the \ref api_core. 53 * 54 * However, a small amount of functionality must be included that 55 * is tightly coupled to the underlying Windowing System. This 56 * functionality is the \ref api_winsys. Possibly examples 57 * include: 58 * - Creation of the initial VDPAU \ref VdpDevice "VdpDevice" 59 * handle, since this act requires intimate knowledge of the 60 * underlying Window System, such as specific display handle or 61 * driver identification. 62 * - Conversion of VDPAU surfaces to/from underlying Window 63 * System surface types, e.g. to allow manipulation of 64 * VDPAU-generated surfaces via native Window System APIs. 65 * 66 * \section objects Object Types 67 * 68 * VDPAU is roughly object oriented; most functionality is 69 * exposed by creating an object (handle) of a certain class 70 * (type), then executing various functions against that handle. 71 * The set of object classes supported, and their purpose, is 72 * discussed below. 73 * 74 * \subsection device_type Device Type 75 * 76 * A \ref VdpDevice "VdpDevice" is the root object in VDPAU's 77 * object system. The \ref api_winsys allows creation of a \ref 78 * VdpDevice "VdpDevice" object handle, from which all other API 79 * entry points can be retrieved and invoked. 80 * 81 * \subsection surface_types Surface Types 82 * 83 * A surface stores pixel information. Various types of surfaces 84 * existing for different purposes: 85 * 86 * - \ref VdpVideoSurface "VdpVideoSurface"s store decompressed 87 * YCbCr video frames in an implementation-defined internal 88 * format. 89 * - \ref VdpOutputSurface "VdpOutputSurface"s store RGB 4:4:4 90 * data. They are legal render targets for video 91 * post-processing and compositing operations. 92 * - \ref VdpBitmapSurface "VdpBitmapSurface"s store RGB 4:4:4 93 * data. These surfaces are designed to contain read-only 94 * bitmap data, to be used for OSD or application UI 95 * compositing. 96 * 97 * \subsection transfer_types Transfer Types 98 * 99 * A data transfer object reads data from a surface (or 100 * surfaces), processes it, and writes the result to another 101 * surface. Various types of processing are possible: 102 * 103 * - \ref VdpDecoder "VdpDecoder" objects process compressed video 104 * data, and generate decompressed images. 105 * - \ref VdpOutputSurface "VdpOutputSurface"s have their own \ref 106 * VdpOutputSurfaceRender "rendering functionality". 107 * - \ref VdpVideoMixer "VdpVideoMixer" objects perform video 108 * post-processing, de-interlacing, and compositing. 109 * - \ref VdpPresentationQueue "VdpPresentationQueue" is 110 * responsible for timestamp-based display of surfaces. 111 * 112 * \section data_flow Data Flow 113 * 114 * Compressed video data originates in the application's memory 115 * space. This memory is typically obtained using \c malloc, and 116 * filled via regular file or network read system calls. 117 * Alternatively, the application may \c mmap a file. 118 * 119 * The compressed data is then processed using a \ref VdpDecoder 120 * "VdpDecoder", which will decompress the field or frame, 121 * and write the result into a \ref VdpVideoSurface 122 * "VdpVideoSurface". This action may require reading pixel data 123 * from some number of other \ref VdpVideoSurface "VdpVideoSurface" 124 * objects, depending on the type of compressed data and 125 * field/frame in question. 126 * 127 * If the application wishes to display any form of OSD or 128 * user-interface, this must be created in a \ref 129 * VdpOutputSurface "VdpOutputSurface". 130 * 131 * This process begins with the creation of \ref VdpBitmapSurface 132 * "VdpBitmapSurface" objects to contain the OSD/UI's static data, 133 * such as individual glyphs. 134 * 135 * \ref VdpOutputSurface "VdpOutputSurface" \ref 136 * VdpOutputSurfaceRender "rendering functionality" may be used 137 * to composite together various \ref VdpBitmapSurface 138 * "VdpBitmapSurface"s and \ref VdpOutputSurface 139 * "VdpOutputSurface"s, into another VdpOutputSurface 140 * "VdpOutputSurface". 141 * 142 * Once video has been decoded, it must be post-processed. This 143 * involves various steps such as color space conversion, 144 * de-interlacing, and other video adjustments. This step is 145 * performed using an \ref VdpVideoMixer "VdpVideoMixer" object. 146 * This object can not only perform the aforementioned video 147 * post-processing, but also composite the video with a number of 148 * \ref VdpOutputSurface "VdpOutputSurface"s, thus allowing complex 149 * user interfaces to be built. The final result is written into 150 * another \ref VdpOutputSurface "VdpOutputSurface". 151 * 152 * Note that at this point, the resultant \ref VdpOutputSurface 153 * "VdpOutputSurface" may be fed back through the above path, 154 * either using \ref VdpOutputSurface "VdpOutputSurface" \ref 155 * VdpOutputSurfaceRender "rendering functionality", 156 * or as input to the \ref VdpVideoMixer "VdpVideoMixer" object. 157 * 158 * Finally, the resultant \ref VdpOutputSurface 159 * "VdpOutputSurface" must be displayed on screen. This is the job 160 * of the \ref VdpPresentationQueue "VdpPresentationQueue" object. 161 * 162 * \image html vdpau_data_flow.png 163 * 164 * \section entry_point_retrieval Entry Point Retrieval 165 * 166 * VDPAU is designed so that multiple implementations can be 167 * used without application changes. For example, VDPAU could be 168 * hosted on X11, or via direct GPU access. 169 * 170 * The key technology behind this is the use of function 171 * pointers and a "get proc address" style API for all entry 172 * points. Put another way, functions are not called directly 173 * via global symbols set up by the linker, but rather through 174 * pointers. 175 * 176 * In practical terms, the \ref api_winsys provides factory 177 * functions which not only create and return \ref VdpDevice 178 * "VdpDevice" objects, but also a function pointer to a \ref 179 * VdpGetProcAddress function, through which all entry point 180 * function pointers will be retrieved. 181 * 182 * \subsection entry_point_philosophy Philosophy 183 * 184 * It is entirely possible to envisage a simpler scheme whereby 185 * such function pointers are hidden. That is, the application 186 * would link against a wrapper library that exposed "real" 187 * functions. The application would then call such functions 188 * directly, by symbol, like any other function. The wrapper 189 * library would handle loading the appropriate back-end, and 190 * implementing a similar "get proc address" scheme internally. 191 * 192 * However, the above scheme does not work well in the context 193 * of separated \ref api_core and \ref api_winsys. In this 194 * scenario, one would require a separate wrapper library per 195 * Window System, since each Window System would have a 196 * different function name and prototype for the main factory 197 * function. If an application then wanted to be Window System 198 * agnostic (making final determination at run-time via some 199 * form of plugin), it may then need to link against two 200 * wrapper libraries, which would cause conflicts for all 201 * symbols other than the main factory function. 202 * 203 * Another disadvantage of the wrapper library approach is the 204 * extra level of function call required; the wrapper library 205 * would internally implement the existing "get proc address" 206 * and "function pointer" style dispatch anyway. Exposing this 207 * directly to the application is slightly more efficient. 208 * 209 * \section threading Multi-threading 210 * 211 * All VDPAU functionality is fully thread-safe; any number of 212 * threads may call into any VDPAU functions at any time. VDPAU 213 * may not be called from signal-handlers. 214 * 215 * Note, however, that this simply guarantees that internal 216 * VDPAU state will not be corrupted by thread usage, and that 217 * crashes and deadlocks will not occur. Completely arbitrary 218 * thread usage may not generate the results that an application 219 * desires. In particular, care must be taken when multiple 220 * threads are performing operations on the same VDPAU objects. 221 * 222 * VDPAU implementations guarantee correct flow of surface 223 * content through the rendering pipeline, but only when 224 * function calls that read from or write to a surface return to 225 * the caller prior to any thread calling any other function(s) 226 * that read from or write to the surface. Invoking multiple 227 * reads from a surface in parallel is OK. 228 * 229 * Note that this restriction is placed upon VDPAU function 230 * invocations, and specifically not upon any back-end 231 * hardware's physical rendering operations. VDPAU 232 * implementations are expected to internally synchronize such 233 * hardware operations. 234 * 235 * In a single-threaded application, the above restriction comes 236 * naturally; each function call completes before it is possible 237 * to begin a new function call. 238 * 239 * In a multi-threaded application, threads may need to be 240 * synchronized. For example, consider the situation where: 241 * 242 * - Thread 1 is parsing compressed video data, passing them 243 * through a \ref VdpDecoder "VdpDecoder" object, and filling a 244 * ring-buffer of \ref VdpVideoSurface "VdpVideoSurface"s 245 * - Thread 2 is consuming those \ref VdpVideoSurface 246 * "VdpVideoSurface"s, and using a \ref VdpVideoMixer 247 * "VdpVideoMixer" to process them and composite them with UI. 248 * 249 * In this case, the threads must synchronize to ensure that 250 * thread 1's call to \ref VdpDecoderRender has returned prior to 251 * thread 2's call(s) to \ref VdpVideoMixerRender that use that 252 * specific surface. This could be achieved using the following 253 * pseudo-code: 254 * 255 * \code 256 * Queue<VdpVideoSurface> q_full_surfaces; 257 * Queue<VdpVideoSurface> q_empty_surfaces; 258 * 259 * thread_1() { 260 * for (;;) { 261 * VdpVideoSurface s = q_empty_surfaces.get(); 262 * // Parse compressed stream here 263 * VdpDecoderRender(s, ...); 264 * q_full_surfaces.put(s); 265 * } 266 * } 267 * 268 * // This would need to be more complex if 269 * // VdpVideoMixerRender were to be provided with more 270 * // than one field/frame at a time. 271 * thread_2() { 272 * for (;;) { 273 * // Possibly, other rendering operations to mixer 274 * // layer surfaces here. 275 * VdpOutputSurface t = ...; 276 * VdpPresentationQueueBlockUntilSurfaceIdle(t); 277 * VdpVideoSurface s = q_full_surfaces.get(); 278 * VdpVideoMixerRender(s, t, ...); 279 * q_empty_surfaces.put(s); 280 * // Possibly, other rendering operations to "t" here 281 * VdpPresentationQueueDisplay(t, ...); 282 * } 283 * } 284 * \endcode 285 * 286 * Finally, note that VDPAU makes no guarantees regarding any 287 * level of parallelism in any given implementation. Put another 288 * way, use of multi-threading is not guaranteed to yield any 289 * performance gain, and in theory could even slightly reduce 290 * performance due to threading/synchronization overhead. 291 * 292 * However, the intent of the threading requirements is to allow 293 * for e.g. video decoding and video mixer operations to proceed 294 * in parallel in hardware. Given a (presumably multi-threaded) 295 * application that kept each portion of the hardware busy, this 296 * would yield a performance increase. 297 * 298 * \section endianness Surface Endianness 299 * 300 * When dealing with surface content, i.e. the input/output of 301 * Put/GetBits functions, applications must take care to access 302 * memory in the correct fashion, so as to avoid endianness 303 * issues. 304 * 305 * By established convention in the 3D graphics world, RGBA data 306 * is defined to be an array of 32-bit pixels containing packed 307 * RGBA components, not as an array of bytes or interleaved RGBA 308 * components. VDPAU follows this convention. As such, 309 * applications are expected to access such surfaces as arrays 310 * of 32-bit components (i.e. using a 32-bit pointer), and not 311 * as interleaved arrays of 8-bit components (i.e. using an 312 * 8-bit pointer.) Deviation from this convention will lead to 313 * endianness issues, unless appropriate care is taken. 314 * 315 * The same convention is followed for some packed YCbCr formats 316 * such as \ref VDP_YCBCR_FORMAT_Y8U8V8A8; i.e. they are 317 * considered arrays of 32-bit pixels, and hence should be 318 * accessed as such. 319 * 320 * For YCbCr formats with chroma decimation and/or planar 321 * formats, however, this convention is awkward. Therefore, 322 * formats such as \ref VDP_YCBCR_FORMAT_NV12 are defined as 323 * arrays of (potentially interleaved) byte-sized components. 324 * Hence, applications should manipulate such data 8-bits at a 325 * time, using 8-bit pointers. 326 * 327 * Note that one common usage for the input/output of 328 * Put/GetBits APIs is file I/O. Typical file I/O APIs treat all 329 * memory as a simple array of 8-bit values. This violates the 330 * rule requiring surface data to be accessed in its true native 331 * format. As such, applications may be required to solve 332 * endianness issues. Possible solutions include: 333 * 334 * - Authoring static UI data files according to the endianness 335 * of the target execution platform. 336 * - Conditionally byte-swapping Put/GetBits data buffers at 337 * run-time based on execution platform. 338 * 339 * Note: Complete details regarding each surface format's 340 * precise pixel layout is included with the documentation of 341 * each surface type. For example, see \ref 342 * VDP_RGBA_FORMAT_B8G8R8A8. 343 * 344 * \section video_decoder_usage Video Decoder Usage 345 * 346 * VDPAU is a slice-level API. Put another way, VDPAU implementations accept 347 * "slice" data from the bitstream, and perform all required processing of 348 * those slices (e.g VLD decoding, IDCT, motion compensation, in-loop 349 * deblocking, etc.). 350 * 351 * The client application is responsible for: 352 * 353 * - Extracting the slices from the bitstream (e.g. parsing/demultiplexing 354 * container formats, scanning the data to determine slice start positions 355 * and slice sizes). 356 * - Parsing various bitstream headers/structures (e.g. sequence header, 357 * sequence parameter set, picture parameter set, entry point structures, 358 * etc.) Various fields from the parsed header structures needs to be 359 * provided to VDPAU alongside the slice bitstream in a "picture info" 360 * structure. 361 * - Surface management (e.g. H.264 DPB processing, display re-ordering) 362 * 363 * It is recommended that applications pass solely the slice data to VDPAU; 364 * specifically that any header data structures be excluded from the portion 365 * of the bitstream passed to VDPAU. VDPAU implementations must operate 366 * correctly if non-slice data is included, at least for formats employing 367 * start codes to delimit slice data. However, any extra data may need 368 * to be uploaded to hardware for parsing thus lowering performance, and/or, 369 * in the worst case, may even overflow internal buffers that are sized solely 370 * for slice data. 371 * 372 * The exact data that should be passed to VDPAU is detailed below for each 373 * supported format: 374 * 375 * \subsection bitstream_mpeg1_mpeg2 MPEG-1 and MPEG-2 376 * 377 * Include all slices beginning with start codes 0x00000101 through 378 * 0x000001AF. The slice start code must be included for all slices. 379 * 380 * \subsection bitstream_h264 H.264 381 * 382 * Include all NALs with nal_unit_type of 1 or 5 (coded slice of non-IDR/IDR 383 * picture respectively). The complete slice start code (including 0x000001 384 * prefix) must be included for all slices, even when the prefix is not 385 * included in the bitstream. 386 * 387 * Note that if desired: 388 * 389 * - The slice start code prefix may be included in a separate bitstream 390 * buffer array entry to the actual slice data extracted from the bitstream. 391 * - Multiple bitstream buffer array entries (e.g. one per slice) may point at 392 * the same physical data storage for the slice start code prefix. 393 * 394 * \subsection bitstream_vc1_sp_mp VC-1 Simple and Main Profile 395 * 396 * VC-1 simple/main profile bitstreams always consist of a single slice per 397 * picture, and do not use start codes to delimit pictures. Instead, the 398 * container format must indicate where each picture begins/ends. 399 * 400 * As such, no slice start codes should be included in the data passed to 401 * VDPAU; simply pass in the exact data from the bitstream. 402 * 403 * Header information contained in the bitstream should be parsed by the 404 * application and passed to VDPAU using the "picture info" data structure; 405 * this header information explicitly must not be included in the bitstream 406 * data passed to VDPAU for this encoding format. 407 * 408 * \subsection bitstream_vc1_ap VC-1 Advanced Profile 409 * 410 * Include all slices beginning with start codes 0x0000010D (frame), 411 * 0x0000010C (field) or 0x0000010B (slice). The slice start code should be 412 * included in all cases. 413 * 414 * Some VC-1 advanced profile streams do not contain slice start codes; again, 415 * the container format must indicate where picture data begins and ends. In 416 * this case, pictures are assumed to be progressive and to contain a single 417 * slice. It is highly recommended that applications detect this condition, 418 * and add the missing start codes to the bitstream passed to VDPAU. However, 419 * VDPAU implementations must allow bitstreams with missing start codes, and 420 * act as if a 0x0000010D (frame) start code had been present. 421 * 422 * Note that pictures containing multiple slices, or interlace streams, must 423 * contain a complete set of slice start codes in the original bitstream; 424 * without them, it is not possible to correctly parse and decode the stream. 425 * 426 * The bitstream passed to VDPAU should contain all original emulation 427 * prevention bytes present in the original bitstream; do not remove these 428 * from the bitstream. 429 * 430 * \subsection bitstream_mpeg4part2 MPEG-4 Part 2 and DivX 431 * 432 * Include all slices beginning with start codes 0x000001B6. The slice start 433 * code must be included for all slices. 434 * 435 * \subsection bitstream_hevc H.265/HEVC - High Efficiency Video Codec 436 * 437 * Include all video coding layer (VCL) NAL units, with nal_unit_type values 438 * of 0 (TRAIL_N) through 31 (RSV_VCL31) inclusive. In addition to parsing 439 * and providing NAL units, an H.265/HEVC decoder application using VDPAU 440 * for decoding must parse certain values of the first slice segment header 441 * in a VCL NAL unit and provide it through VdpPictureInfoHEVC. Please see 442 * the documentation for VdpPictureInfoHEVC below for further details. 443 * 444 * The complete slice start code (including the 0x000001 prefix) must be 445 * included for all slices, even when the prefix is not included in the 446 * bitstream. 447 * 448 * Note that if desired: 449 * 450 * - The slice start code prefix may be included in a separate bitstream 451 * buffer array entry to the actual slice data extracted from the bitstream. 452 * - Multiple bitstream buffer array entries (e.g. one per slice) may point at 453 * the same physical data storage for the slice start code prefix. 454 * 455 * \section video_mixer_usage Video Mixer Usage 456 * 457 * \subsection video_surface_content VdpVideoSurface Content 458 * 459 * Each \ref VdpVideoSurface "VdpVideoSurface" is expected to contain an 460 * entire frame's-worth of data, irrespective of whether an interlaced of 461 * progressive sequence is being decoded. 462 * 463 * Depending on the exact encoding structure of the compressed video stream, 464 * the application may need to call \ref VdpDecoderRender twice to fill a 465 * single \ref VdpVideoSurface "VdpVideoSurface". When the stream contains an 466 * encoded progressive frame, or a "frame coded" interlaced field-pair, a 467 * single \ref VdpDecoderRender call will fill the entire surface. When the 468 * stream contains separately encoded interlaced fields, two 469 * \ref VdpDecoderRender calls will be required; one for the top field, and 470 * one for the bottom field. 471 * 472 * Implementation note: When \ref VdpDecoderRender renders an interlaced 473 * field, this operation must not disturb the content of the other field in 474 * the surface. 475 * 476 * \subsection vm_surf_list VdpVideoMixer Surface List 477 * 478 * An video stream is logically composed of a sequence of fields. An 479 * example is shown below, in display order, assuming top field first: 480 * 481 * <pre>t0 b0 t1 b1 t2 b2 t3 b3 t4 b4 t5 b5 t6 b6 t7 b7 t8 b8 t9 b9</pre> 482 * 483 * The canonical usage is to call \ref VdpVideoMixerRender once for decoded 484 * field, in display order, to yield one post-processed frame for display. 485 * 486 * For each call to \ref VdpVideoMixerRender, the field to be processed should 487 * be provided as the \b video_surface_current parameter. 488 * 489 * To enable operation of advanced de-interlacing algorithms and/or 490 * post-processing algorithms, some past and/or future surfaces should be 491 * provided as context. These are provided in the \b video_surface_past and 492 * \b video_surface_future lists. In general, these lists may contain any 493 * number of surfaces. Specific implementations may have specific requirements 494 * determining the minimum required number of surfaces for optimal operation, 495 * and the maximum number of useful surfaces, beyond which surfaces are not 496 * used. It is recommended that in all cases other than plain bob/weave, at 497 * least 2 past and 1 future field be provided. 498 * 499 * Note that it is entirely possible, in general, for any of the 500 * \ref VdpVideoMixer "VdpVideoMixer" post-processing steps other than 501 * de-interlacing to require access to multiple input fields/frames. For 502 * example, an motion-sensitive noise-reduction algorithm. 503 * 504 * For example, when processing field t4, the \ref VdpVideoMixerRender 505 * parameters may contain the following values, if the application chose to 506 * provide 3 fields of context for both the past and future: 507 * 508 * <pre> 509 * current_picture_structure: VDP_VIDEO_MIXER_PICTURE_STRUCTURE_TOP_FIELD 510 * past: [b3, t3, b2] 511 * current: t4 512 * future: [b4, t5, b5] 513 * </pre> 514 * 515 * Note that for both the past/future lists, array index 0 represents the 516 * field temporally closest to current, in display order. 517 * 518 * The \ref VdpVideoMixerRender parameter \b current_picture_structure applies 519 * to \b video_surface_current. The picture structure for the other surfaces 520 * will be automatically derived from that for the current picture. The 521 * derivation algorithm is extremely simple; the concatenated list 522 * past/current/future is simply assumed to have an alternating top/bottom 523 * pattern throughout. 524 * 525 * Continuing the example above, subsequent calls to \ref VdpVideoMixerRender 526 * would provide the following sets of parameters: 527 * 528 * <pre> 529 * current_picture_structure: VDP_VIDEO_MIXER_PICTURE_STRUCTURE_BOTTOM_FIELD 530 * past: [t4, b3, t3] 531 * current: b4 532 * future: [t5, b5, t6] 533 * </pre> 534 * 535 * then: 536 * 537 * <pre> 538 * current_picture_structure: VDP_VIDEO_MIXER_PICTURE_STRUCTURE_TOP_FIELD 539 * past: [b4, t4, b3] 540 * current: t5 541 * future: [b5, t6, b7] 542 * </pre> 543 * 544 * In other words, the concatenated list of past/current/future frames simply 545 * forms a window that slides through the sequence of decoded fields. 546 * 547 * It is syntactically legal for an application to choose not to provide a 548 * particular entry in the past or future lists. In this case, the "slot" in 549 * the surface list must be filled with the special value 550 * \ref VDP_INVALID_HANDLE, to explicitly indicate that the picture is 551 * missing; do not simply shuffle other surfaces together to fill in the gap. 552 * Note that entries should only be omitted under special circumstances, such 553 * as failed decode due to bitstream error during picture header parsing, 554 * since missing entries will typically cause advanced de-interlacing 555 * algorithms to experience significantly degraded operation. 556 * 557 * Specific examples for different de-interlacing types are presented below. 558 * 559 * \subsection deint_weave Weave De-interlacing 560 * 561 * Weave de-interlacing is the act of interleaving the lines of two temporally 562 * adjacent fields to form a frame for display. 563 * 564 * To disable de-interlacing for progressive streams, simply specify 565 * \b current_picture_structure as \ref VDP_VIDEO_MIXER_PICTURE_STRUCTURE_FRAME; 566 * no de-interlacing will be applied. 567 * 568 * Weave de-interlacing for interlaced streams is identical to disabling 569 * de-interlacing, as describe immediately above, because each 570 * \ref VdpVideoSurface already contains an entire frame's worth (i.e. two 571 * fields) of picture data. 572 * 573 * Inverse telecine is disabled when using weave de-interlacing. 574 * 575 * Weave de-interlacing produces one output frame for each input frame. The 576 * application should make one \ref VdpVideoMixerRender call per pair of 577 * decoded fields, or per decoded frame. 578 * 579 * Weave de-interlacing requires no entries in the past/future lists. 580 * 581 * All implementations must support weave de-interlacing. 582 * 583 * \subsection deint_bob Bob De-interlacing 584 * 585 * Bob de-interlacing is the act of vertically scaling a single field to the 586 * size of a single frame. 587 * 588 * To achieve bob de-interlacing, simply provide a single field as 589 * \b video_surface_current, and set \b current_picture_structure 590 * appropriately, to indicate whether a top or bottom field was provided. 591 * 592 * Inverse telecine is disabled when using bob de-interlacing. 593 * 594 * Bob de-interlacing produces one output frame for each input field. The 595 * application should make one \ref VdpVideoMixerRender call per decoded 596 * field. 597 * 598 * Bob de-interlacing requires no entries in the past/future lists. 599 * 600 * Bob de-interlacing is the default when no advanced method is requested and 601 * enabled. Advanced de-interlacing algorithms may fall back to bob e.g. when 602 * required past/future fields are missing. 603 * 604 * All implementations must support bob de-interlacing. 605 * 606 * \subsection deint_adv Advanced De-interlacing 607 * 608 * Operation of both temporal and temporal-spatial de-interlacing is 609 * identical; the only difference is the internal processing the algorithm 610 * performs in generating the output frame. 611 * 612 * These algorithms use various advanced processing on the pixels of both the 613 * current and various past/future fields in order to determine how best to 614 * de-interlacing individual portions of the image. 615 * 616 * Inverse telecine may be enabled when using advanced de-interlacing. 617 * 618 * Advanced de-interlacing produces one output frame for each input field. The 619 * application should make one \ref VdpVideoMixerRender call per decoded 620 * field. 621 * 622 * Advanced de-interlacing requires entries in the past/future lists. 623 * 624 * Availability of advanced de-interlacing algorithms is implementation 625 * dependent. 626 * 627 * \subsection deint_rate De-interlacing Rate 628 * 629 * For all de-interlacing algorithms except weave, a choice may be made to 630 * call \ref VdpVideoMixerRender for either each decoded field, or every 631 * second decoded field. 632 * 633 * If \ref VdpVideoMixerRender is called for every decoded field, the 634 * generated post-processed frame rate is equal to the decoded field rate. 635 * Put another way, the generated post-processed nominal field rate is equal 636 * to 2x the decoded field rate. This is standard practice. 637 * 638 * If \ref VdpVideoMixerRender is called for every second decoded field (say 639 * every top field), the generated post-processed frame rate is half to the 640 * decoded field rate. This mode of operation is thus referred to as 641 * "half-rate". 642 * 643 * Implementations may choose whether to support half-rate de-interlacing 644 * or not. Regular full-rate de-interlacing should be supported by any 645 * supported advanced de-interlacing algorithm. 646 * 647 * The descriptions of de-interlacing algorithms above assume that regular 648 * (not half-rate) operation is being performed, when detailing the number of 649 * VdpVideoMixerRender calls. 650 * 651 * Recall that the concatenation of past/current/future surface lists simply 652 * forms a window into the stream of decoded fields. To achieve standard 653 * de-interlacing, the window is slid through the list of decoded fields one 654 * field at a time, and a call is made to \ref VdpVideoMixerRender for each 655 * movement of the window. To achieve half-rate de-interlacing, the window is 656 * slid through the* list of decoded fields two fields at a time, and a 657 * call is made to \ref VdpVideoMixerRender for each movement of the window. 658 * 659 * \subsection invtc Inverse Telecine 660 * 661 * Assuming the implementation supports it, inverse telecine may be enabled 662 * alongside any advanced de-interlacing algorithm. Inverse telecine is never 663 * active for bob or weave. 664 * 665 * Operation of \ref VdpVideoMixerRender with inverse telecine active is 666 * identical to the basic operation mechanisms describe above in every way; 667 * all inverse telecine processing is performed internally to the 668 * \ref VdpVideoMixer "VdpVideoMixer". 669 * 670 * In particular, there is no provision way for \ref VdpVideoMixerRender to 671 * indicate when identical input fields have been observed, and consequently 672 * identical output frames may have been produced. 673 * 674 * De-interlacing (and inverse telecine) may be applied to streams that are 675 * marked as being progressive. This will allow detection of, and correct 676 * de-interlacing of, mixed interlace/progressive streams, bad edits, etc. 677 * To implement de-interlacing/inverse-telecine on progressive material, 678 * simply treat the stream of decoded frames as a stream of decoded fields, 679 * apply any telecine flags (see the next section), and then apply 680 * de-interlacing to those fields as described above. 681 * 682 * Implementations are free to determine whether inverse telecine operates 683 * in conjunction with half-rate de-interlacing or not. It should always 684 * operate with regular de-interlacing, when advertized. 685 * 686 * \subsection tcflags Telecine (Pull-Down) Flags 687 * 688 * Some media delivery formats, e.g. DVD-Video, include flags that are 689 * intended to modify the decoded field sequence before display. This allows 690 * e.g. 24p content to be encoded at 48i, which saves space relative to a 60i 691 * encoded stream, but still displayed at 60i, to match target consumer 692 * display equipment. 693 * 694 * If the inverse telecine option is not activated in the 695 * \ref VdpVideoMixer "VdpVideoMixer", these flags should be ignored, and the 696 * decoded fields passed directly to \ref VdpVideoMixerRender as detailed 697 * above. 698 * 699 * However, to make full use of the inverse telecine feature, these flags 700 * should be applied to the field stream, yielding another field stream with 701 * some repeated fields, before passing the field stream to 702 * \ref VdpVideoMixerRender. In this scenario, the sliding window mentioned 703 * in the descriptions above applies to the field stream after application of 704 * flags. 705 * 706 * \section extending Extending the API 707 * 708 * \subsection extend_enums Enumerations and Other Constants 709 * 710 * VDPAU defines a number of enumeration types. 711 * 712 * When modifying VDPAU, existing enumeration constants must 713 * continue to exist (although they may be deprecated), and do 714 * so in the existing order. 715 * 716 * The above discussion naturally applies to "manually" defined 717 * enumerations, using pre-processor macros, too. 718 * 719 * \subsection extend_structs Structures 720 * 721 * In most case, VDPAU includes no provision for modifying existing 722 * structure definitions, although they may be deprecated. 723 * 724 * New structures may be created, together with new API entry 725 * points or feature/attribute/parameter values, to expose new 726 * functionality. 727 * 728 * A few structures are considered plausible candidates for future extension. 729 * Such structures include a version number as the first field, indicating the 730 * exact layout of the client-provided data. When changing such structures, the 731 * old structure must be preserved and a new structure created. This allows 732 * applications built against the old version of the structure to continue to 733 * interoperate. For example, to extend the VdpProcamp structure, define a new 734 * VdpProcamp1 and update VdpGenerateCSCMatrix to take the new structure as an 735 * argument. Document in a comment that the caller must fill the struct_version 736 * field with the value 1. VDPAU implementations should use the struct_version 737 * field to determine which version of the structure the application was built 738 * against. Note that you cannot simply increment the value of 739 * VDP_PROCAMP_VERSION because applications recompiled against a newer version 740 * of vdpau.h but that have not been updated to use the new structure must still 741 * report that they're using version 0. 742 * 743 * Note that the layouts of VdpPictureInfo structures are defined by their 744 * corresponding VdpDecoderProfile numbers, so no struct_version field is 745 * needed for them. This layout includes the size of the structure, so new 746 * profiles that extend existing functionality may incorporate the old 747 * VdpPictureInfo as a substructure, but may not modify existing VdpPictureInfo 748 * structures. 749 * 750 * \subsection extend_functions Functions 751 * 752 * Existing functions may not be modified, although they may be 753 * deprecated. 754 * 755 * New functions may be added at will. Note the enumeration 756 * requirements when modifying the enumeration that defines the 757 * list of entry points. 758 * 759 * \section preemption_note Display Preemption 760 * 761 * Please note that the display may be preempted away from 762 * VDPAU at any time. See \ref display_preemption for more 763 * details. 764 * 765 * \subsection trademarks Trademarks 766 * 767 * VDPAU is a trademark of NVIDIA Corporation. You may freely use the 768 * VDPAU trademark, as long as trademark ownership is attributed to 769 * NVIDIA Corporation. 770 */ 771 772 /** 773 * \file vdpau.h 774 * \brief The Core API 775 * 776 * This file contains the \ref api_core "Core API". 777 */ 778 779 #ifndef _VDPAU_H 780 #define _VDPAU_H 781 782 #include <stdint.h> 783 784 #ifdef __cplusplus 785 extern "C" { 786 #endif 787 788 /** 789 * \defgroup api_core Core API 790 * 791 * The core API encompasses all VDPAU functionality that operates 792 * in the same fashion across all Window Systems. 793 * 794 * @{ 795 */ 796 797 /** 798 * \defgroup base_types Basic Types 799 * 800 * VDPAU primarily uses ISO C99 types from \c stdint.h. 801 * 802 * @{ 803 */ 804 805 /** \brief A true \ref VdpBool value */ 806 #define VDP_TRUE 1 807 /** \brief A false \ref VdpBool value */ 808 #define VDP_FALSE 0 809 /** 810 * \brief A boolean value, holding \ref VDP_TRUE or \ref 811 * VDP_FALSE. 812 */ 813 typedef int VdpBool; 814 815 /** @} */ 816 817 /** 818 * \defgroup misc_types Miscellaneous Types 819 * 820 * @{ 821 */ 822 823 /** 824 * \brief An invalid object handle value. 825 * 826 * This value may be used to represent an invalid, or 827 * non-existent, object (\ref VdpDevice "VdpDevice", 828 * \ref VdpVideoSurface "VdpVideoSurface", etc.) 829 * 830 * Note that most APIs require valid object handles in all 831 * cases, and will fail when presented with this value. 832 */ 833 #define VDP_INVALID_HANDLE 0xffffffffU 834 835 /** 836 * \brief The set of all chroma formats for \ref VdpVideoSurface 837 * "VdpVideoSurface"s. 838 */ 839 typedef uint32_t VdpChromaType; 840 841 /** \hideinitializer \brief 4:2:0 chroma format. Undefined field/frame based 842 * Video surfaces allocated with this chroma type have undefined 843 * field/frame structure. The implementation is free to internally morph 844 * the surface between frame/field(NV12/NV24) as required by 845 * VdpVideoDecoder operation. Interop with OpenGL allows registration 846 * of these surfaces for either field- or frame-based interop. But, an implicit 847 * field/frame structure conversion may be performed. 848 */ 849 #define VDP_CHROMA_TYPE_420 ((VdpChromaType)0) 850 /** \hideinitializer \brief 4:2:2 chroma format. Undefined field/frame based 851 * Video surfaces allocated with this chroma type have undefined 852 * field/frame structure. The implementation is free to internally morph 853 * the surface between frame/field(NV12/NV24) as required by 854 * VdpVideoDecoder operation. Interop with OpenGL allows registration 855 * of these surfaces for either field- or frame-based interop. But, an implicit 856 * field/frame structure conversion may be performed. 857 */ 858 #define VDP_CHROMA_TYPE_422 ((VdpChromaType)1) 859 /** \hideinitializer \brief 4:4:4 chroma format. Undefined field/frame based 860 * Video surfaces allocated with this chroma type have undefined 861 * field/frame structure. The implementation is free to internally morph 862 * the surface between frame/field(NV12/NV24) as required by 863 * VdpVideoDecoder operation. Interop with OpenGL allows registration 864 * of these surfaces for either field- or frame-based interop. But, an implicit 865 * field/frame structure conversion may be performed. 866 */ 867 #define VDP_CHROMA_TYPE_444 ((VdpChromaType)2) 868 869 /** \hideinitializer \brief 4:2:0 chroma format. Field based. 870 * Video surfaces allocated with this chroma type can only be 871 * interoped with OpenGL if the matching field/frame structure is 872 * specified in the OpenGL API */ 873 #define VDP_CHROMA_TYPE_420_FIELD ((VdpChromaType)3) 874 /** \hideinitializer \brief 4:2:2 chroma format. Field based. 875 * Video surfaces allocated with this chroma type can only be 876 * interoped with OpenGL if the matching field/frame structure is 877 * specified in the OpenGL API */ 878 #define VDP_CHROMA_TYPE_422_FIELD ((VdpChromaType)4) 879 /** \hideinitializer \brief 4:4:4 chroma format. Field based. 880 * Video surfaces allocated with this chroma type can only be 881 * interoped with OpenGL if the matching field/frame structure is 882 * specified in the OpenGL API */ 883 #define VDP_CHROMA_TYPE_444_FIELD ((VdpChromaType)5) 884 885 /** \hideinitializer \brief 4:2:0 chroma format. Frame based. 886 * Video surfaces allocated with this chroma type can only be 887 * interoped with OpenGL if the matching field/frame structure is 888 * specified in the OpenGL API */ 889 #define VDP_CHROMA_TYPE_420_FRAME ((VdpChromaType)6) 890 /** \hideinitializer \brief 4:2:2 chroma format. Frame based. 891 * Video surfaces allocated with this chroma type can only be 892 * interoped with OpenGL if the matching field/frame structure is 893 * specified in the OpenGL API */ 894 #define VDP_CHROMA_TYPE_422_FRAME ((VdpChromaType)7) 895 /** \hideinitializer \brief 4:4:4 chroma format. Frame based. 896 * Video surfaces allocated with this chroma type can only be 897 * interoped with OpenGL if the matching field/frame structure is 898 * specified in the OpenGL API */ 899 #define VDP_CHROMA_TYPE_444_FRAME ((VdpChromaType)8) 900 /** \hideinitializer \brief 4:2:0 chroma format. Undefined field/frame based 901 * Video surfaces allocated with this chroma type have undefined 902 * field/frame structure. The implementation is free to internally morph 903 * the surface between frame/field as required by VdpVideoDecoder operation. 904 * Interop with OpenGL allows registration of these surfaces for either 905 * field- or frame-based interop. But, an implicit field/frame structure 906 * conversion may be performed. 907 */ 908 #define VDP_CHROMA_TYPE_420_16 ((VdpChromaType)9) 909 /** \hideinitializer \brief 4:2:2 chroma format. Undefined field/frame based 910 * Video surfaces allocated with this chroma type have undefined 911 * field/frame structure. The implementation is free to internally morph 912 * the surface between frame/field as required by VdpVideoDecoder operation. 913 * Interop with OpenGL allows registration of these surfaces for either 914 * field- or frame-based interop. But, an implicit field/frame structure 915 * conversion may be performed. 916 */ 917 #define VDP_CHROMA_TYPE_422_16 ((VdpChromaType)10) 918 /** \hideinitializer \brief 4:4:4 chroma format. Undefined field/frame based 919 * Video surfaces allocated with this chroma type have undefined 920 * field/frame structure. The implementation is free to internally morph 921 * the surface between frame/field as required by VdpVideoDecoder operation. 922 * Interop with OpenGL allows registration of these surfaces for either 923 * field- or frame-based interop. But, an implicit field/frame structure 924 * conversion may be performed. 925 */ 926 #define VDP_CHROMA_TYPE_444_16 ((VdpChromaType)11) 927 928 /** \hideinitializer \brief 4:2:0 chroma format. Field based. 929 * Video surfaces allocated with this chroma type can only be 930 * interoped with OpenGL if the matching field/frame structure is 931 * specified in the OpenGL API */ 932 #define VDP_CHROMA_TYPE_420_FIELD_16 ((VdpChromaType)12) 933 /** \hideinitializer \brief 4:2:2 chroma format. Field based. 934 * Video surfaces allocated with this chroma type can only be 935 * interoped with OpenGL if the matching field/frame structure is 936 * specified in the OpenGL API */ 937 #define VDP_CHROMA_TYPE_422_FIELD_16 ((VdpChromaType)13) 938 /** \hideinitializer \brief 4:4:4 chroma format. Field based. 939 * Video surfaces allocated with this chroma type can only be 940 * interoped with OpenGL if the matching field/frame structure is 941 * specified in the OpenGL API */ 942 #define VDP_CHROMA_TYPE_444_FIELD_16 ((VdpChromaType)14) 943 944 /** \hideinitializer \brief 4:2:0 chroma format. Frame based. 945 * Video surfaces allocated with this chroma type can only be 946 * interoped with OpenGL if the matching field/frame structure is 947 * specified in the OpenGL API */ 948 #define VDP_CHROMA_TYPE_420_FRAME_16 ((VdpChromaType)15) 949 /** \hideinitializer \brief 4:2:2 chroma format. Frame based. 950 * Video surfaces allocated with this chroma type can only be 951 * interoped with OpenGL if the matching field/frame structure is 952 * specified in the OpenGL API */ 953 #define VDP_CHROMA_TYPE_422_FRAME_16 ((VdpChromaType)16) 954 /** \hideinitializer \brief 4:4:4 chroma format. Frame based. 955 * Video surfaces allocated with this chroma type can only be 956 * interoped with OpenGL if the matching field/frame structure is 957 * specified in the OpenGL API */ 958 #define VDP_CHROMA_TYPE_444_FRAME_16 ((VdpChromaType)17) 959 960 /** 961 * \brief The set of all known YCbCr surface formats. 962 */ 963 typedef uint32_t VdpYCbCrFormat; 964 965 /** 966 * \hideinitializer 967 * \brief The "NV12" YCbCr surface format. 968 * 969 * This format has a two planes, a Y plane and a UV plane. 970 * 971 * The Y plane is an array of byte-sized Y components. 972 * Applications should access this data via a uint8_t pointer. 973 * 974 * The UV plane is an array of interleaved byte-sized U and V 975 * components, in the order U, V, U, V. Applications should 976 * access this data via a uint8_t pointer. 977 */ 978 #define VDP_YCBCR_FORMAT_NV12 ((VdpYCbCrFormat)0) 979 /** 980 * \hideinitializer 981 * \brief The "YV12" YCbCr surface format. 982 * 983 * This format has a three planes, a Y plane, a V plane, and a U 984 * plane. 985 * 986 * Each of the planes is an array of byte-sized components. 987 * 988 * Applications should access this data via a uint8_t pointer. 989 */ 990 #define VDP_YCBCR_FORMAT_YV12 ((VdpYCbCrFormat)1) 991 /** 992 * \hideinitializer 993 * \brief The "UYVY" YCbCr surface format. 994 * 995 * This format may also be known as Y422, UYNV, HDYC. 996 * 997 * This format has a single plane. 998 * 999 * This plane is an array of interleaved byte-sized Y, U, and V 1000 * components, in the order U, Y, V, Y, U, Y, V, Y. 1001 * 1002 * Applications should access this data via a uint8_t pointer. 1003 */ 1004 #define VDP_YCBCR_FORMAT_UYVY ((VdpYCbCrFormat)2) 1005 /** 1006 * \hideinitializer 1007 * \brief The "YUYV" YCbCr surface format. 1008 * 1009 * This format may also be known as YUY2, YUNV, V422. 1010 * 1011 * This format has a single plane. 1012 * 1013 * This plane is an array of interleaved byte-sized Y, U, and V 1014 * components, in the order Y, U, Y, V, Y, U, Y, V. 1015 * 1016 * Applications should access this data via a uint8_t pointer. 1017 */ 1018 #define VDP_YCBCR_FORMAT_YUYV ((VdpYCbCrFormat)3) 1019 /** 1020 * \hideinitializer 1021 * \brief A packed YCbCr format. 1022 * 1023 * This format has a single plane. 1024 * 1025 * This plane is an array packed 32-bit pixel data. Within each 1026 * 32-bit pixel, bits [31:24] contain A, bits [23:16] contain V, 1027 * bits [15:8] contain U, and bits [7:0] contain Y. 1028 * 1029 * Applications should access this data via a uint32_t pointer. 1030 */ 1031 #define VDP_YCBCR_FORMAT_Y8U8V8A8 ((VdpYCbCrFormat)4) 1032 /** 1033 * \hideinitializer 1034 * \brief A packed YCbCr format. 1035 * 1036 * This format has a single plane. 1037 * 1038 * This plane is an array packed 32-bit pixel data. Within each 1039 * 32-bit pixel, bits [31:24] contain A, bits [23:16] contain Y, 1040 * bits [15:8] contain U, and bits [7:0] contain V. 1041 * 1042 * Applications should access this data via a uint32_t pointer. 1043 */ 1044 #define VDP_YCBCR_FORMAT_V8U8Y8A8 ((VdpYCbCrFormat)5) 1045 /** 1046 * \hideinitializer 1047 * \brief The "Y_UV_444" YCbCr surface format. 1048 * 1049 * This format has two planes, a Y plane and a UV plane. 1050 * 1051 * The Y plane is an array of byte-sized Y components. 1052 * Applications should access this data via a uint8_t pointer. 1053 * 1054 * The UV plane is an array of interleaved byte-sized U and V 1055 * components, in the order U, V, U, V. Applications should 1056 * access this data via a uint8_t pointer. 1057 */ 1058 #define VDP_YCBCR_FORMAT_Y_UV_444 ((VdpYCbCrFormat)6) 1059 /** 1060 * \hideinitializer 1061 * \brief The "Y_U_V_444" YCbCr surface format. 1062 * 1063 * This format has three planes, a Y plane, a V plane, and a U 1064 * plane. 1065 * 1066 * Each of the planes is an array of byte-sized components. 1067 * 1068 * Applications should access this data via a uint8_t pointer. 1069 */ 1070 #define VDP_YCBCR_FORMAT_Y_U_V_444 ((VdpYCbCrFormat)7) 1071 /** 1072 * \hideinitializer 1073 * \brief The P010 surface format. 1074 * 1075 * This format has two planes, a Y plane and a UV plane. 1076 * 1077 * The Y plane is an array of two byte sized Y components. 1078 * Applications should access this data via a uint16_t pointer. 1079 * 1080 * The UV plane is an array of interleaved two byte sized U and V 1081 * components, in the order U, V, U, V. Applications should 1082 * access this data via a uint8_t pointer. 1083 * 1084 * Note that the P010 surface format has an identical memory 1085 * layout as the P016 surface format, with bits 0 through 5 1086 * set to zero. 1087 */ 1088 #define VDP_YCBCR_FORMAT_P010 ((VdpYCbCrFormat)8) 1089 /** 1090 * \hideinitializer 1091 * \brief The P016 surface format. 1092 * 1093 * This format has two planes, a Y plane and a UV plane. 1094 * 1095 * The Y plane is an array of two byte sized Y components. 1096 * Applications should access this data via a uint16_t pointer. 1097 * 1098 * The UV plane is an array of interleaved two byte sized U and V 1099 * components, in the order U, V, U, V. Applications should 1100 * access this data via a uint8_t pointer. 1101 */ 1102 #define VDP_YCBCR_FORMAT_P016 ((VdpYCbCrFormat)9) 1103 /** 1104 * \hideinitializer 1105 * \brief The "Y_U_V_444_16" YCbCr surface format. 1106 * 1107 * This format has three planes, a Y plane, a V plane, and a U 1108 * plane. 1109 * 1110 * Each of the planes is an array of two byte-sized components. 1111 * 1112 * Applications should access this data via a uint16_t pointer. 1113 */ 1114 #define VDP_YCBCR_FORMAT_Y_U_V_444_16 ((VdpYCbCrFormat)11) 1115 1116 /** 1117 * \brief The set of all known RGB surface formats. 1118 */ 1119 typedef uint32_t VdpRGBAFormat; 1120 1121 /** 1122 * \hideinitializer 1123 * \brief A packed RGB format. 1124 * 1125 * This format has a single plane. 1126 * 1127 * This plane is an array packed 32-bit pixel data. Within each 1128 * 32-bit pixel, bits [31:24] contain A, bits [23:16] contain R, 1129 * bits [15:8] contain G, and bits [7:0] contain B. 1130 * 1131 * Applications should access this data via a uint32_t pointer. 1132 */ 1133 #define VDP_RGBA_FORMAT_B8G8R8A8 ((VdpRGBAFormat)0) 1134 /** 1135 * \hideinitializer 1136 * \brief A packed RGB format. 1137 * 1138 * This format has a single plane. 1139 * 1140 * This plane is an array packed 32-bit pixel data. Within each 1141 * 32-bit pixel, bits [31:24] contain A, bits [23:16] contain B, 1142 * bits [15:8] contain G, and bits [7:0] contain R. 1143 * 1144 * Applications should access this data via a uint32_t pointer. 1145 */ 1146 #define VDP_RGBA_FORMAT_R8G8B8A8 ((VdpRGBAFormat)1) 1147 /** 1148 * \hideinitializer 1149 * \brief A packed RGB format. 1150 * 1151 * This format has a single plane. 1152 * 1153 * This plane is an array packed 32-bit pixel data. Within each 1154 * 32-bit pixel, bits [31:30] contain A, bits [29:20] contain B, 1155 * bits [19:10] contain G, and bits [9:0] contain R. 1156 * 1157 * Applications should access this data via a uint32_t pointer. 1158 */ 1159 #define VDP_RGBA_FORMAT_R10G10B10A2 ((VdpRGBAFormat)2) 1160 /** 1161 * \hideinitializer 1162 * \brief A packed RGB format. 1163 * 1164 * This format has a single plane. 1165 * 1166 * This plane is an array packed 32-bit pixel data. Within each 1167 * 32-bit pixel, bits [31:30] contain A, bits [29:20] contain R, 1168 * bits [19:10] contain G, and bits [9:0] contain B. 1169 * 1170 * Applications should access this data via a uint32_t pointer. 1171 */ 1172 #define VDP_RGBA_FORMAT_B10G10R10A2 ((VdpRGBAFormat)3) 1173 /** 1174 * \hideinitializer 1175 * \brief An alpha-only surface format. 1176 * 1177 * This format has a single plane. 1178 * 1179 * This plane is an array of byte-sized components. 1180 * 1181 * Applications should access this data via a uint8_t pointer. 1182 */ 1183 #define VDP_RGBA_FORMAT_A8 ((VdpRGBAFormat)4) 1184 1185 /** 1186 * \brief The set of all known indexed surface formats. 1187 */ 1188 typedef uint32_t VdpIndexedFormat; 1189 1190 /** 1191 * \hideinitializer 1192 * \brief A 4-bit indexed format, with alpha. 1193 * 1194 * This format has a single plane. 1195 * 1196 * This plane is an array of byte-sized components. Within each 1197 * byte, bits [7:4] contain I (index), and bits [3:0] contain A. 1198 * 1199 * Applications should access this data via a uint8_t pointer. 1200 */ 1201 #define VDP_INDEXED_FORMAT_A4I4 ((VdpIndexedFormat)0) 1202 /** 1203 * \hideinitializer 1204 * \brief A 4-bit indexed format, with alpha. 1205 * 1206 * This format has a single plane. 1207 * 1208 * This plane is an array of byte-sized components. Within each 1209 * byte, bits [7:4] contain A, and bits [3:0] contain I (index). 1210 * 1211 * Applications should access this data via a uint8_t pointer. 1212 */ 1213 #define VDP_INDEXED_FORMAT_I4A4 ((VdpIndexedFormat)1) 1214 /** 1215 * \hideinitializer 1216 * \brief A 8-bit indexed format, with alpha. 1217 * 1218 * This format has a single plane. 1219 * 1220 * This plane is an array of interleaved byte-sized A and I 1221 * (index) components, in the order A, I, A, I. 1222 * 1223 * Applications should access this data via a uint8_t pointer. 1224 */ 1225 #define VDP_INDEXED_FORMAT_A8I8 ((VdpIndexedFormat)2) 1226 /** 1227 * \hideinitializer 1228 * \brief A 8-bit indexed format, with alpha. 1229 * 1230 * This format has a single plane. 1231 * 1232 * This plane is an array of interleaved byte-sized A and I 1233 * (index) components, in the order I, A, I, A. 1234 * 1235 * Applications should access this data via a uint8_t pointer. 1236 */ 1237 #define VDP_INDEXED_FORMAT_I8A8 ((VdpIndexedFormat)3) 1238 1239 /** 1240 * \brief A location within a surface. 1241 * 1242 * The VDPAU co-ordinate system has its origin at the top-left 1243 * of a surface, with x and y components increasing right and 1244 * down. 1245 */ 1246 typedef struct { 1247 /** X co-ordinate. */ 1248 uint32_t x; 1249 /** Y co-ordinate. */ 1250 uint32_t y; 1251 } VdpPoint; 1252 1253 /** 1254 * \brief A rectangular region of a surface. 1255 * 1256 * The co-ordinates are top-left inclusive, bottom-right 1257 * exclusive. 1258 * 1259 * The VDPAU co-ordinate system has its origin at the top-left 1260 * of a surface, with x and y components increasing right and 1261 * down. 1262 */ 1263 typedef struct { 1264 /** Left X co-ordinate. Inclusive. */ 1265 uint32_t x0; 1266 /** Top Y co-ordinate. Inclusive. */ 1267 uint32_t y0; 1268 /** Right X co-ordinate. Exclusive. */ 1269 uint32_t x1; 1270 /** Bottom Y co-ordinate. Exclusive. */ 1271 uint32_t y1; 1272 } VdpRect; 1273 1274 /** 1275 * A constant RGBA color. 1276 * 1277 * Note that the components are stored as float values in the 1278 * range 0.0...1.0 rather than format-specific integer values. 1279 * This allows VdpColor values to be independent from the exact 1280 * surface format(s) in use. 1281 */ 1282 typedef struct { 1283 float red; 1284 float green; 1285 float blue; 1286 float alpha; 1287 } VdpColor; 1288 1289 /** @} */ 1290 1291 /** 1292 * \defgroup error_handling Error Handling 1293 * 1294 * @{ 1295 */ 1296 1297 /** 1298 * \hideinitializer 1299 * \brief The set of all possible error codes. 1300 */ 1301 typedef enum { 1302 /** The operation completed successfully; no error. */ 1303 VDP_STATUS_OK = 0, 1304 /** 1305 * No backend implementation could be loaded. 1306 */ 1307 VDP_STATUS_NO_IMPLEMENTATION, 1308 /** 1309 * The display was preempted, or a fatal error occurred. 1310 * 1311 * The application must re-initialize VDPAU. 1312 */ 1313 VDP_STATUS_DISPLAY_PREEMPTED, 1314 /** 1315 * An invalid handle value was provided. 1316 * 1317 * Either the handle does not exist at all, or refers to an object of an 1318 * incorrect type. 1319 */ 1320 VDP_STATUS_INVALID_HANDLE, 1321 /** 1322 * An invalid pointer was provided. 1323 * 1324 * Typically, this means that a NULL pointer was provided for an "output" 1325 * parameter. 1326 */ 1327 VDP_STATUS_INVALID_POINTER, 1328 /** 1329 * An invalid/unsupported \ref VdpChromaType value was supplied. 1330 */ 1331 VDP_STATUS_INVALID_CHROMA_TYPE, 1332 /** 1333 * An invalid/unsupported \ref VdpYCbCrFormat value was supplied. 1334 */ 1335 VDP_STATUS_INVALID_Y_CB_CR_FORMAT, 1336 /** 1337 * An invalid/unsupported \ref VdpRGBAFormat value was supplied. 1338 */ 1339 VDP_STATUS_INVALID_RGBA_FORMAT, 1340 /** 1341 * An invalid/unsupported \ref VdpIndexedFormat value was supplied. 1342 */ 1343 VDP_STATUS_INVALID_INDEXED_FORMAT, 1344 /** 1345 * An invalid/unsupported \ref VdpColorStandard value was supplied. 1346 */ 1347 VDP_STATUS_INVALID_COLOR_STANDARD, 1348 /** 1349 * An invalid/unsupported \ref VdpColorTableFormat value was supplied. 1350 */ 1351 VDP_STATUS_INVALID_COLOR_TABLE_FORMAT, 1352 /** 1353 * An invalid/unsupported \ref VdpOutputSurfaceRenderBlendFactor value was 1354 * supplied. 1355 */ 1356 VDP_STATUS_INVALID_BLEND_FACTOR, 1357 /** 1358 * An invalid/unsupported \ref VdpOutputSurfaceRenderBlendEquation value 1359 * was supplied. 1360 */ 1361 VDP_STATUS_INVALID_BLEND_EQUATION, 1362 /** 1363 * An invalid/unsupported flag value/combination was supplied. 1364 */ 1365 VDP_STATUS_INVALID_FLAG, 1366 /** 1367 * An invalid/unsupported \ref VdpDecoderProfile value was supplied. 1368 */ 1369 VDP_STATUS_INVALID_DECODER_PROFILE, 1370 /** 1371 * An invalid/unsupported \ref VdpVideoMixerFeature value was supplied. 1372 */ 1373 VDP_STATUS_INVALID_VIDEO_MIXER_FEATURE, 1374 /** 1375 * An invalid/unsupported \ref VdpVideoMixerParameter value was supplied. 1376 */ 1377 VDP_STATUS_INVALID_VIDEO_MIXER_PARAMETER, 1378 /** 1379 * An invalid/unsupported \ref VdpVideoMixerAttribute value was supplied. 1380 */ 1381 VDP_STATUS_INVALID_VIDEO_MIXER_ATTRIBUTE, 1382 /** 1383 * An invalid/unsupported \ref VdpVideoMixerPictureStructure value was 1384 * supplied. 1385 */ 1386 VDP_STATUS_INVALID_VIDEO_MIXER_PICTURE_STRUCTURE, 1387 /** 1388 * An invalid/unsupported \ref VdpFuncId value was supplied. 1389 */ 1390 VDP_STATUS_INVALID_FUNC_ID, 1391 /** 1392 * The size of a supplied object does not match the object it is being 1393 * used with. 1394 * 1395 * For example, a \ref VdpVideoMixer "VdpVideoMixer" is configured to 1396 * process \ref VdpVideoSurface "VdpVideoSurface" objects of a specific 1397 * size. If presented with a \ref VdpVideoSurface "VdpVideoSurface" of a 1398 * different size, this error will be raised. 1399 */ 1400 VDP_STATUS_INVALID_SIZE, 1401 /** 1402 * An invalid/unsupported value was supplied. 1403 * 1404 * This is a catch-all error code for values of type other than those 1405 * with a specific error code. 1406 */ 1407 VDP_STATUS_INVALID_VALUE, 1408 /** 1409 * An invalid/unsupported structure version was specified in a versioned 1410 * structure. This implies that the implementation is older than the 1411 * header file the application was built against. 1412 */ 1413 VDP_STATUS_INVALID_STRUCT_VERSION, 1414 /** 1415 * The system does not have enough resources to complete the requested 1416 * operation at this time. 1417 */ 1418 VDP_STATUS_RESOURCES, 1419 /** 1420 * The set of handles supplied are not all related to the same VdpDevice. 1421 * 1422 * When performing operations that operate on multiple surfaces, such as 1423 * \ref VdpOutputSurfaceRenderOutputSurface or \ref VdpVideoMixerRender, 1424 * all supplied surfaces must have been created within the context of the 1425 * same \ref VdpDevice "VdpDevice" object. This error is raised if they were 1426 * not. 1427 */ 1428 VDP_STATUS_HANDLE_DEVICE_MISMATCH, 1429 /** 1430 * A catch-all error, used when no other error code applies. 1431 */ 1432 VDP_STATUS_ERROR, 1433 } VdpStatus; 1434 1435 /** 1436 * \brief Retrieve a string describing an error code. 1437 * \param[in] status The error code. 1438 * \return A pointer to the string. Note that this is a 1439 * statically allocated read-only string. As such, the 1440 * application must not free the returned pointer. The 1441 * pointer is valid as long as the VDPAU implementation is 1442 * present within the application's address space. 1443 */ 1444 typedef char const * VdpGetErrorString( 1445 VdpStatus status 1446 ); 1447 1448 /** @} */ 1449 1450 /** 1451 * \defgroup versioning Versioning 1452 * 1453 * 1454 * @{ 1455 */ 1456 1457 /** 1458 * \brief The VDPAU interface version described by this header file. 1459 * 1460 * This version will only increase if a major incompatible change is made. 1461 * For example, if the parameters passed to an existing function are modified, 1462 * rather than simply adding new functions/enumerations), or if the mechanism 1463 * used to load the backend driver is modified incompatibly. Such changes are 1464 * unlikely. 1465 * 1466 * This value also represents the DSO version of VDPAU-related 1467 * shared-libraries. 1468 * 1469 * VDPAU version numbers are simple integers that increase monotonically 1470 * (typically by value 1). 1471 */ 1472 #define VDPAU_INTERFACE_VERSION 1 1473 1474 /** 1475 * \brief The VDPAU version described by this header file. 1476 * 1477 * This version will increase whenever any non-documentation change is made to 1478 * vdpau.h, or related header files such as vdpau_x11.h. Such changes 1479 * typically involve the addition of new functions, constants, or features. 1480 * Such changes are expected to be completely backwards-compatible. 1481 * 1482 * VDPAU version numbers are simple integers that increase monotonically 1483 * (typically by value 1). 1484 */ 1485 #define VDPAU_VERSION 1 1486 1487 /** 1488 * \brief Retrieve the VDPAU version implemented by the backend. 1489 * \param[out] api_version The API version. 1490 * \return VdpStatus The completion status of the operation. 1491 */ 1492 typedef VdpStatus VdpGetApiVersion( 1493 /* output parameters follow */ 1494 uint32_t * api_version 1495 ); 1496 1497 /** 1498 * \brief Retrieve an implementation-specific string description 1499 * of the implementation. This typically includes detailed version 1500 * information. 1501 * \param[out] information_string A pointer to the information 1502 * string. Note that this is a statically allocated 1503 * read-only string. As such, the application must not 1504 * free the returned pointer. The pointer is valid as long 1505 * as the implementation is present within the 1506 * application's address space. 1507 * \return VdpStatus The completion status of the operation. 1508 * 1509 * Note that the returned string is useful for information 1510 * reporting. It is not intended that the application should 1511 * parse this string in order to determine any information about 1512 * the implementation. 1513 */ 1514 typedef VdpStatus VdpGetInformationString( 1515 /* output parameters follow */ 1516 char const * * information_string 1517 ); 1518 1519 /** @} */ 1520 1521 /** 1522 * \defgroup VdpDevice VdpDevice; Primary API object 1523 * 1524 * The VdpDevice is the root of the VDPAU object system. Using a 1525 * VdpDevice object, all other object types may be created. See 1526 * the sections describing those other object types for details 1527 * on object creation. 1528 * 1529 * Note that VdpDevice objects are created using the \ref 1530 * api_winsys. 1531 * 1532 * @{ 1533 */ 1534 1535 /** 1536 * \brief An opaque handle representing a VdpDevice object. 1537 */ 1538 typedef uint32_t VdpDevice; 1539 1540 /** 1541 * \brief Destroy a VdpDevice. 1542 * \param[in] device The device to destroy. 1543 * \return VdpStatus The completion status of the operation. 1544 */ 1545 typedef VdpStatus VdpDeviceDestroy( 1546 VdpDevice device 1547 ); 1548 1549 /** @} */ 1550 1551 /** 1552 * \defgroup VdpCSCMatrix VdpCSCMatrix; CSC Matrix Manipulation 1553 * 1554 * When converting from YCbCr to RGB data formats, a color space 1555 * conversion operation must be performed. This operation is 1556 * parameterized using a "color space conversion matrix". The 1557 * VdpCSCMatrix is a data structure representing this 1558 * information. 1559 * 1560 * @{ 1561 */ 1562 1563 /** 1564 * \brief Storage for a color space conversion matrix. 1565 * 1566 * Note that the application may choose to construct the matrix 1567 * content by either: 1568 * - Directly filling in the fields of the CSC matrix 1569 * - Using the \ref VdpGenerateCSCMatrix helper function. 1570 * 1571 * The color space conversion equation is as follows: 1572 * 1573 * \f[ 1574 * \left( \begin{array}{c} R \\ G \\ B \end{array} \right) 1575 * = 1576 * \left( \begin{array}{cccc} 1577 * m_{0,0} & m_{0,1} & m_{0,2} & m_{0,3} \\ 1578 * m_{1,0} & m_{1,1} & m_{1,2} & m_{1,3} \\ 1579 * m_{2,0} & m_{2,1} & m_{2,2} & m_{2,3} 1580 * \end{array} 1581 * \right) 1582 * * 1583 * \left( \begin{array}{c} Y \\ Cb \\ Cr \\ 1.0 \end{array} 1584 * \right) 1585 * \f] 1586 */ 1587 typedef float VdpCSCMatrix[3][4]; 1588 1589 #define VDP_PROCAMP_VERSION 0 1590 1591 /** 1592 * \brief Procamp operation parameterization data. 1593 * 1594 * When performing a color space conversion operation, various 1595 * adjustments can be performed at the same time, such as 1596 * brightness and contrast. This structure defines the level of 1597 * adjustments to make. 1598 */ 1599 typedef struct { 1600 /** 1601 * This field must be filled with VDP_PROCAMP_VERSION 1602 */ 1603 uint32_t struct_version; 1604 /** 1605 * Brightness adjustment amount. A value clamped between 1606 * -1.0 and 1.0. 0.0 represents no modification. 1607 */ 1608 float brightness; 1609 /** 1610 * Contrast adjustment amount. A value clamped between 1611 * 0.0 and 10.0. 1.0 represents no modification. 1612 */ 1613 float contrast; 1614 /** 1615 * Saturation adjustment amount. A value clamped between 0.0 and 1616 * 10.0. 1.0 represents no modification. 1617 */ 1618 float saturation; 1619 /** 1620 * Hue adjustment amount. A value clamped between 1621 * -PI and PI. 0.0 represents no modification. 1622 */ 1623 float hue; 1624 } VdpProcamp; 1625 1626 /** 1627 * \brief YCbCr color space specification. 1628 * 1629 * A number of YCbCr color spaces exist. This enumeration 1630 * defines the specifications known to VDPAU. 1631 */ 1632 typedef uint32_t VdpColorStandard; 1633 1634 /** \hideinitializer \brief ITU-R BT.601 */ 1635 #define VDP_COLOR_STANDARD_ITUR_BT_601 ((VdpColorStandard)0) 1636 /** \hideinitializer \brief ITU-R BT.709 */ 1637 #define VDP_COLOR_STANDARD_ITUR_BT_709 ((VdpColorStandard)1) 1638 /** \hideinitializer \brief SMPTE-240M */ 1639 #define VDP_COLOR_STANDARD_SMPTE_240M ((VdpColorStandard)2) 1640 1641 /** 1642 * \brief Generate a color space conversion matrix 1643 * \param[in] procamp The procamp adjustments to make. If NULL, 1644 * no adjustments will be made. 1645 * \param[in] standard The YCbCr color space to convert from. 1646 * \param[out] csc_matrix The CSC matrix to initialize. 1647 * \return VdpStatus The completion status of the operation. 1648 */ 1649 typedef VdpStatus VdpGenerateCSCMatrix( 1650 VdpProcamp * procamp, 1651 VdpColorStandard standard, 1652 /* output parameters follow */ 1653 VdpCSCMatrix * csc_matrix 1654 ); 1655 1656 /** @} */ 1657 1658 /** 1659 * \defgroup VdpVideoSurface VdpVideoSurface; Video Surface object 1660 * 1661 * A VdpVideoSurface stores YCbCr data in an internal format, 1662 * with a variety of possible chroma sub-sampling options. 1663 * 1664 * A VdpVideoSurface may be filled with: 1665 * - Data provided by the CPU via \ref 1666 * VdpVideoSurfacePutBitsYCbCr (i.e. software decode.) 1667 * - The result of applying a \ref VdpDecoder "VdpDecoder" to 1668 * compressed video data. 1669 * 1670 * VdpVideoSurface content may be accessed by: 1671 * - The application via \ref VdpVideoSurfaceGetBitsYCbCr 1672 * - The Hardware that implements \ref VdpOutputSurface 1673 * "VdpOutputSurface" \ref VdpOutputSurfaceRender 1674 * "rendering functionality". 1675 * - The Hardware the implements \ref VdpVideoMixer 1676 * "VdpVideoMixer" functionality. 1677 * 1678 * VdpVideoSurfaces are not directly displayable. They must be 1679 * converted into a displayable format using \ref VdpVideoMixer 1680 * "VdpVideoMixer" objects. 1681 * 1682 * See \ref video_mixer_usage for additional information. 1683 * 1684 * @{ 1685 */ 1686 1687 /** 1688 * \brief Query the implementation's VdpVideoSurface 1689 * capabilities. 1690 * \param[in] device The device to query. 1691 * \param[in] surface_chroma_type The type of chroma type for 1692 * which information is requested. 1693 * \param[out] is_supported Is this chroma type supported? 1694 * \param[out] max_width The maximum supported surface width for 1695 * this chroma type. 1696 * \param[out] max_height The maximum supported surface height 1697 * for this chroma type. 1698 * \return VdpStatus The completion status of the operation. 1699 */ 1700 typedef VdpStatus VdpVideoSurfaceQueryCapabilities( 1701 VdpDevice device, 1702 VdpChromaType surface_chroma_type, 1703 /* output parameters follow */ 1704 VdpBool * is_supported, 1705 uint32_t * max_width, 1706 uint32_t * max_height 1707 ); 1708 1709 /** 1710 * \brief Query the implementation's VdpVideoSurface 1711 * GetBits/PutBits capabilities. 1712 * \param[in] device The device to query. 1713 * \param[in] surface_chroma_type The type of chroma type for 1714 * which information is requested. 1715 * \param[in] bits_ycbcr_format The format of application "bits" 1716 * buffer for which information is requested. 1717 * \param[out] is_supported Is this chroma type supported? 1718 * \return VdpStatus The completion status of the operation. 1719 */ 1720 typedef VdpStatus VdpVideoSurfaceQueryGetPutBitsYCbCrCapabilities( 1721 VdpDevice device, 1722 VdpChromaType surface_chroma_type, 1723 VdpYCbCrFormat bits_ycbcr_format, 1724 /* output parameters follow */ 1725 VdpBool * is_supported 1726 ); 1727 1728 /** 1729 * \brief An opaque handle representing a VdpVideoSurface 1730 * object. 1731 */ 1732 typedef uint32_t VdpVideoSurface; 1733 1734 /** 1735 * \brief Create a VdpVideoSurface. 1736 * \param[in] device The device that will contain the surface. 1737 * \param[in] chroma_type The chroma type of the new surface. 1738 * \param[in] width The width of the new surface. 1739 * \param[in] height The height of the new surface. 1740 * \param[out] surface The new surface's handle. 1741 * \return VdpStatus The completion status of the operation. 1742 * 1743 * The memory backing the surface may not be initialized during 1744 * creation. Applications are expected to initialize any region 1745 * that they use, via \ref VdpDecoderRender or \ref 1746 * VdpVideoSurfacePutBitsYCbCr. 1747 * 1748 * Note that certain widths/heights are impossible for specific values of 1749 * chroma_type. For example, the definition of VDP_CHROMA_TYPE_420 implies 1750 * that the width must be even, since each single chroma sample covers two 1751 * luma samples horizontally. A similar argument applies to surface heights, 1752 * although doubly so, since interlaced pictures must be supported; each 1753 * field's height must itself be a multiple of 2. Hence the overall surface's 1754 * height must be a multiple of 4. 1755 * 1756 * Similar rules apply to other chroma_type values. 1757 * 1758 * Implementations may also impose additional restrictions on the surface 1759 * sizes they support, potentially requiring additional rounding of actual 1760 * surface sizes. 1761 * 1762 * In most cases, this is not an issue, since: 1763 * - Video streams are encoded as an array of macro-blocks, which typically 1764 * have larger size alignment requirements than video surfaces do. 1765 * - APIs such as \ref VdpVideoMixerRender allow specification of a sub-region 1766 * of the surface to read, which allows the padding data to be clipped away. 1767 * 1768 * However, other APIs such as \ref VdpVideoSurfaceGetBitsYCbCr and 1769 * \ref VdpVideoSurfacePutBitsYCbCr do not allow a sub-region to be specified, 1770 * and always operate on surface size that was actually allocated, rather 1771 * than the surface size that was requested. In this case, applications need 1772 * to be aware of the actual surface size, in order to allocate appropriately 1773 * sized buffers for the get-/put-bits operations. 1774 * 1775 * For this reason, applications may need to call 1776 * \ref VdpVideoSurfaceGetParameters after creation, in order to retrieve the 1777 * actual surface size. 1778 */ 1779 typedef VdpStatus VdpVideoSurfaceCreate( 1780 VdpDevice device, 1781 VdpChromaType chroma_type, 1782 uint32_t width, 1783 uint32_t height, 1784 /* output parameters follow */ 1785 VdpVideoSurface * surface 1786 ); 1787 1788 /** 1789 * \brief Destroy a VdpVideoSurface. 1790 * \param[in] surface The surface's handle. 1791 * \return VdpStatus The completion status of the operation. 1792 */ 1793 typedef VdpStatus VdpVideoSurfaceDestroy( 1794 VdpVideoSurface surface 1795 ); 1796 1797 /** 1798 * \brief Retrieve the parameters used to create a 1799 * VdpVideoSurface. 1800 * \param[in] surface The surface's handle. 1801 * \param[out] chroma_type The chroma type of the surface. 1802 * \param[out] width The width of the surface. 1803 * \param[out] height The height of the surface. 1804 * \return VdpStatus The completion status of the operation. 1805 */ 1806 typedef VdpStatus VdpVideoSurfaceGetParameters( 1807 VdpVideoSurface surface, 1808 /* output parameters follow */ 1809 VdpChromaType * chroma_type, 1810 uint32_t * width, 1811 uint32_t * height 1812 ); 1813 1814 /** 1815 * \brief Copy image data from a VdpVideoSurface to application 1816 * memory in a specified YCbCr format. 1817 * \param[in] surface The surface's handle. 1818 * \param[in] destination_ycbcr_format The format of the 1819 * application's data buffers. 1820 * \param[in] destination_data Pointers to the application data 1821 * buffers into which the image data will be written. Note 1822 * that this is an array of pointers, one per plane. The 1823 * destination_format parameter will define how many 1824 * planes are required. 1825 * \param[in] destination_pitches Pointers to the pitch values 1826 * for the application data buffers. Note that this is an 1827 * array of pointers, one per plane. The 1828 * destination_format parameter will define how many 1829 * planes are required. 1830 * \return VdpStatus The completion status of the operation. 1831 */ 1832 typedef VdpStatus VdpVideoSurfaceGetBitsYCbCr( 1833 VdpVideoSurface surface, 1834 VdpYCbCrFormat destination_ycbcr_format, 1835 void * const * destination_data, 1836 uint32_t const * destination_pitches 1837 ); 1838 1839 /** 1840 * \brief Copy image data from application memory in a specific 1841 * YCbCr format to a VdpVideoSurface. 1842 * \param[in] surface The surface's handle. 1843 * \param[in] source_ycbcr_format The format of the 1844 * application's data buffers. 1845 * \param[in] source_data Pointers to the application data 1846 * buffers from which the image data will be copied. Note 1847 * that this is an array of pointers, one per plane. The 1848 * source_format parameter will define how many 1849 * planes are required. 1850 * \param[in] source_pitches Pointers to the pitch values 1851 * for the application data buffers. Note that this is an 1852 * array of pointers, one per plane. The 1853 * source_format parameter will define how many 1854 * planes are required. 1855 * \return VdpStatus The completion status of the operation. 1856 */ 1857 typedef VdpStatus VdpVideoSurfacePutBitsYCbCr( 1858 VdpVideoSurface surface, 1859 VdpYCbCrFormat source_ycbcr_format, 1860 void const * const * source_data, 1861 uint32_t const * source_pitches 1862 ); 1863 1864 /** @} */ 1865 1866 /** 1867 * \defgroup VdpOutputSurface VdpOutputSurface; Output Surface object 1868 * 1869 * A VdpOutputSurface stores RGBA data in a defined format. 1870 * 1871 * A VdpOutputSurface may be filled with: 1872 * - Data provided by the CPU via the various 1873 * VdpOutputSurfacePutBits functions. 1874 * - Using the VdpOutputSurface \ref VdpOutputSurfaceRender 1875 * "rendering functionality". 1876 * - Using a \ref VdpVideoMixer "VdpVideoMixer" object. 1877 * 1878 * VdpOutputSurface content may be accessed by: 1879 * - The application via the various VdpOutputSurfaceGetBits 1880 * functions. 1881 * - The Hardware that implements VdpOutputSurface 1882 * \ref VdpOutputSurfaceRender "rendering functionality". 1883 * - The Hardware the implements \ref VdpVideoMixer 1884 * "VdpVideoMixer" functionality. 1885 * - The Hardware that implements \ref VdpPresentationQueue 1886 * "VdpPresentationQueue" functionality, 1887 * 1888 * VdpOutputSurfaces are directly displayable using a \ref 1889 * VdpPresentationQueue "VdpPresentationQueue" object. 1890 * 1891 * @{ 1892 */ 1893 1894 /** 1895 * \brief The set of all known color table formats, for use with 1896 * \ref VdpOutputSurfacePutBitsIndexed. 1897 */ 1898 typedef uint32_t VdpColorTableFormat; 1899 1900 /** 1901 * \hideinitializer 1902 * \brief 8-bit per component packed into 32-bits 1903 * 1904 * This format is an array of packed 32-bit RGB color values. 1905 * Bits [31:24] are unused, bits [23:16] contain R, bits [15:8] 1906 * contain G, and bits [7:0] contain B. Note: The format is 1907 * physically an array of uint32_t values, and should be accessed 1908 * as such by the application in order to avoid endianness 1909 * issues. 1910 */ 1911 #define VDP_COLOR_TABLE_FORMAT_B8G8R8X8 ((VdpColorTableFormat)0) 1912 1913 /** 1914 * \brief Query the implementation's VdpOutputSurface 1915 * capabilities. 1916 * \param[in] device The device to query. 1917 * \param[in] surface_rgba_format The surface format for 1918 * which information is requested. 1919 * \param[out] is_supported Is this surface format supported? 1920 * \param[out] max_width The maximum supported surface width for 1921 * this chroma type. 1922 * \param[out] max_height The maximum supported surface height 1923 * for this chroma type. 1924 * \return VdpStatus The completion status of the operation. 1925 */ 1926 typedef VdpStatus VdpOutputSurfaceQueryCapabilities( 1927 VdpDevice device, 1928 VdpRGBAFormat surface_rgba_format, 1929 /* output parameters follow */ 1930 VdpBool * is_supported, 1931 uint32_t * max_width, 1932 uint32_t * max_height 1933 ); 1934 1935 /** 1936 * \brief Query the implementation's capability to perform a 1937 * PutBits operation using application data matching the 1938 * surface's format. 1939 * \param[in] device The device to query. 1940 * \param[in] surface_rgba_format The surface format for 1941 * which information is requested. 1942 * \param[out] is_supported Is this surface format supported? 1943 * \return VdpStatus The completion status of the operation. 1944 */ 1945 typedef VdpStatus VdpOutputSurfaceQueryGetPutBitsNativeCapabilities( 1946 VdpDevice device, 1947 VdpRGBAFormat surface_rgba_format, 1948 /* output parameters follow */ 1949 VdpBool * is_supported 1950 ); 1951 1952 /** 1953 * \brief Query the implementation's capability to perform a 1954 * PutBits operation using application data in a specific 1955 * indexed format. 1956 * \param[in] device The device to query. 1957 * \param[in] surface_rgba_format The surface format for 1958 * which information is requested. 1959 * \param[in] bits_indexed_format The format of the application 1960 * data buffer. 1961 * \param[in] color_table_format The format of the color lookup 1962 * table. 1963 * \param[out] is_supported Is this surface format supported? 1964 * \return VdpStatus The completion status of the operation. 1965 */ 1966 typedef VdpStatus VdpOutputSurfaceQueryPutBitsIndexedCapabilities( 1967 VdpDevice device, 1968 VdpRGBAFormat surface_rgba_format, 1969 VdpIndexedFormat bits_indexed_format, 1970 VdpColorTableFormat color_table_format, 1971 /* output parameters follow */ 1972 VdpBool * is_supported 1973 ); 1974 1975 /** 1976 * \brief Query the implementation's capability to perform a 1977 * PutBits operation using application data in a specific 1978 * YCbCr/YUB format. 1979 * \param[in] device The device to query. 1980 * \param[in] surface_rgba_format The surface format for which 1981 * information is requested. 1982 * \param[in] bits_ycbcr_format The format of the application 1983 * data buffer. 1984 * \param[out] is_supported Is this surface format supported? 1985 * \return VdpStatus The completion status of the operation. 1986 */ 1987 typedef VdpStatus VdpOutputSurfaceQueryPutBitsYCbCrCapabilities( 1988 VdpDevice device, 1989 VdpRGBAFormat surface_rgba_format, 1990 VdpYCbCrFormat bits_ycbcr_format, 1991 /* output parameters follow */ 1992 VdpBool * is_supported 1993 ); 1994 1995 /** 1996 * \brief An opaque handle representing a VdpOutputSurface 1997 * object. 1998 */ 1999 typedef uint32_t VdpOutputSurface; 2000 2001 /** 2002 * \brief Create a VdpOutputSurface. 2003 * \param[in] device The device that will contain the surface. 2004 * \param[in] rgba_format The format of the new surface. 2005 * \param[in] width The width of the new surface. 2006 * \param[in] height The height of the new surface. 2007 * \param[out] surface The new surface's handle. 2008 * \return VdpStatus The completion status of the operation. 2009 * 2010 * The memory backing the surface will be initialized to 0 color 2011 * and 0 alpha (i.e. black.) 2012 */ 2013 typedef VdpStatus VdpOutputSurfaceCreate( 2014 VdpDevice device, 2015 VdpRGBAFormat rgba_format, 2016 uint32_t width, 2017 uint32_t height, 2018 /* output parameters follow */ 2019 VdpOutputSurface * surface 2020 ); 2021 2022 /** 2023 * \brief Destroy a VdpOutputSurface. 2024 * \param[in] surface The surface's handle. 2025 * \return VdpStatus The completion status of the operation. 2026 */ 2027 typedef VdpStatus VdpOutputSurfaceDestroy( 2028 VdpOutputSurface surface 2029 ); 2030 2031 /** 2032 * \brief Retrieve the parameters used to create a 2033 * VdpOutputSurface. 2034 * \param[in] surface The surface's handle. 2035 * \param[out] rgba_format The format of the surface. 2036 * \param[out] width The width of the surface. 2037 * \param[out] height The height of the surface. 2038 * \return VdpStatus The completion status of the operation. 2039 */ 2040 typedef VdpStatus VdpOutputSurfaceGetParameters( 2041 VdpOutputSurface surface, 2042 /* output parameters follow */ 2043 VdpRGBAFormat * rgba_format, 2044 uint32_t * width, 2045 uint32_t * height 2046 ); 2047 2048 /** 2049 * \brief Copy image data from a VdpOutputSurface to application 2050 * memory in the surface's native format. 2051 * \param[in] surface The surface's handle. 2052 * \param[in] source_rect The sub-rectangle of the source 2053 * surface to copy. If NULL, the entire surface will be 2054 * retrieved. 2055 * \param[in] destination_data Pointers to the application data 2056 * buffers into which the image data will be written. Note 2057 * that this is an array of pointers, one per plane. The 2058 * destination_format parameter will define how many 2059 * planes are required. 2060 * \param[in] destination_pitches Pointers to the pitch values 2061 * for the application data buffers. Note that this is an 2062 * array of pointers, one per plane. The 2063 * destination_format parameter will define how many 2064 * planes are required. 2065 * \return VdpStatus The completion status of the operation. 2066 */ 2067 typedef VdpStatus VdpOutputSurfaceGetBitsNative( 2068 VdpOutputSurface surface, 2069 VdpRect const * source_rect, 2070 void * const * destination_data, 2071 uint32_t const * destination_pitches 2072 ); 2073 2074 /** 2075 * \brief Copy image data from application memory in the 2076 * surface's native format to a VdpOutputSurface. 2077 * \param[in] surface The surface's handle. 2078 * \param[in] source_data Pointers to the application data 2079 * buffers from which the image data will be copied. Note 2080 * that this is an array of pointers, one per plane. The 2081 * source_format parameter will define how many 2082 * planes are required. 2083 * \param[in] source_pitches Pointers to the pitch values 2084 * for the application data buffers. Note that this is an 2085 * array of pointers, one per plane. The 2086 * source_format parameter will define how many 2087 * planes are required. 2088 * \param[in] destination_rect The sub-rectangle of the surface 2089 * to fill with application data. If NULL, the entire 2090 * surface will be updated. 2091 * \return VdpStatus The completion status of the operation. 2092 */ 2093 typedef VdpStatus VdpOutputSurfacePutBitsNative( 2094 VdpOutputSurface surface, 2095 void const * const * source_data, 2096 uint32_t const * source_pitches, 2097 VdpRect const * destination_rect 2098 ); 2099 2100 /** 2101 * \brief Copy image data from application memory in a specific 2102 * indexed format to a VdpOutputSurface. 2103 * \param[in] surface The surface's handle. 2104 * \param[in] source_indexed_format The format of the 2105 * application's data buffers. 2106 * \param[in] source_data Pointers to the application data 2107 * buffers from which the image data will be copied. Note 2108 * that this is an array of pointers, one per plane. The 2109 * source_indexed_format parameter will define how many 2110 * planes are required. 2111 * \param[in] source_pitches Pointers to the pitch values 2112 * for the application data buffers. Note that this is an 2113 * array of pointers, one per plane. The 2114 * source_indexed_format parameter will define how many 2115 * planes are required. 2116 * \param[in] destination_rect The sub-rectangle of the surface 2117 * to fill with application data. If NULL, the entire 2118 * surface will be updated. 2119 * \param[in] color_table_format The format of the color_table. 2120 * \param[in] color_table A table that maps between source index 2121 * and target color data. See \ref VdpColorTableFormat for 2122 * details regarding the memory layout. 2123 * \return VdpStatus The completion status of the operation. 2124 */ 2125 typedef VdpStatus VdpOutputSurfacePutBitsIndexed( 2126 VdpOutputSurface surface, 2127 VdpIndexedFormat source_indexed_format, 2128 void const * const * source_data, 2129 uint32_t const * source_pitch, 2130 VdpRect const * destination_rect, 2131 VdpColorTableFormat color_table_format, 2132 void const * color_table 2133 ); 2134 2135 /** 2136 * \brief Copy image data from application memory in a specific 2137 * YCbCr format to a VdpOutputSurface. 2138 * \param[in] surface The surface's handle. 2139 * \param[in] source_ycbcr_format The format of the 2140 * application's data buffers. 2141 * \param[in] source_data Pointers to the application data 2142 * buffers from which the image data will be copied. Note 2143 * that this is an array of pointers, one per plane. The 2144 * source_ycbcr_format parameter will define how many 2145 * planes are required. 2146 * \param[in] source_pitches Pointers to the pitch values 2147 * for the application data buffers. Note that this is an 2148 * array of pointers, one per plane. The 2149 * source_ycbcr_format parameter will define how many 2150 * planes are required. 2151 * \param[in] destination_rect The sub-rectangle of the surface 2152 * to fill with application data. If NULL, the entire 2153 * surface will be updated. 2154 * \param[in] csc_matrix The color space conversion matrix used 2155 * by the copy operation. If NULL, a default matrix will 2156 * be used internally. Th default matrix is equivalent to 2157 * ITU-R BT.601 with no procamp changes. 2158 * \return VdpStatus The completion status of the operation. 2159 */ 2160 typedef VdpStatus VdpOutputSurfacePutBitsYCbCr( 2161 VdpOutputSurface surface, 2162 VdpYCbCrFormat source_ycbcr_format, 2163 void const * const * source_data, 2164 uint32_t const * source_pitches, 2165 VdpRect const * destination_rect, 2166 VdpCSCMatrix const * csc_matrix 2167 ); 2168 2169 /** @} */ 2170 2171 /** 2172 * \defgroup VdpBitmapSurface VdpBitmapSurface; Bitmap Surface object 2173 * 2174 * A VdpBitmapSurface stores RGBA data in a defined format. 2175 * 2176 * A VdpBitmapSurface may be filled with: 2177 * - Data provided by the CPU via the \ref 2178 * VdpBitmapSurfacePutBitsNative function. 2179 * 2180 * VdpBitmapSurface content may be accessed by: 2181 * - The Hardware that implements \ref VdpOutputSurface 2182 * "VdpOutputSurface" \ref VdpOutputSurfaceRender 2183 * "rendering functionality" 2184 * 2185 * VdpBitmapSurface objects are intended to store static read-only data, such 2186 * as font glyphs, and the bitmaps used to compose an applications' 2187 * user-interface. 2188 * 2189 * The primary differences between VdpBitmapSurfaces and 2190 * \ref VdpOutputSurface "VdpOutputSurface"s are: 2191 * 2192 * - You cannot render to a VdpBitmapSurface, just upload native data via 2193 * the PutBits API. 2194 * 2195 * - The read-only nature of a VdpBitmapSurface gives the implementation more 2196 * flexibility in its choice of data storage location for the bitmap data. 2197 * For example, some implementations may choose to store some/all 2198 * VdpBitmapSurface objects in system memory to relieve GPU memory pressure. 2199 * 2200 * - VdpBitmapSurface and VdpOutputSurface may support different subsets of all 2201 * known RGBA formats. 2202 * 2203 * @{ 2204 */ 2205 2206 /** 2207 * \brief Query the implementation's VdpBitmapSurface 2208 * capabilities. 2209 * \param[in] device The device to query. 2210 * \param[in] surface_rgba_format The surface format for 2211 * which information is requested. 2212 * \param[out] is_supported Is this surface format supported? 2213 * \param[out] max_width The maximum supported surface width for 2214 * this chroma type. 2215 * \param[out] max_height The maximum supported surface height 2216 * for this chroma type. 2217 * \return VdpStatus The completion status of the operation. 2218 */ 2219 typedef VdpStatus VdpBitmapSurfaceQueryCapabilities( 2220 VdpDevice device, 2221 VdpRGBAFormat surface_rgba_format, 2222 /* output parameters follow */ 2223 VdpBool * is_supported, 2224 uint32_t * max_width, 2225 uint32_t * max_height 2226 ); 2227 2228 /** 2229 * \brief An opaque handle representing a VdpBitmapSurface 2230 * object. 2231 */ 2232 typedef uint32_t VdpBitmapSurface; 2233 2234 /** 2235 * \brief Create a VdpBitmapSurface. 2236 * \param[in] device The device that will contain the surface. 2237 * \param[in] rgba_format The format of the new surface. 2238 * \param[in] width The width of the new surface. 2239 * \param[in] height The height of the new surface. 2240 * \param[in] frequently_accessed Is this bitmap used 2241 * frequently, or infrequently, by compositing options? 2242 * Implementations may use this as a hint to determine how 2243 * to allocate the underlying storage for the surface. 2244 * \param[out] surface The new surface's handle. 2245 * \return VdpStatus The completion status of the operation. 2246 * 2247 * The memory backing the surface may not be initialized 2248 * during creation. Applications are expected initialize any 2249 * region that they use, via \ref VdpBitmapSurfacePutBitsNative. 2250 */ 2251 typedef VdpStatus VdpBitmapSurfaceCreate( 2252 VdpDevice device, 2253 VdpRGBAFormat rgba_format, 2254 uint32_t width, 2255 uint32_t height, 2256 VdpBool frequently_accessed, 2257 /* output parameters follow */ 2258 VdpBitmapSurface * surface 2259 ); 2260 2261 /** 2262 * \brief Destroy a VdpBitmapSurface. 2263 * \param[in] surface The surface's handle. 2264 * \return VdpStatus The completion status of the operation. 2265 */ 2266 typedef VdpStatus VdpBitmapSurfaceDestroy( 2267 VdpBitmapSurface surface 2268 ); 2269 2270 /** 2271 * \brief Retrieve the parameters used to create a 2272 * VdpBitmapSurface. 2273 * \param[in] surface The surface's handle. 2274 * \param[out] rgba_format The format of the surface. 2275 * \param[out] width The width of the surface. 2276 * \param[out] height The height of the surface. 2277 * \param[out] frequently_accessed The frequently_accessed state 2278 * of the surface. 2279 * \return VdpStatus The completion status of the operation. 2280 */ 2281 typedef VdpStatus VdpBitmapSurfaceGetParameters( 2282 VdpBitmapSurface surface, 2283 /* output parameters follow */ 2284 VdpRGBAFormat * rgba_format, 2285 uint32_t * width, 2286 uint32_t * height, 2287 VdpBool * frequently_accessed 2288 ); 2289 2290 /** 2291 * \brief Copy image data from application memory in the 2292 * surface's native format to a VdpBitmapSurface. 2293 * \param[in] surface The surface's handle. 2294 * \param[in] source_data Pointers to the application data 2295 * buffers from which the image data will be copied. Note 2296 * that this is an array of pointers, one per plane. The 2297 * source_format parameter will define how many 2298 * planes are required. 2299 * \param[in] source_pitches Pointers to the pitch values 2300 * for the application data buffers. Note that this is an 2301 * array of pointers, one per plane. The 2302 * source_format parameter will define how many 2303 * planes are required. 2304 * \param[in] destination_rect The sub-rectangle of the surface 2305 * to fill with application data. If NULL, the entire 2306 * surface will be updated. 2307 * \return VdpStatus The completion status of the operation. 2308 */ 2309 typedef VdpStatus VdpBitmapSurfacePutBitsNative( 2310 VdpBitmapSurface surface, 2311 void const * const * source_data, 2312 uint32_t const * source_pitches, 2313 VdpRect const * destination_rect 2314 ); 2315 2316 /** @} */ 2317 2318 /** 2319 * \defgroup VdpOutputSurfaceRender VdpOutputSurface Rendering Functionality 2320 * 2321 * \ref VdpOutputSurface "VdpOutputSurface" objects 2322 * directly provide some rendering/compositing operations. These 2323 * are described below. 2324 * 2325 * @{ 2326 */ 2327 2328 /** 2329 * \hideinitializer 2330 * \brief The blending equation factors. 2331 */ 2332 typedef enum { 2333 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ZERO = 0, 2334 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE = 1, 2335 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_SRC_COLOR = 2, 2336 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_SRC_COLOR = 3, 2337 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_SRC_ALPHA = 4, 2338 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA = 5, 2339 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_DST_ALPHA = 6, 2340 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_DST_ALPHA = 7, 2341 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_DST_COLOR = 8, 2342 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_DST_COLOR = 9, 2343 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_SRC_ALPHA_SATURATE = 10, 2344 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_CONSTANT_COLOR = 11, 2345 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR = 12, 2346 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_CONSTANT_ALPHA = 13, 2347 VDP_OUTPUT_SURFACE_RENDER_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA = 14, 2348 } VdpOutputSurfaceRenderBlendFactor; 2349 2350 /** 2351 * \hideinitializer 2352 * \brief The blending equations. 2353 */ 2354 typedef enum { 2355 VDP_OUTPUT_SURFACE_RENDER_BLEND_EQUATION_SUBTRACT = 0, 2356 VDP_OUTPUT_SURFACE_RENDER_BLEND_EQUATION_REVERSE_SUBTRACT = 1, 2357 VDP_OUTPUT_SURFACE_RENDER_BLEND_EQUATION_ADD = 2, 2358 VDP_OUTPUT_SURFACE_RENDER_BLEND_EQUATION_MIN = 3, 2359 VDP_OUTPUT_SURFACE_RENDER_BLEND_EQUATION_MAX = 4, 2360 } VdpOutputSurfaceRenderBlendEquation; 2361 2362 #define VDP_OUTPUT_SURFACE_RENDER_BLEND_STATE_VERSION 0 2363 2364 /** 2365 * \brief Complete blending operation definition. 2366 * 2367 * A "blend state" operation controls the math behind certain rendering 2368 * operations. 2369 * 2370 * The blend math is the familiar OpenGL blend math: 2371 * \f[ 2372 * dst.a = equation(blendFactorDstAlpha*dst.a, 2373 * blendFactorSrcAlpha*src.a); 2374 * \f] 2375 * \f[ 2376 * dst.rgb = equation(blendFactorDstColor*dst.rgb, 2377 * blendFactorSrcColor*src.rgb); 2378 * \f] 2379 * 2380 * Note that when equation is MIN or MAX, the blend factors and constants 2381 * are ignored, and are treated as if they were 1.0. 2382 */ 2383 typedef struct { 2384 /** 2385 * This field must be filled with VDP_OUTPUT_SURFACE_RENDER_BLEND_STATE_VERSIION 2386 */ 2387 uint32_t struct_version; 2388 VdpOutputSurfaceRenderBlendFactor blend_factor_source_color; 2389 VdpOutputSurfaceRenderBlendFactor blend_factor_destination_color; 2390 VdpOutputSurfaceRenderBlendFactor blend_factor_source_alpha; 2391 VdpOutputSurfaceRenderBlendFactor blend_factor_destination_alpha; 2392 VdpOutputSurfaceRenderBlendEquation blend_equation_color; 2393 VdpOutputSurfaceRenderBlendEquation blend_equation_alpha; 2394 VdpColor blend_constant; 2395 } VdpOutputSurfaceRenderBlendState; 2396 2397 /** 2398 * \hideinitializer 2399 * \brief Do not rotate source_surface prior to compositing. 2400 */ 2401 #define VDP_OUTPUT_SURFACE_RENDER_ROTATE_0 0 2402 2403 /** 2404 * \hideinitializer 2405 * \brief Rotate source_surface 90 degrees clockwise prior to 2406 * compositing. 2407 */ 2408 #define VDP_OUTPUT_SURFACE_RENDER_ROTATE_90 1 2409 2410 /** 2411 * \hideinitializer 2412 * \brief Rotate source_surface 180 degrees prior to 2413 * compositing. 2414 */ 2415 #define VDP_OUTPUT_SURFACE_RENDER_ROTATE_180 2 2416 2417 /** 2418 * \hideinitializer 2419 * \brief Rotate source_surface 270 degrees clockwise prior to 2420 * compositing. 2421 */ 2422 #define VDP_OUTPUT_SURFACE_RENDER_ROTATE_270 3 2423 2424 /** 2425 * \hideinitializer 2426 * \brief A separate color is used for each vertex of the 2427 * smooth-shaded quad. Hence, colors array contains 4 2428 * elements rather than 1. See description of colors 2429 * array. 2430 */ 2431 #define VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX (1 << 2) 2432 2433 /** 2434 * \brief Composite a sub-rectangle of a \ref VdpOutputSurface 2435 * "VdpOutputSurface" into a sub-rectangle of another 2436 * \ref VdpOutputSurface VdpOutputSurface. 2437 * \param[in] destination_surface The destination surface of the 2438 * compositing operation. 2439 * \param[in] destination_rect The sub-rectangle of the 2440 * destination surface to update. If NULL, the entire 2441 * destination surface will be updated. 2442 * \param[in] source_surface The source surface for the 2443 * compositing operation. The surface is treated as having 2444 * four components: red, green, blue and alpha. Any 2445 * missing components are treated as 1.0. For example, for 2446 * an A8 VdpOutputSurface, alpha will come from the surface 2447 * but red, green and blue will be treated as 1.0. If 2448 * source_surface is VDP_INVALID_HANDLE, all components will 2449 * be treated as 1.0. Note that destination_surface and 2450 * source_surface must have been allocated via the same 2451 * \ref VdpDevice "VdpDevice". 2452 * \param[in] source_rect The sub-rectangle of the source 2453 * surface to read from. If NULL, the entire 2454 * source_surface will be read. Left/right and/or top/bottom 2455 * co-ordinates may be swapped to flip the source. Any 2456 * flip occurs prior to any requested rotation. Values 2457 * from outside the source surface are valid and samples 2458 * at those locations will be taken from the nearest edge. 2459 * \param[in] colors A pointer to an array of \ref VdpColor 2460 * "VdpColor" objects. If the flag 2461 * VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX is set, 2462 * VDPAU will four entries from the array, and treat them 2463 * as the colors corresponding to the upper-left, 2464 * upper-right, lower-right and lower-left corners of the 2465 * post-rotation source (i.e. indices 0, 1, 2 and 3 run 2466 * clockwise from the upper left corner). If the flag 2467 * VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX is not 2468 * set, VDPAU will use the single VdpColor for all four 2469 * corners. If colors is NULL then red, green, blue and 2470 * alpha values of 1.0 will be used. 2471 * \param[in] blend_state If a blend state is provided, the 2472 * blend state will be used for the composite operation. If 2473 * NULL, blending is effectively disabled, which is 2474 * equivalent to a blend equation of ADD, source blend 2475 * factors of ONE and destination blend factors of ZERO. 2476 * See \ref VdpOutputSurfaceRenderBlendState for details 2477 * regarding the mathematics of the blending operation. 2478 * \param[in] flags A set of flags influencing how the 2479 * compositing operation works. 2480 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_0 2481 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_90 2482 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_180 2483 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_270 2484 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX 2485 * \return VdpStatus The completion status of the operation. 2486 * 2487 * The general compositing pipeline is as follows. 2488 * 2489 * -# Extract source_rect from source_surface. 2490 * 2491 * -# The extracted source is rotated 0, 90, 180 or 270 degrees 2492 * according to the flags. 2493 * 2494 * -# The rotated source is component-wise multiplied by a 2495 * smooth-shaded quad with a (potentially) different color at 2496 * each vertex. 2497 * 2498 * -# The resulting rotated, smooth-shaded quad is scaled to the 2499 * size of destination_rect and composited with 2500 * destination_surface using the provided blend state. 2501 * 2502 */ 2503 typedef VdpStatus VdpOutputSurfaceRenderOutputSurface( 2504 VdpOutputSurface destination_surface, 2505 VdpRect const * destination_rect, 2506 VdpOutputSurface source_surface, 2507 VdpRect const * source_rect, 2508 VdpColor const * colors, 2509 VdpOutputSurfaceRenderBlendState const * blend_state, 2510 uint32_t flags 2511 ); 2512 2513 /** 2514 * \brief Composite a sub-rectangle of a \ref VdpBitmapSurface 2515 * "VdpBitmapSurface" into a sub-rectangle of a 2516 * \ref VdpOutputSurface VdpOutputSurface. 2517 * \param[in] destination_surface The destination surface of the 2518 * compositing operation. 2519 * \param[in] destination_rect The sub-rectangle of the 2520 * destination surface to update. If NULL, the entire 2521 * destination surface will be updated. 2522 * \param[in] source_surface The source surface for the 2523 * compositing operation. The surface is treated as having 2524 * four components: red, green, blue and alpha. Any 2525 * missing components are treated as 1.0. For example, for 2526 * an A8 VdpBitmapSurface, alpha will come from the surface 2527 * but red, green and blue will be treated as 1.0. If 2528 * source_surface is VDP_INVALID_HANDLE, all components will 2529 * be treated as 1.0. Note that destination_surface and 2530 * source_surface must have been allocated via the same 2531 * \ref VdpDevice "VdpDevice". 2532 * \param[in] source_rect The sub-rectangle of the source 2533 * surface to read from. If NULL, the entire 2534 * source_surface will be read. Left/right ot top/bottom 2535 * co-ordinates may be swapped to flip the source. Any 2536 * flip occurs prior to any requested rotation. Values 2537 * from outside the source surface are valid and samples 2538 * at those locations will be taken from the nearest edge. 2539 * \param[in] colors A pointer to an array of \ref VdpColor 2540 * "VdpColor" objects. If the flag 2541 * VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX is set, 2542 * VDPAU will four entries from the array, and treat them 2543 * as the colors corresponding to the upper-left, 2544 * upper-right, lower-right and lower-left corners of the 2545 * post-rotation source (i.e. indices 0, 1, 2 and 3 run 2546 * clockwise from the upper left corner). If the flag 2547 * VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX is not 2548 * set, VDPAU will use the single VdpColor for all four 2549 * corners. If colors is NULL then red, green, blue and 2550 * alpha values of 1.0 will be used. 2551 * \param[in] blend_state If a blend state is provided, the 2552 * blend state will be used for the composite operation. If 2553 * NULL, blending is effectively disabled, which is 2554 * equivalent to a blend equation of ADD, source blend 2555 * factors of ONE and destination blend factors of ZERO. 2556 * See \ref VdpOutputSurfaceRenderBlendState for details 2557 * regarding the mathematics of the blending operation. 2558 * \param[in] flags A set of flags influencing how the 2559 * compositing operation works. 2560 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_0 2561 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_90 2562 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_180 2563 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_ROTATE_270 2564 * \arg \ref VDP_OUTPUT_SURFACE_RENDER_COLOR_PER_VERTEX 2565 * \return VdpStatus The completion status of the operation. 2566 * 2567 * The general compositing pipeline is as follows. 2568 * 2569 * -# Extract source_rect from source_surface. 2570 * 2571 * -# The extracted source is rotated 0, 90, 180 or 270 degrees 2572 * according to the flags. 2573 * 2574 * -# The rotated source is component-wise multiplied by a 2575 * smooth-shaded quad with a (potentially) different color at 2576 * each vertex. 2577 * 2578 * -# The resulting rotated, smooth-shaded quad is scaled to the 2579 * size of destination_rect and composited with 2580 * destination_surface using the provided blend state. 2581 * 2582 */ 2583 typedef VdpStatus VdpOutputSurfaceRenderBitmapSurface( 2584 VdpOutputSurface destination_surface, 2585 VdpRect const * destination_rect, 2586 VdpBitmapSurface source_surface, 2587 VdpRect const * source_rect, 2588 VdpColor const * colors, 2589 VdpOutputSurfaceRenderBlendState const * blend_state, 2590 uint32_t flags 2591 ); 2592 2593 /** @} */ 2594 2595 /** 2596 * \defgroup VdpDecoder VdpDecoder; Video Decoding object 2597 * 2598 * The VdpDecoder object decodes compressed video data, writing 2599 * the results to a \ref VdpVideoSurface "VdpVideoSurface". 2600 * 2601 * A specific VDPAU implementation may support decoding multiple 2602 * types of compressed video data. However, VdpDecoder objects 2603 * are able to decode a specific type of compressed video data. 2604 * This type must be specified during creation. 2605 * 2606 * @{ 2607 */ 2608 2609 /** 2610 * \brief The set of all known compressed video formats, and 2611 * associated profiles, that may be decoded. 2612 */ 2613 typedef uint32_t VdpDecoderProfile; 2614 2615 /** \hideinitializer */ 2616 #define VDP_DECODER_PROFILE_MPEG1 ((VdpDecoderProfile)0) 2617 /** \hideinitializer */ 2618 #define VDP_DECODER_PROFILE_MPEG2_SIMPLE ((VdpDecoderProfile)1) 2619 /** \hideinitializer */ 2620 #define VDP_DECODER_PROFILE_MPEG2_MAIN ((VdpDecoderProfile)2) 2621 /** \hideinitializer */ 2622 /** \brief MPEG 4 part 10 == H.264 == AVC */ 2623 #define VDP_DECODER_PROFILE_H264_BASELINE ((VdpDecoderProfile)6) 2624 /** \hideinitializer */ 2625 #define VDP_DECODER_PROFILE_H264_MAIN ((VdpDecoderProfile)7) 2626 /** \hideinitializer */ 2627 #define VDP_DECODER_PROFILE_H264_HIGH ((VdpDecoderProfile)8) 2628 /** \hideinitializer */ 2629 #define VDP_DECODER_PROFILE_VC1_SIMPLE ((VdpDecoderProfile)9) 2630 /** \hideinitializer */ 2631 #define VDP_DECODER_PROFILE_VC1_MAIN ((VdpDecoderProfile)10) 2632 /** \hideinitializer */ 2633 #define VDP_DECODER_PROFILE_VC1_ADVANCED ((VdpDecoderProfile)11) 2634 /** \hideinitializer */ 2635 #define VDP_DECODER_PROFILE_MPEG4_PART2_SP ((VdpDecoderProfile)12) 2636 /** \hideinitializer */ 2637 #define VDP_DECODER_PROFILE_MPEG4_PART2_ASP ((VdpDecoderProfile)13) 2638 /** \hideinitializer */ 2639 #define VDP_DECODER_PROFILE_DIVX4_QMOBILE ((VdpDecoderProfile)14) 2640 /** \hideinitializer */ 2641 #define VDP_DECODER_PROFILE_DIVX4_MOBILE ((VdpDecoderProfile)15) 2642 /** \hideinitializer */ 2643 #define VDP_DECODER_PROFILE_DIVX4_HOME_THEATER ((VdpDecoderProfile)16) 2644 /** \hideinitializer */ 2645 #define VDP_DECODER_PROFILE_DIVX4_HD_1080P ((VdpDecoderProfile)17) 2646 /** \hideinitializer */ 2647 #define VDP_DECODER_PROFILE_DIVX5_QMOBILE ((VdpDecoderProfile)18) 2648 /** \hideinitializer */ 2649 #define VDP_DECODER_PROFILE_DIVX5_MOBILE ((VdpDecoderProfile)19) 2650 /** \hideinitializer */ 2651 #define VDP_DECODER_PROFILE_DIVX5_HOME_THEATER ((VdpDecoderProfile)20) 2652 /** \hideinitializer */ 2653 #define VDP_DECODER_PROFILE_DIVX5_HD_1080P ((VdpDecoderProfile)21) 2654 /** \hideinitializer */ 2655 #define VDP_DECODER_PROFILE_H264_CONSTRAINED_BASELINE ((VdpDecoderProfile)22) 2656 /** \hideinitializer */ 2657 #define VDP_DECODER_PROFILE_H264_EXTENDED ((VdpDecoderProfile)23) 2658 /** \hideinitializer */ 2659 #define VDP_DECODER_PROFILE_H264_PROGRESSIVE_HIGH ((VdpDecoderProfile)24) 2660 /** \hideinitializer */ 2661 #define VDP_DECODER_PROFILE_H264_CONSTRAINED_HIGH ((VdpDecoderProfile)25) 2662 /** \hideinitializer */ 2663 /** \brief Support for 8 bit depth only */ 2664 #define VDP_DECODER_PROFILE_H264_HIGH_444_PREDICTIVE ((VdpDecoderProfile)26) 2665 /** \hideinitializer */ 2666 #define VDP_DECODER_PROFILE_VP9_PROFILE_0 ((VdpDecoderProfile)27) 2667 /** \hideinitializer */ 2668 #define VDP_DECODER_PROFILE_VP9_PROFILE_1 ((VdpDecoderProfile)28) 2669 /** \hideinitializer */ 2670 #define VDP_DECODER_PROFILE_VP9_PROFILE_2 ((VdpDecoderProfile)29) 2671 /** \hideinitializer */ 2672 #define VDP_DECODER_PROFILE_VP9_PROFILE_3 ((VdpDecoderProfile)30) 2673 /** \hideinitializer */ 2674 /** \brief MPEG-H Part 2 == H.265 == HEVC */ 2675 #define VDP_DECODER_PROFILE_HEVC_MAIN ((VdpDecoderProfile)100) 2676 /** \hideinitializer */ 2677 #define VDP_DECODER_PROFILE_HEVC_MAIN_10 ((VdpDecoderProfile)101) 2678 /** \hideinitializer */ 2679 #define VDP_DECODER_PROFILE_HEVC_MAIN_STILL ((VdpDecoderProfile)102) 2680 /** \hideinitializer */ 2681 #define VDP_DECODER_PROFILE_HEVC_MAIN_12 ((VdpDecoderProfile)103) 2682 /** \hideinitializer */ 2683 #define VDP_DECODER_PROFILE_HEVC_MAIN_444 ((VdpDecoderProfile)104) 2684 /** \hideinitializer */ 2685 #define VDP_DECODER_PROFILE_HEVC_MAIN_444_10 ((VdpDecoderProfile)105) 2686 /** \hideinitializer */ 2687 #define VDP_DECODER_PROFILE_HEVC_MAIN_444_12 ((VdpDecoderProfile)106) 2688 2689 /** \hideinitializer */ 2690 #define VDP_DECODER_LEVEL_MPEG1_NA 0 2691 2692 /** \hideinitializer */ 2693 #define VDP_DECODER_LEVEL_MPEG2_LL 0 2694 /** \hideinitializer */ 2695 #define VDP_DECODER_LEVEL_MPEG2_ML 1 2696 /** \hideinitializer */ 2697 #define VDP_DECODER_LEVEL_MPEG2_HL14 2 2698 /** \hideinitializer */ 2699 #define VDP_DECODER_LEVEL_MPEG2_HL 3 2700 2701 /** \hideinitializer */ 2702 #define VDP_DECODER_LEVEL_H264_1 10 2703 /** \hideinitializer */ 2704 #define VDP_DECODER_LEVEL_H264_1b 9 2705 /** \hideinitializer */ 2706 #define VDP_DECODER_LEVEL_H264_1_1 11 2707 /** \hideinitializer */ 2708 #define VDP_DECODER_LEVEL_H264_1_2 12 2709 /** \hideinitializer */ 2710 #define VDP_DECODER_LEVEL_H264_1_3 13 2711 /** \hideinitializer */ 2712 #define VDP_DECODER_LEVEL_H264_2 20 2713 /** \hideinitializer */ 2714 #define VDP_DECODER_LEVEL_H264_2_1 21 2715 /** \hideinitializer */ 2716 #define VDP_DECODER_LEVEL_H264_2_2 22 2717 /** \hideinitializer */ 2718 #define VDP_DECODER_LEVEL_H264_3 30 2719 /** \hideinitializer */ 2720 #define VDP_DECODER_LEVEL_H264_3_1 31 2721 /** \hideinitializer */ 2722 #define VDP_DECODER_LEVEL_H264_3_2 32 2723 /** \hideinitializer */ 2724 #define VDP_DECODER_LEVEL_H264_4 40 2725 /** \hideinitializer */ 2726 #define VDP_DECODER_LEVEL_H264_4_1 41 2727 /** \hideinitializer */ 2728 #define VDP_DECODER_LEVEL_H264_4_2 42 2729 /** \hideinitializer */ 2730 #define VDP_DECODER_LEVEL_H264_5 50 2731 /** \hideinitializer */ 2732 #define VDP_DECODER_LEVEL_H264_5_1 51 2733 2734 /** \hideinitializer */ 2735 #define VDP_DECODER_LEVEL_VC1_SIMPLE_LOW 0 2736 /** \hideinitializer */ 2737 #define VDP_DECODER_LEVEL_VC1_SIMPLE_MEDIUM 1 2738 2739 /** \hideinitializer */ 2740 #define VDP_DECODER_LEVEL_VC1_MAIN_LOW 0 2741 /** \hideinitializer */ 2742 #define VDP_DECODER_LEVEL_VC1_MAIN_MEDIUM 1 2743 /** \hideinitializer */ 2744 #define VDP_DECODER_LEVEL_VC1_MAIN_HIGH 2 2745 2746 /** \hideinitializer */ 2747 #define VDP_DECODER_LEVEL_VC1_ADVANCED_L0 0 2748 /** \hideinitializer */ 2749 #define VDP_DECODER_LEVEL_VC1_ADVANCED_L1 1 2750 /** \hideinitializer */ 2751 #define VDP_DECODER_LEVEL_VC1_ADVANCED_L2 2 2752 /** \hideinitializer */ 2753 #define VDP_DECODER_LEVEL_VC1_ADVANCED_L3 3 2754 /** \hideinitializer */ 2755 #define VDP_DECODER_LEVEL_VC1_ADVANCED_L4 4 2756 2757 /** \hideinitializer */ 2758 #define VDP_DECODER_LEVEL_MPEG4_PART2_SP_L0 0 2759 /** \hideinitializer */ 2760 #define VDP_DECODER_LEVEL_MPEG4_PART2_SP_L1 1 2761 /** \hideinitializer */ 2762 #define VDP_DECODER_LEVEL_MPEG4_PART2_SP_L2 2 2763 /** \hideinitializer */ 2764 #define VDP_DECODER_LEVEL_MPEG4_PART2_SP_L3 3 2765 2766 /** \hideinitializer */ 2767 #define VDP_DECODER_LEVEL_MPEG4_PART2_ASP_L0 0 2768 /** \hideinitializer */ 2769 #define VDP_DECODER_LEVEL_MPEG4_PART2_ASP_L1 1 2770 /** \hideinitializer */ 2771 #define VDP_DECODER_LEVEL_MPEG4_PART2_ASP_L2 2 2772 /** \hideinitializer */ 2773 #define VDP_DECODER_LEVEL_MPEG4_PART2_ASP_L3 3 2774 /** \hideinitializer */ 2775 #define VDP_DECODER_LEVEL_MPEG4_PART2_ASP_L4 4 2776 /** \hideinitializer */ 2777 #define VDP_DECODER_LEVEL_MPEG4_PART2_ASP_L5 5 2778 2779 /** \hideinitializer */ 2780 #define VDP_DECODER_LEVEL_DIVX_NA 0 2781 2782 /** \hideinitializer */ 2783 #define VDP_DECODER_LEVEL_VP9_L1 1 2784 2785 /** 2786 * The VDPAU H.265/HEVC decoder levels correspond to the values of 2787 * general_level_idc as described in the H.265 Specification, Annex A, 2788 * Table A.1. The enumeration values are equal to thirty times the level 2789 * number. 2790 */ 2791 #define VDP_DECODER_LEVEL_HEVC_1 30 2792 /** \hideinitializer */ 2793 #define VDP_DECODER_LEVEL_HEVC_2 60 2794 /** \hideinitializer */ 2795 #define VDP_DECODER_LEVEL_HEVC_2_1 63 2796 /** \hideinitializer */ 2797 #define VDP_DECODER_LEVEL_HEVC_3 90 2798 /** \hideinitializer */ 2799 #define VDP_DECODER_LEVEL_HEVC_3_1 93 2800 /** \hideinitializer */ 2801 #define VDP_DECODER_LEVEL_HEVC_4 120 2802 /** \hideinitializer */ 2803 #define VDP_DECODER_LEVEL_HEVC_4_1 123 2804 /** \hideinitializer */ 2805 #define VDP_DECODER_LEVEL_HEVC_5 150 2806 /** \hideinitializer */ 2807 #define VDP_DECODER_LEVEL_HEVC_5_1 153 2808 /** \hideinitializer */ 2809 #define VDP_DECODER_LEVEL_HEVC_5_2 156 2810 /** \hideinitializer */ 2811 #define VDP_DECODER_LEVEL_HEVC_6 180 2812 /** \hideinitializer */ 2813 #define VDP_DECODER_LEVEL_HEVC_6_1 183 2814 /** \hideinitializer */ 2815 #define VDP_DECODER_LEVEL_HEVC_6_2 186 2816 2817 typedef enum { 2818 VDP_VIDEO_SURFACE_FIELD_STRUCTURE = (1 << 0), 2819 VDP_VIDEO_SURFACE_FRAME_STRUCTURE = (1 << 1) 2820 } VdpVideoSurfaceSupportedPictureStructure; 2821 2822 typedef enum { 2823 VDP_DECODER_PROFILE_MAX_LEVEL = 0, 2824 VDP_DECODER_PROFILE_MAX_MACROBLOCKS = 1, 2825 VDP_DECODER_PROFILE_MAX_WIDTH = 2, 2826 VDP_DECODER_PROFILE_MAX_HEIGHT = 3, 2827 VDP_DECODER_PROFILE_SUPPORTED_PICTURE_STRUCTURE = 4, 2828 /** 2829 * A list of supported chroma types, stored as a bitmask of 1 shifted 2830 * by each supported VdpChromaType value. E.g., 2831 * (1 << VDP_CHROMA_TYPE_420) | 2832 * (1 << VDP_CHROMA_TYPE_422) | 2833 * (1 << VDP_CHROMA_TYPE_444) 2834 */ 2835 VDP_DECODER_PROFILE_SUPPORTED_CHROMA_TYPES = 5 2836 } VdpDecoderCapability; 2837 2838 /** 2839 * \brief Query the supported value of the requested capability, for 2840 * the specified profile on the specified device. 2841 * \param[in] device The device to query. 2842 * \param[in] profile The decoder profile for which information is requested. 2843 * \param[in] capability The decoder profile capability for which the value 2844 * is requested. 2845 * \param[out] capability_value The value of the requested capability. 2846 * \return VdpStatus The completion status of the operation. 2847 */ 2848 2849 typedef VdpStatus VdpDecoderQueryProfileCapability( 2850 VdpDevice device, 2851 VdpDecoderProfile profile, 2852 /* output parameters follow */ 2853 VdpDecoderCapability capability, 2854 void * capability_value 2855 ); 2856 2857 /** 2858 * \brief Query the implementation's VdpDecoder capabilities. 2859 * \param[in] device The device to query. 2860 * \param[in] profile The decoder profile for which information is requested. 2861 * \param[out] is_supported Is this profile supported? 2862 * \param[out] max_level The maximum specification level supported for this 2863 * profile. 2864 * \param[out] max_macroblocks The maximum supported surface size in 2865 * macroblocks. Note that this could be greater than that dictated by 2866 * the maximum level. 2867 * \param[out] max_width The maximum supported surface width for this profile. 2868 * Note that this could be greater than that dictated by the maximum 2869 * level. 2870 * \param[out] max_height The maximum supported surface height for this 2871 * profile. Note that this could be greater than that dictated by the 2872 * maximum level. 2873 * \return VdpStatus The completion status of the operation. 2874 */ 2875 typedef VdpStatus VdpDecoderQueryCapabilities( 2876 VdpDevice device, 2877 VdpDecoderProfile profile, 2878 /* output parameters follow */ 2879 VdpBool * is_supported, 2880 uint32_t * max_level, 2881 uint32_t * max_macroblocks, 2882 uint32_t * max_width, 2883 uint32_t * max_height 2884 ); 2885 2886 /** 2887 * \brief An opaque handle representing a VdpDecoder object. 2888 */ 2889 typedef uint32_t VdpDecoder; 2890 2891 /** 2892 * \brief Create a VdpDecoder. 2893 * \param[in] device The device that will contain the surface. 2894 * \param[in] profile The video format the decoder will decode. 2895 * \param[in] width The width of the new surface. 2896 * \param[in] height The height of the new surface. 2897 * \param[in] max_references The maximum number of references that may be 2898 * used by a single frame in the stream to be decoded. This parameter 2899 * exists mainly for formats such as H.264, where different streams 2900 * may use a different number of references. Requesting too many 2901 * references may waste memory, but decoding should still operate 2902 * correctly. Requesting too few references will cause decoding to 2903 * fail. 2904 * \param[out] decoder The new decoder's handle. 2905 * \return VdpStatus The completion status of the operation. 2906 */ 2907 typedef VdpStatus VdpDecoderCreate( 2908 VdpDevice device, 2909 VdpDecoderProfile profile, 2910 uint32_t width, 2911 uint32_t height, 2912 uint32_t max_references, 2913 /* output parameters follow */ 2914 VdpDecoder * decoder 2915 ); 2916 2917 /** 2918 * \brief Destroy a VdpDecoder. 2919 * \param[in] surface The decoder's handle. 2920 * \return VdpStatus The completion status of the operation. 2921 */ 2922 typedef VdpStatus VdpDecoderDestroy( 2923 VdpDecoder decoder 2924 ); 2925 2926 /** 2927 * \brief Retrieve the parameters used to create a 2928 * VdpDecoder. 2929 * \param[in] surface The surface's handle. 2930 * \param[out] profile The video format used to create the 2931 * decoder. 2932 * \param[out] width The width of surfaces decode by the 2933 * decoder. 2934 * \param[out] height The height of surfaces decode by the 2935 * decoder 2936 * \return VdpStatus The completion status of the operation. 2937 */ 2938 typedef VdpStatus VdpDecoderGetParameters( 2939 VdpDecoder decoder, 2940 /* output parameters follow */ 2941 VdpDecoderProfile * profile, 2942 uint32_t * width, 2943 uint32_t * height 2944 ); 2945 2946 #define VDP_BITSTREAM_BUFFER_VERSION 0 2947 2948 /** 2949 * \brief Application data buffer containing compressed video 2950 * data. 2951 */ 2952 typedef struct { 2953 /** 2954 * This field must be filled with VDP_BITSTREAM_BUFFER_VERSION 2955 */ 2956 uint32_t struct_version; 2957 /** A pointer to the bitstream data bytes */ 2958 void const * bitstream; 2959 /** The number of data bytes */ 2960 uint32_t bitstream_bytes; 2961 } VdpBitstreamBuffer; 2962 2963 /** 2964 * \brief A generic "picture information" type. 2965 * 2966 * This type serves solely to document the expected usage of a 2967 * generic (void *) function parameter. In actual usage, the 2968 * application is expected to physically provide a pointer to an 2969 * instance of one of the "real" VdpPictureInfo* structures, 2970 * picking the type appropriate for the decoder object in 2971 * question. 2972 */ 2973 typedef void VdpPictureInfo; 2974 2975 /** 2976 * \brief Picture parameter information for an MPEG 1 or MPEG 2 2977 * picture. 2978 * 2979 * Note: References to bitstream fields below may refer to data literally parsed 2980 * from the bitstream, or derived from the bitstream using a mechanism described 2981 * in the specification. 2982 */ 2983 typedef struct { 2984 /** 2985 * Reference used by B and P frames. 2986 * Set to VDP_INVALID_HANDLE when not used. 2987 */ 2988 VdpVideoSurface forward_reference; 2989 /** 2990 * Reference used by B frames. 2991 * Set to VDP_INVALID_HANDLE when not used. 2992 */ 2993 VdpVideoSurface backward_reference; 2994 /** Number of slices in the bitstream provided. */ 2995 uint32_t slice_count; 2996 2997 /** \name MPEG bitstream 2998 * 2999 * Copies of the MPEG bitstream fields. 3000 * @{ */ 3001 uint8_t picture_structure; 3002 uint8_t picture_coding_type; 3003 uint8_t intra_dc_precision; 3004 uint8_t frame_pred_frame_dct; 3005 uint8_t concealment_motion_vectors; 3006 uint8_t intra_vlc_format; 3007 uint8_t alternate_scan; 3008 uint8_t q_scale_type; 3009 uint8_t top_field_first; 3010 /** MPEG-1 only. For MPEG-2, set to 0. */ 3011 uint8_t full_pel_forward_vector; 3012 /** MPEG-1 only. For MPEG-2, set to 0. */ 3013 uint8_t full_pel_backward_vector; 3014 /** For MPEG-1, fill both horizontal and vertical entries. */ 3015 uint8_t f_code[2][2]; 3016 /** Convert to raster order. */ 3017 uint8_t intra_quantizer_matrix[64]; 3018 /** Convert to raster order. */ 3019 uint8_t non_intra_quantizer_matrix[64]; 3020 /** @} */ 3021 } VdpPictureInfoMPEG1Or2; 3022 3023 /** 3024 * \brief Information about an H.264 reference frame 3025 * 3026 * Note: References to bitstream fields below may refer to data literally parsed 3027 * from the bitstream, or derived from the bitstream using a mechanism described 3028 * in the specification. 3029 */ 3030 typedef struct { 3031 /** 3032 * The surface that contains the reference image. 3033 * Set to VDP_INVALID_HANDLE for unused entries. 3034 */ 3035 VdpVideoSurface surface; 3036 /** Is this a long term reference (else short term). */ 3037 VdpBool is_long_term; 3038 /** 3039 * Is the top field used as a reference. 3040 * Set to VDP_FALSE for unused entries. 3041 */ 3042 VdpBool top_is_reference; 3043 /** 3044 * Is the bottom field used as a reference. 3045 * Set to VDP_FALSE for unused entries. 3046 */ 3047 VdpBool bottom_is_reference; 3048 /** [0]: top, [1]: bottom */ 3049 int32_t field_order_cnt[2]; 3050 /** 3051 * Copy of the H.264 bitstream field: 3052 * frame_num from slice_header for short-term references, 3053 * LongTermPicNum from decoding algorithm for long-term references. 3054 */ 3055 uint16_t frame_idx; 3056 } VdpReferenceFrameH264; 3057 3058 /** 3059 * \brief Picture parameter information for an H.264 picture. 3060 * 3061 * Note: The \ref referenceFrames array must contain the "DPB" as 3062 * defined by the H.264 specification. In particular, once a 3063 * reference frame has been decoded to a surface, that surface must 3064 * continue to appear in the DPB until no longer required to predict 3065 * any future frame. Once a surface is removed from the DPB, it can 3066 * no longer be used as a reference, unless decoded again. 3067 * 3068 * Also note that only surfaces previously generated using \ref 3069 * VdpDecoderRender may be used as reference frames. In particular, 3070 * surfaces filled using any "put bits" API will not work. 3071 * 3072 * Note: References to bitstream fields below may refer to data literally parsed 3073 * from the bitstream, or derived from the bitstream using a mechanism described 3074 * in the specification. 3075 * 3076 * Note: VDPAU clients must use VdpPictureInfoH264Predictive to describe the 3077 * attributes of a frame being decoded with 3078 * VDP_DECODER_PROFILE_H264_HIGH_444_PREDICTIVE. 3079 */ 3080 typedef struct { 3081 /** Number of slices in the bitstream provided. */ 3082 uint32_t slice_count; 3083 /** [0]: top, [1]: bottom */ 3084 int32_t field_order_cnt[2]; 3085 /** Will the decoded frame be used as a reference later. */ 3086 VdpBool is_reference; 3087 3088 /** \name H.264 bitstream 3089 * 3090 * Copies of the H.264 bitstream fields. 3091 * @{ */ 3092 uint16_t frame_num; 3093 uint8_t field_pic_flag; 3094 uint8_t bottom_field_flag; 3095 uint8_t num_ref_frames; 3096 uint8_t mb_adaptive_frame_field_flag; 3097 uint8_t constrained_intra_pred_flag; 3098 uint8_t weighted_pred_flag; 3099 uint8_t weighted_bipred_idc; 3100 uint8_t frame_mbs_only_flag; 3101 uint8_t transform_8x8_mode_flag; 3102 int8_t chroma_qp_index_offset; 3103 int8_t second_chroma_qp_index_offset; 3104 int8_t pic_init_qp_minus26; 3105 uint8_t num_ref_idx_l0_active_minus1; 3106 uint8_t num_ref_idx_l1_active_minus1; 3107 uint8_t log2_max_frame_num_minus4; 3108 uint8_t pic_order_cnt_type; 3109 uint8_t log2_max_pic_order_cnt_lsb_minus4; 3110 uint8_t delta_pic_order_always_zero_flag; 3111 uint8_t direct_8x8_inference_flag; 3112 uint8_t entropy_coding_mode_flag; 3113 uint8_t pic_order_present_flag; 3114 uint8_t deblocking_filter_control_present_flag; 3115 uint8_t redundant_pic_cnt_present_flag; 3116 /** Convert to raster order. */ 3117 uint8_t scaling_lists_4x4[6][16]; 3118 /** Convert to raster order. */ 3119 uint8_t scaling_lists_8x8[2][64]; 3120 /** @} */ 3121 3122 /** See \ref VdpPictureInfoH264 for instructions regarding this field. */ 3123 VdpReferenceFrameH264 referenceFrames[16]; 3124 } VdpPictureInfoH264; 3125 3126 /** 3127 * \brief Picture parameter information for an H.264 Hi444PP picture. 3128 * 3129 * Note: VDPAU clients must use VdpPictureInfoH264Predictive to describe the 3130 * attributes of a frame being decoded with 3131 * VDP_DECODER_PROFILE_H264_HIGH_444_PREDICTIVE. 3132 * 3133 * Note: software drivers may choose to honor values of 3134 * qpprime_y_zero_transform_bypass_flag greater than 1 for internal use. 3135 */ 3136 typedef struct { 3137 /** \ref VdpPictureInfoH264 struct. */ 3138 VdpPictureInfoH264 pictureInfo; 3139 3140 /** \name H.264 bitstream 3141 * 3142 * Copies of the H.264 bitstream fields. 3143 * @{ */ 3144 /** 3145 * 0 - lossless disabled 3146 * 1 - lossless enabled 3147 */ 3148 uint8_t qpprime_y_zero_transform_bypass_flag; 3149 /** 3150 * 0 - disabled 3151 * 1 - enabled 3152 */ 3153 uint8_t separate_colour_plane_flag; 3154 /** @} */ 3155 } VdpPictureInfoH264Predictive; 3156 3157 /** 3158 * \brief Picture parameter information for a VC1 picture. 3159 * 3160 * Note: References to bitstream fields below may refer to data literally parsed 3161 * from the bitstream, or derived from the bitstream using a mechanism described 3162 * in the specification. 3163 */ 3164 typedef struct { 3165 /** 3166 * Reference used by B and P frames. 3167 * Set to VDP_INVALID_HANDLE when not used. 3168 */ 3169 VdpVideoSurface forward_reference; 3170 /** 3171 * Reference used by B frames. 3172 * Set to VDP_INVALID_HANDLE when not used. 3173 */ 3174 VdpVideoSurface backward_reference; 3175 3176 /** Number of slices in the bitstream provided. */ 3177 uint32_t slice_count; 3178 /** I=0, P=1, B=3, BI=4 from 7.1.1.4. */ 3179 uint8_t picture_type; 3180 /** Progressive=0, Frame-interlace=2, Field-interlace=3; see VC-1 7.1.1.15. */ 3181 uint8_t frame_coding_mode; 3182 3183 /** \name VC-1 bitstream 3184 * 3185 * Copies of the VC-1 bitstream fields. 3186 * @{ */ 3187 /** See VC-1 6.1.5. */ 3188 uint8_t postprocflag; 3189 /** See VC-1 6.1.8. */ 3190 uint8_t pulldown; 3191 /** See VC-1 6.1.9. */ 3192 uint8_t interlace; 3193 /** See VC-1 6.1.10. */ 3194 uint8_t tfcntrflag; 3195 /** See VC-1 6.1.11. */ 3196 uint8_t finterpflag; 3197 /** See VC-1 6.1.3. */ 3198 uint8_t psf; 3199 /** See VC-1 6.2.8. */ 3200 uint8_t dquant; 3201 /** See VC-1 6.2.3. */ 3202 uint8_t panscan_flag; 3203 /** See VC-1 6.2.4. */ 3204 uint8_t refdist_flag; 3205 /** See VC-1 6.2.11. */ 3206 uint8_t quantizer; 3207 /** See VC-1 6.2.7. */ 3208 uint8_t extended_mv; 3209 /** See VC-1 6.2.14. */ 3210 uint8_t extended_dmv; 3211 /** See VC-1 6.2.10. */ 3212 uint8_t overlap; 3213 /** See VC-1 6.2.9. */ 3214 uint8_t vstransform; 3215 /** See VC-1 6.2.5. */ 3216 uint8_t loopfilter; 3217 /** See VC-1 6.2.6. */ 3218 uint8_t fastuvmc; 3219 /** See VC-1 6.12.15. */ 3220 uint8_t range_mapy_flag; 3221 uint8_t range_mapy; 3222 /** See VC-1 6.2.16. */ 3223 uint8_t range_mapuv_flag; 3224 uint8_t range_mapuv; 3225 3226 /** 3227 * See VC-1 J.1.10. 3228 * Only used by simple and main profiles. 3229 */ 3230 uint8_t multires; 3231 /** 3232 * See VC-1 J.1.16. 3233 * Only used by simple and main profiles. 3234 */ 3235 uint8_t syncmarker; 3236 /** 3237 * VC-1 SP/MP range reduction control. 3238 * Only used by simple and main profiles. 3239 * Bit 0: Copy of rangered VC-1 bitstream field; See VC-1 J.1.17. 3240 * Bit 1: Copy of rangeredfrm VC-1 bitstream fiels; See VC-1 7.1.13. 3241 */ 3242 uint8_t rangered; 3243 /** 3244 * See VC-1 J.1.17. 3245 * Only used by simple and main profiles. 3246 */ 3247 uint8_t maxbframes; 3248 /** @} */ 3249 3250 /** 3251 * Out-of-loop deblocking enable. 3252 * Bit 0 of POSTPROC from VC-1 7.1.1.27 3253 * Note that bit 1 of POSTPROC (dering enable) should not be included. 3254 */ 3255 uint8_t deblockEnable; 3256 /** 3257 * Parameter used by VC-1 Annex H deblocking algorithm. Note that VDPAU 3258 * implementations may choose which deblocking algorithm to use. 3259 * See VC-1 7.1.1.6 3260 */ 3261 uint8_t pquant; 3262 } VdpPictureInfoVC1; 3263 3264 /** 3265 * \brief Picture parameter information for an MPEG-4 Part 2 picture. 3266 * 3267 * Note: References to bitstream fields below may refer to data literally parsed 3268 * from the bitstream, or derived from the bitstream using a mechanism described 3269 * in the specification. 3270 */ 3271 typedef struct { 3272 /** 3273 * Reference used by B and P frames. 3274 * Set to VDP_INVALID_HANDLE when not used. 3275 */ 3276 VdpVideoSurface forward_reference; 3277 /** 3278 * Reference used by B frames. 3279 * Set to VDP_INVALID_HANDLE when not used. 3280 */ 3281 VdpVideoSurface backward_reference; 3282 3283 /** \name MPEG 4 part 2 bitstream 3284 * 3285 * Copies of the MPEG 4 part 2 bitstream fields. 3286 * @{ */ 3287 int32_t trd[2]; 3288 int32_t trb[2]; 3289 uint16_t vop_time_increment_resolution; 3290 uint8_t vop_coding_type; 3291 uint8_t vop_fcode_forward; 3292 uint8_t vop_fcode_backward; 3293 uint8_t resync_marker_disable; 3294 uint8_t interlaced; 3295 uint8_t quant_type; 3296 uint8_t quarter_sample; 3297 uint8_t short_video_header; 3298 /** Derived from vop_rounding_type bitstream field. */ 3299 uint8_t rounding_control; 3300 uint8_t alternate_vertical_scan_flag; 3301 uint8_t top_field_first; 3302 uint8_t intra_quantizer_matrix[64]; 3303 uint8_t non_intra_quantizer_matrix[64]; 3304 /** @} */ 3305 } VdpPictureInfoMPEG4Part2; 3306 3307 /** 3308 * \brief Picture parameter information for a DivX 4 picture. 3309 * 3310 * Due to similarites between MPEG-4 Part 2 and DivX 4, the picture 3311 * parameter structure is re-used. 3312 */ 3313 typedef VdpPictureInfoMPEG4Part2 VdpPictureInfoDivX4; 3314 3315 /** 3316 * \brief Picture parameter information for a DivX 5 picture. 3317 * 3318 * Due to similarites between MPEG-4 Part 2 and DivX 5, the picture 3319 * parameter structure is re-used. 3320 */ 3321 typedef VdpPictureInfoMPEG4Part2 VdpPictureInfoDivX5; 3322 3323 typedef struct 3324 { 3325 unsigned int width; 3326 unsigned int height; 3327 3328 //Frame Indices 3329 VdpVideoSurface lastReference; 3330 VdpVideoSurface goldenReference; 3331 VdpVideoSurface altReference; 3332 3333 unsigned char colorSpace; 3334 3335 unsigned short profile; 3336 unsigned short frameContextIdx; 3337 unsigned short keyFrame; 3338 unsigned short showFrame; 3339 unsigned short errorResilient; 3340 unsigned short frameParallelDecoding; 3341 unsigned short subSamplingX; 3342 unsigned short subSamplingY; 3343 unsigned short intraOnly; 3344 unsigned short allowHighPrecisionMv; 3345 unsigned short refreshEntropyProbs; 3346 3347 unsigned char refFrameSignBias[4]; 3348 3349 unsigned char bitDepthMinus8Luma; 3350 unsigned char bitDepthMinus8Chroma; 3351 unsigned char loopFilterLevel; 3352 unsigned char loopFilterSharpness; 3353 3354 unsigned char modeRefLfEnabled; 3355 unsigned char log2TileColumns; 3356 unsigned char log2TileRows; 3357 3358 unsigned char segmentEnabled; 3359 unsigned char segmentMapUpdate; 3360 unsigned char segmentMapTemporalUpdate; 3361 unsigned char segmentFeatureMode; 3362 3363 unsigned char segmentFeatureEnable[8][4]; 3364 short segmentFeatureData[8][4]; 3365 unsigned char mbSegmentTreeProbs[7]; 3366 unsigned char segmentPredProbs[3]; 3367 unsigned char reservedSegment16Bits[2]; 3368 3369 int qpYAc; 3370 int qpYDc; 3371 int qpChDc; 3372 int qpChAc; 3373 3374 unsigned int activeRefIdx[3]; 3375 unsigned int resetFrameContext; 3376 unsigned int mcompFilterType; 3377 unsigned int mbRefLfDelta[4]; 3378 unsigned int mbModeLfDelta[2]; 3379 unsigned int uncompressedHeaderSize; 3380 unsigned int compressedHeaderSize; 3381 } VdpPictureInfoVP9; 3382 3383 /** 3384 * \brief Picture parameter information for an H.265/HEVC picture. 3385 * 3386 * References to bitsream fields below may refer to data literally parsed from 3387 * the bitstream, or derived from the bitstream using a mechanism described in 3388 * Rec. ITU-T H.265 (04/2013), hereafter referred to as "the H.265/HEVC 3389 * Specification". 3390 * 3391 * VDPAU H.265/HEVC implementations implement the portion of the decoding 3392 * process described by clauses 8.4, 8.5, 8.6 and 8.7 of the the 3393 * H.265/HEVC Specification. VdpPictureInfoHEVC provides enough data 3394 * to complete this portion of the decoding process, plus additional 3395 * information not defined in the H.265/HEVC Specification that may be 3396 * useful to particular implementations. 3397 * 3398 * Client applications must supply every field in this struct. 3399 */ 3400 typedef struct { 3401 /** \name HEVC Sequence Parameter Set 3402 * 3403 * Copies of the HEVC Sequence Parameter Set bitstream fields. 3404 * @{ */ 3405 uint8_t chroma_format_idc; 3406 /** Only valid if chroma_format_idc == 3. Ignored otherwise.*/ 3407 uint8_t separate_colour_plane_flag; 3408 uint32_t pic_width_in_luma_samples; 3409 uint32_t pic_height_in_luma_samples; 3410 uint8_t bit_depth_luma_minus8; 3411 uint8_t bit_depth_chroma_minus8; 3412 uint8_t log2_max_pic_order_cnt_lsb_minus4; 3413 /** Provides the value corresponding to the nuh_temporal_id of the frame 3414 to be decoded. */ 3415 uint8_t sps_max_dec_pic_buffering_minus1; 3416 uint8_t log2_min_luma_coding_block_size_minus3; 3417 uint8_t log2_diff_max_min_luma_coding_block_size; 3418 uint8_t log2_min_transform_block_size_minus2; 3419 uint8_t log2_diff_max_min_transform_block_size; 3420 uint8_t max_transform_hierarchy_depth_inter; 3421 uint8_t max_transform_hierarchy_depth_intra; 3422 uint8_t scaling_list_enabled_flag; 3423 /** Scaling lists, in diagonal order, to be used for this frame. */ 3424 /** Scaling List for 4x4 quantization matrix, 3425 indexed as ScalingList4x4[matrixId][i]. */ 3426 uint8_t ScalingList4x4[6][16]; 3427 /** Scaling List for 8x8 quantization matrix, 3428 indexed as ScalingList8x8[matrixId][i]. */ 3429 uint8_t ScalingList8x8[6][64]; 3430 /** Scaling List for 16x16 quantization matrix, 3431 indexed as ScalingList16x16[matrixId][i]. */ 3432 uint8_t ScalingList16x16[6][64]; 3433 /** Scaling List for 32x32 quantization matrix, 3434 indexed as ScalingList32x32[matrixId][i]. */ 3435 uint8_t ScalingList32x32[2][64]; 3436 /** Scaling List DC Coefficients for 16x16, 3437 indexed as ScalingListDCCoeff16x16[matrixId]. */ 3438 uint8_t ScalingListDCCoeff16x16[6]; 3439 /** Scaling List DC Coefficients for 32x32, 3440 indexed as ScalingListDCCoeff32x32[matrixId]. */ 3441 uint8_t ScalingListDCCoeff32x32[2]; 3442 uint8_t amp_enabled_flag; 3443 uint8_t sample_adaptive_offset_enabled_flag; 3444 uint8_t pcm_enabled_flag; 3445 /** Only needs to be set if pcm_enabled_flag is set. Ignored otherwise. */ 3446 uint8_t pcm_sample_bit_depth_luma_minus1; 3447 /** Only needs to be set if pcm_enabled_flag is set. Ignored otherwise. */ 3448 uint8_t pcm_sample_bit_depth_chroma_minus1; 3449 /** Only needs to be set if pcm_enabled_flag is set. Ignored otherwise. */ 3450 uint8_t log2_min_pcm_luma_coding_block_size_minus3; 3451 /** Only needs to be set if pcm_enabled_flag is set. Ignored otherwise. */ 3452 uint8_t log2_diff_max_min_pcm_luma_coding_block_size; 3453 /** Only needs to be set if pcm_enabled_flag is set. Ignored otherwise. */ 3454 uint8_t pcm_loop_filter_disabled_flag; 3455 /** Per spec, when zero, assume short_term_ref_pic_set_sps_flag 3456 is also zero. */ 3457 uint8_t num_short_term_ref_pic_sets; 3458 uint8_t long_term_ref_pics_present_flag; 3459 /** Only needed if long_term_ref_pics_present_flag is set. Ignored 3460 otherwise. */ 3461 uint8_t num_long_term_ref_pics_sps; 3462 uint8_t sps_temporal_mvp_enabled_flag; 3463 uint8_t strong_intra_smoothing_enabled_flag; 3464 /** @} */ 3465 3466 /** \name HEVC Picture Parameter Set 3467 * 3468 * Copies of the HEVC Picture Parameter Set bitstream fields. 3469 * @{ */ 3470 uint8_t dependent_slice_segments_enabled_flag; 3471 uint8_t output_flag_present_flag; 3472 uint8_t num_extra_slice_header_bits; 3473 uint8_t sign_data_hiding_enabled_flag; 3474 uint8_t cabac_init_present_flag; 3475 uint8_t num_ref_idx_l0_default_active_minus1; 3476 uint8_t num_ref_idx_l1_default_active_minus1; 3477 int8_t init_qp_minus26; 3478 uint8_t constrained_intra_pred_flag; 3479 uint8_t transform_skip_enabled_flag; 3480 uint8_t cu_qp_delta_enabled_flag; 3481 /** Only needed if cu_qp_delta_enabled_flag is set. Ignored otherwise. */ 3482 uint8_t diff_cu_qp_delta_depth; 3483 int8_t pps_cb_qp_offset; 3484 int8_t pps_cr_qp_offset; 3485 uint8_t pps_slice_chroma_qp_offsets_present_flag; 3486 uint8_t weighted_pred_flag; 3487 uint8_t weighted_bipred_flag; 3488 uint8_t transquant_bypass_enabled_flag; 3489 uint8_t tiles_enabled_flag; 3490 uint8_t entropy_coding_sync_enabled_flag; 3491 /** Only valid if tiles_enabled_flag is set. Ignored otherwise. */ 3492 uint8_t num_tile_columns_minus1; 3493 /** Only valid if tiles_enabled_flag is set. Ignored otherwise. */ 3494 uint8_t num_tile_rows_minus1; 3495 /** Only valid if tiles_enabled_flag is set. Ignored otherwise. */ 3496 uint8_t uniform_spacing_flag; 3497 /** Only need to set 0..num_tile_columns_minus1. The struct 3498 definition reserves up to the maximum of 20. Invalid values are 3499 ignored. */ 3500 uint16_t column_width_minus1[20]; 3501 /** Only need to set 0..num_tile_rows_minus1. The struct 3502 definition reserves up to the maximum of 22. Invalid values are 3503 ignored.*/ 3504 uint16_t row_height_minus1[22]; 3505 /** Only needed if tiles_enabled_flag is set. Invalid values are 3506 ignored. */ 3507 uint8_t loop_filter_across_tiles_enabled_flag; 3508 uint8_t pps_loop_filter_across_slices_enabled_flag; 3509 uint8_t deblocking_filter_control_present_flag; 3510 /** Only valid if deblocking_filter_control_present_flag is set. Ignored 3511 otherwise. */ 3512 uint8_t deblocking_filter_override_enabled_flag; 3513 /** Only valid if deblocking_filter_control_present_flag is set. Ignored 3514 otherwise. */ 3515 uint8_t pps_deblocking_filter_disabled_flag; 3516 /** Only valid if deblocking_filter_control_present_flag is set and 3517 pps_deblocking_filter_disabled_flag is not set. Ignored otherwise.*/ 3518 int8_t pps_beta_offset_div2; 3519 /** Only valid if deblocking_filter_control_present_flag is set and 3520 pps_deblocking_filter_disabled_flag is not set. Ignored otherwise. */ 3521 int8_t pps_tc_offset_div2; 3522 uint8_t lists_modification_present_flag; 3523 uint8_t log2_parallel_merge_level_minus2; 3524 uint8_t slice_segment_header_extension_present_flag; 3525 /** @} */ 3526 3527 /** \name HEVC Slice Segment Header 3528 * 3529 * Copies of the HEVC Slice Segment Header bitstream fields and calculated 3530 * values detailed in the specification. 3531 * @{ */ 3532 /** Set to 1 if nal_unit_type is equal to IDR_W_RADL or IDR_N_LP. 3533 Set to zero otherwise. */ 3534 uint8_t IDRPicFlag; 3535 /** Set to 1 if nal_unit_type in the range of BLA_W_LP to 3536 RSV_IRAP_VCL23, inclusive. Set to zero otherwise.*/ 3537 uint8_t RAPPicFlag; 3538 /** See section 7.4.7.1 of the specification. */ 3539 uint8_t CurrRpsIdx; 3540 /** See section 7.4.7.2 of the specification. */ 3541 uint32_t NumPocTotalCurr; 3542 /** Corresponds to specification field, NumDeltaPocs[RefRpsIdx]. 3543 Only applicable when short_term_ref_pic_set_sps_flag == 0. 3544 Implementations will ignore this value in other cases. See 7.4.8. */ 3545 uint32_t NumDeltaPocsOfRefRpsIdx; 3546 /** Section 7.6.3.1 of the H.265/HEVC Specification defines the syntax of 3547 the slice_segment_header. This header contains information that 3548 some VDPAU implementations may choose to skip. The VDPAU API 3549 requires client applications to track the number of bits used in the 3550 slice header for structures associated with short term and long term 3551 reference pictures. First, VDPAU requires the number of bits used by 3552 the short_term_ref_pic_set array in the slice_segment_header. */ 3553 uint32_t NumShortTermPictureSliceHeaderBits; 3554 /** Second, VDPAU requires the number of bits used for long term reference 3555 pictures in the slice_segment_header. This is equal to the number 3556 of bits used for the contents of the block beginning with 3557 "if(long_term_ref_pics_present_flag)". */ 3558 uint32_t NumLongTermPictureSliceHeaderBits; 3559 /** @} */ 3560 3561 /** Slice Decoding Process - Picture Order Count */ 3562 /** The value of PicOrderCntVal of the picture in the access unit 3563 containing the SEI message. The picture being decoded. */ 3564 int32_t CurrPicOrderCntVal; 3565 3566 /** Slice Decoding Process - Reference Picture Sets */ 3567 /** Array of video reference surfaces. 3568 Set any unused positions to VDP_INVALID_HANDLE. */ 3569 VdpVideoSurface RefPics[16]; 3570 /** Array of picture order counts. These correspond to positions 3571 in the RefPics array. */ 3572 int32_t PicOrderCntVal[16]; 3573 /** Array used to specify whether a particular RefPic is 3574 a long term reference. A value of "1" indicates a long-term 3575 reference. */ 3576 uint8_t IsLongTerm[16]; 3577 /** Copy of specification field, see Section 8.3.2 of the 3578 H.265/HEVC Specification. */ 3579 uint8_t NumPocStCurrBefore; 3580 /** Copy of specification field, see Section 8.3.2 of the 3581 H.265/HEVC Specification. */ 3582 uint8_t NumPocStCurrAfter; 3583 /** Copy of specification field, see Section 8.3.2 of the 3584 H.265/HEVC Specification. */ 3585 uint8_t NumPocLtCurr; 3586 /** Reference Picture Set list, one of the short-term RPS. These 3587 correspond to positions in the RefPics array. */ 3588 uint8_t RefPicSetStCurrBefore[8]; 3589 /** Reference Picture Set list, one of the short-term RPS. These 3590 correspond to positions in the RefPics array. */ 3591 uint8_t RefPicSetStCurrAfter[8]; 3592 /** Reference Picture Set list, one of the long-term RPS. These 3593 correspond to positions in the RefPics array. */ 3594 uint8_t RefPicSetLtCurr[8]; 3595 } VdpPictureInfoHEVC; 3596 3597 /** 3598 * \brief Picture parameter information for an HEVC 444 picture. 3599 * 3600 * Note: VDPAU clients must use VdpPictureInfoHEVC444 to describe the 3601 * attributes of a frame being decoded with 3602 * VDP_DECODER_PROFILE_HEVC_MAIN_444. 3603 */ 3604 typedef struct { 3605 /** \ref VdpPictureInfoHEVC struct. */ 3606 VdpPictureInfoHEVC pictureInfo; 3607 3608 /* SPS Range Extensions for Main 444, Main 10, etc. */ 3609 uint8_t sps_range_extension_flag; 3610 /* sps extension for transform_skip_rotation_enabled_flag */ 3611 uint8_t transformSkipRotationEnableFlag; 3612 /* sps extension for transform_skip_context_enabled_flag */ 3613 uint8_t transformSkipContextEnableFlag; 3614 /* sps implicit_rdpcm_enabled_flag */ 3615 uint8_t implicitRdpcmEnableFlag; 3616 /* sps explicit_rdpcm_enabled_flag */ 3617 uint8_t explicitRdpcmEnableFlag; 3618 /* sps extended_precision_processing_flag,always 0 in current profile */ 3619 uint8_t extendedPrecisionProcessingFlag; 3620 /* sps intra_smoothing_disabled_flag */ 3621 uint8_t intraSmoothingDisabledFlag; 3622 /* sps high_precision_offsets_enabled_flag */ 3623 uint8_t highPrecisionOffsetsEnableFlag; 3624 /* sps persistent_rice_adaptation_enabled_flag */ 3625 uint8_t persistentRiceAdaptationEnableFlag; 3626 /* sps cabac_bypass_alignment_enabled_flag, always 0 in current profile */ 3627 uint8_t cabacBypassAlignmentEnableFlag; 3628 /* sps intraBlockCopyEnableFlag, always 0 not used by the spec as of now */ 3629 uint8_t intraBlockCopyEnableFlag; 3630 3631 /* PPS Range Extensions for Main 444, Main 10, etc. */ 3632 uint8_t pps_range_extension_flag; 3633 /* pps extension log2_max_transform_skip_block_size_minus2, 0...5 */ 3634 uint8_t log2MaxTransformSkipSize; 3635 /* pps cross_component_prediction_enabled_flag */ 3636 uint8_t crossComponentPredictionEnableFlag; 3637 /* pps chroma_qp_adjustment_enabled_flag */ 3638 uint8_t chromaQpAdjustmentEnableFlag; 3639 /* pps diff_cu_chroma_qp_adjustment_depth, 0...3 */ 3640 uint8_t diffCuChromaQpAdjustmentDepth; 3641 /* pps chroma_qp_adjustment_table_size_minus1+1, 1...6 */ 3642 uint8_t chromaQpAdjustmentTableSize; 3643 /* pps log2_sao_offset_scale_luma, max(0,bitdepth-10), */ 3644 /* maxBitdepth 16 for future. */ 3645 uint8_t log2SaoOffsetScaleLuma; 3646 /* pps log2_sao_offset_scale_chroma */ 3647 uint8_t log2SaoOffsetScaleChroma; 3648 /* -[12,+12] */ 3649 int8_t cb_qp_adjustment[6]; 3650 /* -[12,+12] */ 3651 int8_t cr_qp_adjustment[6]; 3652 3653 } VdpPictureInfoHEVC444; 3654 3655 /** 3656 * \brief Picture parameter information for HEVC FormatRangeExtensions picture. 3657 * 3658 * HEVC Main 444 Profile is part of Format Range Extensions profiles, 3659 * Due to similarities between Format Range Extensions profiles, the picture 3660 * parameter structure is re-used for Format Range Extensions profiles 3661 * supported. 3662 */ 3663 typedef VdpPictureInfoHEVC444 VdpPictureInfoHEVCRangeExt; 3664 3665 /** 3666 * \brief Decode a compressed field/frame and render the result 3667 * into a \ref VdpVideoSurface "VdpVideoSurface". 3668 * \param[in] decoder The decoder object that will perform the 3669 * decode operation. 3670 * \param[in] target The video surface to render to. 3671 * \param[in] picture_info A (pointer to a) structure containing 3672 * information about the picture to be decoded. Note that 3673 * the appropriate type of VdpPictureInfo* structure must 3674 * be provided to match to profile that the decoder was 3675 * created for. 3676 * \param[in] bitstream_buffer_count The number of bitstream 3677 * buffers containing compressed data for this picture. 3678 * \param[in] bitstream_buffers An array of bitstream buffers. 3679 * \return VdpStatus The completion status of the operation. 3680 * 3681 * See \ref video_mixer_usage for additional information. 3682 */ 3683 typedef VdpStatus VdpDecoderRender( 3684 VdpDecoder decoder, 3685 VdpVideoSurface target, 3686 VdpPictureInfo const * picture_info, 3687 uint32_t bitstream_buffer_count, 3688 VdpBitstreamBuffer const * bitstream_buffers 3689 ); 3690 3691 /** @} */ 3692 3693 /** 3694 * \defgroup VdpVideoMixer VdpVideoMixer; Video Post-processing and Compositing object 3695 * 3696 * VdpVideoMixer can perform some subset of the following 3697 * post-processing steps on video: 3698 * - De-interlacing 3699 * - Various types, with or without inverse telecine 3700 * - Noise-reduction 3701 * - Sharpness adjustment 3702 * - Color space conversion to RGB 3703 * - Chroma format upscaling to 4:4:4 3704 * 3705 * A VdpVideoMixer takes a source \ref VdpVideoSurface 3706 * "VdpVideoSurface" VdpVideoSurface and performs various video 3707 * processing steps on it (potentially using information from 3708 * past or future video surfaces). It scales the video and 3709 * converts it to RGB, then optionally composites it with 3710 * multiple auxiliary \ref VdpOutputSurface "VdpOutputSurface"s 3711 * before writing the result to the destination \ref 3712 * VdpOutputSurface "VdpOutputSurface". 3713 * 3714 * The video mixer compositing model is as follows: 3715 * 3716 * - A rectangle will be rendered on an output surface. No 3717 * pixels will be rendered outside of this output rectangle. 3718 * The contents of this rectangle will be a composite of many 3719 * layers. 3720 * 3721 * - The first layer is the background color. The background 3722 * color will fill the entire rectangle. 3723 * 3724 * - The second layer is the processed video which has been 3725 * converted to RGB. These pixels will overwrite the 3726 * background color of the first layer except where the second 3727 * layer's rectangle does not completely cover the output 3728 * rectangle. In those regions the background color will 3729 * continue to show. If any portion of the second layer's 3730 * output rectangle is outside of the output rectangle, those 3731 * portions will be clipped. 3732 * 3733 * - The third layer contains some number of auxiliary layers 3734 * (in the form of \ref VdpOutputSurface "VdpOutputSurface"s) 3735 * which will be composited using the alpha value from the 3736 * those surfaces. The compositing operations are equivalent 3737 * to rendering with \ref VdpOutputSurfaceRenderOutputSurface 3738 * using a source blend factor of SOURCE_ALPHA, a destination 3739 * blend factor of ONE_MINUS_SOURCE_ALPHA and an equation of 3740 * ADD. 3741 * 3742 * @{ 3743 */ 3744 3745 /** 3746 * \brief A VdpVideoMixer feature that must be requested at 3747 * creation time to be used. 3748 * 3749 * Certain advanced VdpVideoMixer features are optional, and the 3750 * ability to use those features at all must be requested when 3751 * the VdpVideoMixer object is created. Each feature is named via 3752 * a specific VdpVideoMixerFeature value. 3753 * 3754 * Once requested, these features are permanently available 3755 * within that specific VdpVideoMixer object. All features that 3756 * are not explicitly requested at creation time default to 3757 * being permanently unavailable. 3758 * 3759 * Even when requested, all features default to being initially 3760 * disabled. However, applications can subsequently enable and 3761 * disable features at any time. See \ref 3762 * VdpVideoMixerSetFeatureEnables. 3763 * 3764 * Some features allow configuration of their operation. Each 3765 * configurable item is an \ref VdpVideoMixerAttribute. These 3766 * attributes may be manipulated at any time using \ref 3767 * VdpVideoMixerSetAttributeValues. 3768 */ 3769 typedef uint32_t VdpVideoMixerFeature; 3770 3771 /** 3772 * \hideinitializer 3773 * \brief A VdpVideoMixerFeature. 3774 * 3775 * When requested and enabled, motion adaptive temporal 3776 * deinterlacing will be used on interlaced content. 3777 * 3778 * When multiple de-interlacing options are requested and 3779 * enabled, the back-end implementation chooses the best 3780 * algorithm to apply. 3781 */ 3782 #define VDP_VIDEO_MIXER_FEATURE_DEINTERLACE_TEMPORAL ((VdpVideoMixerFeature)0) 3783 /** 3784 * \hideinitializer 3785 * \brief A VdpVideoMixerFeature. 3786 * 3787 * When requested and enabled, this enables a more advanced 3788 * version of temporal de-interlacing, that additionally uses 3789 * edge-guided spatial interpolation. 3790 * 3791 * When multiple de-interlacing options are requested and 3792 * enabled, the back-end implementation chooses the best 3793 * algorithm to apply. 3794 */ 3795 #define VDP_VIDEO_MIXER_FEATURE_DEINTERLACE_TEMPORAL_SPATIAL ((VdpVideoMixerFeature)1) 3796 /** 3797 * \hideinitializer 3798 * \brief A VdpVideoMixerFeature. 3799 * 3800 * When requested and enabled, cadence detection will be enabled 3801 * on interlaced content and the video mixer will try to extract 3802 * progressive frames from pull-down material. 3803 */ 3804 #define VDP_VIDEO_MIXER_FEATURE_INVERSE_TELECINE ((VdpVideoMixerFeature)2) 3805 /** 3806 * \hideinitializer 3807 * \brief A VdpVideoMixerFeature. 3808 * 3809 * When requested and enabled, a noise reduction algorithm will 3810 * be applied to the video. 3811 */ 3812 #define VDP_VIDEO_MIXER_FEATURE_NOISE_REDUCTION ((VdpVideoMixerFeature)3) 3813 /** 3814 * \hideinitializer 3815 * \brief A VdpVideoMixerFeature. 3816 * 3817 * When requested and enabled, a sharpening algorithm will be 3818 * applied to the video. 3819 */ 3820 #define VDP_VIDEO_MIXER_FEATURE_SHARPNESS ((VdpVideoMixerFeature)4) 3821 /** 3822 * \hideinitializer 3823 * \brief A VdpVideoMixerFeature. 3824 * 3825 * When requested and enabled, the alpha of the rendered 3826 * surface, which is normally set to the alpha of the background 3827 * color, will be forced to 0.0 on pixels corresponding to 3828 * source video surface luminance values in the range specified 3829 * by attributes \ref VDP_VIDEO_MIXER_ATTRIBUTE_LUMA_KEY_MIN_LUMA 3830 * to \ref VDP_VIDEO_MIXER_ATTRIBUTE_LUMA_KEY_MAX_LUMA. This 3831 * keying is performed after scaling and de-interlacing. 3832 */ 3833 #define VDP_VIDEO_MIXER_FEATURE_LUMA_KEY ((VdpVideoMixerFeature)5) 3834 /** 3835 * \hideinitializer 3836 * \brief A VdpVideoMixerFeature. 3837 * 3838 * A VDPAU implementation may support multiple scaling algorithms of 3839 * differing quality, and may potentially support a different subset 3840 * of algorithms on different hardware. 3841 * 3842 * In some cases, higher quality algorithms may require more resources 3843 * (memory size, memory bandwidth, etc.) to operate. Hence, these high 3844 * quality algorithms must be explicitly requested and enabled by the client 3845 * application. This allows applications operating in a resource-constrained 3846 * environment to have some level of control over resource usage. 3847 * 3848 * Basic scaling is always built into any video mixer, and is known as 3849 * level 0. Scaling quality increases beginning with optional level 1, 3850 * through optional level 9. 3851 * 3852 * If an application requests and enables multiple high quality scaling 3853 * algorithms, the highest level enabled scaling algorithm will be used. 3854 */ 3855 #define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1 ((VdpVideoMixerFeature)11) 3856 /** 3857 * \hideinitializer 3858 * \brief A VdpVideoMixerFeature. 3859 * 3860 * See \ref VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1 for details. 3861 */ 3862 #define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L2 ((VdpVideoMixerFeature)12) 3863 /** 3864 * \hideinitializer 3865 * \brief A VdpVideoMixerFeature. 3866 * 3867 * See \ref VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1 for details. 3868 */ 3869 #define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L3 ((VdpVideoMixerFeature)13) 3870 /** 3871 * \hideinitializer 3872 * \brief A VdpVideoMixerFeature. 3873 * 3874 * See \ref VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1 for details. 3875 */ 3876 #define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L4 ((VdpVideoMixerFeature)14) 3877 /** 3878 * \hideinitializer 3879 * \brief A VdpVideoMixerFeature. 3880 * 3881 * See \ref VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1 for details. 3882 */ 3883 #define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L5 ((VdpVideoMixerFeature)15) 3884 /** 3885 * \hideinitializer 3886 * \brief A VdpVideoMixerFeature. 3887 * 3888 * See \ref VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1 for details. 3889 */ 3890 #define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L6 ((VdpVideoMixerFeature)16) 3891 /** 3892 * \hideinitializer 3893 * \brief A VdpVideoMixerFeature. 3894 * 3895 * See \ref VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1 for details. 3896 */ 3897 #define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L7 ((VdpVideoMixerFeature)17) 3898 /** 3899 * \hideinitializer 3900 * \brief A VdpVideoMixerFeature. 3901 * 3902 * See \ref VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1 for details. 3903 */ 3904 #define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L8 ((VdpVideoMixerFeature)18) 3905 /** 3906 * \hideinitializer 3907 * \brief A VdpVideoMixerFeature. 3908 * 3909 * See \ref VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1 for details. 3910 */ 3911 #define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L9 ((VdpVideoMixerFeature)19) 3912 3913 /** 3914 * \brief A VdpVideoMixer creation parameter. 3915 * 3916 * When a VdpVideoMixer is created, certain parameters may be 3917 * supplied. Each parameter is named via a specific 3918 * VdpVideoMixerParameter value. 3919 * 3920 * Each parameter has a specific type, and specific default 3921 * value if not specified at VdpVideoMixer creation time. The 3922 * application may query the legal supported range for some 3923 * parameters. 3924 */ 3925 typedef uint32_t VdpVideoMixerParameter; 3926 3927 /** 3928 * \hideinitializer 3929 * \brief The exact width of input video surfaces. 3930 * 3931 * This parameter's type is uint32_t. 3932 * 3933 * This parameter defaults to 0 if not specified, which entails 3934 * that it must be specified. 3935 * 3936 * The application may query this parameter's supported 3937 * range. 3938 */ 3939 #define VDP_VIDEO_MIXER_PARAMETER_VIDEO_SURFACE_WIDTH ((VdpVideoMixerParameter)0) 3940 /** 3941 * \hideinitializer 3942 * \brief The exact height of input video surfaces. 3943 * 3944 * This parameter's type is uint32_t. 3945 * 3946 * This parameter defaults to 0 if not specified, which entails 3947 * that it must be specified. 3948 * 3949 * The application may query this parameter's supported 3950 * range. 3951 */ 3952 #define VDP_VIDEO_MIXER_PARAMETER_VIDEO_SURFACE_HEIGHT ((VdpVideoMixerParameter)1) 3953 /** 3954 * \hideinitializer 3955 * \brief The chroma type of the input video surfaces the will 3956 * process. 3957 * 3958 * This parameter's type is VdpChromaType. 3959 * 3960 * If not specified, this parameter defaults to 3961 * VDP_CHROMA_TYPE_420. 3962 * 3963 * The application may not query this application's supported 3964 * range, since it is a potentially disjoint enumeration. 3965 */ 3966 #define VDP_VIDEO_MIXER_PARAMETER_CHROMA_TYPE ((VdpVideoMixerParameter)2) 3967 /** 3968 * \hideinitializer 3969 * \brief The number of auxiliary layers in the mixer's 3970 * compositing model. 3971 * 3972 * Note that this indicates the maximum number of layers that 3973 * may be processed by a given \ref VdpVideoMixer "VdpVideoMixer" 3974 * object. Each individual \ref VdpVideoMixerRender invocation 3975 * may choose to use a different number of actual layers, from 0 3976 * up to this limit. 3977 * 3978 * This attribute's type is uint32_t. 3979 * 3980 * If not specified, this parameter defaults to 0. 3981 * 3982 * The application may query this parameter's supported 3983 * range. 3984 */ 3985 #define VDP_VIDEO_MIXER_PARAMETER_LAYERS ((VdpVideoMixerParameter)3) 3986 3987 /** 3988 * \brief An adjustable attribute of VdpVideoMixer operation. 3989 * 3990 * Various attributes of VdpVideoMixer operation may be adjusted 3991 * at any time. Each attribute is named via a specific 3992 * VdpVideoMixerAttribute value. 3993 * 3994 * Each attribute has a specific type, and specific default 3995 * value if not specified at VdpVideoMixer creation time. The 3996 * application may query the legal supported range for some 3997 * attributes. 3998 */ 3999 typedef uint32_t VdpVideoMixerAttribute; 4000 4001 /** 4002 * \hideinitializer 4003 * \brief The background color in the VdpVideoMixer's compositing 4004 * model. 4005 * 4006 * This attribute's type is VdpColor. 4007 * 4008 * This parameter defaults to black (all color components 0.0 4009 * and alpha 1.0). 4010 * 4011 * The application may not query this parameter's supported 4012 * range, since the type is not scalar. 4013 */ 4014 #define VDP_VIDEO_MIXER_ATTRIBUTE_BACKGROUND_COLOR ((VdpVideoMixerAttribute)0) 4015 /** 4016 * \hideinitializer 4017 * \brief The color-space conversion matrix used by the 4018 * VdpVideoMixer. 4019 * 4020 * This attribute's type is \ref VdpCSCMatrix. 4021 * 4022 * Note: When using \ref VdpVideoMixerGetAttributeValues to retrieve the 4023 * current CSC matrix, the attribute_values array must contain a pointer to 4024 * a pointer a VdpCSCMatrix (VdpCSCMatrix** as a void *). The get function will 4025 * either initialize the referenced CSC matrix to the current value, *or* 4026 * clear the supplied pointer to NULL, if the previous set call supplied a 4027 * value of NULL in parameter_values, to request the default matrix. 4028 * 4029 * \code 4030 * VdpCSCMatrix matrix; 4031 * VdpCSCMatrix * matrix_ptr; 4032 * void * attribute_values[] = {&matrix_ptr}; 4033 * VdpStatus st = vdp_video_mixer_get_attribute_values(..., attribute_values, ...); 4034 * \endcode 4035 * 4036 * This parameter defaults to a matrix suitable for ITU-R BT.601 4037 * input surfaces, with no procamp adjustments. 4038 * 4039 * The application may not query this parameter's supported 4040 * range, since the type is not scalar. 4041 */ 4042 #define VDP_VIDEO_MIXER_ATTRIBUTE_CSC_MATRIX ((VdpVideoMixerAttribute)1) 4043 /** 4044 * \hideinitializer 4045 * \brief The amount of noise reduction algorithm to apply. 4046 * 4047 * This attribute's type is float. 4048 * 4049 * This parameter defaults to 0.0, which equates to no noise 4050 * reduction. 4051 * 4052 * The application may query this parameter's supported range. 4053 * However, the range is fixed as 0.0...1.0. 4054 */ 4055 #define VDP_VIDEO_MIXER_ATTRIBUTE_NOISE_REDUCTION_LEVEL ((VdpVideoMixerAttribute)2) 4056 /** 4057 * \hideinitializer 4058 * \brief The amount of sharpening, or blurring, to apply. 4059 * 4060 * This attribute's type is float. 4061 * 4062 * This parameter defaults to 0.0, which equates to no 4063 * sharpening. 4064 * 4065 * Positive values request sharpening. Negative values request 4066 * blurring. 4067 * 4068 * The application may query this parameter's supported range. 4069 * However, the range is fixed as -1.0...1.0. 4070 */ 4071 #define VDP_VIDEO_MIXER_ATTRIBUTE_SHARPNESS_LEVEL ((VdpVideoMixerAttribute)3) 4072 /** 4073 * \hideinitializer 4074 * \brief The minimum luma value for the luma key algorithm. 4075 * 4076 * This attribute's type is float. 4077 * 4078 * This parameter defaults to 0.0. 4079 * 4080 * The application may query this parameter's supported range. 4081 * However, the range is fixed as 0.0...1.0. 4082 */ 4083 #define VDP_VIDEO_MIXER_ATTRIBUTE_LUMA_KEY_MIN_LUMA ((VdpVideoMixerAttribute)4) 4084 /** 4085 * \hideinitializer 4086 * \brief The maximum luma value for the luma key algorithm. 4087 * 4088 * This attribute's type is float. 4089 * 4090 * This parameter defaults to 1.0. 4091 * 4092 * The application may query this parameter's supported range. 4093 * However, the range is fixed as 0.0...1.0. 4094 */ 4095 #define VDP_VIDEO_MIXER_ATTRIBUTE_LUMA_KEY_MAX_LUMA ((VdpVideoMixerAttribute)5) 4096 /** 4097 * \hideinitializer 4098 * \brief Whether de-interlacers should operate solely on luma, and bob chroma. 4099 * 4100 * Note: This attribute only affects advanced de-interlacing algorithms, not 4101 * bob or weave. 4102 * 4103 * This attribute's type is uint8_t. 4104 * 4105 * This parameter defaults to 0. 4106 * 4107 * The application may query this parameter's supported range. 4108 * However, the range is fixed as 0 (no/off) ... 1 (yes/on). 4109 */ 4110 #define VDP_VIDEO_MIXER_ATTRIBUTE_SKIP_CHROMA_DEINTERLACE ((VdpVideoMixerAttribute)6) 4111 4112 /** 4113 * \brief Query the implementation's support for a specific 4114 * feature. 4115 * \param[in] device The device to query. 4116 * \param[in] feature The feature for which support is to be 4117 * queried. 4118 * \param[out] is_supported Is the specified feature supported? 4119 * \return VdpStatus The completion status of the operation. 4120 */ 4121 typedef VdpStatus VdpVideoMixerQueryFeatureSupport( 4122 VdpDevice device, 4123 VdpVideoMixerFeature feature, 4124 /* output parameters follow */ 4125 VdpBool * is_supported 4126 ); 4127 4128 /** 4129 * \brief Query the implementation's support for a specific 4130 * parameter. 4131 * \param[in] device The device to query. 4132 * \param[in] parameter The parameter for which support is to be 4133 * queried. 4134 * \param[out] is_supported Is the specified parameter 4135 * supported? 4136 * \return VdpStatus The completion status of the operation. 4137 */ 4138 typedef VdpStatus VdpVideoMixerQueryParameterSupport( 4139 VdpDevice device, 4140 VdpVideoMixerParameter parameter, 4141 /* output parameters follow */ 4142 VdpBool * is_supported 4143 ); 4144 4145 /** 4146 * \brief Query the implementation's support for a specific 4147 * attribute. 4148 * \param[in] device The device to query. 4149 * \param[in] feature The feature for which support is to be 4150 * queried. 4151 * \param[out] is_supported Is the specified feature supported? 4152 * \return VdpStatus The completion status of the operation. 4153 */ 4154 typedef VdpStatus VdpVideoMixerQueryAttributeSupport( 4155 VdpDevice device, 4156 VdpVideoMixerAttribute attribute, 4157 /* output parameters follow */ 4158 VdpBool * is_supported 4159 ); 4160 4161 /** 4162 * \brief Query the implementation's supported for a specific 4163 * parameter. 4164 * \param[in] device The device to query. 4165 * \param[in] parameter The parameter for which support is to be 4166 * queried. 4167 * \param[out] min_value The minimum supported value. 4168 * \param[out] max_value The maximum supported value. 4169 * \return VdpStatus The completion status of the operation. 4170 */ 4171 typedef VdpStatus VdpVideoMixerQueryParameterValueRange( 4172 VdpDevice device, 4173 VdpVideoMixerParameter parameter, 4174 /* output parameters follow */ 4175 void * min_value, 4176 void * max_value 4177 ); 4178 4179 /** 4180 * \brief Query the implementation's supported for a specific 4181 * attribute. 4182 * \param[in] device The device to query. 4183 * \param[in] attribute The attribute for which support is to be 4184 * queried. 4185 * \param[out] min_value The minimum supported value. 4186 * \param[out] max_value The maximum supported value. 4187 * \return VdpStatus The completion status of the operation. 4188 */ 4189 typedef VdpStatus VdpVideoMixerQueryAttributeValueRange( 4190 VdpDevice device, 4191 VdpVideoMixerAttribute attribute, 4192 /* output parameters follow */ 4193 void * min_value, 4194 void * max_value 4195 ); 4196 4197 /** 4198 * \brief An opaque handle representing a VdpVideoMixer object. 4199 */ 4200 typedef uint32_t VdpVideoMixer; 4201 4202 /** 4203 * \brief Create a VdpVideoMixer. 4204 * \param[in] device The device that will contain the mixer. 4205 * \param[in] feature_count The number of features to request. 4206 * \param[in] features The list of features to request. 4207 * \param[in] parameter_count The number of parameters to set. 4208 * \param[in] parameters The list of parameters to set. 4209 * \param[in] parameter_values The values for the parameters. Note that each 4210 * entry in the value array is a pointer to the actual value. In other 4211 * words, the values themselves are not cast to "void *" and passed 4212 * "inside" the array. 4213 * \param[out] mixer The new mixer's handle. 4214 * \return VdpStatus The completion status of the operation. 4215 * 4216 * Initially, all requested features will be disabled. They can 4217 * be enabled using \ref VdpVideoMixerSetFeatureEnables. 4218 * 4219 * Initially, all attributes will have default values. Values 4220 * can be changed using \ref VdpVideoMixerSetAttributeValues. 4221 */ 4222 typedef VdpStatus VdpVideoMixerCreate( 4223 VdpDevice device, 4224 // The set of features to request 4225 uint32_t feature_count, 4226 VdpVideoMixerFeature const * features, 4227 // The parameters used during creation 4228 uint32_t parameter_count, 4229 VdpVideoMixerParameter const * parameters, 4230 void const * const * parameter_values, 4231 /* output parameters follow */ 4232 VdpVideoMixer * mixer 4233 ); 4234 4235 /** 4236 * \brief Enable or disable features. 4237 * \param[in] mixer The mixer to manipulate. 4238 * \param[in] feature_count The number of features to 4239 * enable/disable. 4240 * \param[in] features The list of features to enable/disable. 4241 * \param[in] feature_enables The list of new feature enable 4242 * values. 4243 * \return VdpStatus The completion status of the operation. 4244 */ 4245 typedef VdpStatus VdpVideoMixerSetFeatureEnables( 4246 VdpVideoMixer mixer, 4247 uint32_t feature_count, 4248 VdpVideoMixerFeature const * features, 4249 VdpBool const * feature_enables 4250 ); 4251 4252 /** 4253 * \brief Set attribute values 4254 * \param[in] mixer The mixer to manipulate. 4255 * \param[in] attribute_count The number of attributes to set. 4256 * \param[in] attributes The list of attributes to set. 4257 * \param[in] attribute_values The values for the attributes. Note that each 4258 * entry in the value array is a pointer to the actual value. In other 4259 * words, the values themselves are not cast to "void *" and passed 4260 * "inside" the array. A NULL pointer requests that the default value be 4261 * set for that attribute. 4262 * \return VdpStatus The completion status of the operation. 4263 */ 4264 typedef VdpStatus VdpVideoMixerSetAttributeValues( 4265 VdpVideoMixer mixer, 4266 uint32_t attribute_count, 4267 VdpVideoMixerAttribute const * attributes, 4268 void const * const * attribute_values 4269 ); 4270 4271 /** 4272 * \brief Retrieve whether features were requested at creation 4273 * time. 4274 * \param[in] mixer The mixer to query. 4275 * \param[in] feature_count The number of features to query. 4276 * \param[in] features The list of features to query. 4277 * \param[out] feature_supported A list of values indicating 4278 * whether the feature was requested, and hence is 4279 * available. 4280 * \return VdpStatus The completion status of the operation. 4281 */ 4282 typedef VdpStatus VdpVideoMixerGetFeatureSupport( 4283 VdpVideoMixer mixer, 4284 uint32_t feature_count, 4285 VdpVideoMixerFeature const * features, 4286 /* output parameters follow */ 4287 VdpBool * feature_supports 4288 ); 4289 4290 /** 4291 * \brief Retrieve whether features are enabled. 4292 * \param[in] mixer The mixer to manipulate. 4293 * \param[in] feature_count The number of features to query. 4294 * \param[in] features The list of features to query. 4295 * \param[out] feature_enabled A list of values indicating 4296 * whether the feature is enabled. 4297 * \return VdpStatus The completion status of the operation. 4298 */ 4299 typedef VdpStatus VdpVideoMixerGetFeatureEnables( 4300 VdpVideoMixer mixer, 4301 uint32_t feature_count, 4302 VdpVideoMixerFeature const * features, 4303 /* output parameters follow */ 4304 VdpBool * feature_enables 4305 ); 4306 4307 /** 4308 * \brief Retrieve parameter values given at creation time. 4309 * \param[in] mixer The mixer to manipulate. 4310 * \param[in] parameter_count The number of parameters to query. 4311 * \param[in] parameters The list of parameters to query. 4312 * \param[out] parameter_values The list of current values for 4313 * the parameters. Note that each entry in the value array is a pointer to 4314 * storage that will receive the actual value. If the attribute's type is 4315 * a pointer itself, please closely read the documentation for that 4316 * attribute type for any other data passing requirements. 4317 * \return VdpStatus The completion status of the operation. 4318 */ 4319 typedef VdpStatus VdpVideoMixerGetParameterValues( 4320 VdpVideoMixer mixer, 4321 uint32_t parameter_count, 4322 VdpVideoMixerParameter const * parameters, 4323 /* output parameters follow */ 4324 void * const * parameter_values 4325 ); 4326 4327 /** 4328 * \brief Retrieve current attribute values. 4329 * \param[in] mixer The mixer to manipulate. 4330 * \param[in] attribute_count The number of attributes to query. 4331 * \param[in] attributes The list of attributes to query. 4332 * \param[out] attribute_values The list of current values for 4333 * the attributes. Note that each entry in the value array is a pointer to 4334 * storage that will receive the actual value. If the attribute's type is 4335 * a pointer itself, please closely read the documentation for that 4336 * attribute type for any other data passing requirements. 4337 * \return VdpStatus The completion status of the operation. 4338 */ 4339 typedef VdpStatus VdpVideoMixerGetAttributeValues( 4340 VdpVideoMixer mixer, 4341 uint32_t attribute_count, 4342 VdpVideoMixerAttribute const * attributes, 4343 /* output parameters follow */ 4344 void * const * attribute_values 4345 ); 4346 4347 /** 4348 * \brief Destroy a VdpVideoMixer. 4349 * \param[in] device The device to destroy. 4350 * \return VdpStatus The completion status of the operation. 4351 */ 4352 typedef VdpStatus VdpVideoMixerDestroy( 4353 VdpVideoMixer mixer 4354 ); 4355 4356 /** 4357 * \hideinitializer 4358 * \brief The structure of the picture present in a \ref 4359 * VdpVideoSurface "VdpVideoSurface". 4360 */ 4361 typedef enum { 4362 /** 4363 * The picture is a field, and is the top field of the surface. 4364 */ 4365 VDP_VIDEO_MIXER_PICTURE_STRUCTURE_TOP_FIELD, 4366 /** 4367 * The picture is a field, and is the bottom field of the 4368 * surface. 4369 */ 4370 VDP_VIDEO_MIXER_PICTURE_STRUCTURE_BOTTOM_FIELD, 4371 /** 4372 * The picture is a frame, and hence is the entire surface. 4373 */ 4374 VDP_VIDEO_MIXER_PICTURE_STRUCTURE_FRAME, 4375 } VdpVideoMixerPictureStructure; 4376 4377 #define VDP_LAYER_VERSION 0 4378 4379 /** 4380 * \brief Definition of an additional \ref VdpOutputSurface 4381 * "VdpOutputSurface" layer in the composting model. 4382 */ 4383 typedef struct { 4384 /** 4385 * This field must be filled with VDP_LAYER_VERSION 4386 */ 4387 uint32_t struct_version; 4388 /** 4389 * The surface to composite from. 4390 */ 4391 VdpOutputSurface source_surface; 4392 /** 4393 * The sub-rectangle of the source surface to use. If NULL, the 4394 * entire source surface will be used. 4395 */ 4396 VdpRect const * source_rect; 4397 /** 4398 * The sub-rectangle of the destination surface to map 4399 * this layer into. This rectangle is relative to the entire 4400 * destination surface. This rectangle will be clipped by \ref 4401 * VdpVideoMixerRender's \b destination_rect. If NULL, the 4402 * destination rectangle will be sized to match the source 4403 * rectangle, and will be located at the origin. 4404 */ 4405 VdpRect const * destination_rect; 4406 } VdpLayer; 4407 4408 /** 4409 * \brief Perform a video post-processing and compositing 4410 * operation. 4411 * \param[in] mixer The mixer object that will perform the 4412 * mixing/rendering operation. 4413 * \param[in] background_surface A background image. If set to any value other 4414 * than VDP_INVALID_HANDLE, the specific surface will be used instead of 4415 * the background color as the first layer in the mixer's compositing 4416 * process. 4417 * \param[in] background_source_rect When background_surface is specified, 4418 * this parameter indicates the portion of background_surface that will 4419 * be used as the background layer. The specified region will be 4420 * extracted and scaled to match the size of destination_rect. If NULL, 4421 * the entire background_surface will be used. 4422 * \param[in] current_picture_structure The picture structure of 4423 * the field/frame to be processed. This field/frame is 4424 * presented in the \b video_surface_current parameter. If 4425 * frame, then all \b video_surface_* parameters are 4426 * assumed to be frames. If field, then all 4427 * video_surface_* parameters are assumed to be fields, 4428 * with alternating top/bottom-ness derived from 4429 * video_surface_current. 4430 * \param[in] video_surfaces_past_count The number of provided 4431 * fields/frames prior to the current picture. 4432 * \param[in] video_surfaces_past The fields/frames prior to the 4433 * current field/frame. Note that array index 0 is the 4434 * field/frame temporally nearest to the current 4435 * field/frame, with increasing array indices used for 4436 * older frames. Unavailable entries may be set to 4437 * \ref VDP_INVALID_HANDLE. 4438 * \param[in] video_surface_current The field/frame to be 4439 * processed. 4440 * \param[in] video_surfaces_future_count The number of provided 4441 * fields/frames following the current picture. 4442 * \param[in] video_surfaces_future The fields/frames that 4443 * follow the current field/frame. Note that array index 0 4444 * is the field/frame temporally nearest to the current 4445 * field/frame, with increasing array indices used for 4446 * newer frames. Unavailable entries may be set to \ref 4447 * VDP_INVALID_HANDLE. 4448 * \param[in] video_source_rect The sub-rectangle of the source 4449 * video surface to extract and process. If NULL, the 4450 * entire surface will be used. Left/right and/or top/bottom 4451 * co-ordinates may be swapped to flip the source. Values 4452 * from outside the video surface are valid and samples 4453 * at those locations will be taken from the nearest edge. 4454 * \param[in] destination_surface 4455 * \param[in] destination_rect The sub-rectangle of the 4456 * destination surface to modify. Note that rectangle clips 4457 * all other actions. 4458 * \param[in] destination_video_rect The sub-rectangle of the 4459 * destination surface that will contain the processed 4460 * video. This rectangle is relative to the entire 4461 * destination surface. This rectangle is clipped by \b 4462 * destination_rect. If NULL, the destination rectangle 4463 * will be sized to match the source rectangle, and will 4464 * be located at the origin. 4465 * \param[in] layer_count The number of additional layers to 4466 * composite above the video. 4467 * \param[in] layers The array of additional layers to composite 4468 * above the video. 4469 * \return VdpStatus The completion status of the operation. 4470 * 4471 * For a complete discussion of how to use this API, please see 4472 * \ref video_mixer_usage. 4473 */ 4474 typedef VdpStatus VdpVideoMixerRender( 4475 VdpVideoMixer mixer, 4476 VdpOutputSurface background_surface, 4477 VdpRect const * background_source_rect, 4478 VdpVideoMixerPictureStructure current_picture_structure, 4479 uint32_t video_surface_past_count, 4480 VdpVideoSurface const * video_surface_past, 4481 VdpVideoSurface video_surface_current, 4482 uint32_t video_surface_future_count, 4483 VdpVideoSurface const * video_surface_future, 4484 VdpRect const * video_source_rect, 4485 VdpOutputSurface destination_surface, 4486 VdpRect const * destination_rect, 4487 VdpRect const * destination_video_rect, 4488 uint32_t layer_count, 4489 VdpLayer const * layers 4490 ); 4491 4492 /** @} */ 4493 4494 /** 4495 * \defgroup VdpPresentationQueue VdpPresentationQueue; Video presentation (display) object 4496 * 4497 * The VdpPresentationQueue manages a queue of surfaces and 4498 * associated timestamps. For each surface in the queue, once 4499 * the associated timestamp is reached, the surface is displayed 4500 * to the user. This timestamp-based approach yields high 4501 * quality video delivery. 4502 * 4503 * The exact location of the displayed content is Window System 4504 * specific. For this reason, the \ref api_winsys provides an 4505 * API to create a \ref VdpPresentationQueueTarget object (e.g. 4506 * via \ref VdpPresentationQueueTargetCreateX11) which 4507 * encapsulates this information. 4508 * 4509 * Note that the presentation queue performs no scaling of 4510 * surfaces to match the display target's size, aspect ratio, 4511 * etc. 4512 * 4513 * Surfaces that are too large to fit into the display target 4514 * will be clipped. Surfaces that are too small to fill the 4515 * display target will be aligned to the top-left corner of the 4516 * display target, with the balance of the display target being 4517 * filled with a constant configurable "background" color. 4518 * 4519 * Note that the presentation queue operates in a manner that is 4520 * semantically equivalent to an overlay surface, with any 4521 * required color key painting hidden internally. However, 4522 * implementations are free to use whatever semantically 4523 * equivalent technique they wish. Note that implementations 4524 * that actually use color-keyed overlays will typically use 4525 * the "background" color as the overlay color key value, so 4526 * this color should be chosen with care. 4527 * 4528 * @{ 4529 */ 4530 4531 /** 4532 * \brief The representation of a point in time. 4533 * 4534 * VdpTime timestamps are intended to be a high-precision timing 4535 * system, potentially independent from any other time domain in 4536 * the system. 4537 * 4538 * Time is represented in units of nanoseconds. The origin 4539 * (i.e. the time represented by a value of 0) is implementation 4540 * dependent. 4541 */ 4542 typedef uint64_t VdpTime; 4543 4544 /** 4545 * \brief An opaque handle representing the location where 4546 * video will be presented. 4547 * 4548 * VdpPresentationQueueTarget are created using a \ref api_winsys 4549 * specific API, such as \ref 4550 * VdpPresentationQueueTargetCreateX11. 4551 */ 4552 typedef uint32_t VdpPresentationQueueTarget; 4553 4554 /** 4555 * \brief Destroy a VdpPresentationQueueTarget. 4556 * \param[in] presentation_queue_target The target to destroy. 4557 * \return VdpStatus The completion status of the operation. 4558 */ 4559 typedef VdpStatus VdpPresentationQueueTargetDestroy( 4560 VdpPresentationQueueTarget presentation_queue_target 4561 ); 4562 4563 /** 4564 * \brief An opaque handle representing a presentation queue 4565 * object. 4566 */ 4567 typedef uint32_t VdpPresentationQueue; 4568 4569 /** 4570 * \brief Create a VdpPresentationQueue. 4571 * \param[in] device The device that will contain the queue. 4572 * \param[in] presentation_queue_target The location to display 4573 * the content. 4574 * \param[out] presentation_queue The new queue's handle. 4575 * \return VdpStatus The completion status of the operation. 4576 * 4577 * Note: The initial value for the background color will be set to 4578 * an implementation-defined value. 4579 */ 4580 typedef VdpStatus VdpPresentationQueueCreate( 4581 VdpDevice device, 4582 VdpPresentationQueueTarget presentation_queue_target, 4583 /* output parameters follow */ 4584 VdpPresentationQueue * presentation_queue 4585 ); 4586 4587 /** 4588 * \brief Destroy a VdpPresentationQueue. 4589 * \param[in] presentation_queue The queue to destroy. 4590 * \return VdpStatus The completion status of the operation. 4591 */ 4592 typedef VdpStatus VdpPresentationQueueDestroy( 4593 VdpPresentationQueue presentation_queue 4594 ); 4595 4596 /** 4597 * \brief Configure the background color setting. 4598 * \param[in] presentation_queue The queue to manipulate. 4599 * \param[in] background_color The new background color. 4600 * 4601 * Note: Implementations may choose whether to apply the 4602 * new background color value immediately, or defer it until 4603 * the next surface is presented. 4604 */ 4605 typedef VdpStatus VdpPresentationQueueSetBackgroundColor( 4606 VdpPresentationQueue presentation_queue, 4607 VdpColor * const background_color 4608 ); 4609 4610 /** 4611 * \brief Retrieve the current background color setting. 4612 * \param[in] presentation_queue The queue to query. 4613 * \param[out] background_color The current background color. 4614 */ 4615 typedef VdpStatus VdpPresentationQueueGetBackgroundColor( 4616 VdpPresentationQueue presentation_queue, 4617 VdpColor * background_color 4618 ); 4619 4620 /** 4621 * \brief Retrieve the presentation queue's "current" time. 4622 * \param[in] presentation_queue The queue to query. 4623 * \param[out] current_time The current time, which may 4624 * represent a point between display VSYNC events. 4625 * \return VdpStatus The completion status of the operation. 4626 */ 4627 typedef VdpStatus VdpPresentationQueueGetTime( 4628 VdpPresentationQueue presentation_queue, 4629 /* output parameters follow */ 4630 VdpTime * current_time 4631 ); 4632 4633 /** 4634 * \brief Enter a surface into the presentation queue. 4635 * \param[in] presentation_queue The queue to query. 4636 * \param[in] surface The surface to enter into the queue. 4637 * \param[in] clip_width If set to a non-zero value, the presentation queue 4638 * will display only clip_width pixels of the surface (anchored to the 4639 * top-left corner of the surface. 4640 * \param[in] clip_height If set to a non-zero value, the presentation queue 4641 * will display only clip_height lines of the surface (anchored to the 4642 * top-left corner of the surface. 4643 * \param[in] earliest_presentation_time The timestamp 4644 * associated with the surface. The presentation queue 4645 * will not display the surface until the presentation 4646 * queue's current time is at least this value. 4647 * \return VdpStatus The completion status of the operation. 4648 * 4649 * Applications may choose to allow resizing of the presentation queue target 4650 * (which may be e.g. a regular Window when using an X11-based 4651 * implementation). 4652 * 4653 * \b clip_width and \b clip_height may be used to limit the size of the 4654 * displayed region of a surface, in order to match the specific region that 4655 * was rendered to. 4656 * 4657 * In turn, this allows the application to allocate over-sized (e.g. 4658 * screen-sized) surfaces, but render to a region that matches the current 4659 * size of the video window. 4660 * 4661 * Using this technique, an application's response to window resizing may 4662 * simply be to render to, and display, a different region of the surface, 4663 * rather than de-/re-allocation of surfaces to match the updated window size. 4664 * 4665 * Implementations may impose an upper bound on the number of entries 4666 * contained by the presentation queue at a given time. This limit is likely 4667 * different to the number of \ref VdpOutputSurface "VdpOutputSurface"s that 4668 * may be allocated at a given time. This limit applies to entries in the 4669 * QUEUED or VISIBLE state only. In other words, entries that have 4670 * transitioned from a QUEUED or VISIBLE state to an IDLE state do not count 4671 * toward this limit. 4672 */ 4673 typedef VdpStatus VdpPresentationQueueDisplay( 4674 VdpPresentationQueue presentation_queue, 4675 VdpOutputSurface surface, 4676 uint32_t clip_width, 4677 uint32_t clip_height, 4678 VdpTime earliest_presentation_time 4679 ); 4680 4681 /** 4682 * \brief Wait for a surface to finish being displayed. 4683 * \param[in] presentation_queue The queue to query. 4684 * \param[in] surface The surface to wait for. 4685 * \param[out] first_presentation_time The timestamp of the 4686 * VSYNC at which this surface was first displayed. Note 4687 * that 0 means the surface was never displayed. 4688 * \return VdpStatus The completion status of the operation. 4689 * 4690 * Note that this API would block forever if queried about the surface most 4691 * recently added to a presentation queue. That is because there would be no 4692 * other surface that could possibly replace that surface as the currently 4693 * displayed surface, and hence that surface would never become idle. For 4694 * that reason, this function will return an error in that case. 4695 */ 4696 typedef VdpStatus VdpPresentationQueueBlockUntilSurfaceIdle( 4697 VdpPresentationQueue presentation_queue, 4698 VdpOutputSurface surface, 4699 /* output parameters follow */ 4700 VdpTime * first_presentation_time 4701 ); 4702 4703 /** 4704 * \hideinitializer 4705 * \brief The status of a surface within a presentation queue. 4706 */ 4707 typedef enum { 4708 /** The surface is not queued or currently visible. */ 4709 VDP_PRESENTATION_QUEUE_STATUS_IDLE, 4710 /** The surface is in the queue, and not currently visible. */ 4711 VDP_PRESENTATION_QUEUE_STATUS_QUEUED, 4712 /** The surface is the currently visible surface. */ 4713 VDP_PRESENTATION_QUEUE_STATUS_VISIBLE, 4714 } VdpPresentationQueueStatus; 4715 4716 /** 4717 * \brief Poll the current queue status of a surface. 4718 * \param[in] presentation_queue The queue to query. 4719 * \param[in] surface The surface to query. 4720 * \param[out] status The current status of the surface within 4721 * the queue. 4722 * \param[out] first_presentation_time The timestamp of the 4723 * VSYNC at which this surface was first displayed. Note 4724 * that 0 means the surface was never displayed. 4725 * \return VdpStatus The completion status of the operation. 4726 */ 4727 typedef VdpStatus VdpPresentationQueueQuerySurfaceStatus( 4728 VdpPresentationQueue presentation_queue, 4729 VdpOutputSurface surface, 4730 /* output parameters follow */ 4731 VdpPresentationQueueStatus * status, 4732 VdpTime * first_presentation_time 4733 ); 4734 4735 /** @} */ 4736 4737 /** 4738 * \defgroup display_preemption Display Preemption 4739 * 4740 * The Window System may operate within a frame-work (such as 4741 * Linux's VT switching) where the display is shared between the 4742 * Window System (e.g. X) and some other output mechanism (e.g. 4743 * the VT.) Given this scenario, the Window System's control of 4744 * the display could be preempted, and restored, at any time. 4745 * 4746 * VDPAU does not mandate that implementations hide such 4747 * preemptions from VDPAU client applications; doing so may 4748 * impose extreme burdens upon VDPAU implementations. Equally, 4749 * however, implementations are free to hide such preemptions 4750 * from client applications. 4751 * 4752 * VDPAU allows implementations to inform the client application 4753 * when such a preemption has occurred, and then refuse to 4754 * continue further operation. 4755 * 4756 * Similarly, some form of fatal hardware error could prevent further 4757 * operation of the VDPAU implementation, without a complete 4758 * re-initialization. 4759 * 4760 * The following discusses the behavior of implementations that 4761 * choose not to hide preemption from client applications. 4762 * 4763 * When preemption occurs, VDPAU internally destroys all 4764 * objects; the client application need not do this. However, if 4765 * the client application wishes to continue operation, it must 4766 * recreate all objects that it uses. It is probable that this 4767 * recreation will not succeed until the display ownership is 4768 * restored to the Window System. 4769 * 4770 * Once preemption has occurred, all VDPAU entry points will 4771 * return the specific error code \ref 4772 * VDP_STATUS_DISPLAY_PREEMPTED. 4773 * 4774 * VDPAU client applications may also be notified of such 4775 * preemptions and fatal errors via a callback. See \ref 4776 * VdpPreemptionCallbackRegister for more details. 4777 * 4778 * @{ 4779 */ 4780 4781 /** 4782 * \brief A callback to notify the client application that a 4783 * device's display has been preempted. 4784 * \param[in] device The device that had its display preempted. 4785 * \param[in] context The client-supplied callback context 4786 * information. 4787 * \return void No return value 4788 */ 4789 typedef void VdpPreemptionCallback( 4790 VdpDevice device, 4791 void * context 4792 ); 4793 4794 /** 4795 * \brief Configure the display preemption callback. 4796 * \param[in] device The device to be monitored for preemption. 4797 * \param[in] callback The client application's callback 4798 * function. If NULL, the callback is unregistered. 4799 * \param[in] context The client-supplied callback context 4800 * information. This information will be passed to the 4801 * callback function if/when invoked. 4802 * \return VdpStatus The completion status of the operation. 4803 */ 4804 typedef VdpStatus VdpPreemptionCallbackRegister( 4805 VdpDevice device, 4806 VdpPreemptionCallback callback, 4807 void * context 4808 ); 4809 4810 /** @} */ 4811 4812 /** 4813 * \defgroup get_proc_address Entry Point Retrieval 4814 * 4815 * In order to facilitate multiple implementations of VDPAU 4816 * co-existing within a single process, all functionality is 4817 * available via function pointers. The mechanism to retrieve 4818 * those function pointers is described below. 4819 * 4820 * @{ 4821 */ 4822 4823 /** 4824 * \brief A type suitable for \ref VdpGetProcAddress 4825 * "VdpGetProcAddress"'s \b function_id parameter. 4826 */ 4827 typedef uint32_t VdpFuncId; 4828 4829 /** \hideinitializer */ 4830 #define VDP_FUNC_ID_GET_ERROR_STRING ((VdpFuncId)0) 4831 /** \hideinitializer */ 4832 #define VDP_FUNC_ID_GET_PROC_ADDRESS ((VdpFuncId)1) 4833 /** \hideinitializer */ 4834 #define VDP_FUNC_ID_GET_API_VERSION ((VdpFuncId)2) 4835 /** \hideinitializer */ 4836 #define VDP_FUNC_ID_GET_INFORMATION_STRING ((VdpFuncId)4) 4837 /** \hideinitializer */ 4838 #define VDP_FUNC_ID_DEVICE_DESTROY ((VdpFuncId)5) 4839 /** \hideinitializer */ 4840 #define VDP_FUNC_ID_GENERATE_CSC_MATRIX ((VdpFuncId)6) 4841 /** \hideinitializer */ 4842 #define VDP_FUNC_ID_VIDEO_SURFACE_QUERY_CAPABILITIES ((VdpFuncId)7) 4843 /** \hideinitializer */ 4844 #define VDP_FUNC_ID_VIDEO_SURFACE_QUERY_GET_PUT_BITS_Y_CB_CR_CAPABILITIES ((VdpFuncId)8) 4845 /** \hideinitializer */ 4846 #define VDP_FUNC_ID_VIDEO_SURFACE_CREATE ((VdpFuncId)9) 4847 /** \hideinitializer */ 4848 #define VDP_FUNC_ID_VIDEO_SURFACE_DESTROY ((VdpFuncId)10) 4849 /** \hideinitializer */ 4850 #define VDP_FUNC_ID_VIDEO_SURFACE_GET_PARAMETERS ((VdpFuncId)11) 4851 /** \hideinitializer */ 4852 #define VDP_FUNC_ID_VIDEO_SURFACE_GET_BITS_Y_CB_CR ((VdpFuncId)12) 4853 /** \hideinitializer */ 4854 #define VDP_FUNC_ID_VIDEO_SURFACE_PUT_BITS_Y_CB_CR ((VdpFuncId)13) 4855 /** \hideinitializer */ 4856 #define VDP_FUNC_ID_OUTPUT_SURFACE_QUERY_CAPABILITIES ((VdpFuncId)14) 4857 /** \hideinitializer */ 4858 #define VDP_FUNC_ID_OUTPUT_SURFACE_QUERY_GET_PUT_BITS_NATIVE_CAPABILITIES ((VdpFuncId)15) 4859 /** \hideinitializer */ 4860 #define VDP_FUNC_ID_OUTPUT_SURFACE_QUERY_PUT_BITS_INDEXED_CAPABILITIES ((VdpFuncId)16) 4861 /** \hideinitializer */ 4862 #define VDP_FUNC_ID_OUTPUT_SURFACE_QUERY_PUT_BITS_Y_CB_CR_CAPABILITIES ((VdpFuncId)17) 4863 /** \hideinitializer */ 4864 #define VDP_FUNC_ID_OUTPUT_SURFACE_CREATE ((VdpFuncId)18) 4865 /** \hideinitializer */ 4866 #define VDP_FUNC_ID_OUTPUT_SURFACE_DESTROY ((VdpFuncId)19) 4867 /** \hideinitializer */ 4868 #define VDP_FUNC_ID_OUTPUT_SURFACE_GET_PARAMETERS ((VdpFuncId)20) 4869 /** \hideinitializer */ 4870 #define VDP_FUNC_ID_OUTPUT_SURFACE_GET_BITS_NATIVE ((VdpFuncId)21) 4871 /** \hideinitializer */ 4872 #define VDP_FUNC_ID_OUTPUT_SURFACE_PUT_BITS_NATIVE ((VdpFuncId)22) 4873 /** \hideinitializer */ 4874 #define VDP_FUNC_ID_OUTPUT_SURFACE_PUT_BITS_INDEXED ((VdpFuncId)23) 4875 /** \hideinitializer */ 4876 #define VDP_FUNC_ID_OUTPUT_SURFACE_PUT_BITS_Y_CB_CR ((VdpFuncId)24) 4877 /** \hideinitializer */ 4878 #define VDP_FUNC_ID_BITMAP_SURFACE_QUERY_CAPABILITIES ((VdpFuncId)25) 4879 /** \hideinitializer */ 4880 #define VDP_FUNC_ID_BITMAP_SURFACE_CREATE ((VdpFuncId)26) 4881 /** \hideinitializer */ 4882 #define VDP_FUNC_ID_BITMAP_SURFACE_DESTROY ((VdpFuncId)27) 4883 /** \hideinitializer */ 4884 #define VDP_FUNC_ID_BITMAP_SURFACE_GET_PARAMETERS ((VdpFuncId)28) 4885 /** \hideinitializer */ 4886 #define VDP_FUNC_ID_BITMAP_SURFACE_PUT_BITS_NATIVE ((VdpFuncId)29) 4887 /** \hideinitializer */ 4888 #define VDP_FUNC_ID_OUTPUT_SURFACE_RENDER_OUTPUT_SURFACE ((VdpFuncId)33) 4889 /** \hideinitializer */ 4890 #define VDP_FUNC_ID_OUTPUT_SURFACE_RENDER_BITMAP_SURFACE ((VdpFuncId)34) 4891 /** \hideinitializer */ 4892 #define VDP_FUNC_ID_OUTPUT_SURFACE_RENDER_VIDEO_SURFACE_LUMA ((VdpFuncId)35) 4893 /** \hideinitializer */ 4894 #define VDP_FUNC_ID_DECODER_QUERY_CAPABILITIES ((VdpFuncId)36) 4895 /** \hideinitializer */ 4896 #define VDP_FUNC_ID_DECODER_CREATE ((VdpFuncId)37) 4897 /** \hideinitializer */ 4898 #define VDP_FUNC_ID_DECODER_DESTROY ((VdpFuncId)38) 4899 /** \hideinitializer */ 4900 #define VDP_FUNC_ID_DECODER_GET_PARAMETERS ((VdpFuncId)39) 4901 /** \hideinitializer */ 4902 #define VDP_FUNC_ID_DECODER_RENDER ((VdpFuncId)40) 4903 /** \hideinitializer */ 4904 #define VDP_FUNC_ID_VIDEO_MIXER_QUERY_FEATURE_SUPPORT ((VdpFuncId)41) 4905 /** \hideinitializer */ 4906 #define VDP_FUNC_ID_VIDEO_MIXER_QUERY_PARAMETER_SUPPORT ((VdpFuncId)42) 4907 /** \hideinitializer */ 4908 #define VDP_FUNC_ID_VIDEO_MIXER_QUERY_ATTRIBUTE_SUPPORT ((VdpFuncId)43) 4909 /** \hideinitializer */ 4910 #define VDP_FUNC_ID_VIDEO_MIXER_QUERY_PARAMETER_VALUE_RANGE ((VdpFuncId)44) 4911 /** \hideinitializer */ 4912 #define VDP_FUNC_ID_VIDEO_MIXER_QUERY_ATTRIBUTE_VALUE_RANGE ((VdpFuncId)45) 4913 /** \hideinitializer */ 4914 #define VDP_FUNC_ID_VIDEO_MIXER_CREATE ((VdpFuncId)46) 4915 /** \hideinitializer */ 4916 #define VDP_FUNC_ID_VIDEO_MIXER_SET_FEATURE_ENABLES ((VdpFuncId)47) 4917 /** \hideinitializer */ 4918 #define VDP_FUNC_ID_VIDEO_MIXER_SET_ATTRIBUTE_VALUES ((VdpFuncId)48) 4919 /** \hideinitializer */ 4920 #define VDP_FUNC_ID_VIDEO_MIXER_GET_FEATURE_SUPPORT ((VdpFuncId)49) 4921 /** \hideinitializer */ 4922 #define VDP_FUNC_ID_VIDEO_MIXER_GET_FEATURE_ENABLES ((VdpFuncId)50) 4923 /** \hideinitializer */ 4924 #define VDP_FUNC_ID_VIDEO_MIXER_GET_PARAMETER_VALUES ((VdpFuncId)51) 4925 /** \hideinitializer */ 4926 #define VDP_FUNC_ID_VIDEO_MIXER_GET_ATTRIBUTE_VALUES ((VdpFuncId)52) 4927 /** \hideinitializer */ 4928 #define VDP_FUNC_ID_VIDEO_MIXER_DESTROY ((VdpFuncId)53) 4929 /** \hideinitializer */ 4930 #define VDP_FUNC_ID_VIDEO_MIXER_RENDER ((VdpFuncId)54) 4931 /** \hideinitializer */ 4932 #define VDP_FUNC_ID_PRESENTATION_QUEUE_TARGET_DESTROY ((VdpFuncId)55) 4933 /** \hideinitializer */ 4934 #define VDP_FUNC_ID_PRESENTATION_QUEUE_CREATE ((VdpFuncId)56) 4935 /** \hideinitializer */ 4936 #define VDP_FUNC_ID_PRESENTATION_QUEUE_DESTROY ((VdpFuncId)57) 4937 /** \hideinitializer */ 4938 #define VDP_FUNC_ID_PRESENTATION_QUEUE_SET_BACKGROUND_COLOR ((VdpFuncId)58) 4939 /** \hideinitializer */ 4940 #define VDP_FUNC_ID_PRESENTATION_QUEUE_GET_BACKGROUND_COLOR ((VdpFuncId)59) 4941 /** \hideinitializer */ 4942 #define VDP_FUNC_ID_PRESENTATION_QUEUE_GET_TIME ((VdpFuncId)62) 4943 /** \hideinitializer */ 4944 #define VDP_FUNC_ID_PRESENTATION_QUEUE_DISPLAY ((VdpFuncId)63) 4945 /** \hideinitializer */ 4946 #define VDP_FUNC_ID_PRESENTATION_QUEUE_BLOCK_UNTIL_SURFACE_IDLE ((VdpFuncId)64) 4947 /** \hideinitializer */ 4948 #define VDP_FUNC_ID_PRESENTATION_QUEUE_QUERY_SURFACE_STATUS ((VdpFuncId)65) 4949 /** \hideinitializer */ 4950 #define VDP_FUNC_ID_PREEMPTION_CALLBACK_REGISTER ((VdpFuncId)66) 4951 /** \hideinitializer */ 4952 #define VDP_FUNC_ID_DECODER_QUERY_CAPABILITY ((VdpFuncId)67) 4953 4954 #define VDP_FUNC_ID_BASE_WINSYS 0x1000 4955 4956 /** 4957 * \brief Retrieve a VDPAU function pointer. 4958 * \param[in] device The device that the function will operate 4959 * against. 4960 * \param[in] function_id The specific function to retrieve. 4961 * \param[out] function_pointer The actual pointer for the 4962 * application to call. 4963 * \return VdpStatus The completion status of the operation. 4964 */ 4965 typedef VdpStatus VdpGetProcAddress( 4966 VdpDevice device, 4967 VdpFuncId function_id, 4968 /* output parameters follow */ 4969 void * * function_pointer 4970 ); 4971 4972 /** @} */ 4973 /** @} */ 4974 4975 /** 4976 * \defgroup api_winsys Window System Integration Layer 4977 * 4978 * The set of VDPAU functionality specific to an individual 4979 * Windowing System. 4980 */ 4981 4982 #ifdef __cplusplus 4983 } 4984 #endif 4985 4986 #endif 4987 4988