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-2009 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 * \file vdpau_x11.h
35 * \brief X11 Window System Integration Layer
36 *
37 * This file contains the \ref api_winsys_x11 X11 Window System
38 * Integration Layer.
39 */
40
41#ifndef _VDPAU_X11_H
42#define _VDPAU_X11_H
43
44#include <X11/Xlib.h>
45#include "vdpau.h"
46
47#ifdef __cplusplus
48extern "C" {
49#endif
50
51/**
52 * \ingroup api_winsys
53 * @{
54 */
55
56/**
57 * \defgroup api_winsys_x11 X11 Window System Integration Layer
58 *
59 * The set of VDPAU functionality specific to usage with the X
60 * Window System.
61 *
62 * \section Driver Library Layout
63 *
64 * An X11-oriented VDPAU installation consists of the following
65 * components:
66 *
67 * - Header files. These files are located in the standard
68 *   system header file path.
69 *   - \c vdpau/vdpau.h
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 a
76 *   system-defined library path, which is configurable at compile
77 *   time but is typically /usr/lib/vdpau.  Use `pkg-config
78 *   --variable=moduledir vdpau` to locate the driver install path.
79 *   - \c $moduledir/libvdpau_\%s.so.1
80 *   For example:
81 *   - \c /usr/lib/vdpau/libvdpau_nvidia.so.1
82 *   - \c /usr/lib/vdpau/libvdpau_intel.so.1
83 *   - \c /usr/lib/vdpau/libvdpau_ati.so.1
84 *   The library path can be overridden by the VDPAU_DRIVER_PATH
85 *   environment variable.
86 *
87 * The VDPAU wrapper library implements just one function; \ref
88 * vdp_device_create_x11. The wrapper implements this function by
89 * dynamically loading the appropriate back-end driver file mentioned
90 * above. When available, the wrapper uses the DRI2 extension's
91 * DRI2Connect request with the driver type 'DRI2DriverVDPAU' to
92 * determine which back-end driver to load. If that fails, the wrapper
93 * library hard-codes the driver name as "nvidia", although this can
94 * be overridden using the environment variable VDPAU_DRIVER.
95 *
96 * The back-end driver is expected to implement a function named
97 * \b vdp_imp_device_create_x11. The wrapper will call this function to
98 * actually implement the \ref vdp_device_create_x11 application call.
99 *
100 * Note that it is theoretically possible for an application to
101 * create multiple \ref VdpDevice "VdpDevice" objects. In this
102 * case, the wrapper library may load multiple back-end drivers
103 * into the same application, and/or invoke a specific back-end
104 * driver's \b VdpImpDeviceCreateX11 multiple times. The wrapper
105 * library imposes no policy regarding whether the application
106 * may instantiate multiple \ref VdpDevice "VdpDevice" objects for
107 * the same display and/or screen. However, back-end drivers are
108 * free to limit the number of \ref VdpDevice "VdpDevice" objects
109 * as required by their implementation.
110 *
111 * @{
112 */
113
114/**
115 * \brief Create a VdpDevice object for use with X11.
116 * \param[in] display The X Display that the VdpDevice VdpDevice
117 *       will operate against.
118 * \param[in] screen The X screen that the VdpDevice will operate
119 *       against.
120 * \param[out] device The new device's handle.
121 * \param[out] get_proc_address The get_proc_address entry point
122 *       to use with this device.
123 * \return VdpStatus The completion status of the operation.
124 */
125typedef VdpStatus VdpDeviceCreateX11(
126    Display *             display,
127    int                   screen,
128    /* output parameters follow */
129    VdpDevice *           device,
130    VdpGetProcAddress * * get_proc_address
131);
132
133/**
134 * \brief Create a VdpDevice object for use with X11.
135 * This is an actual symbol of type \ref VdpDeviceCreateX11
136 *
137 */
138VdpDeviceCreateX11 vdp_device_create_x11;
139
140/**
141 * \brief Create a VdpPresentationQueueTarget for use with X11.
142 * \param[in] device The device that will contain the queue
143 *       target.
144 * \param[in] drawable The X11 Drawable that the presentation
145 *       queue will present into.
146 * \param[out] target The new queue target's handle.
147 * \return VdpStatus The completion status of the operation.
148 *
149 * Note: VDPAU expects to own the entire drawable for the duration of time
150 * that the presentation queue target exists. In particular,
151 * implementations may choose to manipulate client-visible X11 window state
152 * as required. As such, it is recommended that applications create a
153 * dedicated window for the presentation queue target, as a child
154 * (grand-child, ...) of their top-level application window.
155 *
156 * Applications may also create child-windows of the presentation queue
157 * target, which will cover any presented video in the normal fashion. VDPAU
158 * implementations will not manipulate such child windows in any fashion.
159 */
160typedef VdpStatus VdpPresentationQueueTargetCreateX11(
161    VdpDevice                   device,
162    Drawable                    drawable,
163    /* output parameters follow */
164    VdpPresentationQueueTarget * target
165);
166
167/** \hideinitializer */
168#define VDP_FUNC_ID_PRESENTATION_QUEUE_TARGET_CREATE_X11 (VdpFuncId)(VDP_FUNC_ID_BASE_WINSYS + 0)
169
170/*@}*/
171/*@}*/
172
173#ifdef __cplusplus
174}
175#endif
176
177#endif
178
179