os/graphics/graphicscomposition/openwfcompositionengine/adaptation/include/owfnativestream.h
changeset 0 bde4ae8d615e
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/os/graphics/graphicscomposition/openwfcompositionengine/adaptation/include/owfnativestream.h	Fri Jun 15 03:10:57 2012 +0200
     1.3 @@ -0,0 +1,256 @@
     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 +#ifndef OWFNATIVESTREAM_H_
    1.28 +#define OWFNATIVESTREAM_H_
    1.29 +
    1.30 +/*!
    1.31 + * \brief Image stream implementation for Linux.
    1.32 + *
    1.33 + * WF native stream is an abstraction of image stream or
    1.34 + * a content pipe that can be used to deliver image data from
    1.35 + * place to another. A stream has a producer (source) and a consumer
    1.36 + * (sink) as its users.
    1.37 + *
    1.38 + * Streams operate on buffers, whose count is fixed at creation
    1.39 + * time (minimum is 1, but for non-blocking behavior values
    1.40 + * greater than 1 should be used.) Streams are meant to be used
    1.41 + * strictly on "point-to-point" basis, i.e. there should be only
    1.42 + * one producer and one consumer for each stream.
    1.43 + *
    1.44 + */
    1.45 +
    1.46 +#include "owfsemaphore.h"
    1.47 +#include "owflinkedlist.h"
    1.48 +#include "owfimage.h"
    1.49 +#include "owftypes.h"
    1.50 +
    1.51 +#include <EGL/egl.h>
    1.52 +#include <WF/wfcplatform.h>
    1.53 +
    1.54 +#ifdef __cplusplus
    1.55 +extern "C" {
    1.56 +#endif
    1.57 +
    1.58 +typedef enum
    1.59 +{
    1.60 +    OWF_STREAM_ERROR_NONE               = 0,
    1.61 +    OWF_STREAM_ERROR_INVALID_STREAM     = -1,
    1.62 +    OWF_STREAM_ERROR_INVALID_OBSERVER   = -2,
    1.63 +    OWF_STREAM_ERROR_OUT_OF_MEMORY      = -3
    1.64 +} OWF_STREAM_ERROR;
    1.65 +
    1.66 +typedef WFCHandle           WFCNativeStreamType;
    1.67 +/*!---------------------------------------------------------------------------
    1.68 + * Converts from external WFC native stream handle type to internal OWF native stream handle type.
    1.69 + * The internal handle MUST be persistant. The external handle may already be persistant.
    1.70 + * This method may fail, either due to memory, or due to the stream object not being supported by the compositor
    1.71 + * @post if successful, internal stream object is returned with increased reference (@see owfNativeStreamDestroy) 
    1.72 + * @param publicStream The publicly defined stream handle
    1.73 + * @param error			Pointer to store error code - optionally can be NULL
    1.74 + * @return OWFNativeStreamType an equivalent internal stream handle
    1.75 + *----------------------------------------------------------------------------**/
    1.76 + OWF_PUBLIC OWFNativeStreamType 
    1.77 +owfNativeStreamFromWFC(WFCNativeStreamType publicStream,OWF_STREAM_ERROR* errorReturn);
    1.78 +
    1.79 +/*!---------------------------------------------------------------------------
    1.80 + *  Create new off-screen image stream.
    1.81 + *
    1.82 + *  \param width            Stream image buffer width
    1.83 + *  \param height           Stream image buffer height
    1.84 + *  \param imageFormat      Stream image buffer format
    1.85 + *  \param nbufs            Number of image buffers to allocate
    1.86 + *
    1.87 + *  \param Handle to newly created stream or OWF_INVALID_HANDLe if no
    1.88 + *  stream could be created.
    1.89 + *----------------------------------------------------------------------------*/
    1.90 + OWF_PUBLIC OWFNativeStreamType
    1.91 +owfNativeStreamCreateImageStream(OWFint width,
    1.92 +                                 OWFint height,
    1.93 +                                 const OWF_IMAGE_FORMAT* format,
    1.94 +                                 OWFint nbufs);
    1.95 +
    1.96 +/*!---------------------------------------------------------------------------
    1.97 + *  Increase stream's reference count
    1.98 + *
    1.99 + *  \param stream           Stream handle
   1.100 + *----------------------------------------------------------------------------*/
   1.101 + OWF_API_CALL void
   1.102 +owfNativeStreamAddReference(OWFNativeStreamType stream);
   1.103 +
   1.104 +/*!---------------------------------------------------------------------------
   1.105 + *  Decrease stream's reference count
   1.106 + *
   1.107 + *  \param stream           Stream handle
   1.108 + *----------------------------------------------------------------------------*/
   1.109 + OWF_API_CALL void
   1.110 +owfNativeStreamRemoveReference(OWFNativeStreamType stream);
   1.111 +
   1.112 +/*!----------------------------------------------------------------------------
   1.113 + *  Destroy stream. The stream isn't necessarily immediately destroyed, but
   1.114 + *  only when it's reference count reaches zero.
   1.115 + *
   1.116 + *  \param stream           Stream handle
   1.117 + *----------------------------------------------------------------------------*/
   1.118 + OWF_PUBLIC void
   1.119 +owfNativeStreamDestroy(OWFNativeStreamType stream);
   1.120 +
   1.121 +
   1.122 +/*!---------------------------------------------------------------------------
   1.123 + * Get stream's image header
   1.124 + *
   1.125 + * \param stream            Stream handle
   1.126 + * \param width             Stream width
   1.127 + * \param height            Stream height
   1.128 + * \param stride            Stream stride
   1.129 + * \param format            Stream format
   1.130 + * \param pixelSize         Stream pixelSize
   1.131 + *
   1.132 + * All the parameters above, except stream handle, are pointers to locations
   1.133 + * where the particular value should be written to. Passing in a NULL
   1.134 + * pointer means that the particular values is of no interest to the caller.
   1.135 + *
   1.136 + * E.g. to query only width & height one would call this function with
   1.137 + * parameters (stream_handle, &width, &height, NULL, NULL, NULL);
   1.138 + *
   1.139 + *----------------------------------------------------------------------------*/
   1.140 + OWF_PUBLIC void
   1.141 +owfNativeStreamGetHeader(OWFNativeStreamType stream,
   1.142 +                           OWFint* width,
   1.143 +                           OWFint* height,
   1.144 +                           OWFint* stride,
   1.145 +                           OWF_IMAGE_FORMAT* format,
   1.146 +                           OWFint* pixelSize);
   1.147 +
   1.148 +/*!---------------------------------------------------------------------------
   1.149 + *  Acquire read buffer from stream
   1.150 + *
   1.151 + *  \param stream           Stream handle
   1.152 + *
   1.153 + *  \return Handle to next readable (unread since last write)
   1.154 + *  buffer from the stream or OWF_INVALID_HANDLE if no unread buffers
   1.155 + *  are available.
   1.156 + *----------------------------------------------------------------------------*/
   1.157 + OWF_PUBLIC OWFNativeStreamBuffer
   1.158 +owfNativeStreamAcquireReadBuffer(OWFNativeStreamType stream);
   1.159 +
   1.160 +/*!---------------------------------------------------------------------------
   1.161 + *  Release read buffer.
   1.162 + *
   1.163 + *  \param stream           Stream handle
   1.164 + *  \param buf              Buffer handle
   1.165 + *----------------------------------------------------------------------------*/
   1.166 + OWF_PUBLIC void
   1.167 +owfNativeStreamReleaseReadBuffer(OWFNativeStreamType stream,
   1.168 +                                 OWFNativeStreamBuffer buf);
   1.169 +
   1.170 +/*!---------------------------------------------------------------------------
   1.171 + *  Acquires writable buffer from a stream. The caller has exclusive access
   1.172 + *  to returned buffer until the buffer is commited to stream by
   1.173 + *  calling ReleaseWriteBuffer.
   1.174 + *
   1.175 + *  \param stream           Stream handle
   1.176 + *
   1.177 + *  \return Handle to next writable buffer or OWF_INVALID_HANDLE if no such
   1.178 + *  buffer is available.
   1.179 + *----------------------------------------------------------------------------*/
   1.180 + OWF_PUBLIC OWFNativeStreamBuffer
   1.181 +owfNativeStreamAcquireWriteBuffer(OWFNativeStreamType stream);
   1.182 +
   1.183 +/*!---------------------------------------------------------------------------
   1.184 + *  \brief Commit write buffer to stream.
   1.185 + *
   1.186 + * If sync object is specified, the handle to sync object is
   1.187 + * associated with the buffer. The sync object is signalled
   1.188 + * when the image/buffer has been either:
   1.189 + * - composed into the target stream
   1.190 + * - dropped (ignored) due to it being superceded by a newer
   1.191 + *   image/buffer before the compositor had a chance to read it
   1.192 + *
   1.193 + * Sync object is signalled exactly once. The caller is responsible
   1.194 + * of destroying the object.
   1.195 + *
   1.196 + *  \param stream           Stream handle
   1.197 + *  \param buf              Buffer handle
   1.198 + *  \param dpy              Optional EGLDisplay
   1.199 + *  \param sync             Optional EGLSync object which is signaled when
   1.200 + *                          the buffer is consumed or dropped.
   1.201 + *----------------------------------------------------------------------------*/
   1.202 + OWF_PUBLIC void
   1.203 +owfNativeStreamReleaseWriteBuffer(OWFNativeStreamType stream,
   1.204 +                                  OWFNativeStreamBuffer buf,
   1.205 +                                  EGLDisplay dpy,
   1.206 +                                  EGLSyncKHR sync);
   1.207 +
   1.208 +
   1.209 +/*!---------------------------------------------------------------------------
   1.210 + *  Enable/disable stream content notifications.
   1.211 + *
   1.212 + *  \param stream           Stream handle
   1.213 + *  \param send             Boolean value indicating whether the stream should
   1.214 + *                          send content notifications to its observers.
   1.215 + *----------------------------------------------------------------------------*/
   1.216 + OWF_API_CALL void
   1.217 +owfNativeStreamEnableUpdateNotifications(OWFNativeStreamType stream,
   1.218 +                                         OWFboolean send);
   1.219 +
   1.220 +
   1.221 +/*!---------------------------------------------------------------------------
   1.222 + *  Return pointer to stream buffer's pixel data. The buffer must be
   1.223 + *  a valid read/write buffer.
   1.224 + *
   1.225 + *  \param stream           Stream handle
   1.226 + *  \param buffer           Buffer handle
   1.227 + *
   1.228 + *  \return Pointer to buffers pixel data.
   1.229 + *----------------------------------------------------------------------------*/
   1.230 + OWF_PUBLIC void*
   1.231 +owfNativeStreamGetBufferPtr(OWFNativeStreamType stream,
   1.232 +                            OWFNativeStreamBuffer buffer);
   1.233 +
   1.234 +/*!---------------------------------------------------------------------------
   1.235 + *  Set/reset stream's protection flag. This flag is used for preventing the
   1.236 + *  user from deleting a stream that s/he doesn't really own or should
   1.237 + *  not twiddle with too much (on-screen context's target stream, for example)
   1.238 + *
   1.239 + *  \param stream           Stream handle
   1.240 + *  \param flag             Protection status
   1.241 + *----------------------------------------------------------------------------*/
   1.242 + OWF_API_CALL void
   1.243 +owfNativeStreamSetProtectionFlag(OWFNativeStreamType stream,
   1.244 +                                 OWFboolean flag);
   1.245 + /*!---------------------------------------------------------------------------
   1.246 +  *  Sets (internal) target stream flip state
   1.247 +  *
   1.248 +  *  \param stream           Stream handle
   1.249 +  *
   1.250 +  *----------------------------------------------------------------------------*/
   1.251 + OWF_API_CALL void
   1.252 +owfSetStreamFlipState(OWFNativeStreamType stream, OWFboolean flip);
   1.253 + 
   1.254 +
   1.255 +#ifdef __cplusplus
   1.256 +}
   1.257 +#endif
   1.258 +
   1.259 +#endif