/* * Cogl * * A Low Level GPU Graphics and Utilities API * * Copyright (C) 2011,2012,2013 Intel Corporation. * * Permission is hereby granted, free of charge, to any person * obtaining a copy of this software and associated documentation * files (the "Software"), to deal in the Software without * restriction, including without limitation the rights to use, copy, * modify, merge, publish, distribute, sublicense, and/or sell copies * of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be * included in all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE * SOFTWARE. * * * * Authors: * Robert Bragg */ #if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION) #error "Only can be included directly." #endif #ifndef __COGL_ONSCREEN_H #define __COGL_ONSCREEN_H #include #include #include #include COGL_BEGIN_DECLS typedef struct _CoglOnscreen CoglOnscreen; #define COGL_ONSCREEN(X) ((CoglOnscreen *)(X)) /** * cogl_onscreen_new: (constructor) * @context: A #CoglContext * @width: The desired framebuffer width * @height: The desired framebuffer height * * Instantiates an "unallocated" #CoglOnscreen framebuffer that may be * configured before later being allocated, either implicitly when * it is first used or explicitly via cogl_framebuffer_allocate(). * * Return value: (transfer full): A newly instantiated #CoglOnscreen framebuffer * Since: 1.8 * Stability: unstable */ CoglOnscreen * cogl_onscreen_new (CoglContext *context, int width, int height); #ifdef COGL_HAS_X11 typedef void (*CoglOnscreenX11MaskCallback) (CoglOnscreen *onscreen, uint32_t event_mask, void *user_data); /** * cogl_x11_onscreen_set_foreign_window_xid: * @onscreen: The unallocated framebuffer to associated with an X * window. * @xid: The XID of an existing X window * @update: A callback that notifies of updates to what Cogl requires * to be in the core X protocol event mask. * @user_data: user data passed to @update * * Ideally we would recommend that you let Cogl be responsible for * creating any X window required to back an onscreen framebuffer but * if you really need to target a window created manually this * function can be called before @onscreen has been allocated to set a * foreign XID for your existing X window. * * Since Cogl needs, for example, to track changes to the size of an X * window it requires that certain events be selected for via the core * X protocol. This requirement may also be changed asynchronously so * you must pass in an @update callback to inform you of Cogl's * required event mask. * * For example if you are using Xlib you could use this API roughly * as follows: * [{ * static void * my_update_cogl_x11_event_mask (CoglOnscreen *onscreen, * uint32_t event_mask, * void *user_data) * { * XSetWindowAttributes attrs; * MyData *data = user_data; * attrs.event_mask = event_mask | data->my_event_mask; * XChangeWindowAttributes (data->xdpy, * data->xwin, * CWEventMask, * &attrs); * } * * { * *snip* * cogl_x11_onscreen_set_foreign_window_xid (onscreen, * data->xwin, * my_update_cogl_x11_event_mask, * data); * *snip* * } * }] * * Since: 2.0 * Stability: Unstable */ void cogl_x11_onscreen_set_foreign_window_xid (CoglOnscreen *onscreen, uint32_t xid, CoglOnscreenX11MaskCallback update, void *user_data); /** * cogl_x11_onscreen_get_window_xid: * @onscreen: A #CoglOnscreen framebuffer * * Assuming you know the given @onscreen framebuffer is based on an x11 window * this queries the XID of that window. If * cogl_x11_onscreen_set_foreign_window_xid() was previously called then it * will return that same XID otherwise it will be the XID of a window Cogl * created internally. If the window has not been allocated yet and a foreign * xid has not been set then it's undefined what value will be returned. * * It's undefined what this function does if called when not using an x11 based * renderer. * * Since: 1.10 * Stability: unstable */ uint32_t cogl_x11_onscreen_get_window_xid (CoglOnscreen *onscreen); /* XXX: we should maybe remove this, since nothing currently uses * it and the current implementation looks dubious. */ uint32_t cogl_x11_onscreen_get_visual_xid (CoglOnscreen *onscreen); #endif /* COGL_HAS_X11 */ #ifdef COGL_HAS_WIN32_SUPPORT /** * cogl_win32_onscreen_set_foreign_window: * @onscreen: A #CoglOnscreen framebuffer * @hwnd: A win32 window handle * * Ideally we would recommend that you let Cogl be responsible for * creating any window required to back an onscreen framebuffer but * if you really need to target a window created manually this * function can be called before @onscreen has been allocated to set a * foreign XID for your existing X window. * * Since: 1.10 * Stability: unstable */ void cogl_win32_onscreen_set_foreign_window (CoglOnscreen *onscreen, HWND hwnd); /** * cogl_win32_onscreen_get_window: * @onscreen: A #CoglOnscreen framebuffer * * Queries the internally created window HWND backing the given @onscreen * framebuffer. If cogl_win32_onscreen_set_foreign_window() has been used then * it will return the same handle set with that API. * * Since: 1.10 * Stability: unstable */ HWND cogl_win32_onscreen_get_window (CoglOnscreen *onscreen); #endif /* COGL_HAS_WIN32_SUPPORT */ #if defined (COGL_HAS_EGL_PLATFORM_WAYLAND_SUPPORT) struct wl_surface * cogl_wayland_onscreen_get_surface (CoglOnscreen *onscreen); struct wl_shell_surface * cogl_wayland_onscreen_get_shell_surface (CoglOnscreen *onscreen); /** * cogl_wayland_onscreen_set_foreign_surface: * @onscreen: An unallocated framebuffer. * @surface A Wayland surface to associate with the @onscreen. * * Allows you to explicitly notify Cogl of an existing Wayland surface to use, * which prevents Cogl from allocating a surface and shell surface for the * @onscreen. An allocated surface will not be destroyed when the @onscreen is * freed. * * This function must be called before @onscreen is allocated. * * Since: 1.16 * Stability: unstable */ void cogl_wayland_onscreen_set_foreign_surface (CoglOnscreen *onscreen, struct wl_surface *surface); /** * cogl_wayland_onscreen_resize: * @onscreen: A #CoglOnscreen framebuffer * @width: The desired width of the framebuffer * @height: The desired height of the framebuffer * @offset_x: A relative x offset for the new framebuffer * @offset_y: A relative y offset for the new framebuffer * * Resizes the backbuffer of the given @onscreen framebuffer to the * given size. Since a buffer is usually conceptually scaled with a * center point the @offset_x and @offset_y arguments allow the newly * allocated buffer to be positioned relative to the old buffer size. * * For example a buffer that is being resized by moving the bottom right * corner, and the top left corner is remaining static would use x and y * offsets of (0, 0) since the top-left of the new buffer should have the same * position as the old buffer. If the center of the old buffer is being zoomed * into then all the corners of the new buffer move out from the center and the x * and y offsets would be (-half_x_size_increase, -half_y_size_increase) where * x/y_size_increase is how many pixels bigger the buffer is on the x and y * axis. * * Note that if some drawing commands have been applied to the * framebuffer since the last swap buffers then the resize will be * queued and will only take effect in the next swap buffers. * * If multiple calls to cogl_wayland_onscreen_resize() get queued * before the next swap buffers request then the relative x and y * offsets accumulate instead of being replaced. The @width and * @height values superseed the old values. * * Since: 1.10 * Stability: unstable */ void cogl_wayland_onscreen_resize (CoglOnscreen *onscreen, int width, int height, int offset_x, int offset_y); #endif /* COGL_HAS_EGL_PLATFORM_WAYLAND_SUPPORT */ /** * cogl_onscreen_set_swap_throttled: * @onscreen: A #CoglOnscreen framebuffer * @throttled: Whether swap throttling is wanted or not. * * Requests that the given @onscreen framebuffer should have swap buffer * requests (made using cogl_onscreen_swap_buffers()) throttled either by a * displays vblank period or perhaps some other mechanism in a composited * environment. * * Since: 1.8 * Stability: unstable */ void cogl_onscreen_set_swap_throttled (CoglOnscreen *onscreen, CoglBool throttled); /** * cogl_onscreen_show: * @onscreen: The onscreen framebuffer to make visible * * This requests to make @onscreen visible to the user. * * Actually the precise semantics of this function depend on the * window system currently in use, and if you don't have a * multi-windowining system this function may in-fact do nothing. * * This function will implicitly allocate the given @onscreen * framebuffer before showing it if it hasn't already been allocated. * * When using the Wayland winsys calling this will set the surface to * a toplevel type which will make it appear. If the application wants * to set a different type for the surface, it can avoid calling * cogl_onscreen_show() and set its own type directly with the Wayland * client API via cogl_wayland_onscreen_get_surface(). * * Since Cogl doesn't explicitly track the visibility status of * onscreen framebuffers it wont try to avoid redundant window system * requests e.g. to show an already visible window. This also means * that it's acceptable to alternatively use native APIs to show and * hide windows without confusing Cogl. * * Since: 2.0 * Stability: Unstable */ void cogl_onscreen_show (CoglOnscreen *onscreen); /** * cogl_onscreen_hide: * @onscreen: The onscreen framebuffer to make invisible * * This requests to make @onscreen invisible to the user. * * Actually the precise semantics of this function depend on the * window system currently in use, and if you don't have a * multi-windowining system this function may in-fact do nothing. * * This function does not implicitly allocate the given @onscreen * framebuffer before hiding it. * * Since Cogl doesn't explicitly track the visibility status of * onscreen framebuffers it wont try to avoid redundant window system * requests e.g. to show an already visible window. This also means * that it's acceptable to alternatively use native APIs to show and * hide windows without confusing Cogl. * * Since: 2.0 * Stability: Unstable */ void cogl_onscreen_hide (CoglOnscreen *onscreen); /** * cogl_onscreen_swap_buffers: * @onscreen: A #CoglOnscreen framebuffer * * Swaps the current back buffer being rendered too, to the front for display. * * This function also implicitly discards the contents of the color, depth and * stencil buffers as if cogl_framebuffer_discard_buffers() were used. The * significance of the discard is that you should not expect to be able to * start a new frame that incrementally builds on the contents of the previous * frame. * * It is highly recommended that applications use * cogl_onscreen_swap_buffers_with_damage() instead whenever possible * and also use the cogl_onscreen_get_buffer_age() api so they can * perform incremental updates to older buffers instead of having to * render a full buffer for every frame. * * Since: 1.10 * Stability: unstable */ void cogl_onscreen_swap_buffers (CoglOnscreen *onscreen); /** * cogl_onscreen_get_buffer_age: * @onscreen: A #CoglOnscreen framebuffer * * Gets the current age of the buffer contents. * * This function allows applications to query the age of the current * back buffer contents for a #CoglOnscreen as the number of frames * elapsed since the contents were most recently defined. * * These age values exposes enough information to applications about * how Cogl internally manages back buffers to allow applications to * re-use the contents of old frames and minimize how much must be * redrawn for the next frame. * * The back buffer contents can either be reported as invalid (has an * age of 0) or it may be reported to be the same contents as from n * frames prior to the current frame. * * The queried value remains valid until the next buffer swap. * * One caveat is that under X11 the buffer age does not reflect * changes to buffer contents caused by the window systems. X11 * applications must track Expose events to determine what buffer * regions need to additionally be repaired each frame. * * The recommended way to take advantage of this buffer age api is to * build up a circular buffer of length 3 for tracking damage regions * over the last 3 frames and when starting a new frame look at the * age of the buffer and combine the damage regions for the current * frame with the damage regions of previous @age frames so you know * everything that must be redrawn to update the old contents for the * new frame. * * If the system doesn't not support being able to track the age * of back buffers then this function will always return 0 which * implies that the contents are undefined. * * Return value: The age of the buffer contents or 0 when the buffer * contents are undefined. * * Since: 1.14 * Stability: stable */ int cogl_onscreen_get_buffer_age (CoglOnscreen *onscreen); /** * cogl_onscreen_swap_buffers_with_damage: * @onscreen: A #CoglOnscreen framebuffer * @rectangles: An array of integer 4-tuples representing damaged * rectangles as (x, y, width, height) tuples. * @n_rectangles: The number of 4-tuples to be read from @rectangles * * Swaps the current back buffer being rendered too, to the front for * display and provides information to any system compositor about * what regions of the buffer have changed (damage) with respect to * the last swapped buffer. * * This function has the same semantics as * cogl_framebuffer_swap_buffers() except that it additionally allows * applications to pass a list of damaged rectangles which may be * passed on to a compositor so that it can minimize how much of the * screen is redrawn in response to this applications newly swapped * front buffer. * * For example if your application is only animating a small object in * the corner of the screen and everything else is remaining static * then it can help the compositor to know that only the bottom right * corner of your newly swapped buffer has really changed with respect * to your previously swapped front buffer. * * If @n_rectangles is 0 then the whole buffer will implicitly be * reported as damaged as if cogl_onscreen_swap_buffers() had been * called. * * This function also implicitly discards the contents of the color, * depth and stencil buffers as if cogl_framebuffer_discard_buffers() * were used. The significance of the discard is that you should not * expect to be able to start a new frame that incrementally builds on * the contents of the previous frame. If you want to perform * incremental updates to older back buffers then please refer to the * cogl_onscreen_get_buffer_age() api. * * Whenever possible it is recommended that applications use this * function instead of cogl_onscreen_swap_buffers() to improve * performance when running under a compositor. * * It is highly recommended to use this API in conjunction with * the cogl_onscreen_get_buffer_age() api so that your application can * perform incremental rendering based on old back buffers. * * Since: 1.16 * Stability: unstable */ void cogl_onscreen_swap_buffers_with_damage (CoglOnscreen *onscreen, const int *rectangles, int n_rectangles); /** * cogl_onscreen_swap_region: * @onscreen: A #CoglOnscreen framebuffer * @rectangles: An array of integer 4-tuples representing rectangles as * (x, y, width, height) tuples. * @n_rectangles: The number of 4-tuples to be read from @rectangles * * Swaps a region of the back buffer being rendered too, to the front for * display. @rectangles represents the region as array of @n_rectangles each * defined by 4 sequential (x, y, width, height) integers. * * This function also implicitly discards the contents of the color, depth and * stencil buffers as if cogl_framebuffer_discard_buffers() were used. The * significance of the discard is that you should not expect to be able to * start a new frame that incrementally builds on the contents of the previous * frame. * * Since: 1.10 * Stability: unstable */ void cogl_onscreen_swap_region (CoglOnscreen *onscreen, const int *rectangles, int n_rectangles); /** * CoglFrameEvent: * @COGL_FRAME_EVENT_SYNC: Notifies that the system compositor has * acknowledged a frame and is ready for a * new frame to be created. * @COGL_FRAME_EVENT_COMPLETE: Notifies that a frame has ended. This * is a good time for applications to * collect statistics about the frame * since the #CoglFrameInfo should hold * the most data at this point. No other * events should be expected after a * @COGL_FRAME_EVENT_COMPLETE event. * * Identifiers that are passed to #CoglFrameCallback functions * (registered using cogl_onscreen_add_frame_callback()) that * mark the progression of a frame in some way which usually * means that new information will have been accumulated in the * frame's corresponding #CoglFrameInfo object. * * The last event that will be sent for a frame will be a * @COGL_FRAME_EVENT_COMPLETE event and so these are a good * opportunity to collect statistics about a frame since the * #CoglFrameInfo should hold the most data at this point. * * A frame may not be completed before the next frame can start * so applications should avoid needing to collect all statistics for * a particular frame before they can start a new frame. * * Since: 1.14 * Stability: unstable */ typedef enum _CoglFrameEvent { COGL_FRAME_EVENT_SYNC = 1, COGL_FRAME_EVENT_COMPLETE } CoglFrameEvent; /** * CoglFrameCallback: * @onscreen: The onscreen that the frame is associated with * @event: A #CoglFrameEvent notifying how the frame has progressed * @info: The meta information, such as timing information, about * the frame that has progressed. * @user_data: The user pointer passed to * cogl_onscreen_add_frame_callback() * * Is a callback that can be registered via * cogl_onscreen_add_frame_callback() to be called when a frame * progresses in some notable way. * * Please see the documentation for #CoglFrameEvent and * cogl_onscreen_add_frame_callback() for more details about what * events can be notified. * * Since: 1.14 * Stability: unstable */ typedef void (*CoglFrameCallback) (CoglOnscreen *onscreen, CoglFrameEvent event, CoglFrameInfo *info, void *user_data); /** * CoglFrameClosure: * * An opaque type that tracks a #CoglFrameCallback and associated user * data. A #CoglFrameClosure pointer will be returned from * cogl_onscreen_add_frame_callback() and it allows you to remove a * callback later using cogl_onscreen_remove_frame_callback(). * * Since: 1.14 * Stability: unstable */ typedef struct _CoglClosure CoglFrameClosure; /** * cogl_onscreen_add_frame_callback: * @onscreen: A #CoglOnscreen framebuffer * @callback: (scope notified): A callback function to call for frame events * @user_data: (closure): A private pointer to be passed to @callback * @destroy: (allow-none): An optional callback to destroy @user_data * when the @callback is removed or @onscreen is freed. * * Installs a @callback function that will be called for significant * events relating to the given @onscreen framebuffer. * * The @callback will be used to notify when the system compositor is * ready for this application to render a new frame. In this case * %COGL_FRAME_EVENT_SYNC will be passed as the event argument to the * given @callback in addition to the #CoglFrameInfo corresponding to * the frame beeing acknowledged by the compositor. * * The @callback will also be called to notify when the frame has * ended. In this case %COGL_FRAME_EVENT_COMPLETE will be passed as * the event argument to the given @callback in addition to the * #CoglFrameInfo corresponding to the newly presented frame. The * meaning of "ended" here simply means that no more timing * information will be collected within the corresponding * #CoglFrameInfo and so this is a good opportunity to analyse the * given info. It does not necessarily mean that the GPU has finished * rendering the corresponding frame. * * We highly recommend throttling your application according to * %COGL_FRAME_EVENT_SYNC events so that your application can avoid * wasting resources, drawing more frames than your system compositor * can display. * * Return value: a #CoglFrameClosure pointer that can be used to * remove the callback and associated @user_data later. * Since: 1.14 * Stability: unstable */ CoglFrameClosure * cogl_onscreen_add_frame_callback (CoglOnscreen *onscreen, CoglFrameCallback callback, void *user_data, CoglUserDataDestroyCallback destroy); /** * cogl_onscreen_remove_frame_callback: * @onscreen: A #CoglOnscreen * @closure: A #CoglFrameClosure returned from * cogl_onscreen_add_frame_callback() * * Removes a callback and associated user data that were previously * registered using cogl_onscreen_add_frame_callback(). * * If a destroy callback was passed to * cogl_onscreen_add_frame_callback() to destroy the user data then * this will get called. * * Since: 1.14 * Stability: unstable */ void cogl_onscreen_remove_frame_callback (CoglOnscreen *onscreen, CoglFrameClosure *closure); typedef void (*CoglSwapBuffersNotify) (CoglFramebuffer *framebuffer, void *user_data); /** * cogl_onscreen_add_swap_buffers_callback: * @onscreen: A #CoglOnscreen framebuffer * @callback: (scope notified): A callback function to call when a swap * has completed * @user_data: (closure): A private pointer to be passed to @callback * * Installs a @callback function that should be called whenever a swap buffers * request (made using cogl_onscreen_swap_buffers()) for the given * @onscreen completes. * * Applications should check for the %COGL_FEATURE_ID_SWAP_BUFFERS_EVENT * feature before using this API. It's currently undefined when and if * registered callbacks will be called if this feature is not supported. * * We recommend using this mechanism when available to manually throttle your * applications (in conjunction with cogl_onscreen_set_swap_throttled()) so * your application will be able to avoid long blocks in the driver caused by * throttling when you request to swap buffers too quickly. * * Return value: a unique identifier that can be used to remove to remove * the callback later. * Since: 1.10 * Stability: unstable * Deprecated: 1.14: Use cogl_onscreen_add_frame_callback() instead */ COGL_DEPRECATED_IN_1_14_FOR (cogl_onscreen_add_frame_callback) unsigned int cogl_onscreen_add_swap_buffers_callback (CoglOnscreen *onscreen, CoglSwapBuffersNotify callback, void *user_data); /** * cogl_onscreen_remove_swap_buffers_callback: * @onscreen: A #CoglOnscreen framebuffer * @id: An identifier returned from cogl_onscreen_add_swap_buffers_callback() * * Removes a callback that was previously registered * using cogl_onscreen_add_swap_buffers_callback(). * * Since: 1.10 * Stability: unstable * Deprecated: 1.14: Use cogl_onscreen_remove_frame_callback() instead */ COGL_DEPRECATED_IN_1_14_FOR (cogl_onscreen_remove_frame_callback) void cogl_onscreen_remove_swap_buffers_callback (CoglOnscreen *onscreen, unsigned int id); /** * cogl_onscreen_set_resizable: * @onscreen: A #CoglOnscreen framebuffer * * Lets you request Cogl to mark an @onscreen framebuffer as * resizable or not. * * By default, if possible, a @onscreen will be created by Cogl * as non resizable, but it is not guaranteed that this is always * possible for all window systems. * * Cogl does not know whether marking the @onscreen framebuffer * is truly meaningful for your current window system (consider * applications being run fullscreen on a phone or TV) so this * function may not have any useful effect. If you are running on a * multi windowing system such as X11 or Win32 or OSX then Cogl will * request to the window system that users be allowed to resize the * @onscreen, although it's still possible that some other window * management policy will block this possibility. * * Whenever an @onscreen framebuffer is resized the viewport * will be automatically updated to match the new size of the * framebuffer with an origin of (0,0). If your application needs more * specialized control of the viewport it will need to register a * resize handler using cogl_onscreen_add_resize_callback() so that it * can track when the viewport has been changed automatically. * * Since: 2.0 */ void cogl_onscreen_set_resizable (CoglOnscreen *onscreen, CoglBool resizable); /** * cogl_onscreen_get_resizable: * @onscreen: A #CoglOnscreen framebuffer * * Lets you query whether @onscreen has been marked as resizable via * the cogl_onscreen_set_resizable() api. * * By default, if possible, a @onscreen will be created by Cogl * as non resizable, but it is not guaranteed that this is always * possible for all window systems. * * If cogl_onscreen_set_resizable(@onscreen, %TRUE) has been * previously called then this function will return %TRUE, but it's * possible that the current windowing system being used does not * support window resizing (consider fullscreen windows on a phone or * a TV). This function is not aware of whether resizing is truly * meaningful with your window system, only whether the @onscreen has * been marked as resizable. * * Return value: Returns whether @onscreen has been marked as * resizable or not. * Since: 2.0 */ CoglBool cogl_onscreen_get_resizable (CoglOnscreen *onscreen); /** * CoglOnscreenResizeCallback: * @onscreen: A #CoglOnscreen framebuffer that was resized * @width: The new width of @onscreen * @height: The new height of @onscreen * @user_data: The private passed to * cogl_onscreen_add_resize_callback() * * Is a callback type used with the * cogl_onscreen_add_resize_callback() allowing applications to be * notified whenever an @onscreen framebuffer is resized. * * Cogl automatically updates the viewport of an @onscreen * framebuffer that is resized so this callback is also an indication * that the viewport has been modified too * * A resize callback will only ever be called while dispatching * Cogl events from the system mainloop; so for example during * cogl_poll_renderer_dispatch(). This is so that callbacks shouldn't * occur while an application might have arbitrary locks held for * example. * * Since: 2.0 */ typedef void (*CoglOnscreenResizeCallback) (CoglOnscreen *onscreen, int width, int height, void *user_data); /** * CoglOnscreenResizeClosure: * * An opaque type that tracks a #CoglOnscreenResizeCallback and * associated user data. A #CoglOnscreenResizeClosure pointer will be * returned from cogl_onscreen_add_resize_callback() and it allows you * to remove a callback later using * cogl_onscreen_remove_resize_callback(). * * Since: 2.0 * Stability: unstable */ typedef struct _CoglClosure CoglOnscreenResizeClosure; /** * cogl_onscreen_add_resize_callback: * @onscreen: A #CoglOnscreen framebuffer * @callback: (scope notified): A #CoglOnscreenResizeCallback to call when * the @onscreen changes size. * @user_data: (closure): Private data to be passed to @callback. * @destroy: (allow-none): An optional callback to destroy @user_data * when the @callback is removed or @onscreen is freed. * * Registers a @callback with @onscreen that will be called whenever * the @onscreen framebuffer changes size. * * The @callback can be removed using * cogl_onscreen_remove_resize_callback() passing the returned closure * pointer. * * Since Cogl automatically updates the viewport of an @onscreen * framebuffer that is resized, a resize callback can also be used to * track when the viewport has been changed automatically by Cogl in * case your application needs more specialized control over the * viewport. * * A resize callback will only ever be called while dispatching * Cogl events from the system mainloop; so for example during * cogl_poll_renderer_dispatch(). This is so that callbacks shouldn't * occur while an application might have arbitrary locks held for * example. * * Return value: a #CoglOnscreenResizeClosure pointer that can be used to * remove the callback and associated @user_data later. * Since: 2.0 */ CoglOnscreenResizeClosure * cogl_onscreen_add_resize_callback (CoglOnscreen *onscreen, CoglOnscreenResizeCallback callback, void *user_data, CoglUserDataDestroyCallback destroy); /** * cogl_onscreen_remove_resize_callback: * @onscreen: A #CoglOnscreen framebuffer * @closure: An identifier returned from cogl_onscreen_add_resize_callback() * * Removes a resize @callback and @user_data pair that were previously * associated with @onscreen via cogl_onscreen_add_resize_callback(). * * Since: 2.0 */ void cogl_onscreen_remove_resize_callback (CoglOnscreen *onscreen, CoglOnscreenResizeClosure *closure); /** * CoglOnscreenDirtyInfo: * @x: Left edge of the dirty rectangle * @y: Top edge of the dirty rectangle, measured from the top of the window * @width: Width of the dirty rectangle * @height: Height of the dirty rectangle * * A structure passed to callbacks registered using * cogl_onscreen_add_dirty_callback(). The members describe a * rectangle within the onscreen buffer that should be redrawn. * * Since: 1.16 * Stability: unstable */ typedef struct _CoglOnscreenDirtyInfo CoglOnscreenDirtyInfo; struct _CoglOnscreenDirtyInfo { int x, y; int width, height; }; /** * CoglOnscreenDirtyCallback: * @onscreen: The onscreen that the frame is associated with * @info: A #CoglOnscreenDirtyInfo struct containing the details of the * dirty area * @user_data: The user pointer passed to * cogl_onscreen_add_frame_callback() * * Is a callback that can be registered via * cogl_onscreen_add_dirty_callback() to be called when the windowing * system determines that a region of the onscreen window has been * lost and the application should redraw it. * * Since: 1.16 * Stability: unstable */ typedef void (*CoglOnscreenDirtyCallback) (CoglOnscreen *onscreen, const CoglOnscreenDirtyInfo *info, void *user_data); /** * CoglOnscreenDirtyClosure: * * An opaque type that tracks a #CoglOnscreenDirtyCallback and associated * user data. A #CoglOnscreenDirtyClosure pointer will be returned from * cogl_onscreen_add_dirty_callback() and it allows you to remove a * callback later using cogl_onscreen_remove_dirty_callback(). * * Since: 1.16 * Stability: unstable */ typedef struct _CoglClosure CoglOnscreenDirtyClosure; /** * cogl_onscreen_add_dirty_callback: * @onscreen: A #CoglOnscreen framebuffer * @callback: (scope notified): A callback function to call for dirty events * @user_data: (closure): A private pointer to be passed to @callback * @destroy: (allow-none): An optional callback to destroy @user_data when the * @callback is removed or @onscreen is freed. * * Installs a @callback function that will be called whenever the * window system has lost the contents of a region of the onscreen * buffer and the application should redraw it to repair the buffer. * For example this may happen in a window system without a compositor * if a window that was previously covering up the onscreen window has * been moved causing a region of the onscreen to be exposed. * * The @callback will be passed a #CoglOnscreenDirtyInfo struct which * decribes a rectangle containing the newly dirtied region. Note that * this may be called multiple times to describe a non-rectangular * region composed of multiple smaller rectangles. * * The dirty events are separate from %COGL_FRAME_EVENT_SYNC events so * the application should also listen for this event before rendering * the dirty region to ensure that the framebuffer is actually ready * for rendering. * * Return value: a #CoglOnscreenDirtyClosure pointer that can be used to * remove the callback and associated @user_data later. * Since: 1.16 * Stability: unstable */ CoglOnscreenDirtyClosure * cogl_onscreen_add_dirty_callback (CoglOnscreen *onscreen, CoglOnscreenDirtyCallback callback, void *user_data, CoglUserDataDestroyCallback destroy); /** * cogl_onscreen_remove_dirty_callback: * @onscreen: A #CoglOnscreen * @closure: A #CoglOnscreenDirtyClosure returned from * cogl_onscreen_add_dirty_callback() * * Removes a callback and associated user data that were previously * registered using cogl_onscreen_add_dirty_callback(). * * If a destroy callback was passed to * cogl_onscreen_add_dirty_callback() to destroy the user data then * this will also get called. * * Since: 1.16 * Stability: unstable */ void cogl_onscreen_remove_dirty_callback (CoglOnscreen *onscreen, CoglOnscreenDirtyClosure *closure); /** * cogl_is_onscreen: * @object: A #CoglObject pointer * * Gets whether the given object references a #CoglOnscreen. * * Return value: %TRUE if the object references a #CoglOnscreen * and %FALSE otherwise. * Since: 1.10 * Stability: unstable */ CoglBool cogl_is_onscreen (void *object); /** * cogl_onscreen_get_frame_counter: * * Gets the value of the framebuffers frame counter. This is * a counter that increases by one each time * cogl_onscreen_swap_buffers() or cogl_onscreen_swap_region() * is called. * * Return value: the current frame counter value * Since: 1.14 * Stability: unstable */ int64_t cogl_onscreen_get_frame_counter (CoglOnscreen *onscreen); COGL_END_DECLS #endif /* __COGL_ONSCREEN_H */