os/graphics/graphicscomposition/openwfcompositionengine/composition/include/wfccontext.h
author sl
Tue, 10 Jun 2014 14:32:02 +0200
changeset 1 260cb5ec6c19
permissions -rw-r--r--
Update contrib.
sl@0
     1
/* Copyright (c) 2009 The Khronos Group Inc.
sl@0
     2
 * Portions copyright (c) 2009-2010  Nokia Corporation and/or its subsidiary(-ies)
sl@0
     3
 *
sl@0
     4
 * Permission is hereby granted, free of charge, to any person obtaining a
sl@0
     5
 * copy of this software and/or associated documentation files (the
sl@0
     6
 * "Materials"), to deal in the Materials without restriction, including
sl@0
     7
 * without limitation the rights to use, copy, modify, merge, publish,
sl@0
     8
 * distribute, sublicense, and/or sell copies of the Materials, and to
sl@0
     9
 * permit persons to whom the Materials are furnished to do so, subject to
sl@0
    10
 * the following conditions:
sl@0
    11
 *
sl@0
    12
 * The above copyright notice and this permission notice shall be included
sl@0
    13
 * in all copies or substantial portions of the Materials.
sl@0
    14
 *
sl@0
    15
 * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
sl@0
    16
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
sl@0
    17
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
sl@0
    18
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
sl@0
    19
 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
sl@0
    20
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
sl@0
    21
 * MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
sl@0
    22
 */
sl@0
    23
sl@0
    24
/*! \ingroup wfc
sl@0
    25
 *  \file wfccontext.h
sl@0
    26
 *
sl@0
    27
 *  \brief Context handling interface
sl@0
    28
 */
sl@0
    29
#ifndef WFCCONTEXT_H_
sl@0
    30
#define WFCCONTEXT_H_
sl@0
    31
sl@0
    32
#include "WF/wfc.h"
sl@0
    33
#include "wfcstructs.h"
sl@0
    34
#include "wfcdevice.h"
sl@0
    35
#include "owfscreen.h"
sl@0
    36
sl@0
    37
#ifdef __cplusplus
sl@0
    38
