os/graphics/graphicscomposition/openwfcompositionengine/composition/include/wfcscene.h
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/graphics/graphicscomposition/openwfcompositionengine/composition/include/wfcscene.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,191 @@
1.4 +/* Copyright (c) 2009 The Khronos Group Inc.
1.5 + * Portions copyright (c) 2009-2010 Nokia Corporation and/or its subsidiary(-ies)
1.6 + *
1.7 + * Permission is hereby granted, free of charge, to any person obtaining a
1.8 + * copy of this software and/or associated documentation files (the
1.9 + * "Materials"), to deal in the Materials without restriction, including
1.10 + * without limitation the rights to use, copy, modify, merge, publish,
1.11 + * distribute, sublicense, and/or sell copies of the Materials, and to
1.12 + * permit persons to whom the Materials are furnished to do so, subject to
1.13 + * the following conditions:
1.14 + *
1.15 + * The above copyright notice and this permission notice shall be included
1.16 + * in all copies or substantial portions of the Materials.
1.17 + *
1.18 + * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
1.19 + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
1.20 + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
1.21 + * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
1.22 + * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
1.23 + * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
1.24 + * MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
1.25 + */
1.26 +
1.27 +/*! \ingroup wfc
1.28 + * \file wfcscene.h
1.29 + *
1.30 + * \brief Scene handling interface
1.31 + */
1.32 +
1.33 +#ifndef WFCSCENE_H_
1.34 +#define WFCSCENE_H_
1.35 +
1.36 +#include "WF/wfc.h"
1.37 +#include "wfcelement.h"
1.38 +
1.39 +#include "owfpool.h"
1.40 +#ifdef __cplusplus
1.41 +extern "C" {
1.42 +#endif
1.43 +
1.44 +/*!
1.45 + * \brief Clone a scene
1.46 + *
1.47 + * \param scene Pointer to scene to clone
1.48 + * \returns cloned scene
1.49 + */
1.50 +OWF_API_CALL WFC_SCENE*
1.51 +WFC_Scene_Clone(WFC_SCENE* scene);
1.52 +
1.53 +/*!
1.54 + * \brief Create new scene in a context
1.55 + *
1.56 + * \param context Context to create the scene in
1.57 + *
1.58 + * \return New scene object
1.59 + */
1.60 +OWF_API_CALL WFC_SCENE*
1.61 +WFC_Scene_Create(WFC_CONTEXT* context);
1.62 +
1.63 +/*!
1.64 + * \brief Destroy a scene.
1.65 + *
1.66 + * Free all resources used by the scene and return the
1.67 + * scene object into the scene pool
1.68 + *
1.69 + * \param scene Scene
1.70 + */
1.71 +
1.72 +OWF_API_CALL void
1.73 +WFC_Scene_Destroy(WFC_SCENE* scene);
1.74 +
1.75 +/*!
1.76 + * \brief Insert element to scene above given element
1.77 + *
1.78 + * \param scene Scene
1.79 + * \param element Element to add
1.80 + * \param elementBelow Element above which the new element should be
1.81 + * inserted.
1.82 + * \return WFCErrorCode
1.83 + */
1.84 +
1.85 +OWF_API_CALL WFCErrorCode
1.86 +WFC_Scene_InsertElement(WFC_SCENE* scene,
1.87 + WFC_ELEMENT* element,
1.88 + WFCElement elementBelow);
1.89 +
1.90 +/*!
1.91 + * \brief Remove element from scene
1.92 + *
1.93 + * \param scene Scene
1.94 + * \param element Element to remove
1.95 + *
1.96 + * \return WFCErrorCode
1.97 + */
1.98 +OWF_API_CALL void
1.99 +WFC_Scene_RemoveElement(WFC_SCENE* scene,
1.100 + WFCElement element);
1.101 +
1.102 +
1.103 +/*!
1.104 + * \brief Get element's neighbour element (i.e. element on top of it
1.105 + * or underneath it)
1.106 + *
1.107 + * \param scene Scene
1.108 + * \param element Element
1.109 + * \param n Neighbour element offset (< 0 for elements underneath,
1.110 + * > 0 for elements on top)
1.111 + *
1.112 + * \return Neigbour element id or WFC_INVALID_HANDLE
1.113 + */
1.114 +OWF_API_CALL WFCElement
1.115 +WFC_Scene_GetNeighbourElement(WFC_SCENE* scene, WFCElement element, WFCint n);
1.116 +
1.117 +/*!
1.118 + * \brief Search the scene for given element.
1.119 + *
1.120 + * \param scene Scene to search
1.121 + * \param element Handle of the element to find
1.122 + *
1.123 + */
1.124 +OWF_API_CALL WFC_ELEMENT*
1.125 +WFC_Scene_FindElement(WFC_SCENE* scene,
1.126 + WFCElement element);
1.127 +/*!
1.128 + * \brief Unlock scene sources & masks.
1.129 + *
1.130 + * \param scene Scene
1.131 + */
1.132 +OWF_API_CALL void
1.133 +WFC_Scene_UnlockSourcesAndMasks(WFC_SCENE* scene);
1.134 +
1.135 +/*!
1.136 + * \brief Lock all sources' & masks' streams for reading prior to rendering.
1.137 +
1.138 + * Locking is actually just acquiring the read buffer for each source/mask
1.139 + * stream.
1.140 + *
1.141 + * All source read buffers must be acquired before the composition starts
1.142 + * because if multiple elements share same source, they all should get same
1.143 + * frame from that source.
1.144 + *
1.145 + * If each source buffer were locked/unlocked multiple times during
1.146 + * composition (i.e. once for each element that uses it), the buffer
1.147 + * contents might change between elements thus yielding wrong visual results.
1.148 + *
1.149 + * \param scene Scene
1.150 + */
1.151 +OWF_API_CALL void
1.152 +WFC_Scene_LockSourcesAndMasks(WFC_SCENE* scene);
1.153 +
1.154 +/*!
1.155 + * \brief Check scene for conflicts
1.156 + *
1.157 + * \param scene Scene to check
1.158 + *
1.159 + * \return WFC_TRUE if there's a conflict (inconsistency) in the
1.160 + * scene graph, WFC_FALSE otherwise.
1.161 + */
1.162 +OWF_API_CALL WFCboolean
1.163 +WFC_Scene_HasConflicts(WFC_SCENE* scene);
1.164 +
1.165 +/*!
1.166 + * \brief Commit changes to scene
1.167 + *
1.168 + * \param scene Scene
1.169 + */
1.170 +OWF_API_CALL void
1.171 +WFC_Scene_Commit(WFC_SCENE* scene);
1.172 +
1.173 +/*!
1.174 + * Return handle of the lowest element in the scene.
1.175 + *
1.176 + * \param scene Scene
1.177 + * \return Handle of the bottom element
1.178 + */
1.179 +OWF_API_CALL WFCElement
1.180 +WFC_Scene_LowestElement(WFC_SCENE* scene);
1.181 +
1.182 +/*!
1.183 + * \brief Search for the topmost element
1.184 + *
1.185 + * \param scene Scene to search
1.186 + * \return pointer to the topmost element
1.187 + */
1.188 +OWF_API_CALL WFC_ELEMENT*
1.189 +WFC_Scene_TopMostElement(WFC_SCENE* scene);
1.190 +
1.191 +#ifdef __cplusplus
1.192 +}
1.193 +#endif
1.194 +#endif /* WFCSCENE_H_ */