1/*
2Copyright (c) 2012, Broadcom Europe Ltd
3All rights reserved.
4
5Redistribution and use in source and binary forms, with or without
6modification, are permitted provided that the following conditions are met:
7 * Redistributions of source code must retain the above copyright
8 notice, this list of conditions and the following disclaimer.
9 * Redistributions in binary form must reproduce the above copyright
10 notice, this list of conditions and the following disclaimer in the
11 documentation and/or other materials provided with the distribution.
12 * Neither the name of the copyright holder nor the
13 names of its contributors may be used to endorse or promote products
14 derived from this software without specific prior written permission.
15
16THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
20DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26*/
27
28#if !defined(WFC_SERVER_API_H)
29#define WFC_SERVER_API_H
30
31#include "interface/vcos/vcos.h"
32#include "interface/vcos/vcos_stdbool.h"
33#include "interface/khronos/include/WF/wfc.h"
34#include "interface/khronos/wf/wfc_int.h"
35#include "interface/khronos/include/EGL/eglext.h"
36
37/** Defining WFC_FULL_LOGGING will enable trace level logging across all WFC
38 * components.
39#define WFC_FULL_LOGGING
40 */
41
42/** General purpose callback function.
43 * Note: callbacks are often made on a thread other than the original function's.
44 *
45 * @param cb_data Callback additional data.
46 */
47typedef void (*WFC_CALLBACK_T)(void *cb_data);
48
49/** Extensible stream information block, supplied during creation and
50 * retrievable using wfc_server_stream_get_info. */
51typedef struct WFC_STREAM_INFO_T
52{
53 uint32_t size; /**< Size of the strucuture, for versioning. */
54 uint32_t flags; /**< Stream flags. */
55} WFC_STREAM_INFO_T;
56
57/** Create a connection to the server, as necessary. If this fails, no other
58 * server functions should be called. If it succeeds, there must be one call to
59 * wfc_server_disconnect() when use of the server has ended.
60 *
61 * @return VCOS_SUCCESS or a failure code.
62 */
63VCOS_STATUS_T wfc_server_connect(void);
64
65/** Destroy a connection to the server. This must be called once and only once
66 * for each successful call to wfc_server_connect().
67 */
68void wfc_server_disconnect(void);
69
70/** Increase the keep alive count by one. If it rises from zero, the VideoCore
71 * will be prevented from being suspended.
72 */
73void wfc_server_use_keep_alive(void);
74
75/** Drop the keep alive count by one. If it reaches zero, the VideoCore may be
76 * suspended.
77 */
78void wfc_server_release_keep_alive(void);
79
80/** Create a new on- or off-screen context for composition. The type of the context
81 * is either WFC_CONTEXT_TYPE_ON_SCREEN or WFC_CONTEXT_TYPE_OFF_SCREEN.
82 *
83 * @param context The client context identifier.
84 * @param context_type The type of the context.
85 * @param screen_or_stream_num The screen number for and on-screen context, or the
86 * target client stream identifier for an off-screen context.
87 * @param pid_lo The low 32-bits of the owning client process identifier.
88 * @param pid_hi The high 32-bits of the owning client process identifier.
89 * @return Zero on failure, or the width and height of the context in pixels,
90 * packed in the top and bottom 16 bits, respectively.
91 */
92uint32_t wfc_server_create_context(WFCContext context, uint32_t context_type,
93 uint32_t screen_or_stream_num, uint32_t pid_lo, uint32_t pid_hi);
94
95/** Destroy a context.
96 *
97 * @param context The client context identifier.
98 */
99void wfc_server_destroy_context(WFCContext ctx);
100
101/** Flags to be passed to wfc_server_commit_scene. A bitwise combination of
102 * flags may be passed in to control behaviour.
103 */
104typedef enum
105{
106 WFC_SERVER_COMMIT_WAIT = 1, /**< Wait for scene to be committed. */
107 WFC_SERVER_COMMIT_COMPOSE = 2, /**< Trigger composition */
108} WFC_SERVER_COMMIT_FLAGS_T;
109
110/** Commit a scene in the context. If the WAIT flag is set, a callback
111 * must be given and shall be called once a new scene can be given. If the
112 * COMPOSE flag is set, the newly committed scene shall be composed
113 * as soon as possible (subject to presence of a deferral stream).
114 *
115 * @param context The client context identifier.
116 * @param scene The scene to be composed.
117 * @param flags Combination of WFC_SERVER_COMMIT_FLAGS_T values, or 0.
118 * @param scene_taken_cb Called when scene has been taken, generally on a
119 * different thread, or zero for no callback.
120 * @param scene_taken_data Passed to scene_taken_cb.
121 * @return VCOS_SUCCESS if successful, VCOS_EAGAIN if the scene cannot be
122 * taken immediately and the wait flag is false.
123 */
124uint32_t wfc_server_commit_scene(WFCContext ctx, const WFC_SCENE_T *scene,
125 uint32_t flags, WFC_CALLBACK_T scene_taken_cb, void *scene_taken_data);
126
127/** Activate a context. While a context is active, it will be automatically
128 * composed when any of the streams in its current scene are updated.
129 *
130 * @param context The client context identifier.
131 */
132void wfc_server_activate(WFCContext ctx);
133
134/** Deactivate a context.
135 *
136 * @param context The client context identifier.
137 */
138void wfc_server_deactivate(WFCContext ctx);
139
140/** Set the deferral stream for a context. When a deferral stream is set on a
141 * context and a new scene is given for that context, composition is deferred
142 * until the stream is updated.
143 *
144 * @param context The client context identifier.
145 * @param stream The deferral stream, or WFC_INVALID_HANDLE for none.
146 */
147void wfc_server_set_deferral_stream(WFCContext ctx, WFCNativeStreamType stream);
148
149/** Create a stream and its buffers, for supplying pixel data to one or more
150 * elements, and optionally for storing the output of off-screen composition.
151 *
152 * @param stream The client stream identifier.
153 * @param flags Stream flags.
154 * @param pid_lo The low 32-bits of the owning client process identifier.
155 * @param pid_hi The high 32-bits of the owning client process identifier.
156 * @return The client stream identifier on success, or WFC_INVALID_HANDLE on error.
157 */
158WFCNativeStreamType wfc_server_stream_create(
159 WFCNativeStreamType stream, uint32_t flags, uint32_t pid_lo, uint32_t pid_hi);
160
161/** Create a stream and its buffers, for supplying pixel data to one or more
162 * elements, and optionally for storing the output of off-screen composition.
163 *
164 * @param stream The client stream identifier.
165 * @param info Stream configuration.
166 * @param pid_lo The low 32-bits of the owning client process identifier.
167 * @param pid_hi The high 32-bits of the owning client process identifier.
168 * @return The client stream identifier on success, or WFC_INVALID_HANDLE on error.
169 */
170WFCNativeStreamType wfc_server_stream_create_info(
171 WFCNativeStreamType stream, const WFC_STREAM_INFO_T *info, uint32_t pid_lo, uint32_t pid_hi);
172
173/** Destroy a stream.
174 *
175 * @param stream The client stream identifier.
176 * @param pid_lo The low 32-bits of the owning client process identifier.
177 * @param pid_hi The high 32-bits of the owning client process identifier.
178 */
179void wfc_server_stream_destroy(WFCNativeStreamType stream, uint32_t pid_lo, uint32_t pid_hi);
180
181/** Set callback for when src/dest rectangles are updated.
182 *
183 * @param stream The client stream identifier.
184 * @param rects_change_cb Called when either src or dest rectangles have been
185 * updated.
186 * @param rects_change_data Passed to the callback.
187 * @return VCOS_SUCCESS if successful, or an error code if not.
188 */
189void wfc_server_stream_on_rects_change(WFCNativeStreamType stream,
190 WFC_CALLBACK_T rects_change_cb, void *rects_change_data);
191
192/** Get destination and source rectangles, following request from server
193 *
194 * @param stream The client stream identifier.
195 * @param rects The rectangle data is written here.
196 * @return VCOS_SUCCESS if successful, or an error code if not.
197 */
198#define WFC_SERVER_STREAM_RECTS_SIZE 8
199uint32_t wfc_server_stream_get_rects(WFCNativeStreamType stream, int32_t rects[WFC_SERVER_STREAM_RECTS_SIZE]);
200
201/** Returns true if given stream number is currently in use.
202 *
203 * @param stream The client stream identifier.
204 * @return True if the client stream identifier is already in use, false if not.
205 */
206bool wfc_server_stream_is_in_use(WFCNativeStreamType stream);
207
208/** Allocate images in the stream into which an off-screen context can write
209 * composited output.
210 *
211 * @param stream The client stream identifier.
212 * @param width The width of the images, in pixels.
213 * @param height The height of the images, in pixels.
214 * @param nbufs The number of images to allocate in the stream.
215 * @return True on success, false on failure.
216 */
217bool wfc_server_stream_allocate_images(WFCNativeStreamType stream, uint32_t width, uint32_t height, uint32_t nbufs);
218
219/** Signal that the given EGLImageKHR is the new front image for the stream.
220 * @param stream The client stream identifier.
221 * @param ustorage The innards of KHRN_IMAGE_T
222 * @param width etc..
223 * @param height etc...
224 * @param stride
225 * @param offset
226 * @param format
227 * @param flags
228 * @param flip
229 */
230void wfc_server_stream_signal_eglimage_data(WFCNativeStreamType stream,
231 uint32_t ustorage, uint32_t width, uint32_t height, uint32_t stride,
232 uint32_t offset, uint32_t format, uint32_t flags, bool flip);
233
234/** Signal that the given multimedia image handle is the new front image for
235 * the stream.
236 *
237 * @param stream The client stream identifier.
238 * @param image_handle The new front image for the stream.
239 */
240void wfc_server_stream_signal_mm_image_data(WFCNativeStreamType stream, uint32_t image_handle);
241
242/** Signal that a raw image memhandle is the new front image for the stream.
243 *
244 * @param stream The client stream identifier.
245 * @param handle The new front image memhandle for the stream.
246 * @param format The image format. See WFC_PIXEL_FORMAT_T for supported formats.
247 * @param width The image width, in pixels.
248 * @param height The image height, in pixels.
249 * @param pitch The image pitch, in bytes.
250 * @param vpitch The image vertical pitch, in pixels.
251 */
252void wfc_server_stream_signal_raw_pixels(WFCNativeStreamType stream,
253 uint32_t handle, uint32_t format, uint32_t width, uint32_t height,
254 uint32_t pitch, uint32_t vpitch);
255
256/** Signal that the given image is the new front image for the stream.
257 *
258 * The type of each image the stream must be the same e.g. it is not permitted
259 * to mix opaque and raw pixel multimedia images within the same stream.
260 *
261 * @param stream The client stream identifier.
262 * @param image Structure describing the image.
263 */
264void wfc_server_stream_signal_image(WFCNativeStreamType stream,
265 const WFC_STREAM_IMAGE_T *image);
266
267/** Register a stream as in use by a given process.
268 *
269 * @param stream The client stream identifier.
270 * @param pid_lo The low 32-bits of the process ID.
271 * @param pid_hi The high 32-bits of the process ID.
272 */
273void wfc_server_stream_register(WFCNativeStreamType stream, uint32_t pid_lo, uint32_t pid_hi);
274
275/** Unregister a stream as in use by a given process.
276 *
277 * @param stream The client stream identifier.
278 * @param pid_lo The low 32-bits of the process ID.
279 * @param pid_hi The high 32-bits of the process ID.
280 */
281void wfc_server_stream_unregister(WFCNativeStreamType stream, uint32_t pid_lo, uint32_t pid_hi);
282
283/** Retrieve the stream configuration information, if available.
284 *
285 * @param stream The client stream identifier.
286 * @param info Address of block to receive the information on success.
287 * @return VCOS_SUCCESS if successful, or an error code if not.
288 */
289uint32_t wfc_server_stream_get_info(WFCNativeStreamType stream, WFC_STREAM_INFO_T *info);
290
291/** Set callback for when there is an image available. The stream must have
292 * been created with either the WFC_STREAM_FLAGS_EGL or WFC_STREAM_FLAGS_BUF_AVAIL
293 * flags set.
294 *
295 * @param stream The client stream identifier.
296 * @param image_available_cb Called when there is an image available.
297 * @param image_available_data Passed to the callback.
298 */
299void wfc_server_stream_on_image_available(WFCNativeStreamType stream,
300 WFC_CALLBACK_T image_available_cb, void *image_available_data);
301
302#endif /* WFC_SERVER_API_H */
303