extern "C"
sl@0
    39
{
sl@0
    40
#endif
sl@0
    41
sl@0
    42
#define MAX_SOURCE_WIDTH        OWF_SURFACE_WIDTH
sl@0
    43
#define MAX_SOURCE_HEIGHT       OWF_SURFACE_HEIGHT
sl@0
    44
/*!
sl@0
    45
Initialize context attributes
sl@0
    46
\return ATTR_ERROR_NONE if attributes have been properly initialised.
sl@0
    47
*/
sl@0
    48
OWF_API_CALL OWF_ATTRIBUTE_LIST_STATUS
sl@0
    49
WFC_Context_InitializeAttributes(WFC_CONTEXT* context,
sl@0
    50
                                 WFCContextType type);
sl@0
    51
sl@0
    52
/*!
sl@0
    53
 *  \brief Create new context on device
sl@0
    54
 *
sl@0
    55
 *  \param device Device on which the context should be created
sl@0
    56
 *  \param type Context type (on- or off-screen)
sl@0
    57
 *
sl@0
    58
 *  \return New context object or NULL in case of failure
sl@0
    59
*/
sl@0
    60
OWF_API_CALL WFC_CONTEXT*
sl@0
    61
WFC_Context_Create(WFC_DEVICE* device,
sl@0
    62
                   WFCNativeStreamType stream,
sl@0
    63
                   WFCContextType type,
sl@0
    64
                   WFCint screenNum);
sl@0
    65
/*!
sl@0
    66
 * \brief Releases the resources associated with the context.  
sl@0
    67
 * Some of these resources hold reference-counts on the context,
sl@0
    68
 * so this must be called BEFORE the main attempt to destroy the context.
sl@0
    69
 * 
sl@0
    70
 *  \param type Context type (on- or off-screen)
sl@0
    71
 */
sl@0
    72
OWF_API_CALL void
sl@0
    73
WFC_Context_Shutdown(WFC_CONTEXT* context);
sl@0
    74
sl@0
    75
/*!
sl@0
    76
 *  \brief Setup context rendering target
sl@0
    77
 *
sl@0
    78
 *  \param context Context
sl@0
    79
 *  \param stream Target stream to use for rendering
sl@0
    80
 */
sl@0
    81
OWF_API_CALL void
sl@0
    82
WFC_Context_SetTargetStream(WFC_CONTEXT* context,
sl@0
    83
                            OWFNativeStreamType stream);
sl@0
    84
sl@0
    85
/*!
sl@0
    86
 * \brief Checks if the given stream would be valid as an off-screen context target.
sl@0
    87
 * Checks that the format can be rendered TO.
sl@0
    88
 * Also checks that the image size is acceptable (within the scratch buffers).
sl@0
    89
 * This is called before the context is created so is effectively a "static" context method.
sl@0
    90
 * 
sl@0
    91
 *  \param stream Target stream to use for rendering
sl@0
    92
 */
sl@0
    93
OWF_API_CALL WFCboolean
sl@0
    94
WFC_Context_IsValidTargetStream(OWFNativeStreamType stream);
sl@0
    95
/*!
sl@0
    96
 * \brief Checks that the image size is acceptable (within the scratch buffers).
sl@0
    97
 * This is called before the source is created.
sl@0
    98
 * 
sl@0
    99
 *  \param stream source stream to use for rendering.
sl@0
   100
 */
sl@0
   101
OWF_API_CALL WFCboolean
sl@0
   102
WFC_Context_IsValidSourceStream(OWFNativeStreamType stream);
sl@0
   103
/*!
sl@0
   104
 * \brief Destroy all masks in context
sl@0
   105
 *
sl@0
   106
 * \param context Context
sl@0
   107
 */
sl@0
   108
OWF_API_CALL void
sl@0
   109
WFC_Context_DestroyMasks(WFC_CONTEXT* context);
sl@0
   110
sl@0
   111
/*!
sl@0
   112
 * \brief Destroy all context sources
sl@0
   113
 */
sl@0
   114
OWF_API_CALL void
sl@0
   115
WFC_Context_DestroySources(WFC_CONTEXT* context);
sl@0
   116
sl@0
   117
/*!
sl@0
   118
 *  \brief Destroy all context elements
sl@0
   119
 *
sl@0
   120
 *  \param context Context object
sl@0
   121
 */
sl@0
   122
OWF_API_CALL void
sl@0
   123
WFC_Context_DestroyElements(WFC_CONTEXT* context);
sl@0
   124
sl@0
   125
/*!
sl@0
   126
 *  \brief Find element from current scene
sl@0
   127
 *
sl@0
   128
 *  \param context Context object
sl@0
   129
 *  \param element Element to find
sl@0
   130
 *
sl@0
   131
 *  \return Element object or NULL if element hasn't been inserted
sl@0
   132
 *  into current scene.
sl@0
   133
 */
sl@0
   134
OWF_API_CALL WFC_ELEMENT*
sl@0
   135
WFC_Context_FindElement(WFC_CONTEXT* context,
sl@0
   136
                        WFCElement element);
sl@0
   137
sl@0
   138
/*!
sl@0
   139
 *  \brief Activate/deactivate auto-composition on context
sl@0
   140
 *
sl@0
   141
 *  \param context Context
sl@0
   142
 *  \param act Auto-composition enable/disable
sl@0
   143
 */
sl@0
   144
OWF_API_CALL void
sl@0
   145
WFC_Context_Activate(WFC_CONTEXT* context,
sl@0
   146
                     WFCboolean act);
sl@0
   147
sl@0
   148
/*!
sl@0
   149
 *  \brief Insert composition request to command stream
sl@0
   150
 *
sl@0
   151
 *  \param device
sl@0
   152
 *  \param context
sl@0
   153
 *  \param wait WFD_TRUE if executed synchronously
sl@0
   154
 */
sl@0
   155
OWF_API_CALL WFCboolean
sl@0
   156
WFC_Context_InvokeComposition(WFC_DEVICE* device,
sl@0
   157
                              WFC_CONTEXT* context,
sl@0
   158
                              WFCboolean wait);
sl@0
   159
sl@0
   160
/*!
sl@0
   161
 *
sl@0
   162
 *  \brief Insert commit request to command stream
sl@0
   163
 *
sl@0
   164
 *  \param device
sl@0
   165
 *  \param context
sl@0
   166
 *  \param wait WFD_TRUE if executed synchronously
sl@0
   167
 */
sl@0
   168
OWF_API_CALL WFCErrorCode
sl@0
   169
WFC_Context_InvokeCommit(WFC_DEVICE* device,
sl@0
   170
                         WFC_CONTEXT* context,
sl@0
   171
                         WFCboolean wait);
sl@0
   172
sl@0
   173
/*!
sl@0
   174
 *  \brief Insert fence token to context's command stream
sl@0
   175
 *
sl@0
   176
 *  \param dpy
sl@0
   177
 *  \param context
sl@0
   178
 *  \param sync
sl@0
   179
 */
sl@0
   180
OWF_API_CALL void
sl@0
   181
WFC_Context_InsertFence(WFC_CONTEXT* context,
sl@0
   182
                        WFCEGLDisplay dpy,
sl@0
   183
                        WFCEGLSync sync);
sl@0
   184
sl@0
   185
/*!
sl@0
   186
 *  \brief Create element
sl@0
   187
 *
sl@0
   188
 *  \param context
sl@0
   189
 */
sl@0
   190
OWF_API_CALL WFC_ELEMENT*
sl@0
   191
WFC_Context_CreateElement(WFC_CONTEXT* context);
sl@0
   192
sl@0
   193
/*! \brief Destroy element
sl@0
   194
 *  \param context
sl@0
   195
 *  \param element
sl@0
   196
 */
sl@0
   197
OWF_API_CALL WFCErrorCode
sl@0
   198
WFC_Context_DestroyElement(WFC_CONTEXT* context, WFCElement element);
sl@0
   199
sl@0
   200
/*!
sl@0
   201
 *  \brief IncreaseClientElementCount
sl@0
   202
 *
sl@0
   203
 *  \param context
sl@0
   204
 *  \return positive increased current element count; negative or zero indicating the count can't be increased
sl@0
   205
 */
sl@0
   206
OWF_API_CALL WFCint
sl@0
   207
WFC_Context_IncreaseClientElementCount(WFC_CONTEXT* context);
sl@0
   208
sl@0
   209
/*!
sl@0
   210
 *  \brief DecreaseClientElementCount
sl@0
   211
 *
sl@0
   212
 *  \param context
sl@0
   213
 *  \return positive or zero decreased current element count; negative indicating the count can't be decreased - p0robably already zero
sl@0
   214
 */
sl@0
   215
OWF_API_CALL WFCint
sl@0
   216
WFC_Context_DecreaseClientElementCount(WFC_CONTEXT* context);
sl@0
   217
sl@0
   218
/*!
sl@0
   219
 *  \brief Insert element into context's scene
sl@0
   220
 *
sl@0
   221
 *  \param context
sl@0
   222
 *  \param element
sl@0
   223
 *  \param subordinate
sl@0
   224
 *
sl@0
   225
 *  \return WFCErrorCode
sl@0
   226
 */
sl@0
   227
OWF_API_CALL WFCErrorCode
sl@0
   228
WFC_Context_InsertElement(WFC_CONTEXT* context,
sl@0
   229
                          WFCElement element,
sl@0
   230
                          WFCElement subordinate);
sl@0
   231
sl@0
   232
/*!
sl@0
   233
 *  \brief Remove element from context's scene
sl@0
   234
 *
sl@0
   235
 *  \param context
sl@0
   236
 *  \param element
sl@0
   237
 *
sl@0
   238
 *  \return WFCErrorCode
sl@0
   239
 */
sl@0
   240
OWF_API_CALL WFCErrorCode
sl@0
   241
WFC_Context_RemoveElement(WFC_CONTEXT* context,
sl@0
   242
                          WFCElement element);
sl@0
   243
sl@0
   244
/*!
sl@0
   245
 *  \brief Fetch the handle of the element that is above the given element.
sl@0
   246
 *
sl@0
   247
 *  \param context
sl@0
   248
 *  \param element
sl@0
   249
 *
sl@0
   250
 *  \return Error code. On return, the location pointed by result
sl@0
   251
 *  will contain handle of the element above OR WFC_INVALID_HANDLE,
sl@0
   252
 *  if no element is above given element.
sl@0
   253
 */
sl@0
   254
OWF_API_CALL WFCErrorCode
sl@0
   255
WFC_Context_GetElementAbove(WFC_CONTEXT* context,
sl@0
   256
                            WFCElement element,
sl@0
   257
                            WFCElement* result);
sl@0
   258
sl@0
   259
/*!
sl@0
   260
 *  \brief Fetch the handle of the element that is below the given element.
sl@0
   261
 *
sl@0
   262
 *  \param context
sl@0
   263
 *  \param element
sl@0
   264
 *
sl@0
   265
 *  \return Error code. On return, the location pointed by result
sl@0
   266
 *  will contain handle of the element below OR WFC_INVALID_HANDLE,
sl@0
   267
 *  if no element is below given element.
sl@0
   268
 */
sl@0
   269
OWF_API_CALL WFCErrorCode
sl@0
   270
WFC_Context_GetElementBelow(WFC_CONTEXT* context,
sl@0
   271
                            WFCElement element,
sl@0
   272
                            WFCElement* result);
sl@0
   273
sl@0
   274
/*!
sl@0
   275
 *  \brief Get context attribute value
sl@0
   276
 *
sl@0
   277
 *  \param context
sl@0
   278
 *  \param attrib
sl@0
   279
 *  \param value
sl@0
   280
 *
sl@0
   281
 *  \return WFCErrorCode
sl@0
   282
 */
sl@0
   283
OWF_API_CALL WFCErrorCode
sl@0
   284
WFC_Context_GetAttribi(WFC_CONTEXT* context,
sl@0
   285
                       WFCContextAttrib attrib,
sl@0
   286
                       WFCint* value);
sl@0
   287
sl@0
   288
/*!
sl@0
   289
 *  \brief Set context attribute value
sl@0
   290
 *
sl@0
   291
 *  \param context
sl@0
   292
 *  \param attrib
sl@0
   293
 *  \param value
sl@0
   294
 *
sl@0
   295
 *  \return WFCErrorCode
sl@0
   296
 */
sl@0
   297
OWF_API_CALL WFCErrorCode
sl@0
   298
WFC_Context_SetAttribi(WFC_CONTEXT* context,
sl@0
   299
                       WFCContextAttrib attrib,
sl@0
   300
                       WFCint value);
sl@0
   301
sl@0
   302
/*!
sl@0
   303
 *  \brief Get context attribute value
sl@0
   304
 *
sl@0
   305
 *  \param context
sl@0
   306
 *  \param attrib
sl@0
   307
 *  \param value
sl@0
   308
 *
sl@0
   309
 *  \return WFCErrorCode
sl@0
   310
 */
sl@0
   311
OWF_API_CALL WFCErrorCode
sl@0
   312
WFC_Context_GetAttribfv(WFC_CONTEXT* context,
sl@0
   313
                        WFCContextAttrib attrib,
sl@0
   314
                        WFCint count,
sl@0
   315
                        WFCfloat* values);
sl@0
   316
sl@0
   317
/*!
sl@0
   318
 *  \brief Set context attribute value
sl@0
   319
 *
sl@0
   320
 *  \param context
sl@0
   321
 *  \param attrib
sl@0
   322
 *  \param value
sl@0
   323
 *
sl@0
   324
 *  \return WFCErrorCode
sl@0
   325
 */
sl@0
   326
OWF_API_CALL WFCErrorCode
sl@0
   327
WFC_Context_SetAttribfv(WFC_CONTEXT* context,
sl@0
   328
                        WFCContextAttrib attrib,
sl@0
   329
                        WFCint count,
sl@0
   330
                        const WFCfloat* values);
sl@0
   331
sl@0
   332
sl@0
   333
/*!
sl@0
   334
 *  \brief Check if context is currently activated
sl@0
   335
 *
sl@0
   336
 *  \param context
sl@0
   337
 */
sl@0
   338
sl@0
   339
OWF_API_CALL WFCboolean
sl@0
   340
WFC_Context_Active(WFC_CONTEXT* context);
sl@0
   341
sl@0
   342
#ifdef __cplusplus
sl@0
   343
}
sl@0
   344
#endif
sl@0
   345
sl@0
   346
#endif /*WFCCONTEXT_H_*/