os/graphics/graphicscomposition/openwfsupport/inc/symbianstream.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 Nokia Corporation and/or its subsidiary(-ies).
     2 // All rights reserved.
     3 // This component and the accompanying materials are made available
     4 // under the terms of "Eclipse Public License v1.0"
     5 // which accompanies this distribution, and is available
     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
     7 //
     8 // Initial Contributors:
     9 // Nokia Corporation - initial contribution.
    10 //
    11 // Contributors:
    12 //
    13 // Description:
    14 // symbianstream.h
    15 // C API for surface stream implementation of OpenWF-C NativeStream
    16 //
    17 
    18 #ifndef __SYMBIANSTREAM_H__
    19 #define __SYMBIANSTREAM_H__
    20 
    21 
    22 #ifdef __cplusplus
    23 class TSurfaceId;
    24 class RSurfaceManager;
    25 #else
    26 typedef struct struct_TSurfaceId TSurfaceId;
    27 #endif
    28 #include <KHR/khrplatform.h>
    29 typedef khronos_int32_t khronos_bool;
    30 typedef khronos_int32_t TErrCode;
    31 
    32 /*!
    33  * \brief Image stream implementation
    34  *
    35  * WF native stream is an abstraction of image stream or
    36  * a content pipe that can be used to deliver image data from
    37  * place to another. A stream has a producer (source) and a consumer
    38  * (sink) as its users.
    39  *
    40  * Streams operate on buffers, whose count is fixed at creation
    41  * time (minimum is 1, but for non-blocking behavior values
    42  * greater than 1 should be used.) Streams are meant to be used
    43  * strictly on "point-to-point" basis, i.e. there should be only
    44  * one producer and one consumer for each stream.
    45  *
    46  */
    47 #	ifdef __cplusplus
    48 extern "C" {
    49 #	endif
    50 
    51 #define KInitialContextSerialNumber 0
    52 #define KNoAssociatedScreenNumber (-1)
    53 
    54 typedef const TSurfaceId*	SymbianStreamType;
    55 
    56 typedef
    57     enum type_SymbianStreamEventBits   {       //note reservations are internal and reorderable
    58     ESOWF_NoEvent                       = 0x00000000, // no event field: used to invalidate an observer
    59                                                         // entry in the observer container
    60     ESOWF_EventComposed                 = 0x00000001, // identifies the callback called when tha internal a stream is updated
    61     
    62     ESOWF_EventUpdated                  = 0x00000010, // identifies the content update
    63                                                         //callback used to trigger a new composition
    64     ESOWF_SIEventsMask                  = ESOWF_EventComposed | ESOWF_EventUpdated,
    65 
    66     // the following events identify the SUS events
    67     ESOWF_EventAvailable                = 0x00000100, // SUS notification
    68     ESOWF_EventDisplayed                = 0x00000200, // SUS notification
    69     ESOWF_EventDisplayedX               = 0x00000400, // SUS notification
    70     ESOWF_SUSEventsMask                 = ESOWF_EventDisplayed | ESOWF_EventAvailable | ESOWF_EventDisplayedX,
    71 
    72     ESOWF_AllEventsMask                 = (ESOWF_SIEventsMask | ESOWF_SUSEventsMask),
    73 
    74     // the following fields are additional operations, extending the observer behaviour
    75     ESOWF_ObserverReturnDefaultEvent    = 0x00010000,
    76     ESOWF_ObserverProcessing            = 0x00020000,
    77     ESOWF_ObserverCheckVisible          = 0x00040000,
    78     ESOWF_ObserverCancel                = 0x00080000,
    79 
    80     // reserved for future extensions
    81     ESOWF_RESERVED_MASK                 = 0xff000000
    82     } SymbianStreamEventBits;
    83 
    84 typedef khronos_int32_t SymOwfNativeStreamBuffer;
    85 
    86 #define SYMBIAN_INVALID_HANDLE  0
    87 
    88 typedef khronos_int32_t	MultipleSymbianStreamEventBits;
    89 typedef khronos_int32_t	SymNativeStreamEvent;
    90 typedef khronos_int32_t SymbianStreamBuffer;
    91 typedef khronos_int32_t	SymOwfPixelFormat;
    92 typedef	khronos_int32_t SymOwfBool;
    93 
    94 typedef enum
    95 {
    96     SOWF_STREAM_ERROR_NONE               = 0,
    97     SOWF_STREAM_ERROR_INVALID_STREAM     = -1,
    98     SOWF_STREAM_ERROR_INVALID_OBSERVER   = -2,
    99     SOWF_STREAM_ERROR_OUT_OF_MEMORY      = -3
   100 } SOWF_STREAM_ERROR;
   101 
   102 /*! Native stream callback function type */
   103 typedef void (*SymOwfStreamCallback)(SymbianStreamType, SymNativeStreamEvent, void*);
   104 /*! Native stream callback function type */
   105 typedef void (*SymbianStreamCallback)(SymbianStreamType, MultipleSymbianStreamEventBits, void*, void*);
   106 
   107 typedef struct{
   108     TInt32      length;
   109     TInt32      id;
   110     TInt32      par;
   111     TInt32      serialNumber;
   112     TInt32      immediateAvailable;
   113     TInt32      immediateVisibility;
   114 } SYMOWF_CONTENT_UPDATED_PARAM;
   115 
   116 typedef struct{
   117     TInt32      length;
   118     TInt32      event;
   119 } SYMOWF_DEFAULT_EVENT_PARAM;
   120 
   121 typedef enum
   122 {
   123     SYM_CONTENT_UPDATE_BEGIN               = 0x00000001,
   124     SYM_CONTENT_UPDATE_END                 = 0x00000002,
   125     SYM_CONTENT_UPDATE                     = 0x00000003,
   126     SYM_CONTENT_UPDATE_MAX                 = 0xffffffff
   127 } SymContentUpdatedCommandsId;
   128 
   129 typedef enum
   130 {
   131     SYM_CONTENT_VISIBLE_NOT_SET            = 0x00000000,
   132     SYM_CONTENT_VISIBLE                    = 0x00000001,
   133     SYM_CONTENT_NOT_VISIBLE                = 0x00000002,
   134     SYM_CONTENT_MAX                        = 0xffffffff
   135 } SymContextVisibilityState;
   136 
   137 typedef enum
   138 {
   139     SYM_CONTENT_PREVIOUS_COMMIT_FALSE      = 0x00000000,
   140     SYM_CONTENT_PREVIOUS_COMMIT_TRUE       = 0x00000001,
   141     SYM_CONTENT_COMMIT_MAX                 = 0xffffffff
   142 } SymContextCommitState;
   143 
   144 
   145 /** Finds, and creates if necessary, a Native Stream object encapsulating the specified surface.
   146 
   147 @param  aId The TSurfaceId for the surface to encapsulate.
   148 @param  aReturnHandle   The Native Stream handle created.
   149 
   150 @pre
   151     -   aId must not be a NULL pointer
   152     -   aReturnHandle must not be a NULL pointer, and must point to writable storage for the handle.
   153     -   aId must be a valid active Surface ID created by the Surface Manager.
   154         -   In particular, aId->IsNull() should return EFalse.
   155     -   Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.
   156 @post
   157     The location pointed to by aReturnHandle is set to a valid Native Stream object and KErrNone is returned, or NULL is set and an error code is returned appropriately.
   158     The method may fail due to memory allocation if the Native Stream does not already exist.
   159     If a stream object is successfully created, then the reference on the stream is increased to ensure it remains live following the method call. See SymbianStreamRemoveReference to release the reference.
   160 
   161 @panic  NativeStream 1000001 Null Surface ID
   162 @panic  NativeStream  1000002 Null return value pointer
   163 @return Symbian error code
   164     -  KErrNone    Method Succeeded
   165     -  KErrBadHandle   aId was not created by the Surface Manager, or has been destroyed.
   166     -  KErrNoMemory    Internal allocation of resources for the Native Stream failed.
   167 **/
   168   IMPORT_C TErrCode SymbianStreamAcquire( const TSurfaceId* aId, SymbianStreamType* aReturnHandle);
   169 
   170 /** Opens the current output buffer of the Native Stream object for non-exclusive reading.
   171 
   172 @param  aStream Native Stream handle that is to be accessed.
   173 @param  aReturnBuffer   Filled with the handle to use to access the current read buffer
   174 
   175 @pre
   176     -   aStream must be an active Native Stream object. It must not be NULL.
   177     -   aReturnBuffer must not be a NULL pointer, and must point to writable storage for the handle.
   178     -   Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.
   179     -   To simplify composition, SymbianStreamAcquireReadBuffer will never fail. It will arbitrarily select a buffer if the stream has never been written to or updated.
   180 @post
   181     -   This method always succeeds and returns quickly.
   182     -   The current read buffer is locked for reading.
   183     -   The location pointed to by aReturnBuffer is set to a handle representing the read buffer at the time of this call.
   184     -   Many readers may access the same buffer, but if the Native Stream represents a multi-buffered TSurfaceId content, writers are blocked from overwriting the current read buffer, which will be the last buffer successfully written to.
   185         -   In single-buffered streams, the content of the buffer may be overwritten while the reader is reading it, leading to tearing, but this behavior is generally considered preferable to blocking the reader.
   186     -   The Native Stream will not be destroyed while buffers are acquired.
   187     -   Note that no operations likely to cause failure will occur during the acquire method, but successful acquire does not guarantee that the buffer pixel data can be successfully mapped using NativeStreamGetBufferPointer.
   188 
   189 @panic NativeStream 1000002 Null return value pointer
   190 @panic NativeStream 1000003 Null Native Stream
   191 @return Symbian error code
   192     -  KErrNone    Method Succeeded
   193     -  KErrNoMemory    Internal allocation of resources for the Native Stream failed.
   194 **/
   195   IMPORT_C TErrCode SymbianStreamAcquireReadBuffer( SymbianStreamType aStream, SymbianStreamBuffer* aReturnBuffer);
   196   
   197  
   198 /** Opens the write buffer of the Native Stream for exclusive writable access.
   199 
   200 @param  aStream Native Stream handle that is to be accessed.
   201 @param  aReturnBuffer   Filled with the handle to use to access the current write buffer
   202 
   203 @pre
   204     -   aStream must be an active Native Stream object. It must not be NULL.
   205     -   aReturnBuffer must not be a NULL pointer, and must point to writable storage for the handle.
   206     -   In single-buffered Native Streams, access is not controlled, any number of readers and/or writer(s) may access the buffer simultaneously, potentially leading to tearing, but this behavior is generally considered preferable to blocking the reader.
   207     -   In multi-buffered Native Streams, the next write buffer must be available, or the method call will fail and return an error. It may fail in three scenarios:
   208         -   There is already an active writer
   209         -   There are still readers attached to the next write buffer candidate (in buffer swapping architectures)
   210         -   The copy from write buffer to read buffer is ongoing, or waiting for readers (in buffer copying architectures)
   211     -   Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.
   212 @post
   213     -   This method returns quickly.
   214     -   If the write buffer cannot be acquired immediately then an error code is returned, indicating why exclusive access to a writable buffer could not be obtained.
   215     -   If the write buffer is acquired the KErrNone is returned, and the contents referenced by aReturnBuffer are filled with a handle representing the current write buffer. The current write buffer is locked for writing.
   216     -   The Native Stream will not be destroyed while buffers are acquired.
   217     -   Note that no resource operations likely to cause failure will occur during the acquire method, but successful acquire does not guarantee that the buffer pixel data can be successfully mapped using NativeStreamGetBufferPointer.
   218 @panic NativeStream 1000002 Null return value pointer
   219 @panic NativeStream 1000003 Null Native Stream
   220 @return Symbian error code
   221     -   KErrNone    Method Succeeded
   222     -   KErrInUse   Write buffer could not be exclusively acquired
   223 **/ 
   224   IMPORT_C TErrCode SymbianStreamAcquireWriteBuffer( SymbianStreamType aStream, SymbianStreamBuffer* aReturnBuffer);
   225   
   226 
   227 /** Registers observers for OpenWF-C SI specified events.
   228 @code   typedef void (*SymOwfStreamCallback)(
   229     SymbianStreamType, SymNativeStreamEvent, void*);
   230 @endcode
   231 @param  aStream Native Stream handle that is to be accessed.
   232 @param  aObserver   Client function to be called when any event is called.
   233 @param  aData   Data supplied by client which will be passed to the method call.
   234 
   235 @pre
   236     -   aStream must be an active Native Stream object. It must not be NULL.
   237     -   aObserver must not be NULL
   238     -   aData may be NULL
   239     -   The combination of observer and data may be already registered, in which case it will be called twice if an event occurs.
   240     -   Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.
   241 @post
   242     -   The method may fail to add the observer to an internal list of observers, due to memory failure.
   243     -   The observer function will be called when any event occurs which was specified in the OpenWF-C SI and has been implemented by OpenWF Support. Symbian OS-specific extension events will not be delivered to observers registering using this method.
   244 @panic NativeStream 1000003 Null Native Stream
   245 @panic NativeStream 1000004 Null aObserver
   246 @return Symbian error code
   247     -   KErrNone    Method Succeeded
   248     -   KErrNoMemory    Internal allocation of resources for the Native Stream failed.
   249 **/
   250   IMPORT_C TErrCode SymbianStreamAddObserver( SymbianStreamType aStream, SymbianStreamCallback aObserver, void* aData);
   251 
   252 /** Registers observers for specific events including Symbian OS-specified events.
   253 @param  aStream Native Stream handle that is to be accessed.
   254 @param  aObserver   Client function to be called when any specified event is called.
   255 @param  aData   Client data passed to the function.
   256 @param  aScreenNumber   Screen Number of the consumer, where relevant.
   257 @param  aEvents Events for which this observer will be called.
   258 
   259 @pre
   260     -   aStream must be an active Native Stream object. It must not be NULL.
   261     -   aObserver must not be NULL
   262     -   aEvents must specify 1 or more event flags
   263     -   Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.
   264     -   aScreenNumber should be one of:
   265         -   zero:   Screen number 0 associated with the first on-screen composition context
   266         -   positive:   A real screen number associated other on-screen composition contexts
   267         -   A good value for aScreenNumber may not be required for all event registrations, and should be set to EScreenNumberAllNoEvents when not required.
   268 
   269 @post
   270     -   The method may fail to add the observer to an internal list of observers, due to memory failure.
   271     -   The observer function will be called when an event specified in the parameter list occurs.
   272     -   If the screen number is zero or positive, or EScreenNumberAllEvents and the event includes ESOWF_EVENTUPDATED 
   273         then this client may be expected to handle bit flagged events - see SymbianStreamEventBits. Such an Observer must 
   274         also send back Available and Displayed notifications to Symbian Stream as required.
   275 @panic NativeStream 1000003 Null Native Stream
   276 @panic NativeStream 1000004 Null aObserver
   277 @return Symbian error code
   278     -   KErrNone    Method Succeeded
   279     -   KErrNoMemory    Internal allocation of resources for the Native Stream failed.
   280     -   KErrArgument    aEvents does not flag any supported events, or aScreenNumber out of range
   281 **/
   282   IMPORT_C TErrCode SymbianStreamAddExtendedObserver( SymbianStreamType aStream, SymbianStreamCallback aObserver, void* aData, khronos_int32_t aScreenNumber, SymbianStreamEventBits aEvents);
   283 
   284 
   285 /** Increases the reference on the Native Stream object, extending its lifetime.
   286 @param  aStream Native Stream handle that is to be accessed.
   287 
   288 @pre
   289     -   aStream must be an active Native Stream object. It must not be NULL.
   290 @post
   291     -   The object will not be destroyed until an equivalent number of calls to SymbianStreamRemoveReference.
   292 @panic NativeStream 1000003 Null Native Stream
   293 @panic NativeStream 1000004 Null aObserver
   294 **/
   295   IMPORT_C void SymbianStreamAddReference(SymbianStreamType aStream);
   296 
   297 /** Provides Symbian OS-aware clients access to extended features of the currently open buffer via Surface Manager.
   298 @param  aStream Native Stream handle that is to be accessed.
   299 @param  aBufferHandle   Handle to acquired read or write buffer.
   300 @param  aReturnIndex    Returns internal buffer number.
   301 @param  aReturnSurface  Returns internal TSurfaceId.
   302 
   303 @pre
   304     -   aStream must be an active Native Stream object. It must not be NULL.
   305     -   aBufferHandle must be a valid acquired buffer on that native stream that has not yet been released.
   306     -   aReturnIndex must not be a NULL pointer, and must point to writable storage for the index value.
   307     -   aReturnSurface must not be a NULL pointer, and must point to writable storage for the TSurfaceId pointer.
   308     -   Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.
   309     -   SymbianStreamGetBufferPointer or SymbianStreamGetBufferId can only be called after a call to SymbianStreamAcquireReadBuffer or SymbianStreamAcquireWriteBuffer, and before the call to SymbianStreamReleaseReadBuffer or SymbianStreamReleaseWriteBuffer.
   310     -   They can be called multiple times in this period, but each call is not guaranteed to return the same information, and the information returned by an earlier call should not be used after repeating the call or after calling SymbianStreamReleaseReadBuffer or SymbianStreamReleaseWriteBuffer.
   311 
   312 @panic NativeStream 1000002 Null return value pointer
   313 @panic NativeStream 1000003 Null Native Stream
   314 @return Symbian error code
   315     -   KErrNone    Method Succeeded
   316     -   KErrBadHandle   aBufferNumber was NULL or not acquired on this Native Stream
   317 **/
   318   IMPORT_C TErrCode SymbianStreamGetBufferId( SymbianStreamType aStream, SymbianStreamBuffer aBufferHandle, khronos_int32_t* aReturnIndex, const TSurfaceId** aReturnSurface);
   319 
   320 /** Finds the persistent Native Stream instance associated with the surface ID. If the association does not exist then this method fails - it does not attempt to create the association.
   321 @param  aId Surface ID handle that is to be accessed.
   322 @param  aReturnStream   Filled with the handle of the equivalent Native Stream
   323 @pre
   324     -   aId must not be NULL.
   325     -   aReturnStream must not be a NULL pointer, and must point to writable storage for the handle.
   326     -   [Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.]
   327 @post
   328     -   If a Native Stream has been successfully acquired, using SymbianStreamAcquire, for the surface ID, then that Native Stream is returned.
   329     -   The reference on the stream is increased to ensure it remains live following the method call. See SymbianStreamRemoveReference to release the reference.
   330     -   If the identified stream is not currently acquired, then NULL is returned, and an error code is set.
   331     -   The error codes set by this method may not distinguish between Surface IDs that have not been Acquired and bad values for the surface ID, such as IsNull() or destroyed surfaces.
   332 
   333 @panic NativeStream 1000001 Null Surface ID
   334 @panic NativeStream 1000002 Null return value pointer
   335 @return Symbian error code
   336     -   KErrNone    Method Succeeded
   337     -   KErrNoMemory    Internal allocation of resources for the Native Stream failed.
   338     -   KErrNotFound    No Native Stream already exists that encapsulates aId.
   339 **/
   340   IMPORT_C TErrCode SymbianStreamFind( const TSurfaceId* aId, SymbianStreamType* aReturnStream);
   341 
   342 /** Returns a pointer to the pixel data associated with the acquired buffer.
   343 @param  aStream Native Stream handle that is to be accessed.
   344 @param  aBuffer Acquired buffer handle.
   345 @param  aReturnPointer  Filled with the handle to use to access the current read buffer
   346 @pre
   347     -   aStream must be an active Native Stream object. It must not be NULL.
   348     -   aBuffer should not be NULL
   349     -   aReturnPointer must not be a NULL pointer, and must point to writable storage for the pointer.
   350     -   aBuffer must be a currently acquired read or write buffer handle on the specified Native Stream.
   351     -   Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.
   352     -   SymbianStreamGetBufferPointer or SymbianStreamGetBufferId should not be called more than once for each buffer acquire. Correct cleanup behavior is not guaranteed if these methods are called multiple times.
   353     -   The pixel data must be mappable to CPU-accessible RAM. For some multimedia content types this may not be possible, and the method will fail. The error reported will be forwarded from Surface Manager.
   354 @post
   355     If unsuccessful, an error code is returned.
   356     -   The method may fail if the pixel data cannot be made available in the caller's address space, for a variety of reasons including running out of virtual memory.
   357     If Successful:
   358     -   Pixel data is made available and a pointer to the first pixel is returned.
   359     -   The layout of the pixel data will be as specified by SymbianStreamGetHeader.
   360     -   The memory may be tagged as read-only if the buffer was generated using AcquireReadBuffer.
   361     -   This layout implies a maximum size to the buffer data. The client should not access data outside that range of addresses.
   362 
   363 @panic NativeStream 1000001 Null Surface ID
   364 @panic NativeStream 1000002 Null return value pointer
   365 @return Symbian error code
   366     -   KErrNone    Method Succeeded
   367     -   KErrBadHandle   aBuffer was NULL or not acquired on this Native Stream
   368     -   <<other>>   mapping of the TSurfaceId failed - reporting the internal error.
   369 **/
   370   IMPORT_C TErrCode SymbianStreamGetBufferPointer( SymbianStreamType aStream, SymbianStreamBuffer aBuffer, void** aReturnPointer);
   371 
   372 /** Returns a description of the format of the image data stored in the Native Stream.
   373 @param  aStream Native Stream handle that is to be accessed.
   374 @param  aWidth  Pointer to fill in width in pixels of accessible buffer.
   375 @param  aHeight Pointer to fill in height in pixels of accessible buffer.
   376 @param  aStride Pointer to fill in offset between rows of pixels.
   377 @param  aFormat Pointer to fill in format code matching well known Symbian OS surface format UIDs.
   378 @param  aFixelSize  Pointer to fill in number of bytes per pixel for the given format.
   379 
   380 @pre
   381     -   aStream must be an active Native Stream object. It must not be NULL.
   382     -   The remaining parameters are each either NULL, or point to local data storage which will be modified.
   383 @post
   384     -   Targets of non-NULL parameters will be filled in with values describing the surface encapsulated by the Native Stream.
   385     -   [Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.]
   386     -   In the current implementation, this information is stored locally and can be efficiently accessed.
   387 @panic NativeStream 1000002 Null return value pointer
   388 @panic NativeStream 1000003 Null Native Stream
   389 **/
   390   IMPORT_C void SymbianStreamGetHeader( SymbianStreamType aStream, khronos_int32_t* aWidth, khronos_int32_t* aHeight, khronos_int32_t* aStride, khronos_int32_t* aFormat, khronos_int32_t* aPixelSize);
   391 
   392 /** Returns extra details of the format of the image data stored in the Native Stream.
   393  This method is intended to allow compositors to access the SurfaceManager hints associated with the 
   394  stream without using SurfaceManager-explicit code.
   395  It is possible in future that some of the hint IDs could be resolved locally rather than calling surface manager.  
   396 @prototype  @internal
   397 @param  aStream Native Stream handle that is to be accessed.
   398 @param  aHint   Well known unique ID for specific hint property
   399 @param  aValueReturn    Pointer to fill in current value for property
   400 @param  aMutableReturn  Pointer to fill in to flag whether the property value is fixed or mutable
   401 
   402 @pre
   403     -   aStream must be an active Native Stream object. It must not be NULL.
   404     -   aHint may be any UID value, but only hint UIDs are likely to be successful.
   405     -   aValueReturn may be NULL, in which case the return value will indicate whether the hint is present
   406     -   aMutableeReturn may be NULL, in which case the client must presume the property may be mutable.
   407     -   Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.
   408 @post
   409     -   If the hint aHint is not associated with the underlying surface then an error is returned.
   410     -   If the hint is available, KErrNone is returned, and if aValueReturn is not NULL, the location pointed to will be filled with the current value of the hint. If not NULL the location pointed to by aMutableReturn indicates whether the hint is mutable.
   411 
   412 @panic NativeStream 1000003 Null Native Stream
   413 @return Symbian error code
   414     -   KErrNone    Method Succeeded
   415     -   KErrArgument    hint not found (from  RSurfaceManager::GetSurfaceHint)
   416     -   <<other>>   error reported from  RSurfaceManager::GetSurfaceHint
   417 **/
   418   IMPORT_C TErrCode SymbianStreamGetHint( SymbianStreamType aStream, khronos_int32_t aUid, khronos_int32_t* aValueReturn, khronos_bool* aMutableReturn);
   419 
   420 
   421 /** Debug method which indicates whether a particular screen number has been registered for screen notifications (from SUS).
   422 @param  aScreenNumber   Any valid screen number.
   423 @param  aReturnState    Points to a Pointer to hold the returned registered object.
   424 
   425 @pre
   426     -   aReturnState    may be NULL, or must point to a location to receive the internal object registered with SUS
   427     -   [Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.]
   428 @post
   429     -   aReturnState void*  opaque handle is NULL if the given screen number is not registered. The type of the internal object returned by this method is subject to change.
   430     -   A change in the value of aReturnState in subsequent calls indicates that the screen has been re-registered.
   431 @return Symbian error code
   432     -   KErrNone    The screen number is registered with SUS.
   433     -   KErrNotFound    The screen number is not registered.
   434     -   KErrNotReady    SUS is not active, but the screen would be registered.
   435     -   KErrAlreadyExists   The screen number is already registered with SUS.
   436 **/
   437   IMPORT_C TErrCode SymbianStreamHasRegisteredScreenNotifications( khronos_int32_t aScreenNumber,void** aReturnState);
   438 
   439 /** Generates a registration with Surface Update Server (SUS) for the given screen number at the given priority.
   440 @param  aScreenNumber   Number of screen to be registered. This number should be acceptable to SUS.
   441 @param  aPriority   Nominal priority of the screen for global updates. Higher values have higher priority.
   442 @param  aInternalVersion    internal compositor version number to be reported to SUS.
   443 
   444 @pre
   445     -   aScreenNumber and aPriority should be within acceptable value ranges for SUS.
   446     -   Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.
   447     -   The thread used to register screen notifications must have an active scheduler and generally run in scheduling mode.
   448 @post
   449     -   Surface Update Server will be started if it has not already been started.
   450     -   The given screen number is registered or re-registered with SUS at the given priority.
   451     -   If SUS cannot be started, for example in debug environments, then an error is returned, but a screen update object is still created, as returned by SymbianStreamHasRegisteredScreenNotifications.
   452     -   The default heap specified when calling this method will be activated when SUS notifies the Native Stream of an update.
   453 @return Symbian error code
   454     -   KErrNone    Method Succeeded
   455     -   KErrNoMemory    Internal allocation of resources for the Native Stream failed.
   456     -   KErrNotReady    SUS was not launched (may occur in unit testing)
   457     -   KErrAlreadyExists   the given screen number is already registered
   458     -   <<other>>   as returned by SUS
   459 **/
   460   IMPORT_C TErrCode SymbianStreamRegisterScreenNotifications( khronos_int32_t aScreenNumber, khronos_int32_t aPriority, khronos_int32_t aInternalVersion);
   461 
   462 /** Releases the buffer previously acquired with SymbianStreamAcquireReadBuffer.
   463 @param  aStream Native Stream handle that is to be accessed.
   464 @param  aBuffer Buffer handle that is to be released.
   465 
   466 @pre
   467     -   aStream must be an active Native Stream object. It must not be NULL.
   468     -   aBuffer must be a buffer handle acquired on this stream using SymbianStreamAcquireReadBuffer and not yet released.
   469     -   Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.
   470 @post
   471     -   The non-exclusive buffer lock is released, potentially allowing writers to modify the content of the buffer.
   472     -   Any memory made available using SymbianStreamGetBufferPointer on this buffer handle may become unmapped from the caller's address space. The pointer must not continue to be used.
   473     -   Clients using SymbianStreamBufferId to efficiently access multimedia resources should release those resources before calling this method; otherwise they risk the contents being overwritten.
   474 @panic NativeStream 1000003 Null Native Stream
   475 @return Symbian error code
   476     -   KErrNone    Method Succeeded
   477     -   KErrBadHandle   aBuffer is not a currently open read buffer on this Native Stream;
   478 **/
   479   IMPORT_C TErrCode SymbianStreamReleaseReadBuffer( SymbianStreamType aStream, SymbianStreamBuffer aBuffer);
   480 
   481 /** Releases the buffer previously acquired with SymbianStreamAcquireWriteBuffer.
   482 @param  aStream Native Stream handle that is to be accessed.
   483 @param  aBuffer Buffer handle that is to be released.
   484 
   485 @pre
   486     -   aStream must be an active Native Stream object. It must not be NULL.
   487     -   aBuffer must be a buffer handle successfully acquired on this stream using SymbianStreamAcquireWriteBuffer and not yet released.
   488     -   Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.
   489 @post
   490     -   This buffer content becomes the read buffer for all subsequent calls to SymbianStreamAcquireReadBuffer
   491     -   The exclusive buffer lock is released.
   492     -   Any memory made available using SymbianStreamGetBufferPointer on this buffer handle may become unmapped from the caller's address space. The pointer should not continue to be used.
   493     -   Clients using SymbianStreamBufferId to access multimedia resources should release those resources before calling this method; otherwise they risk the changes being ignored.
   494     -   Any registered observers will be called with the ESOWF_EVENTUpdated notification.
   495     -   If the surface is multi-buffered, subsequent attempts to SymbianStreamAcquireWriteBuffer will succeed and will select a different buffer to write to, presuming clients do not still have a non-exclusive read lock on the available write buffers.
   496 @panic NativeStream 1000003 Null Native Stream
   497 @return Symbian error code
   498     -   KErrNone    Method Succeeded
   499     -   KErrBadHandle   aBuffer is not a currently open write buffer on this Native Stream;
   500 **/
   501   IMPORT_C TErrCode      SymbianStreamReleaseWriteBuffer( SymbianStreamType aStream, SymbianStreamBuffer aBuffer);
   502 
   503 /** Removes the observer inserted using SymbianStreamAddObserver.
   504 @param  aStream Native Stream handle that is to be accessed.
   505 @param  aObserver   identifies the registered observer.
   506 @param  aData   Client data supplied when registering the observer.
   507 @param  aEvents Events to remove registration from.
   508 
   509 @pre
   510     -   aStream must be an active Native Stream object. It must not be NULL.
   511     -   aData should have been provided as the client data when the observer was registered.
   512     -   aEvents indicates which events should no longer be notified, and should match the original extended events list.
   513     -   If aEvents is empty then the observer is removed from all events.
   514     -   Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.
   515 @post
   516     -   The observer function will no longer be called when the specified events occur, unless the observer was registered more than once, in which case the number of notifications will be reduced.
   517     -   There is a small window of opportunity that events triggered on one thread may complete after the observer has been removed from another thread. Clients should be aware of this potential false call.
   518     
   519 @panic NativeStream 1000006 Null for all search parameters
   520 @panic NativeStream 1000003 Null Native Stream
   521 @return Symbian error code
   522     -   KErrNone    Method Succeeded
   523     -   KErrNotFound    The observer function was not found for this Native Stream.
   524     -   KErrArgument    aEvents does not flag any supported events
   525 **/
   526   IMPORT_C TErrCode SymbianStreamRemoveObserver( SymbianStreamType aStream, void* aData, SymbianStreamEventBits aEvents);
   527 
   528 /** Reduces the references on the Native Stream object and potentially destroys the object.
   529 @param  aStream Native Stream handle that is to be accessed.
   530 
   531 @pre
   532     -   aStream must be an active Native Stream object. It must not be NULL.
   533     -   Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.
   534 @post
   535     -   The recorded references are reduced. If this is the final reference then the Native Stream is destroyed.
   536 @panic NativeStream 1000003 Null Native Stream
   537 **/
   538   IMPORT_C void      SymbianStreamRemoveReference(SymbianStreamType aStream);
   539 
   540 /** Changes the state of the deletion protection flag. The protection state effectively increases the reference, blocking deletion. Direct use of the reference mechanism is preferred.
   541 @deprecated The protection flag is used for off-screen composition in the current compositor implementation. Direct use of the reference mechanism is preferred.
   542     Parameters:
   543 @param  aStream Native Stream handle that is to be accessed.
   544 @param  aFlag   Set true to activate protection - set false to deactivate protection.
   545 
   546 @pre
   547     -   aStream must be an active Native Stream object. It must not be NULL.
   548     -   Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.
   549 @post
   550     If the aFlag is different to the internal protection state then the reference is modified:
   551     -   If aFlag is set then the reference is effectively artificially raised to protect the Native Stream against deletion.
   552     -   If aFlag is clear then the reference returns to normal mode, and the Native Stream may be destroyed.
   553 @panic NativeStream 1000003 Null Native Stream
   554 **/
   555   IMPORT_C void SymbianStreamSetProtectionFlag( SymbianStreamType aStream, khronos_bool aFlag);
   556 
   557 /** Compares two Native Stream handles for equivalency. 
   558  It is probable that the actual handle value is not unique for a particular surface, 
   559  but binary different handles in fact refer to the same internal object.
   560 
   561 
   562 @param  aStream First Native Stream handle that is to be compared.
   563 @param  aStream2    Second Native Stream handle that is to be compared.
   564 
   565 @pre
   566     -   aStream must be an active Native Stream object, or it may be NULL.
   567     -   aStream2 must be an active Native Stream object, or it may be NULL.
   568     -   [Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack. ]
   569     -   Direct comparison will be performed first. No allocations or system calls will be made to resolve this comparison, returning false where, for example the surface IDs refer to the same Surface Manager controlled object.
   570 @post
   571     The given handles are compared, and if necessary the internal objects are compared.
   572 
   573 
   574 @return khronos_bool If they reference the same TSurfaceId then TRUE is returned, else FALSE is returned.
   575 **/
   576   IMPORT_C khronos_bool      SymbianStreamSame(SymbianStreamType aStream, SymbianStreamType aStream2);
   577 
   578 /** Removes the screen number from SUS registration.
   579     Parameters:
   580     aScreenNumber   Screen number to be unregistered.
   581 
   582 @pre
   583     -   aScreenNumber should have previously been registered using SymbianStreamRegisterScreenNotifications.
   584     -   Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.
   585     -   Out of range screen numbers will not have been registered, and will naturally not be found to unregister. No specific error code will indicate these screen numbers.
   586 @post
   587     Notifications of content updated will no longer be received by the Native Stream for that screen number or passed on to any observer.
   588 @return Symbian error code
   589     -   KErrNone    Method Succeeded - screen unregistered
   590     -   KErrNotReady    The Surface Update Server is not present (in test harnesses).
   591     -   KErrArgument    aScreennNum was not registered
   592 **/
   593   IMPORT_C TErrCode      SymbianStreamUnregisterScreenNotifications(khronos_int32_t aScreenNumber);
   594   
   595 
   596 /** Indication that the stream has been displayed in the scene.  
   597  This function is called by a client after it has consumed a buffer following an update notification 
   598  and indicates the state of that consumption.
   599  
   600 @param  aStream Native Stream handle that is to be accessed.
   601 @param  aEvent  The type of consumption notification event.
   602 @param  aScreenNumber   The screen number to which the event applies.
   603 @param  aSerialNumber  The serial number to which the event applies. Changes after each composition, allowing repeat calls within one composition to be detected
   604 @param  aReturnMask Used by the recipient to enable repeating of the ESOWF_EventDisplayedX event.
   605 
   606 @pre
   607 	-	aSerialNumber must be changed after each composition, and allows the Native stream to detect multiple calls from the same composition.
   608     -   aStream must be an active Native Stream object. It must not be NULL.
   609     -   This method, or CheckVisible must be called exactly once after receiving ESOWF_EVENTUpdated, for each type of notification requested in the ESOWF_EVENTUpdated call by any context that has registered both SymbianStreamRegisteredScreenNotifications and SymbianStreamAddObserver (or SymbianStreamAddObserver with ESOWF_EventUpdated).
   610     -   Not calling this method when expected may cause deadlocks, and the result code delivered to SUS after calling the method too often with conflicting result codes is not defined.
   611     -   aEvent indicates which event has occurred. It may be one or more of:
   612         -   ESOWF_EventAvailable    Content is available
   613         -   ESOWF_EventDisplayed    Content is displayed
   614         -   ESOWF_EventDisplayedX   Content is displayed and repeated
   615 @post
   616     -   Matching notifications to the Surface Update Server for this screen number may be completed (via callbacks).
   617     -   If the notification is to be repeated then aReturnMask is modified to indicate which notifications should be repeated.
   618 
   619 **/
   620   IMPORT_C void SymbianStreamProcessNotifications( SymbianStreamType aStream, khronos_int32_t aEvent, khronos_int32_t aScreenNumber, khronos_int32_t aSerialNumber, khronos_int32_t* aReturnMask);
   621   
   622 /** Indication that the stream is not visible in the scene. 
   623  This function is called by a client after it has consumed a buffer following an update notification 
   624  and indicates the state of that consumption was "not visible".
   625  Currently this is fired for any remaining streams at the end of composition 
   626  after all positive SymbianStreamProcessNotifications have been made.
   627 @param  aStream Native Stream handle that is to be accessed.
   628 @param  aEvent  The type of consumption notification event.
   629 @param  aScreenNumber   The screen number to which the event applies.
   630 @param  aSerialNumber  The serial number to which the event applies. Changes after each composition, allowing repeat calls within one composition to be detected.
   631 
   632 @pre
   633 	-	aSerialNumber must be changed after each composition event, and allows the Native stream to detect multiple calls from the same composition.
   634     -   aStream must be an active Native Stream object. It must not be NULL.
   635     -   This method, or ProcessNotifications must be called exactly once after receiving ESOWF_EVENTUpdated, for each type of notification requested in the ESOWF_EVENTUpdated call by any context that has registered both SymbianStreamRegisteredScreenNotifications and SymbianStreamAddObserver (or SymbianStreamAddObserver with ESOWF_EventUpdated).
   636     -   aEvent indicates which event has occurred. It may be one or more of:
   637         -   ESOWF_EventAvailable    Content is available
   638         -   ESOWF_EventDisplayed    Content is displayed
   639         -   ESOWF_EventDisplayedX   Content is displayed and repeated
   640 @post
   641     Notifications to the Surface Update Server may be completed (via callbacks).
   642 
   643 **/
   644   IMPORT_C void  SymbianStreamCheckVisible(SymbianStreamType aStream, khronos_int32_t aEvent, khronos_int32_t aScreenNumber, khronos_int32_t aSerialNumber);
   645 
   646   /** This function is called by a client to adjust the shape of the target stream.
   647    This only effects the results discovered by SymbianStreamGetHeader(),
   648    and has no effect on the underlying SurfaceManager Surface.
   649    The flag should only be called when the stream is opened for writing, 
   650    and it only effects calls to SymbianStreamGetHeader(0 after the write buffer is closed. 
   651    When the aFlip flag is not set the width, height and stride are passed to clients as discovered during construction. 
   652    When the aFlip flag is set, the width and height parameters are exchanged for SymbianStreamGetHeader(), 
   653    and a calculated value for stride is returned.
   654   @param  aStream Native Stream handle that is to be accessed.
   655   @param  aFlip  The flip state
   656 
   657   @post
   658       The flip state is updated when SymbianStreamReleaseWriteBuffer() call is made
   659 
   660   **/
   661   IMPORT_C void  SymbianStreamSetFlipState(SymbianStreamType aStream, SymOwfBool aFlip);
   662   
   663   IMPORT_C TErrCode SymbianStreamGetChunkHandle(SymbianStreamType aStream, TInt* aHandle);
   664   
   665 #	ifdef __cplusplus
   666 	}
   667 #	endif
   668 
   669 #endif  // __SYMBIANSTREAM_H__