os/graphics/graphicscomposition/openwfcompositionengine/adaptation/include/owfnativestream.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 #ifndef OWFNATIVESTREAM_H_
    25 #define OWFNATIVESTREAM_H_
    26 
    27 /*!
    28  * \brief Image stream implementation for Linux.
    29  *
    30  * WF native stream is an abstraction of image stream or
    31  * a content pipe that can be used to deliver image data from
    32  * place to another. A stream has a producer (source) and a consumer
    33  * (sink) as its users.
    34  *
    35  * Streams operate on buffers, whose count is fixed at creation
    36  * time (minimum is 1, but for non-blocking behavior values
    37  * greater than 1 should be used.) Streams are meant to be used
    38  * strictly on "point-to-point" basis, i.e. there should be only
    39  * one producer and one consumer for each stream.
    40  *
    41  */
    42 
    43 #include "owfsemaphore.h"
    44 #include "owflinkedlist.h"
    45 #include "owfimage.h"
    46 #include "owftypes.h"
    47 
    48 #include <EGL/egl.h>
    49 #include <WF/wfcplatform.h>
    50 
    51 #ifdef __cplusplus
    52 extern "C" {
    53 #endif
    54 
    55 typedef enum
    56 {
    57     OWF_STREAM_ERROR_NONE               = 0,
    58     OWF_STREAM_ERROR_INVALID_STREAM     = -1,
    59     OWF_STREAM_ERROR_INVALID_OBSERVER   = -2,
    60     OWF_STREAM_ERROR_OUT_OF_MEMORY      = -3
    61 } OWF_STREAM_ERROR;
    62 
    63 typedef WFCHandle           WFCNativeStreamType;
    64 /*!---------------------------------------------------------------------------
    65  * Converts from external WFC native stream handle type to internal OWF native stream handle type.
    66  * The internal handle MUST be persistant. The external handle may already be persistant.
    67  * This method may fail, either due to memory, or due to the stream object not being supported by the compositor
    68  * @post if successful, internal stream object is returned with increased reference (@see owfNativeStreamDestroy) 
    69  * @param publicStream The publicly defined stream handle
    70  * @param error			Pointer to store error code - optionally can be NULL
    71  * @return OWFNativeStreamType an equivalent internal stream handle
    72  *----------------------------------------------------------------------------**/
    73  OWF_PUBLIC OWFNativeStreamType 
    74 owfNativeStreamFromWFC(WFCNativeStreamType publicStream,OWF_STREAM_ERROR* errorReturn);
    75 
    76 /*!---------------------------------------------------------------------------
    77  *  Create new off-screen image stream.
    78  *
    79  *  \param width            Stream image buffer width
    80  *  \param height           Stream image buffer height
    81  *  \param imageFormat      Stream image buffer format
    82  *  \param nbufs            Number of image buffers to allocate
    83  *
    84  *  \param Handle to newly created stream or OWF_INVALID_HANDLe if no
    85  *  stream could be created.
    86  *----------------------------------------------------------------------------*/
    87  OWF_PUBLIC OWFNativeStreamType
    88 owfNativeStreamCreateImageStream(OWFint width,
    89                                  OWFint height,
    90                                  const OWF_IMAGE_FORMAT* format,
    91                                  OWFint nbufs);
    92 
    93 /*!---------------------------------------------------------------------------
    94  *  Increase stream's reference count
    95  *
    96  *  \param stream           Stream handle
    97  *----------------------------------------------------------------------------*/
    98  OWF_API_CALL void
    99 owfNativeStreamAddReference(OWFNativeStreamType stream);
   100 
   101 /*!---------------------------------------------------------------------------
   102  *  Decrease stream's reference count
   103  *
   104  *  \param stream           Stream handle
   105  *----------------------------------------------------------------------------*/
   106  OWF_API_CALL void
   107 owfNativeStreamRemoveReference(OWFNativeStreamType stream);
   108 
   109 /*!----------------------------------------------------------------------------
   110  *  Destroy stream. The stream isn't necessarily immediately destroyed, but
   111  *  only when it's reference count reaches zero.
   112  *
   113  *  \param stream           Stream handle
   114  *----------------------------------------------------------------------------*/
   115  OWF_PUBLIC void
   116 owfNativeStreamDestroy(OWFNativeStreamType stream);
   117 
   118 
   119 /*!---------------------------------------------------------------------------
   120  * Get stream's image header
   121  *
   122  * \param stream            Stream handle
   123  * \param width             Stream width
   124  * \param height            Stream height
   125  * \param stride            Stream stride
   126  * \param format            Stream format
   127  * \param pixelSize         Stream pixelSize
   128  *
   129  * All the parameters above, except stream handle, are pointers to locations
   130  * where the particular value should be written to. Passing in a NULL
   131  * pointer means that the particular values is of no interest to the caller.
   132  *
   133  * E.g. to query only width & height one would call this function with
   134  * parameters (stream_handle, &width, &height, NULL, NULL, NULL);
   135  *
   136  *----------------------------------------------------------------------------*/
   137  OWF_PUBLIC void
   138 owfNativeStreamGetHeader(OWFNativeStreamType stream,
   139                            OWFint* width,
   140                            OWFint* height,
   141                            OWFint* stride,
   142                            OWF_IMAGE_FORMAT* format,
   143                            OWFint* pixelSize);
   144 
   145 /*!---------------------------------------------------------------------------
   146  *  Acquire read buffer from stream
   147  *
   148  *  \param stream           Stream handle
   149  *
   150  *  \return Handle to next readable (unread since last write)
   151  *  buffer from the stream or OWF_INVALID_HANDLE if no unread buffers
   152  *  are available.
   153  *----------------------------------------------------------------------------*/
   154  OWF_PUBLIC OWFNativeStreamBuffer
   155 owfNativeStreamAcquireReadBuffer(OWFNativeStreamType stream);
   156 
   157 /*!---------------------------------------------------------------------------
   158  *  Release read buffer.
   159  *
   160  *  \param stream           Stream handle
   161  *  \param buf              Buffer handle
   162  *----------------------------------------------------------------------------*/
   163  OWF_PUBLIC void
   164 owfNativeStreamReleaseReadBuffer(OWFNativeStreamType stream,
   165                                  OWFNativeStreamBuffer buf);
   166 
   167 /*!---------------------------------------------------------------------------
   168  *  Acquires writable buffer from a stream. The caller has exclusive access
   169  *  to returned buffer until the buffer is commited to stream by
   170  *  calling ReleaseWriteBuffer.
   171  *
   172  *  \param stream           Stream handle
   173  *
   174  *  \return Handle to next writable buffer or OWF_INVALID_HANDLE if no such
   175  *  buffer is available.
   176  *----------------------------------------------------------------------------*/
   177  OWF_PUBLIC OWFNativeStreamBuffer
   178 owfNativeStreamAcquireWriteBuffer(OWFNativeStreamType stream);
   179 
   180 /*!---------------------------------------------------------------------------
   181  *  \brief Commit write buffer to stream.
   182  *
   183  * If sync object is specified, the handle to sync object is
   184  * associated with the buffer. The sync object is signalled
   185  * when the image/buffer has been either:
   186  * - composed into the target stream
   187  * - dropped (ignored) due to it being superceded by a newer
   188  *   image/buffer before the compositor had a chance to read it
   189  *
   190  * Sync object is signalled exactly once. The caller is responsible
   191  * of destroying the object.
   192  *
   193  *  \param stream           Stream handle
   194  *  \param buf              Buffer handle
   195  *  \param dpy              Optional EGLDisplay
   196  *  \param sync             Optional EGLSync object which is signaled when
   197  *                          the buffer is consumed or dropped.
   198  *----------------------------------------------------------------------------*/
   199  OWF_PUBLIC void
   200 owfNativeStreamReleaseWriteBuffer(OWFNativeStreamType stream,
   201                                   OWFNativeStreamBuffer buf,
   202                                   EGLDisplay dpy,
   203                                   EGLSyncKHR sync);
   204 
   205 
   206 /*!---------------------------------------------------------------------------
   207  *  Enable/disable stream content notifications.
   208  *
   209  *  \param stream           Stream handle
   210  *  \param send             Boolean value indicating whether the stream should
   211  *                          send content notifications to its observers.
   212  *----------------------------------------------------------------------------*/
   213  OWF_API_CALL void
   214 owfNativeStreamEnableUpdateNotifications(OWFNativeStreamType stream,
   215                                          OWFboolean send);
   216 
   217 
   218 /*!---------------------------------------------------------------------------
   219  *  Return pointer to stream buffer's pixel data. The buffer must be
   220  *  a valid read/write buffer.
   221  *
   222  *  \param stream           Stream handle
   223  *  \param buffer           Buffer handle
   224  *
   225  *  \return Pointer to buffers pixel data.
   226  *----------------------------------------------------------------------------*/
   227  OWF_PUBLIC void*
   228 owfNativeStreamGetBufferPtr(OWFNativeStreamType stream,
   229                             OWFNativeStreamBuffer buffer);
   230 
   231 /*!---------------------------------------------------------------------------
   232  *  Set/reset stream's protection flag. This flag is used for preventing the
   233  *  user from deleting a stream that s/he doesn't really own or should
   234  *  not twiddle with too much (on-screen context's target stream, for example)
   235  *
   236  *  \param stream           Stream handle
   237  *  \param flag             Protection status
   238  *----------------------------------------------------------------------------*/
   239  OWF_API_CALL void
   240 owfNativeStreamSetProtectionFlag(OWFNativeStreamType stream,
   241                                  OWFboolean flag);
   242  /*!---------------------------------------------------------------------------
   243   *  Sets (internal) target stream flip state
   244   *
   245   *  \param stream           Stream handle
   246   *
   247   *----------------------------------------------------------------------------*/
   248  OWF_API_CALL void
   249 owfSetStreamFlipState(OWFNativeStreamType stream, OWFboolean flip);
   250  
   251 
   252 #ifdef __cplusplus
   253 }
   254 #endif
   255 
   256 #endif