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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
15 // C API for surface stream implementation of OpenWF-C NativeStream
18 #ifndef __SYMBIANSTREAM_H__
19 #define __SYMBIANSTREAM_H__
24 class RSurfaceManager;
26 typedef struct struct_TSurfaceId TSurfaceId;
28 #include <KHR/khrplatform.h>
29 typedef khronos_int32_t khronos_bool;
30 typedef khronos_int32_t TErrCode;
33 * \brief Image stream implementation
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.
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.
51 #define KInitialContextSerialNumber 0
52 #define KNoAssociatedScreenNumber (-1)
54 typedef const TSurfaceId* SymbianStreamType;
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
62 ESOWF_EventUpdated = 0x00000010, // identifies the content update
63 //callback used to trigger a new composition
64 ESOWF_SIEventsMask = ESOWF_EventComposed | ESOWF_EventUpdated,
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,
72 ESOWF_AllEventsMask = (ESOWF_SIEventsMask | ESOWF_SUSEventsMask),
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,
80 // reserved for future extensions
81 ESOWF_RESERVED_MASK = 0xff000000
82 } SymbianStreamEventBits;
84 typedef khronos_int32_t SymOwfNativeStreamBuffer;
86 #define SYMBIAN_INVALID_HANDLE 0
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;
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
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*);
112 TInt32 immediateAvailable;
113 TInt32 immediateVisibility;
114 } SYMOWF_CONTENT_UPDATED_PARAM;
119 } SYMOWF_DEFAULT_EVENT_PARAM;
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;
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;
139 SYM_CONTENT_PREVIOUS_COMMIT_FALSE = 0x00000000,
140 SYM_CONTENT_PREVIOUS_COMMIT_TRUE = 0x00000001,
141 SYM_CONTENT_COMMIT_MAX = 0xffffffff
142 } SymContextCommitState;
145 /** Finds, and creates if necessary, a Native Stream object encapsulating the specified surface.
147 @param aId The TSurfaceId for the surface to encapsulate.
148 @param aReturnHandle The Native Stream handle created.
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.
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.
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.
168 IMPORT_C TErrCode SymbianStreamAcquire( const TSurfaceId* aId, SymbianStreamType* aReturnHandle);
170 /** Opens the current output buffer of the Native Stream object for non-exclusive reading.
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
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.
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.
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.
195 IMPORT_C TErrCode SymbianStreamAcquireReadBuffer( SymbianStreamType aStream, SymbianStreamBuffer* aReturnBuffer);
198 /** Opens the write buffer of the Native Stream for exclusive writable access.
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
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.
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
224 IMPORT_C TErrCode SymbianStreamAcquireWriteBuffer( SymbianStreamType aStream, SymbianStreamBuffer* aReturnBuffer);
227 /** Registers observers for OpenWF-C SI specified events.
228 @code typedef void (*SymOwfStreamCallback)(
229 SymbianStreamType, SymNativeStreamEvent, void*);
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.
236 - aStream must be an active Native Stream object. It must not be NULL.
237 - aObserver must not 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.
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.
250 IMPORT_C TErrCode SymbianStreamAddObserver( SymbianStreamType aStream, SymbianStreamCallback aObserver, void* aData);
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.
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.
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
282 IMPORT_C TErrCode SymbianStreamAddExtendedObserver( SymbianStreamType aStream, SymbianStreamCallback aObserver, void* aData, khronos_int32_t aScreenNumber, SymbianStreamEventBits aEvents);
285 /** Increases the reference on the Native Stream object, extending its lifetime.
286 @param aStream Native Stream handle that is to be accessed.
289 - aStream must be an active Native Stream object. It must not be NULL.
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
295 IMPORT_C void SymbianStreamAddReference(SymbianStreamType aStream);
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.
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.
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
318 IMPORT_C TErrCode SymbianStreamGetBufferId( SymbianStreamType aStream, SymbianStreamBuffer aBufferHandle, khronos_int32_t* aReturnIndex, const TSurfaceId** aReturnSurface);
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
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.]
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.
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.
340 IMPORT_C TErrCode SymbianStreamFind( const TSurfaceId* aId, SymbianStreamType* aReturnStream);
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
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.
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.
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.
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.
370 IMPORT_C TErrCode SymbianStreamGetBufferPointer( SymbianStreamType aStream, SymbianStreamBuffer aBuffer, void** aReturnPointer);
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.
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.
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
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);
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.
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
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.
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.
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
418 IMPORT_C TErrCode SymbianStreamGetHint( SymbianStreamType aStream, khronos_int32_t aUid, khronos_int32_t* aValueReturn, khronos_bool* aMutableReturn);
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.
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.]
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.
437 IMPORT_C TErrCode SymbianStreamHasRegisteredScreenNotifications( khronos_int32_t aScreenNumber,void** aReturnState);
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.
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.
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
460 IMPORT_C TErrCode SymbianStreamRegisterScreenNotifications( khronos_int32_t aScreenNumber, khronos_int32_t aPriority, khronos_int32_t aInternalVersion);
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.
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.
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;
479 IMPORT_C TErrCode SymbianStreamReleaseReadBuffer( SymbianStreamType aStream, SymbianStreamBuffer aBuffer);
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.
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.
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;
501 IMPORT_C TErrCode SymbianStreamReleaseWriteBuffer( SymbianStreamType aStream, SymbianStreamBuffer aBuffer);
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.
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.
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.
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
526 IMPORT_C TErrCode SymbianStreamRemoveObserver( SymbianStreamType aStream, void* aData, SymbianStreamEventBits aEvents);
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.
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.
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
538 IMPORT_C void SymbianStreamRemoveReference(SymbianStreamType aStream);
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.
543 @param aStream Native Stream handle that is to be accessed.
544 @param aFlag Set true to activate protection - set false to deactivate protection.
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.
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
555 IMPORT_C void SymbianStreamSetProtectionFlag( SymbianStreamType aStream, khronos_bool aFlag);
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.
562 @param aStream First Native Stream handle that is to be compared.
563 @param aStream2 Second Native Stream handle that is to be compared.
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.
571 The given handles are compared, and if necessary the internal objects are compared.
574 @return khronos_bool If they reference the same TSurfaceId then TRUE is returned, else FALSE is returned.
576 IMPORT_C khronos_bool SymbianStreamSame(SymbianStreamType aStream, SymbianStreamType aStream2);
578 /** Removes the screen number from SUS registration.
580 aScreenNumber Screen number to be unregistered.
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.
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
593 IMPORT_C TErrCode SymbianStreamUnregisterScreenNotifications(khronos_int32_t aScreenNumber);
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.
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.
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
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.
620 IMPORT_C void SymbianStreamProcessNotifications( SymbianStreamType aStream, khronos_int32_t aEvent, khronos_int32_t aScreenNumber, khronos_int32_t aSerialNumber, khronos_int32_t* aReturnMask);
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.
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
641 Notifications to the Surface Update Server may be completed (via callbacks).
644 IMPORT_C void SymbianStreamCheckVisible(SymbianStreamType aStream, khronos_int32_t aEvent, khronos_int32_t aScreenNumber, khronos_int32_t aSerialNumber);
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
658 The flip state is updated when SymbianStreamReleaseWriteBuffer() call is made
661 IMPORT_C void SymbianStreamSetFlipState(SymbianStreamType aStream, SymOwfBool aFlip);
663 IMPORT_C TErrCode SymbianStreamGetChunkHandle(SymbianStreamType aStream, TInt* aHandle);
669 #endif // __SYMBIANSTREAM_H__