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 

    23 /*! \ingroup wfc

    24  *  \file wfcscene.h

    25  *

    26  *  \brief Scene handling interface

    27  */

    28 

    29 #ifndef WFCSCENE_H_

    30 #define WFCSCENE_H_

    31 

    32 #include "WF/wfc.h"

    33 #include "wfcelement.h"

    34 

    35 #include "owfpool.h"

    36 #ifdef __cplusplus

    37 extern "C" {

    38 #endif

    39 

    40 /*!

    41  *  \brief Clone a scene

    42  *

    43  *  \param scene Pointer to scene to clone

    44  *  \returns cloned scene

    45  */

    46 OWF_API_CALL WFC_SCENE*

    47 WFC_Scene_Clone(WFC_SCENE* scene);

    48 

    49 /*!

    50  *  \brief Create new scene in a context

    51  *

    52  *  \param context          Context to create the scene in

    53  *

    54  *  \return New scene object

    55  */

    56 OWF_API_CALL WFC_SCENE*

    57 WFC_Scene_Create(WFC_CONTEXT* context);

    58 

    59 /*!

    60  *  \brief Destroy a scene.

    61  *

    62  *  Free all resources used by the scene and return the

    63  *  scene object into the scene pool

    64  *

    65  *  \param scene            Scene

    66  */

    67 

    68 OWF_API_CALL void

    69 WFC_Scene_Destroy(WFC_SCENE* scene);

    70 

    71 /*!

    72  *  \brief Insert element to scene above given element

    73  *

    74  *  \param scene            Scene

    75  *  \param element          Element to add

    76  *  \param elementBelow     Element above which the new element should be

    77  *                          inserted.

    78  *  \return WFCErrorCode

    79  */

    80 

    81 OWF_API_CALL WFCErrorCode

    82 WFC_Scene_InsertElement(WFC_SCENE* scene,

    83                         WFC_ELEMENT* element,

    84                         WFCElement elementBelow);

    85 

    86 /*!

    87  *  \brief Remove element from scene

    88  *

    89  *  \param scene            Scene

    90  *  \param element          Element to remove

    91  *

    92  *  \return WFCErrorCode

    93  */

    94 OWF_API_CALL void

    95 WFC_Scene_RemoveElement(WFC_SCENE* scene,

    96                         WFCElement element);

    97 

    98 

    99 /*!

   100  *  \brief Get element's neighbour element (i.e. element on top of it

   101  *  or underneath it)

   102  *

   103  *  \param scene Scene

   104  *  \param element Element

   105  *  \param n Neighbour element offset (< 0 for elements underneath,

   106  *  > 0 for elements on top)

   107  *

   108  *  \return Neigbour element id or WFC_INVALID_HANDLE

   109  */

   110 OWF_API_CALL WFCElement

   111 WFC_Scene_GetNeighbourElement(WFC_SCENE* scene, WFCElement element, WFCint n);

   112 

   113 /*!

   114  *  \brief Search the scene for given element.

   115  *

   116  *  \param scene            Scene to search

   117  *  \param element          Handle of the element to find

   118  *

   119  */

   120 OWF_API_CALL WFC_ELEMENT*

   121 WFC_Scene_FindElement(WFC_SCENE* scene,

   122                       WFCElement element);

   123 /*!

   124  *  \brief Unlock scene sources & masks.

   125  *

   126  *  \param scene            Scene

   127  */

   128 OWF_API_CALL void

   129 WFC_Scene_UnlockSourcesAndMasks(WFC_SCENE* scene);

   130 

   131 /*!

   132  *  \brief Lock all sources' & masks' streams for reading prior to rendering.

   133 

   134  *  Locking is actually just acquiring the read buffer for each source/mask

   135  *  stream.

   136  *

   137  *  All source read buffers must be acquired before the composition starts

   138  *  because if multiple elements share same source, they all should get same

   139  *  frame from that source.

   140  *

   141  *  If each source buffer were locked/unlocked multiple times during

   142  *  composition (i.e. once for each element that uses it), the buffer

   143  *  contents might change between elements thus yielding wrong visual results.

   144  *

   145  *  \param scene            Scene

   146  */

   147 OWF_API_CALL void

   148 WFC_Scene_LockSourcesAndMasks(WFC_SCENE* scene);

   149 

   150 /*!

   151  *  \brief Check scene for conflicts

   152  *

   153  *  \param scene            Scene to check

   154  *

   155  *  \return WFC_TRUE if there's a conflict (inconsistency) in the

   156  *  scene graph, WFC_FALSE otherwise.

   157  */

   158 OWF_API_CALL WFCboolean

   159 WFC_Scene_HasConflicts(WFC_SCENE* scene);

   160 

   161 /*!

   162  *  \brief Commit changes to scene

   163  *

   164  *  \param scene            Scene

   165  */

   166 OWF_API_CALL void

   167 WFC_Scene_Commit(WFC_SCENE* scene);

   168 

   169 /*!

   170  *  Return handle of the lowest element in the scene.

   171  *

   172  *  \param scene Scene

   173  *  \return Handle of the bottom element

   174  */

   175 OWF_API_CALL WFCElement

   176 WFC_Scene_LowestElement(WFC_SCENE* scene);

   177 

   178 #ifdef __cplusplus

   179 }

   180 #endif

   181 #endif /* WFCSCENE_H_ */