2 * This source file is documented using Doxygen markup.
3 * See http://www.stack.nl/~dimitri/doxygen/
7 * This copyright notice applies to this header file:
9 * Copyright (c) 2008 NVIDIA Corporation
11 * Permission is hereby granted, free of charge, to any person
12 * obtaining a copy of this software and associated documentation
13 * files (the "Software"), to deal in the Software without
14 * restriction, including without limitation the rights to use,
15 * copy, modify, merge, publish, distribute, sublicense, and/or sell
16 * copies of the Software, and to permit persons to whom the
17 * Software is furnished to do so, subject to the following
20 * The above copyright notice and this permission notice shall be
21 * included in all copies or substantial portions of the Software.
23 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
24 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
25 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
26 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
27 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
28 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
29 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
30 * OTHER DEALINGS IN THE SOFTWARE.
35 * \brief X11 Window System Integration Layer
37 * This file contains the \ref api_winsys_x11 "X11 Window System
57 * \defgroup api_winsys_x11 X11 Window System Integration Layer
59 * The set of VDPAU functionality specific to usage with the X
62 * \section Driver Library Layout
64 * An X11-oriented VDPAU installation consists of the following
67 * - Header files. These files are located in the standard
68 * system header file path.
70 * - \c vdpau/vdpau_x11.h
71 * - The VDPAU wrapper library. These files are located in the
72 * standard system (possibly X11-specific) library path.
73 * - \c libvdpau.so.1 (runtime)
74 * - \c libvdpau.so (development)
75 * - Back-end driver files. These files are located in the
76 * standard system (possibly X11-specific) library path.
77 * - \c libvdpau_\%s.so
79 * - \c libvdpau_nvidia.so
80 * - \c libvdpau_intel.so
81 * - \c libvdpau_ati.so
83 * The VDPAU wrapper library implements just one function; \ref
84 * vdp_device_create_x11. The wrapper will implement this function
85 * by dynamically loading the appropriate back-end driver file
86 * mentioned above. Long-term, the wrapper will use a
87 * VDPAU-specific X extension to determine which back-end driver
88 * to load. Currently, the wrapper library hard-codes the driver
89 * name as "nvidia", although this can be overridden using the
90 * environment variable VDPAU_DRIVER.
92 * The back-end driver is expected to implement a function named
93 * \b vdp_imp_device_create_x11. The wrapper will call this function to
94 * actually implement the \ref vdp_device_create_x11 application call.
96 * Note that it is theoretically possible for an application to
97 * create multiple \ref VdpDevice "VdpDevice" objects. In this
98 * case, the wrapper library may load multiple back-end drivers
99 * into the same application, and/or invoke a specific back-end
100 * driver's \b VdpImpDeviceCreateX11 multiple times. The wrapper
101 * libray imposes no policy regarding whether the application
102 * may instantiate multiple \ref VdpDevice "VdpDevice" objects for
103 * the same display and/or screen. However, back-end drivers are
104 * free to limit the number of \ref VdpDevice "VdpDevice" objects
105 * as required by their implementation.
111 * \brief Create a VdpDevice object for use with X11.
112 * \param[in] display The X Display that the VdpDevice VdpDevice
113 * will operate against.
114 * \param[in] screen The X screen that the VdpDevice will operate
116 * \param[out] device The new device's handle.
117 * \param[out] get_proc_address The get_proc_address entry point
118 * to use with this device.
119 * \return VdpStatus The completion status of the operation.
121 typedef VdpStatus VdpDeviceCreateX11(
124 /* output parameters follow */
126 VdpGetProcAddress * * get_proc_address
130 * \brief Create a VdpDevice object for use with X11.
131 * This is an actual symbol of type \ref VdpDeviceCreateX11
134 VdpDeviceCreateX11 vdp_device_create_x11;
137 * \brief Create a VdpPresentationQueueTarget for use with X11.
138 * \param[in] device The device that will contain the queue
140 * \param[in] drawable The X11 Drawable that the presentation
141 * queue will present into.
142 * \param[out] target The new queue target's handle.
143 * \return VdpStatus The completion status of the operation.
145 * Note: VDPAU expects to own the entire drawable for the duration of time
146 * that the presentation queue target exists. In particular,
147 * implementations may choose to manipulate client-visible X11 window state
148 * as required. As such, it is recommended that applications create a
149 * dedicated window for the presentation queue target, as a child
150 * (grand-child, ...) of their top-level application window.
152 * Applications may also create child-windows of the presentation queue
153 * target, which will cover any presented video in the normal fashion. VDPAU
154 * implementations will not manipulate such child windows in any fashion.
156 typedef VdpStatus VdpPresentationQueueTargetCreateX11(
159 /* output parameters follow */
160 VdpPresentationQueueTarget * target
163 /** \hideinitializer */
164 #define VDP_FUNC_ID_PRESENTATION_QUEUE_TARGET_CREATE_X11 (VdpFuncId)(VDP_FUNC_ID_BASE_WINSYS + 0)