1 /* Copyright (c) 2009 The Khronos Group Inc.

     2  *

     3  * Permission is hereby granted, free of charge, to any person obtaining a

     4  * copy of this software and/or associated documentation files (the

     5  * "Materials"), to deal in the Materials without restriction, including

     6  * without limitation the rights to use, copy, modify, merge, publish,

     7  * distribute, sublicense, and/or sell copies of the Materials, and to

     8  * permit persons to whom the Materials are furnished to do so, subject to

     9  * the following conditions:

    10  *

    11  * The above copyright notice and this permission notice shall be included

    12  * in all copies or substantial portions of the Materials.

    13  *

    14  * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

    15  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

    16  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

    17  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY

    18  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,

    19  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE

    20  * MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.

    21  */

    22 /*! \ingroup wfc

    23  *  \file wfcdevice.h

    24  *

    25  *  \brief Device handling interface

    26  */

    27 #ifndef WFCDEVICE_H_

    28 #define WFCDEVICE_H_

    29 

    30 #include "WF/wfc.h"

    31 #include "wfcstructs.h"

    32 #include "wfcimageprovider.h"

    33 

    34 #ifdef __cplusplus

    35 extern "C" {

    36 #endif

    37 

    38 /*!

    39  *  Get list of available devices.

    40  *

    41  *  \param idList Pointer to list where device IDs should be written

    42  *  \param listCapacity Maximum number of IDs to write

    43  *  \param filterList User provided array

    44  *

    45  *  \return Number of IDs written.

    46  */

    47 OWF_API_CALL WFCint

    48 WFC_Devices_GetIds(WFCint* idList,

    49                    WFCint listCapacity,

    50                    const WFCint* filterList);

    51 

    52 /*!

    53  *  \brief Create instance of a device whose ID

    54  *  matches deviceId

    55  *

    56  *  \param deviceId ID of the device to create. Must be WFC_DEFAULT_DEVICE_ID

    57  *  or some other valid device ID (returned by Devices_GetIds)

    58  *

    59  *  \return Handle to created device or WFC_INVALID_HANDLE

    60  *

    61  */

    62 OWF_API_CALL WFCint

    63 WFC_Device_Create(WFCint deviceId);

    64 

    65 /*!

    66  *  \brief Destroy device, or rather queue it for destruction.

    67  *

    68  *  \param device Device

    69  */

    70 OWF_API_CALL void

    71 WFC_Device_Destroy(WFC_DEVICE* device);

    72 

    73 /*!

    74  *  \brief Set error code for device.

    75  *

    76  *  Obs! In case the previous

    77  *  error code hasn't been read from the device, this function

    78  *  does nothing; the new error is set only if "current" error

    79  *  is none.

    80  *

    81  *  \param dev Device object

    82  *  \param code Error to set

    83  *

    84  */

    85 OWF_API_CALL void OWF_APIENTRY

    86 WFC_Device_SetError(WFCDevice dev,

    87                     WFCErrorCode code);

    88 

    89 /*!

    90  *  \brief Read and reset last error code from device.

    91  *

    92  *  \param device Device object

    93  *

    94  *  \return WFCErrorCode

    95  */

    96 OWF_API_CALL WFCErrorCode

    97 WFC_Device_GetError(WFC_DEVICE* device);

    98 

    99 /*!

   100  *  \brief Find device object by handle

   101  *

   102  *  \param dev Device handle

   103  *

   104  *  \return Mathing device object or NULL

   105  */

   106 OWF_API_CALL WFC_DEVICE*

   107 WFC_Device_FindByHandle(WFCDevice dev);

   108 

   109 /*!

   110  *  \brief Get device attribute

   111  *

   112  *  \param device Device

   113  *  \param attrib Attribute name

   114  *  \param value Pointer to where the value should be saved

   115  *

   116  *  \return WFCErrorCode

   117  */

   118 OWF_API_CALL WFCErrorCode

   119 WFC_Device_GetAttribi(WFC_DEVICE* device,

   120                       WFCDeviceAttrib attrib,

   121                       WFCint* value);

   122 

   123 /*!

   124  *  \brief Create context on device

   125  *

   126  *  \param device Device

   127  *  \param stream Target stream for context

   128  *  \param type Context type

   129  *

   130  *  \return New context

   131  */

   132 OWF_API_CALL WFC_CONTEXT*

   133 WFC_Device_CreateContext(WFC_DEVICE* device,

   134                          OWFNativeStreamType stream,

   135                          WFCContextType type,

   136                          WFCint screenNum);

   137 

   138 /*!

   139  *  \brief Destroy context from device

   140  */

   141 OWF_API_CALL WFCErrorCode

   142 WFC_Device_DestroyContext(WFC_DEVICE* device,

   143                           WFCContext context);

   144 

   145 /*!

   146  *  \brief Destroy all device's contexts

   147  *

   148  *  \param device Device object

   149  */

   150 OWF_API_CALL void

   151 WFC_Device_DestroyContexts(WFC_DEVICE* device);

   152 

   153 /*!

   154  *  \brief Find context context object by handle

   155  *

   156  *  \param device Device

   157  *  \param context Context handle

   158  *

   159  *  \return Corresponding context object or NULL

   160  *  if handle is invalid.

   161  */

   162 OWF_API_CALL WFC_CONTEXT*

   163 WFC_Device_FindContext(WFC_DEVICE* device,

   164                        WFCContext context);

   165 

   166 /*!

   167  *  \brief Create new element

   168  *

   169  *  \param device

   170  *  \param context

   171  *

   172  *  \return New element or NULL

   173  */

   174 OWF_API_CALL WFC_ELEMENT*

   175 WFC_Device_CreateElement(WFC_DEVICE* device, WFC_CONTEXT* context);

   176 

   177 /*!

   178  *  \brief Destroy element

   179  *

   180  *  \param device

   181  *  \param element

   182  */

   183 OWF_API_CALL WFCErrorCode

   184 WFC_Device_DestroyElement(WFC_DEVICE* device,

   185                           WFCElement element);

   186 

   187 /*!

   188  *  \brief Destroy all elements from device

   189  *

   190  *  \param device Device

   191  */

   192 OWF_API_CALL void

   193 WFC_Device_DestroyElements(WFC_DEVICE* device);

   194 

   195 /*!

   196  *  \brief Find element by handle

   197  *

   198  *  \param device Device

   199  *  \param el Element handle

   200  *

   201  *  \return Element object

   202  */

   203 OWF_API_CALL WFC_ELEMENT*

   204 WFC_Device_FindElement(WFC_DEVICE* device,

   205                        WFCElement el);

   206 

   207 /*!

   208  *  \brief Set element integer vector attribute

   209  *

   210  *  \param device Device

   211  *  \param element Element handle

   212  *  \param attrib Attribute name

   213  *  \param count Attribute value vector length (1 for scalar attribute)

   214  *  \param values Pointer to values

   215  *

   216  *  \return WFCErrorCode: WFC_ERROR_BAD_ATTRIBUTE if attribute name is invalid;

   217  *  WFC_ERROR_INVALID_ARGUMENT if values is NULL or if the count doesn't match

   218  *  the attribute's size; WFC_ERROR_BAD_HANDLE if element handle is invalid.

   219  */

   220 OWF_API_CALL WFCErrorCode

   221 WFC_Device_SetElementAttribiv(WFC_DEVICE* device,

   222                               WFCElement element,

   223                               WFCElementAttrib attrib,

   224                               WFCint count,

   225                               const WFCint* values);

   226 

   227 /*!

   228  *  \brief Set element attribute

   229  */

   230 OWF_API_CALL WFCErrorCode

   231 WFC_Device_SetElementAttribfv(WFC_DEVICE* device,

   232                               WFCElement element,

   233                               WFCElementAttrib attrib,

   234                               WFCint count,

   235                               const WFCfloat* values);

   236 /*!

   237  *  \brief Get element attribute

   238  */

   239 OWF_API_CALL WFCErrorCode

   240 WFC_Device_GetElementAttribiv(WFC_DEVICE* device,

   241                               WFCElement element,

   242                               WFCElementAttrib attrib,

   243                               WFCint count,

   244                               WFCint* values);

   245 /*!

   246  *  \brief Get element attribute

   247  */

   248 OWF_API_CALL WFCErrorCode

   249 WFC_Device_GetElementAttribfv(WFC_DEVICE* device,

   250                               WFCElement element,

   251                               WFCElementAttrib attrib,

   252                               WFCint count,

   253                               WFCfloat* values);

   254 

   255 

   256 /*!

   257  *  \brief Destroy all image providers from device

   258  *

   259  *  \param device Device

   260  */

   261 OWF_API_CALL void

   262 WFC_Device_DestroyImageProviders(WFC_DEVICE* device);

   263 

   264 OWF_API_CALL WFC_IMAGE_PROVIDER*

   265 WFC_Device_FindImageProvider(WFC_DEVICE* device,

   266                              WFCHandle handle,

   267                              WFC_IMAGE_PROVIDER_TYPE type);

   268 

   269 OWF_API_CALL WFC_IMAGE_PROVIDER*

   270 WFC_Device_CreateSource(WFC_DEVICE* device,

   271                         WFC_CONTEXT* context,

   272                         WFCNativeStreamType stream);

   273 

   274 OWF_API_CALL WFC_IMAGE_PROVIDER*

   275 WFC_Device_CreateMask(WFC_DEVICE* device,

   276                       WFC_CONTEXT* context,

   277                       WFCNativeStreamType stream);

   278 

   279 OWF_API_CALL WFCErrorCode

   280 WFC_Device_DestroySource(WFC_DEVICE* device, WFCSource source);

   281 

   282 OWF_API_CALL WFCErrorCode

   283 WFC_Device_DestroyMask(WFC_DEVICE* device, WFCMask mask);

   284 

   285 OWF_API_CALL WFC_IMAGE_PROVIDER*

   286 WFC_Device_FindSource(WFC_DEVICE* device, WFCSource source);

   287 

   288 OWF_API_CALL WFC_IMAGE_PROVIDER*

   289 WFC_Device_FindMask(WFC_DEVICE* device, WFCMask mask);

   290 

   291 OWF_API_CALL void

   292 WFC_Device_EnableContentNotifications(WFC_DEVICE* device,

   293                                       WFC_CONTEXT* context,

   294                                       WFCboolean enable);

   295 

   296 OWF_API_CALL WFCboolean

   297 WFC_Device_StreamIsTarget(WFC_DEVICE* device,

   298                           WFCNativeStreamType stream);

   299 

   300 OWF_API_CALL WFC_CONTEXT*

   301 WFC_Device_FindContextByScreen(WFC_DEVICE* device,

   302                                WFCint screenNumber);

   303 

   304 OWF_API_CALL void

   305 WFC_Device_DestroyContextElements(WFC_DEVICE* device,

   306                                   WFC_CONTEXT* context);

   307 

   308 OWF_API_CALL void

   309 WFC_Device_DestroyContextImageProviders(WFC_DEVICE* device,

   310                                         WFC_CONTEXT* context);

   311 

   312 #ifdef __cplusplus

   313 }

   314 #endif

   315 

   316 #endif /*WFCDEVICE_H_*/