1 /* Xplugin.h -- windowing API for rootless X11 server
2 $Id: Xplugin.h,v 1.3 2003/06/27 20:21:42 torrey Exp $
4 Copyright (c) 2002 Apple Computer, Inc. All rights reserved.
6 Permission is hereby granted, free of charge, to any person
7 obtaining a copy of this software and associated documentation files
8 (the "Software"), to deal in the Software without restriction,
9 including without limitation the rights to use, copy, modify, merge,
10 publish, distribute, sublicense, and/or sell copies of the Software,
11 and to permit persons to whom the Software is furnished to do so,
12 subject to the following conditions:
14 The above copyright notice and this permission notice shall be
15 included in all copies or substantial portions of the Software.
17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
20 NONINFRINGEMENT. IN NO EVENT SHALL THE ABOVE LISTED COPYRIGHT
21 HOLDER(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
22 WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
24 DEALINGS IN THE SOFTWARE.
26 Except as contained in this notice, the name(s) of the above
27 copyright holders shall not be used in advertising or otherwise to
28 promote the sale, use or other dealings in this Software without
29 prior written authorization.
31 Note that these interfaces are provided solely for the use of the
32 X11 server. Any other uses are unsupported and strongly discouraged. */
33 /* $XFree86: xc/programs/Xserver/hw/darwin/quartz/xpr/Xplugin.h,v 1.2 2003/05/02 00:08:49 torrey Exp $ */
40 /* By default we use the X server definition of BoxRec to define xp_box,
41 so that the compiler can silently convert between the two. But if
42 XP_NO_X_HEADERS is defined, we'll define it ourselves. */
44 #ifndef XP_NO_X_HEADERS
45 # include "miscstruct.h"
46 typedef BoxRec xp_box;
48 struct xp_box_struct {
51 typedef struct xp_box_struct xp_box;
54 typedef unsigned int xp_resource_id;
55 typedef xp_resource_id xp_window_id;
56 typedef xp_resource_id xp_surface_id;
57 typedef unsigned int xp_client_id;
58 typedef unsigned int xp_request_type;
63 /* Error codes that the functions declared here may return. They all
64 numerically match their X equivalents, i.e. the XP_ can be dropped
65 if <X11/X.h> has been included. */
74 XP_BadImplementation = 17,
78 /* Event types generated by the plugin. */
80 enum xp_event_type_enum {
81 /* The global display configuration changed somehow. */
82 XP_EVENT_DISPLAY_CHANGED = 1 << 0,
84 /* A window changed state. Argument is xp_window_state_event */
85 XP_EVENT_WINDOW_STATE_CHANGED = 1 << 1,
87 /* An async request encountered an error. Argument is of type
88 xp_async_error_event */
89 XP_EVENT_ASYNC_ERROR = 1 << 2,
91 /* Sent when a surface is destroyed as a side effect of destroying
92 a window. Arg is of type xp_surface_id. */
93 XP_EVENT_SURFACE_DESTROYED = 1 << 3,
95 /* Sent when any GL contexts pointing at the given surface need to
96 call xp_update_gl_context () to refresh their state (because the
97 window moved or was resized. Arg is of type xp_surface_id. */
98 XP_EVENT_SURFACE_CHANGED = 1 << 4,
100 /* Sent when a window has been moved. Arg is of type xp_window_id. */
101 XP_EVENT_WINDOW_MOVED = 1 << 5,
104 /* Function type used to receive events. */
106 typedef void (xp_event_fun) (unsigned int type, const void *arg,
107 unsigned int arg_size, void *user_data);
110 /* Operation types. Used when reporting errors asynchronously. */
112 enum xp_request_type_enum {
114 XP_REQUEST_DESTROY_WINDOW = 1,
115 XP_REQUEST_CONFIGURE_WINDOW = 2,
116 XP_REQUEST_FLUSH_WINDOW = 3,
117 XP_REQUEST_COPY_WINDOW = 4,
118 XP_REQUEST_UNLOCK_WINDOW = 5,
119 XP_REQUEST_DISABLE_UPDATE = 6,
120 XP_REQUEST_REENABLE_UPDATE = 7,
121 XP_REQUEST_HIDE_CURSOR = 8,
122 XP_REQUEST_SHOW_CURSOR = 9,
123 XP_REQUEST_FRAME_DRAW = 10,
126 /* Structure used to report an error asynchronously. Passed as the "arg"
127 of an XP_EVENT_ASYNC_ERROR event. */
129 struct xp_async_error_event_struct {
130 xp_request_type request_type;
135 typedef struct xp_async_error_event_struct xp_async_error_event;
138 /* Possible window states. */
140 enum xp_window_state_enum {
141 /* The window is not in the global list of possibly-visible windows. */
142 XP_WINDOW_STATE_OFFSCREEN = 1 << 0,
144 /* Parts of the window may be obscured by other windows. */
145 XP_WINDOW_STATE_OBSCURED = 1 << 1,
148 /* Structure passed as argument of an XP_EVENT_WINDOW_STATE_CHANGED event. */
150 struct xp_window_state_event_struct {
155 typedef struct xp_window_state_event_struct xp_window_state_event;
158 /* Function type used to supply a colormap for indexed drawables. */
160 typedef xp_error (xp_colormap_fun) (void *data, int first_color,
161 int n_colors, uint32_t *colors);
164 /* Window attributes structure. Used when creating and configuring windows.
165 Also used when configuring surfaces attached to windows. Functions that
166 take one of these structures also take a bit mask defining which
167 fields are set to meaningful values. */
169 enum xp_window_changes_enum {
172 XP_BOUNDS = XP_ORIGIN | XP_SIZE,
174 XP_STACKING = 1 << 3,
176 XP_COLORMAP = 1 << 5,
177 XP_WINDOW_LEVEL = 1 << 6,
180 struct xp_window_changes_struct {
185 unsigned int width, height;
186 int bit_gravity; /* how to resize the backing store */
189 int shape_nrects; /* -1 = remove shape */
191 int shape_tx, shape_ty; /* translation for shape */
195 xp_window_id sibling; /* may be zero; in ABOVE/BELOW modes
196 it may specify a relative window */
197 /* XP_DEPTH, window-only */
200 /* XP_COLORMAP, window-only */
201 xp_colormap_fun *colormap;
204 /* XP_WINDOW_LEVEL, window-only */
208 typedef struct xp_window_changes_struct xp_window_changes;
210 /* Values for bit_gravity field */
212 enum xp_bit_gravity_enum {
213 XP_GRAVITY_NONE = 0, /* no gravity, fill everything */
214 XP_GRAVITY_NORTH_WEST = 1, /* anchor to top-left corner */
215 XP_GRAVITY_NORTH_EAST = 2, /* anchor to top-right corner */
216 XP_GRAVITY_SOUTH_EAST = 3, /* anchor to bottom-right corner */
217 XP_GRAVITY_SOUTH_WEST = 4, /* anchor to bottom-left corner */
220 /* Values for stack_mode field */
222 enum xp_window_stack_mode_enum {
223 XP_UNMAPPED = 0, /* remove the window */
224 XP_MAPPED_ABOVE = 1, /* display the window on top */
225 XP_MAPPED_BELOW = 2, /* display the window at bottom */
228 /* Data formats for depth field and composite functions */
231 XP_DEPTH_NIL = 0, /* null source when compositing */
234 XP_DEPTH_A8, /* for masks when compositing */
238 /* Options that may be passed to the xp_init () function. */
240 enum xp_init_options_enum {
241 /* Don't mark that this process can be in the foreground. */
242 XP_IN_BACKGROUND = 1 << 0,
244 /* Deliver background pointer events to this process. */
245 XP_BACKGROUND_EVENTS = 1 << 1,
250 /* Miscellaneous functions */
252 /* Initialize the plugin library. Only the copy/fill/composite functions
253 may be called without having previously called xp_init () */
255 extern xp_error xp_init (unsigned int options);
257 /* Sets the current set of requested notifications to MASK. When any of
258 these arrive, CALLBACK will be invoked with CALLBACK-DATA. Note that
259 calling this function cancels any previously requested notifications
260 that aren't set in MASK. */
262 extern xp_error xp_select_events (unsigned int mask,
263 xp_event_fun *callback,
264 void *callback_data);
266 /* Waits for all initiated operations to complete. */
268 extern xp_error xp_synchronize (void);
270 /* Causes any display update initiated through the plugin libary to be
271 queued until update is reenabled. Note that calls to these functions
274 extern xp_error xp_disable_update (void);
275 extern xp_error xp_reenable_update (void);
279 /* Cursor functions. */
281 /* Installs the specified cursor. ARGB-DATA should point to 32-bit
282 premultiplied big-endian ARGB data. The HOT-X,HOT-Y parameters
283 specify the offset to the cursor's hot spot from its top-left
286 extern xp_error xp_set_cursor (unsigned int width, unsigned int height,
287 unsigned int hot_x, unsigned int hot_y,
288 const uint32_t *argb_data,
289 unsigned int rowbytes);
291 /* Hide and show the cursor if it's owned by the current process. Calls
292 to these functions nest. */
294 extern xp_error xp_hide_cursor (void);
295 extern xp_error xp_show_cursor (void);
299 /* Window functions. */
301 /* Create a new window as defined by MASK and VALUES. MASK must contain
302 XP_BOUNDS or an error is raised. The id of the newly created window
303 is stored in *RET-ID if this function returns XP_Success. */
305 extern xp_error xp_create_window (unsigned int mask,
306 const xp_window_changes *values,
307 xp_window_id *ret_id);
309 /* Destroys the window identified by ID. */
311 extern xp_error xp_destroy_window (xp_window_id id);
313 /* Reconfigures the given window according to MASK and VALUES. */
315 extern xp_error xp_configure_window (xp_window_id id, unsigned int mask,
316 const xp_window_changes *values);
319 /* Returns true if NATIVE-ID is a window created by the plugin library.
320 If so and RET-ID is non-null, stores the id of the window in *RET-ID. */
322 extern xp_bool xp_lookup_native_window (unsigned int native_id,
323 xp_window_id *ret_id);
325 /* If ID names a window created by the plugin library, stores it's native
326 window id in *RET-NATIVE-ID. */
328 extern xp_error xp_get_native_window (xp_window_id id,
329 unsigned int *ret_native_id);
332 /* Locks the rectangle IN-RECT (or, if null, the entire window) of the
333 given window's backing store. Any other non-null parameters are filled
336 DEPTH = format of returned data. Currently either XP_DEPTH_ARGB8888
337 or XP_DEPTH_RGB565 (possibly with 8 bit planar alpha). Data is
338 always stored in native byte order.
340 BITS[0] = pointer to top-left pixel of locked color data
341 BITS[1] = pointer to top-left of locked alpha data, or null if window
342 has no alpha. If the alpha data is meshed, then BITS[1] = BITS[0].
344 ROWBYTES[0,1] = size in bytes of each row of color,alpha data
346 OUT-RECT = rectangle specifying the current position and size of the
347 locked region relative to the window origin.
349 Note that an error is raised when trying to lock an already locked
350 window. While the window is locked, the only operations that may
351 be performed on it are to modify, access or flush its marked region. */
353 extern xp_error xp_lock_window (xp_window_id id,
354 const xp_box *in_rect,
357 unsigned int rowbytes[2],
360 /* Mark that the region specified by SHAPE-NRECTS, SHAPE-RECTS,
361 SHAPE-TX, and SHAPE-TY in the specified window has been updated, and
362 will need to subsequently be redisplayed. */
364 extern xp_error xp_mark_window (xp_window_id id, int shape_nrects,
365 const xp_box *shape_rects,
366 int shape_tx, int shape_ty);
368 /* Unlocks the specified window. If FLUSH is true, then any marked
369 regions are immediately redisplayed. Note that it's an error to
370 unlock an already unlocked window. */
372 extern xp_error xp_unlock_window (xp_window_id id, xp_bool flush);
374 /* If anything is marked in the given window for redisplay, do it now. */
376 extern xp_error xp_flush_window (xp_window_id id);
378 /* Moves the contents of the region DX,DY pixels away from that specified
379 by DST_RECTS and DST_NRECTS in the window with SRC-ID to the
380 destination region in the window DST-ID. Note that currently source
381 and destination windows must be the same. */
383 extern xp_error xp_copy_window (xp_window_id src_id, xp_window_id dst_id,
384 int dst_nrects, const xp_box *dst_rects,
387 /* Returns true if the given window has any regions marked for
390 extern xp_bool xp_is_window_marked (xp_window_id id);
392 /* If successful returns a superset of the region marked for update in
393 the given window. Use xp_free_region () to release the returned data. */
395 extern xp_error xp_get_marked_shape (xp_window_id id,
396 int *ret_nrects, xp_box **ret_rects);
398 extern void xp_free_shape (int nrects, xp_box *rects);
400 /* Searches for the first window below ABOVE-ID containing the point X,Y,
401 and returns it's window id in *RET-ID. If no window is found, *RET-ID
402 is set to zero. If ABOVE-ID is zero, finds the topmost window
403 containing the given point. */
405 extern xp_error xp_find_window (int x, int y, xp_window_id above_id,
406 xp_window_id *ret_id);
408 /* Returns the current origin and size of the window ID in *BOUNDS-RET if
410 extern xp_error xp_get_window_bounds (xp_window_id id, xp_box *bounds_ret);
414 /* Window surface functions. */
416 /* Create a new VRAM surface on the specified window. If successful,
417 returns the identifier of the new surface in *RET-SID. */
419 extern xp_error xp_create_surface (xp_window_id id, xp_surface_id *ret_sid);
421 /* Destroys the specified surface. */
423 extern xp_error xp_destroy_surface (xp_surface_id sid);
425 /* Reconfigures the specified surface as defined by MASK and VALUES.
426 Note that specifying XP_DEPTH is an error. */
428 extern xp_error xp_configure_surface (xp_surface_id sid, unsigned int mask,
429 const xp_window_changes *values);
431 /* If successful, places the client identifier of the current process
434 extern xp_error xp_get_client_id (xp_client_id *ret_client);
436 /* Given a valid window,surface combination created by the current
437 process, attempts to allow the specified external client access
438 to that surface. If successful, returns two integers in RET-KEY
439 which the client can use to import the surface into their process. */
441 extern xp_error xp_export_surface (xp_window_id wid, xp_surface_id sid,
443 unsigned int ret_key[2]);
445 /* Given a two integer key returned from xp_export_surface (), tries
446 to import the surface into the current process. If successful the
447 local surface identifier is stored in *SID-RET. */
449 extern xp_error xp_import_surface (const unsigned int key[2],
450 xp_surface_id *sid_ret);
452 /* If successful, stores the number of surfaces attached to the
453 specified window in *RET. */
455 extern xp_error xp_get_window_surface_count (xp_window_id id,
458 /* Attaches the CGLContextObj CGL-CTX to the specified surface. */
460 extern xp_error xp_attach_gl_context (void *cgl_ctx, xp_surface_id sid);
462 /* Updates the CGLContextObj CGL-CTX to reflect any recent changes to
463 the surface it's attached to. */
465 extern xp_error xp_update_gl_context (void *cgl_ctx);
469 /* Window frame functions. */
471 /* Possible arguments to xp_frame_get_rect (). */
473 enum xp_frame_rect_enum {
474 XP_FRAME_RECT_TITLEBAR = 1,
475 XP_FRAME_RECT_TRACKING = 2,
476 XP_FRAME_RECT_GROWBOX = 3,
479 /* Classes of window frame. */
481 enum xp_frame_class_enum {
482 XP_FRAME_CLASS_DOCUMENT = 1 << 0,
483 XP_FRAME_CLASS_DIALOG = 1 << 1,
484 XP_FRAME_CLASS_MODAL_DIALOG = 1 << 2,
485 XP_FRAME_CLASS_SYSTEM_MODAL_DIALOG = 1 << 3,
486 XP_FRAME_CLASS_UTILITY = 1 << 4,
487 XP_FRAME_CLASS_TOOLBAR = 1 << 5,
488 XP_FRAME_CLASS_MENU = 1 << 6,
489 XP_FRAME_CLASS_SPLASH = 1 << 7,
490 XP_FRAME_CLASS_BORDERLESS = 1 << 8,
493 /* Attributes of window frames. */
495 enum xp_frame_attr_enum {
496 XP_FRAME_ACTIVE = 0x0001,
497 XP_FRAME_URGENT = 0x0002,
498 XP_FRAME_TITLE = 0x0004,
499 XP_FRAME_PRELIGHT = 0x0008,
500 XP_FRAME_SHADED = 0x0010,
501 XP_FRAME_CLOSE_BOX = 0x0100,
502 XP_FRAME_COLLAPSE = 0x0200,
503 XP_FRAME_ZOOM = 0x0400,
504 XP_FRAME_ANY_BUTTON = 0x0700,
505 XP_FRAME_CLOSE_BOX_CLICKED = 0x0800,
506 XP_FRAME_COLLAPSE_BOX_CLICKED = 0x1000,
507 XP_FRAME_ZOOM_BOX_CLICKED = 0x2000,
508 XP_FRAME_ANY_CLICKED = 0x3800,
509 XP_FRAME_GROW_BOX = 0x4000,
512 #define XP_FRAME_ATTR_IS_SET(a,b) (((a) & (b)) == (b))
513 #define XP_FRAME_ATTR_IS_CLICKED(a,m) ((a) & ((m) << 3))
514 #define XP_FRAME_ATTR_SET_CLICKED(a,m) ((a) |= ((m) << 3))
515 #define XP_FRAME_ATTR_UNSET_CLICKED(a,m) ((a) &= ~((m) << 3))
517 #define XP_FRAME_POINTER_ATTRS (XP_FRAME_PRELIGHT \
518 | XP_FRAME_ANY_BUTTON \
519 | XP_FRAME_ANY_CLICKED)
521 extern xp_error xp_frame_get_rect (int type, int class, const xp_box *outer,
522 const xp_box *inner, xp_box *ret);
523 extern xp_error xp_frame_hit_test (int class, int x, int y,
525 const xp_box *inner, int *ret);
526 extern xp_error xp_frame_draw (xp_window_id wid, int class, unsigned int attr,
527 const xp_box *outer, const xp_box *inner,
528 unsigned int title_len,
529 const unsigned char *title_bytes);
533 /* Memory manipulation functions. */
535 enum xp_composite_op_enum {
536 XP_COMPOSITE_SRC = 0,
540 #define XP_COMPOSITE_FUNCTION(op, src_depth, mask_depth, dest_depth) \
541 (((op) << 24) | ((src_depth) << 16) \
542 | ((mask_depth) << 8) | ((dest_depth) << 0))
544 #define XP_COMPOSITE_FUNCTION_OP(f) (((f) >> 24) & 255)
545 #define XP_COMPOSITE_FUNCTION_SRC_DEPTH(f) (((f) >> 16) & 255)
546 #define XP_COMPOSITE_FUNCTION_MASK_DEPTH(f) (((f) >> 8) & 255)
547 #define XP_COMPOSITE_FUNCTION_DEST_DEPTH(f) (((f) >> 0) & 255)
549 /* Composite WIDTH by HEIGHT pixels from source and mask to destination
550 using a specified function (if source and destination overlap,
551 undefined behavior results).
553 For SRC and DEST, the first element of the array is the color data. If
554 the second element is non-null it implies that there is alpha data
555 (which may be meshed or planar). Data without alpha is assumed to be
558 Passing a null SRC-ROWBYTES pointer implies that the data SRC points
559 to is a single element.
561 Operations that are not supported will return XP_BadImplementation. */
563 extern xp_error xp_composite_pixels (unsigned int width, unsigned int height,
564 unsigned int function,
565 void *src[2], unsigned int src_rowbytes[2],
566 void *mask, unsigned int mask_rowbytes,
567 void *dest[2], unsigned int dest_rowbytes[2]);
569 /* Fill HEIGHT rows of data starting at DST. Each row will have WIDTH
570 bytes filled with the 32-bit pattern VALUE. Each row is DST-ROWBYTES
573 extern void xp_fill_bytes (unsigned int width,
574 unsigned int height, uint32_t value,
575 void *dst, unsigned int dst_rowbytes);
577 /* Copy HEIGHT rows of bytes from SRC to DST. Each row will have WIDTH
578 bytes copied. SRC and DST may overlap, and the right thing will happen. */
580 extern void xp_copy_bytes (unsigned int width, unsigned int height,
581 const void *src, unsigned int src_rowbytes,
582 void *dst, unsigned int dst_rowbytes);
584 /* Suggestions for the minimum number of bytes or pixels for which it
585 makes sense to use some of the xp_ functions */
587 extern unsigned int xp_fill_bytes_threshold, xp_copy_bytes_threshold,
588 xp_composite_area_threshold, xp_scroll_area_threshold;
591 #endif /* XPLUGIN_H */