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