/* Copyright (c) 2009 The Khronos Group Inc.
 * Portions copyright (c) 2009-2010  Nokia Corporation and/or its subsidiary(-ies)
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and/or associated documentation files (the
 * "Materials"), to deal in the Materials without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sublicense, and/or sell copies of the Materials, and to
 * permit persons to whom the Materials are furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Materials.
 *
 * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 * MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
 */

/*! \ingroup wfc
 *  \file wfccontext.h
 *
 *  \brief Context handling interface
 */
#ifndef WFCCONTEXT_H_
#define WFCCONTEXT_H_

#include "WF/wfc.h"
#include "wfcstructs.h"
#include "wfcdevice.h"
#include "owfscreen.h"

#ifdef __cplusplus
extern "C"
{
#endif

#define MAX_SOURCE_WIDTH        OWF_SURFACE_WIDTH
#define MAX_SOURCE_HEIGHT       OWF_SURFACE_HEIGHT
/*!
Initialize context attributes
\return ATTR_ERROR_NONE if attributes have been properly initialised.
*/
OWF_API_CALL OWF_ATTRIBUTE_LIST_STATUS
WFC_Context_InitializeAttributes(WFC_CONTEXT* context,
                                 WFCContextType type);

/*!
 *  \brief Create new context on device
 *
 *  \param device Device on which the context should be created
 *  \param type Context type (on- or off-screen)
 *
 *  \return New context object or NULL in case of failure
*/
OWF_API_CALL WFC_CONTEXT*
WFC_Context_Create(WFC_DEVICE* device,
                   WFCNativeStreamType stream,
                   WFCContextType type,
                   WFCint screenNum);
/*!
 * \brief Releases the resources associated with the context.  
 * Some of these resources hold reference-counts on the context,
 * so this must be called BEFORE the main attempt to destroy the context.
 * 
 *  \param type Context type (on- or off-screen)
 */
OWF_API_CALL void
WFC_Context_Shutdown(WFC_CONTEXT* context);

/*!
 *  \brief Setup context rendering target
 *
 *  \param context Context
 *  \param stream Target stream to use for rendering
 */
OWF_API_CALL void
WFC_Context_SetTargetStream(WFC_CONTEXT* context,
                            OWFNativeStreamType stream);

/*!
 * \brief Checks if the given stream would be valid as an off-screen context target.
 * Checks that the format can be rendered TO.
 * Also checks that the image size is acceptable (within the scratch buffers).
 * This is called before the context is created so is effectively a "static" context method.
 * 
 *  \param stream Target stream to use for rendering
 */
OWF_API_CALL WFCboolean
WFC_Context_IsValidTargetStream(OWFNativeStreamType stream);
/*!
 * \brief Checks that the image size is acceptable (within the scratch buffers).
 * This is called before the source is created.
 * 
 *  \param stream source stream to use for rendering.
 */
OWF_API_CALL WFCboolean
WFC_Context_IsValidSourceStream(OWFNativeStreamType stream);
/*!
 * \brief Destroy all masks in context
 *
 * \param context Context
 */
OWF_API_CALL void
WFC_Context_DestroyMasks(WFC_CONTEXT* context);

/*!
 * \brief Destroy all context sources
 */
OWF_API_CALL void
WFC_Context_DestroySources(WFC_CONTEXT* context);

/*!
 *  \brief Destroy all context elements
 *
 *  \param context Context object
 */
OWF_API_CALL void
WFC_Context_DestroyElements(WFC_CONTEXT* context);

/*!
 *  \brief Find element from current scene
 *
 *  \param context Context object
 *  \param element Element to find
 *
 *  \return Element object or NULL if element hasn't been inserted
 *  into current scene.
 */
OWF_API_CALL WFC_ELEMENT*
WFC_Context_FindElement(WFC_CONTEXT* context,
                        WFCElement element);

/*!
 *  \brief Activate/deactivate auto-composition on context
 *
 *  \param context Context
 *  \param act Auto-composition enable/disable
 */
OWF_API_CALL void
WFC_Context_Activate(WFC_CONTEXT* context,
                     WFCboolean act);

/*!
 *  \brief Insert composition request to command stream
 *
 *  \param device
 *  \param context
 *  \param wait WFD_TRUE if executed synchronously
 */
OWF_API_CALL WFCboolean
WFC_Context_InvokeComposition(WFC_DEVICE* device,
                              WFC_CONTEXT* context,
                              WFCboolean wait);

/*!
 *
 *  \brief Insert commit request to command stream
 *
 *  \param device
 *  \param context
 *  \param wait WFD_TRUE if executed synchronously
 */
OWF_API_CALL WFCErrorCode
WFC_Context_InvokeCommit(WFC_DEVICE* device,
                         WFC_CONTEXT* context,
                         WFCboolean wait);

/*!
 *  \brief Insert fence token to context's command stream
 *
 *  \param dpy
 *  \param context
 *  \param sync
 */
OWF_API_CALL void
WFC_Context_InsertFence(WFC_CONTEXT* context,
                        WFCEGLDisplay dpy,
                        WFCEGLSync sync);

/*!
 *  \brief Create element
 *
 *  \param context
 */
OWF_API_CALL WFC_ELEMENT*
WFC_Context_CreateElement(WFC_CONTEXT* context);

/*! \brief Destroy element
 *  \param context
 *  \param element
 */
OWF_API_CALL WFCErrorCode
WFC_Context_DestroyElement(WFC_CONTEXT* context, WFCElement element);

/*!
 *  \brief IncreaseClientElementCount
 *
 *  \param context
 *  \return positive increased current element count; negative or zero indicating the count can't be increased
 */
OWF_API_CALL WFCint
WFC_Context_IncreaseClientElementCount(WFC_CONTEXT* context);

/*!
 *  \brief DecreaseClientElementCount
 *
 *  \param context
 *  \return positive or zero decreased current element count; negative indicating the count can't be decreased - p0robably already zero
 */
OWF_API_CALL WFCint
WFC_Context_DecreaseClientElementCount(WFC_CONTEXT* context);

/*!
 *  \brief Insert element into context's scene
 *
 *  \param context
 *  \param element
 *  \param subordinate
 *
 *  \return WFCErrorCode
 */
OWF_API_CALL WFCErrorCode
WFC_Context_InsertElement(WFC_CONTEXT* context,
                          WFCElement element,
                          WFCElement subordinate);

/*!
 *  \brief Remove element from context's scene
 *
 *  \param context
 *  \param element
 *
 *  \return WFCErrorCode
 */
OWF_API_CALL WFCErrorCode
WFC_Context_RemoveElement(WFC_CONTEXT* context,
                          WFCElement element);

/*!
 *  \brief Fetch the handle of the element that is above the given element.
 *
 *  \param context
 *  \param element
 *
 *  \return Error code. On return, the location pointed by result
 *  will contain handle of the element above OR WFC_INVALID_HANDLE,
 *  if no element is above given element.
 */
OWF_API_CALL WFCErrorCode
WFC_Context_GetElementAbove(WFC_CONTEXT* context,
                            WFCElement element,
                            WFCElement* result);

/*!
 *  \brief Fetch the handle of the element that is below the given element.
 *
 *  \param context
 *  \param element
 *
 *  \return Error code. On return, the location pointed by result
 *  will contain handle of the element below OR WFC_INVALID_HANDLE,
 *  if no element is below given element.
 */
OWF_API_CALL WFCErrorCode
WFC_Context_GetElementBelow(WFC_CONTEXT* context,
                            WFCElement element,
                            WFCElement* result);

/*!
 *  \brief Get context attribute value
 *
 *  \param context
 *  \param attrib
 *  \param value
 *
 *  \return WFCErrorCode
 */
OWF_API_CALL WFCErrorCode
WFC_Context_GetAttribi(WFC_CONTEXT* context,
                       WFCContextAttrib attrib,
                       WFCint* value);

/*!
 *  \brief Set context attribute value
 *
 *  \param context
 *  \param attrib
 *  \param value
 *
 *  \return WFCErrorCode
 */
OWF_API_CALL WFCErrorCode
WFC_Context_SetAttribi(WFC_CONTEXT* context,
                       WFCContextAttrib attrib,
                       WFCint value);

/*!
 *  \brief Get context attribute value
 *
 *  \param context
 *  \param attrib
 *  \param value
 *
 *  \return WFCErrorCode
 */
OWF_API_CALL WFCErrorCode
WFC_Context_GetAttribfv(WFC_CONTEXT* context,
                        WFCContextAttrib attrib,
                        WFCint count,
                        WFCfloat* values);

/*!
 *  \brief Set context attribute value
 *
 *  \param context
 *  \param attrib
 *  \param value
 *
 *  \return WFCErrorCode
 */
OWF_API_CALL WFCErrorCode
WFC_Context_SetAttribfv(WFC_CONTEXT* context,
                        WFCContextAttrib attrib,
                        WFCint count,
                        const WFCfloat* values);


/*!
 *  \brief Check if context is currently activated
 *
 *  \param context
 */

OWF_API_CALL WFCboolean
WFC_Context_Active(WFC_CONTEXT* context);

#ifdef __cplusplus
}
#endif

#endif /*WFCCONTEXT_H_*/