os/graphics/graphicscomposition/openwfcompositionengine/composition/include/wfcscene.h
author sl@SLION-WIN7.fritz.box
Fri, 15 Jun 2012 03:10:57 +0200
changeset 0 bde4ae8d615e
permissions -rw-r--r--
First public contribution.
     1 /* Copyright (c) 2009 The Khronos Group Inc.
     2  * Portions copyright (c) 2009-2010  Nokia Corporation and/or its subsidiary(-ies)
     3  *
     4  * Permission is hereby granted, free of charge, to any person obtaining a
     5  * copy of this software and/or associated documentation files (the
     6  * "Materials"), to deal in the Materials without restriction, including
     7  * without limitation the rights to use, copy, modify, merge, publish,
     8  * distribute, sublicense, and/or sell copies of the Materials, and to
     9  * permit persons to whom the Materials are furnished to do so, subject to
    10  * the following conditions:
    11  *
    12  * The above copyright notice and this permission notice shall be included
    13  * in all copies or substantial portions of the Materials.
    14  *
    15  * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    18  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    19  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    20  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    21  * MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
    22  */
    23 
    24 /*! \ingroup wfc
    25  *  \file wfcscene.h
    26  *
    27  *  \brief Scene handling interface
    28  */
    29 
    30 #ifndef WFCSCENE_H_
    31 #define WFCSCENE_H_
    32 
    33 #include "WF/wfc.h"
    34 #include "wfcelement.h"
    35 
    36 #include "owfpool.h"
    37 #ifdef __cplusplus
    38 extern "C" {
    39 #endif
    40 
    41 /*!
    42  *  \brief Clone a scene
    43  *
    44  *  \param scene Pointer to scene to clone
    45  *  \returns cloned scene
    46  */
    47 OWF_API_CALL WFC_SCENE*
    48 WFC_Scene_Clone(WFC_SCENE* scene);
    49 
    50 /*!
    51  *  \brief Create new scene in a context
    52  *
    53  *  \param context          Context to create the scene in
    54  *
    55  *  \return New scene object
    56  */
    57 OWF_API_CALL WFC_SCENE*
    58 WFC_Scene_Create(WFC_CONTEXT* context);
    59 
    60 /*!
    61  *  \brief Destroy a scene.
    62  *
    63  *  Free all resources used by the scene and return the
    64  *  scene object into the scene pool
    65  *
    66  *  \param scene            Scene
    67  */
    68 
    69 OWF_API_CALL void
    70 WFC_Scene_Destroy(WFC_SCENE* scene);
    71 
    72 /*!
    73  *  \brief Insert element to scene above given element
    74  *
    75  *  \param scene            Scene
    76  *  \param element          Element to add
    77  *  \param elementBelow     Element above which the new element should be
    78  *                          inserted.
    79  *  \return WFCErrorCode
    80  */
    81 
    82 OWF_API_CALL WFCErrorCode
    83 WFC_Scene_InsertElement(WFC_SCENE* scene,
    84                         WFC_ELEMENT* element,
    85                         WFCElement elementBelow);
    86 
    87 /*!
    88  *  \brief Remove element from scene
    89  *
    90  *  \param scene            Scene
    91  *  \param element          Element to remove
    92  *
    93  *  \return WFCErrorCode
    94  */
    95 OWF_API_CALL void
    96 WFC_Scene_RemoveElement(WFC_SCENE* scene,
    97                         WFCElement element);
    98 
    99 
   100 /*!
   101  *  \brief Get element's neighbour element (i.e. element on top of it
   102  *  or underneath it)
   103  *
   104  *  \param scene Scene
   105  *  \param element Element
   106  *  \param n Neighbour element offset (< 0 for elements underneath,
   107  *  > 0 for elements on top)
   108  *
   109  *  \return Neigbour element id or WFC_INVALID_HANDLE
   110  */
   111 OWF_API_CALL WFCElement
   112 WFC_Scene_GetNeighbourElement(WFC_SCENE* scene, WFCElement element, WFCint n);
   113 
   114 /*!
   115  *  \brief Search the scene for given element.
   116  *
   117  *  \param scene            Scene to search
   118  *  \param element          Handle of the element to find
   119  *
   120  */
   121 OWF_API_CALL WFC_ELEMENT*
   122 WFC_Scene_FindElement(WFC_SCENE* scene,
   123                       WFCElement element);
   124 /*!
   125  *  \brief Unlock scene sources & masks.
   126  *
   127  *  \param scene            Scene
   128  */
   129 OWF_API_CALL void
   130 WFC_Scene_UnlockSourcesAndMasks(WFC_SCENE* scene);
   131 
   132 /*!
   133  *  \brief Lock all sources' & masks' streams for reading prior to rendering.
   134 
   135  *  Locking is actually just acquiring the read buffer for each source/mask
   136  *  stream.
   137  *
   138  *  All source read buffers must be acquired before the composition starts
   139  *  because if multiple elements share same source, they all should get same
   140  *  frame from that source.
   141  *
   142  *  If each source buffer were locked/unlocked multiple times during
   143  *  composition (i.e. once for each element that uses it), the buffer
   144  *  contents might change between elements thus yielding wrong visual results.
   145  *
   146  *  \param scene            Scene
   147  */
   148 OWF_API_CALL void
   149 WFC_Scene_LockSourcesAndMasks(WFC_SCENE* scene);
   150 
   151 /*!
   152  *  \brief Check scene for conflicts
   153  *
   154  *  \param scene            Scene to check
   155  *
   156  *  \return WFC_TRUE if there's a conflict (inconsistency) in the
   157  *  scene graph, WFC_FALSE otherwise.
   158  */
   159 OWF_API_CALL WFCboolean
   160 WFC_Scene_HasConflicts(WFC_SCENE* scene);
   161 
   162 /*!
   163  *  \brief Commit changes to scene
   164  *
   165  *  \param scene            Scene
   166  */
   167 OWF_API_CALL void
   168 WFC_Scene_Commit(WFC_SCENE* scene);
   169 
   170 /*!
   171  *  Return handle of the lowest element in the scene.
   172  *
   173  *  \param scene Scene
   174  *  \return Handle of the bottom element
   175  */
   176 OWF_API_CALL WFCElement
   177 WFC_Scene_LowestElement(WFC_SCENE* scene);
   178 
   179 /*!
   180  *  \brief Search for the topmost element
   181  *
   182  *  \param scene            Scene to search
   183  *  \return pointer to the topmost element
   184  */
   185 OWF_API_CALL WFC_ELEMENT*
   186 WFC_Scene_TopMostElement(WFC_SCENE* scene);
   187 
   188 #ifdef __cplusplus
   189 }
   190 #endif
   191 #endif /* WFCSCENE_H_ */