doc/vdpau_x11.h

   1 /*
   2  * This source file is documented using Doxygen markup.
   3  * See http://www.stack.nl/~dimitri/doxygen/
   4  */
   5
   6 /*
   7  * This copyright notice applies to this header file:
   8  *
   9  * Copyright (c) 2008 NVIDIA Corporation
  10  *
  11  * Permission is hereby granted, free of charge, to any person
  12  * obtaining a copy of this software and associated documentation
  13  * files (the "Software"), to deal in the Software without
  14  * restriction, including without limitation the rights to use,
  15  * copy, modify, merge, publish, distribute, sublicense, and/or sell
  16  * copies of the Software, and to permit persons to whom the
  17  * Software is furnished to do so, subject to the following
  18  * conditions:
  19  *
  20  * The above copyright notice and this permission notice shall be
  21  * included in all copies or substantial portions of the Software.
  22  *
  23  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  24  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  25  * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  26  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  27  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  28  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  29  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  30  * OTHER DEALINGS IN THE SOFTWARE.
  31  */
  32
  33 /**
  34  * \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
  48 extern "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 the
  76  *   standard system (possibly X11-specific) library path.
  77  *   - \c libvdpau_\%s.so
  78  *   For example:
  79  *   - \c libvdpau_nvidia.so
  80  *   - \c libvdpau_intel.so
  81  *   - \c libvdpau_ati.so
  82  *
  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.
  91  *
  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.
  95  *
  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.
 106  *
 107  * @{
 108  */
 109
 110 /**
 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
 115  *       against.
 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.
 120  */
 121 typedef VdpStatus VdpDeviceCreateX11(
 122     Display *             display,
 123     int                   screen,
 124     /* output parameters follow */
 125     VdpDevice *           device,
 126     VdpGetProcAddress * * get_proc_address
 127 );
 128
 129 /**
 130  * \brief Create a VdpDevice object for use with X11.
 131  * This is an actual symbol of type \ref VdpDeviceCreateX11
 132  *
 133  */
 134 VdpDeviceCreateX11 vdp_device_create_x11;
 135
 136 /**
 137  * \brief Create a VdpPresentationQueueTarget for use with X11.
 138  * \param[in] device The device that will contain the queue
 139  *       target.
 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.
 144  *
 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.
 151  *
 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.
 155  */
 156 typedef VdpStatus VdpPresentationQueueTargetCreateX11(
 157     VdpDevice                   device,
 158     Drawable                    drawable,
 159     /* output parameters follow */
 160     VdpPresentationQueueTarget * target
 161 );
 162
 163 /** \hideinitializer */
 164 #define VDP_FUNC_ID_PRESENTATION_QUEUE_TARGET_CREATE_X11 (VdpFuncId)(VDP_FUNC_ID_BASE_WINSYS + 0)
 165
 166 /*@}*/
 167 /*@}*/
 168
 169 #ifdef __cplusplus
 170 }
 171 #endif
 172
 173 #endif
 174