4
* A Low Level GPU Graphics and Utilities API
6
* Copyright (C) 2011,2012,2013 Intel Corporation.
8
* Permission is hereby granted, free of charge, to any person
9
* obtaining a copy of this software and associated documentation
10
* files (the "Software"), to deal in the Software without
11
* restriction, including without limitation the rights to use, copy,
12
* modify, merge, publish, distribute, sublicense, and/or sell copies
13
* of the Software, and to permit persons to whom the Software is
14
* furnished to do so, subject to the following conditions:
16
* The above copyright notice and this permission notice shall be
17
* included in all copies or substantial portions of the Software.
19
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
20
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
21
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
22
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
23
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
24
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
25
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
31
* Robert Bragg <robert@linux.intel.com>
34
#if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION)
35
#error "Only <cogl/cogl.h> can be included directly."
38
#ifndef __COGL_ONSCREEN_H
39
#define __COGL_ONSCREEN_H
41
#include <cogl/cogl-context.h>
42
#include <cogl/cogl-framebuffer.h>
43
#include <cogl/cogl-frame-info.h>
44
#include <cogl/cogl-object.h>
46
#ifdef COGL_HAS_GTYPE_SUPPORT
47
#include <glib-object.h>
52
typedef struct _CoglOnscreen CoglOnscreen;
53
#define COGL_ONSCREEN(X) ((CoglOnscreen *)(X))
55
#ifdef COGL_HAS_GTYPE_SUPPORT
57
* cogl_onscreen_get_gtype:
59
* Returns: a #GType that can be used with the GLib type system.
61
GType cogl_onscreen_get_gtype (void);
65
* cogl_onscreen_new: (constructor)
66
* @context: A #CoglContext
67
* @width: The desired framebuffer width
68
* @height: The desired framebuffer height
70
* Instantiates an "unallocated" #CoglOnscreen framebuffer that may be
71
* configured before later being allocated, either implicitly when
72
* it is first used or explicitly via cogl_framebuffer_allocate().
74
* Return value: (transfer full): A newly instantiated #CoglOnscreen framebuffer
79
cogl_onscreen_new (CoglContext *context, int width, int height);
82
typedef void (*CoglOnscreenX11MaskCallback) (CoglOnscreen *onscreen,
87
* cogl_x11_onscreen_set_foreign_window_xid:
88
* @onscreen: The unallocated framebuffer to associated with an X
90
* @xid: The XID of an existing X window
91
* @update: A callback that notifies of updates to what Cogl requires
92
* to be in the core X protocol event mask.
93
* @user_data: user data passed to @update
95
* Ideally we would recommend that you let Cogl be responsible for
96
* creating any X window required to back an onscreen framebuffer but
97
* if you really need to target a window created manually this
98
* function can be called before @onscreen has been allocated to set a
99
* foreign XID for your existing X window.
101
* Since Cogl needs, for example, to track changes to the size of an X
102
* window it requires that certain events be selected for via the core
103
* X protocol. This requirement may also be changed asynchronously so
104
* you must pass in an @update callback to inform you of Cogl's
105
* required event mask.
107
* For example if you are using Xlib you could use this API roughly
111
* my_update_cogl_x11_event_mask (CoglOnscreen *onscreen,
112
* uint32_t event_mask,
115
* XSetWindowAttributes attrs;
116
* MyData *data = user_data;
117
* attrs.event_mask = event_mask | data->my_event_mask;
118
* XChangeWindowAttributes (data->xdpy,
126
* cogl_x11_onscreen_set_foreign_window_xid (onscreen,
128
* my_update_cogl_x11_event_mask,
135
* Stability: Unstable
138
cogl_x11_onscreen_set_foreign_window_xid (CoglOnscreen *onscreen,
140
CoglOnscreenX11MaskCallback update,
144
* cogl_x11_onscreen_get_window_xid:
145
* @onscreen: A #CoglOnscreen framebuffer
147
* Assuming you know the given @onscreen framebuffer is based on an x11 window
148
* this queries the XID of that window. If
149
* cogl_x11_onscreen_set_foreign_window_xid() was previously called then it
150
* will return that same XID otherwise it will be the XID of a window Cogl
151
* created internally. If the window has not been allocated yet and a foreign
152
* xid has not been set then it's undefined what value will be returned.
154
* It's undefined what this function does if called when not using an x11 based
158
* Stability: unstable
161
cogl_x11_onscreen_get_window_xid (CoglOnscreen *onscreen);
163
/* XXX: we should maybe remove this, since nothing currently uses
164
* it and the current implementation looks dubious. */
166
cogl_x11_onscreen_get_visual_xid (CoglOnscreen *onscreen);
167
#endif /* COGL_HAS_X11 */
170
* cogl_onscreen_set_swap_throttled:
171
* @onscreen: A #CoglOnscreen framebuffer
172
* @throttled: Whether swap throttling is wanted or not.
174
* Requests that the given @onscreen framebuffer should have swap buffer
175
* requests (made using cogl_onscreen_swap_buffers()) throttled either by a
176
* displays vblank period or perhaps some other mechanism in a composited
180
* Stability: unstable
183
cogl_onscreen_set_swap_throttled (CoglOnscreen *onscreen,
187
* cogl_onscreen_show:
188
* @onscreen: The onscreen framebuffer to make visible
190
* This requests to make @onscreen visible to the user.
192
* Actually the precise semantics of this function depend on the
193
* window system currently in use, and if you don't have a
194
* multi-windowining system this function may in-fact do nothing.
196
* This function will implicitly allocate the given @onscreen
197
* framebuffer before showing it if it hasn't already been allocated.
199
* When using the Wayland winsys calling this will set the surface to
200
* a toplevel type which will make it appear. If the application wants
201
* to set a different type for the surface, it can avoid calling
202
* cogl_onscreen_show() and set its own type directly with the Wayland
203
* client API via cogl_wayland_onscreen_get_surface().
205
* <note>Since Cogl doesn't explicitly track the visibility status of
206
* onscreen framebuffers it wont try to avoid redundant window system
207
* requests e.g. to show an already visible window. This also means
208
* that it's acceptable to alternatively use native APIs to show and
209
* hide windows without confusing Cogl.</note>
212
* Stability: Unstable
215
cogl_onscreen_show (CoglOnscreen *onscreen);
218
* cogl_onscreen_hide:
219
* @onscreen: The onscreen framebuffer to make invisible
221
* This requests to make @onscreen invisible to the user.
223
* Actually the precise semantics of this function depend on the
224
* window system currently in use, and if you don't have a
225
* multi-windowining system this function may in-fact do nothing.
227
* This function does not implicitly allocate the given @onscreen
228
* framebuffer before hiding it.
230
* <note>Since Cogl doesn't explicitly track the visibility status of
231
* onscreen framebuffers it wont try to avoid redundant window system
232
* requests e.g. to show an already visible window. This also means
233
* that it's acceptable to alternatively use native APIs to show and
234
* hide windows without confusing Cogl.</note>
237
* Stability: Unstable
240
cogl_onscreen_hide (CoglOnscreen *onscreen);
243
* cogl_onscreen_swap_buffers:
244
* @onscreen: A #CoglOnscreen framebuffer
246
* Swaps the current back buffer being rendered too, to the front for display.
248
* This function also implicitly discards the contents of the color, depth and
249
* stencil buffers as if cogl_framebuffer_discard_buffers() were used. The
250
* significance of the discard is that you should not expect to be able to
251
* start a new frame that incrementally builds on the contents of the previous
254
* <note>It is highly recommended that applications use
255
* cogl_onscreen_swap_buffers_with_damage() instead whenever possible
256
* and also use the cogl_onscreen_get_buffer_age() api so they can
257
* perform incremental updates to older buffers instead of having to
258
* render a full buffer for every frame.</note>
261
* Stability: unstable
264
cogl_onscreen_swap_buffers (CoglOnscreen *onscreen);
268
* cogl_onscreen_get_buffer_age:
269
* @onscreen: A #CoglOnscreen framebuffer
271
* Gets the current age of the buffer contents.
273
* This function allows applications to query the age of the current
274
* back buffer contents for a #CoglOnscreen as the number of frames
275
* elapsed since the contents were most recently defined.
277
* These age values exposes enough information to applications about
278
* how Cogl internally manages back buffers to allow applications to
279
* re-use the contents of old frames and minimize how much must be
280
* redrawn for the next frame.
282
* The back buffer contents can either be reported as invalid (has an
283
* age of 0) or it may be reported to be the same contents as from n
284
* frames prior to the current frame.
286
* The queried value remains valid until the next buffer swap.
288
* <note>One caveat is that under X11 the buffer age does not reflect
289
* changes to buffer contents caused by the window systems. X11
290
* applications must track Expose events to determine what buffer
291
* regions need to additionally be repaired each frame.</note>
293
* The recommended way to take advantage of this buffer age api is to
294
* build up a circular buffer of length 3 for tracking damage regions
295
* over the last 3 frames and when starting a new frame look at the
296
* age of the buffer and combine the damage regions for the current
297
* frame with the damage regions of previous @age frames so you know
298
* everything that must be redrawn to update the old contents for the
301
* <note>If the system doesn't not support being able to track the age
302
* of back buffers then this function will always return 0 which
303
* implies that the contents are undefined.</note>
305
* <note>The %COGL_FEATURE_ID_BUFFER_AGE feature can optionally be
306
* explicitly checked to determine if Cogl is currently tracking the
307
* age of #CoglOnscreen back buffer contents. If this feature is
308
* missing then this function will always return 0.</note>
310
* Return value: The age of the buffer contents or 0 when the buffer
311
* contents are undefined.
317
cogl_onscreen_get_buffer_age (CoglOnscreen *onscreen);
320
* cogl_onscreen_swap_buffers_with_damage:
321
* @onscreen: A #CoglOnscreen framebuffer
322
* @rectangles: An array of integer 4-tuples representing damaged
323
* rectangles as (x, y, width, height) tuples.
324
* @n_rectangles: The number of 4-tuples to be read from @rectangles
326
* Swaps the current back buffer being rendered too, to the front for
327
* display and provides information to any system compositor about
328
* what regions of the buffer have changed (damage) with respect to
329
* the last swapped buffer.
331
* This function has the same semantics as
332
* cogl_framebuffer_swap_buffers() except that it additionally allows
333
* applications to pass a list of damaged rectangles which may be
334
* passed on to a compositor so that it can minimize how much of the
335
* screen is redrawn in response to this applications newly swapped
338
* For example if your application is only animating a small object in
339
* the corner of the screen and everything else is remaining static
340
* then it can help the compositor to know that only the bottom right
341
* corner of your newly swapped buffer has really changed with respect
342
* to your previously swapped front buffer.
344
* If @n_rectangles is 0 then the whole buffer will implicitly be
345
* reported as damaged as if cogl_onscreen_swap_buffers() had been
348
* This function also implicitly discards the contents of the color,
349
* depth and stencil buffers as if cogl_framebuffer_discard_buffers()
350
* were used. The significance of the discard is that you should not
351
* expect to be able to start a new frame that incrementally builds on
352
* the contents of the previous frame. If you want to perform
353
* incremental updates to older back buffers then please refer to the
354
* cogl_onscreen_get_buffer_age() api.
356
* Whenever possible it is recommended that applications use this
357
* function instead of cogl_onscreen_swap_buffers() to improve
358
* performance when running under a compositor.
360
* <note>It is highly recommended to use this API in conjunction with
361
* the cogl_onscreen_get_buffer_age() api so that your application can
362
* perform incremental rendering based on old back buffers.</note>
365
* Stability: unstable
368
cogl_onscreen_swap_buffers_with_damage (CoglOnscreen *onscreen,
369
const int *rectangles,
373
* cogl_onscreen_swap_region:
374
* @onscreen: A #CoglOnscreen framebuffer
375
* @rectangles: An array of integer 4-tuples representing rectangles as
376
* (x, y, width, height) tuples.
377
* @n_rectangles: The number of 4-tuples to be read from @rectangles
379
* Swaps a region of the back buffer being rendered too, to the front for
380
* display. @rectangles represents the region as array of @n_rectangles each
381
* defined by 4 sequential (x, y, width, height) integers.
383
* This function also implicitly discards the contents of the color, depth and
384
* stencil buffers as if cogl_framebuffer_discard_buffers() were used. The
385
* significance of the discard is that you should not expect to be able to
386
* start a new frame that incrementally builds on the contents of the previous
390
* Stability: unstable
393
cogl_onscreen_swap_region (CoglOnscreen *onscreen,
394
const int *rectangles,
399
* @COGL_FRAME_EVENT_SYNC: Notifies that the system compositor has
400
* acknowledged a frame and is ready for a
401
* new frame to be created.
402
* @COGL_FRAME_EVENT_COMPLETE: Notifies that a frame has ended. This
403
* is a good time for applications to
404
* collect statistics about the frame
405
* since the #CoglFrameInfo should hold
406
* the most data at this point. No other
407
* events should be expected after a
408
* @COGL_FRAME_EVENT_COMPLETE event.
410
* Identifiers that are passed to #CoglFrameCallback functions
411
* (registered using cogl_onscreen_add_frame_callback()) that
412
* mark the progression of a frame in some way which usually
413
* means that new information will have been accumulated in the
414
* frame's corresponding #CoglFrameInfo object.
416
* The last event that will be sent for a frame will be a
417
* @COGL_FRAME_EVENT_COMPLETE event and so these are a good
418
* opportunity to collect statistics about a frame since the
419
* #CoglFrameInfo should hold the most data at this point.
421
* <note>A frame may not be completed before the next frame can start
422
* so applications should avoid needing to collect all statistics for
423
* a particular frame before they can start a new frame.</note>
426
* Stability: unstable
428
typedef enum _CoglFrameEvent
430
COGL_FRAME_EVENT_SYNC = 1,
431
COGL_FRAME_EVENT_COMPLETE
436
* @onscreen: The onscreen that the frame is associated with
437
* @event: A #CoglFrameEvent notifying how the frame has progressed
438
* @info: The meta information, such as timing information, about
439
* the frame that has progressed.
440
* @user_data: The user pointer passed to
441
* cogl_onscreen_add_frame_callback()
443
* Is a callback that can be registered via
444
* cogl_onscreen_add_frame_callback() to be called when a frame
445
* progresses in some notable way.
447
* Please see the documentation for #CoglFrameEvent and
448
* cogl_onscreen_add_frame_callback() for more details about what
449
* events can be notified.
452
* Stability: unstable
454
typedef void (*CoglFrameCallback) (CoglOnscreen *onscreen,
455
CoglFrameEvent event,
462
* An opaque type that tracks a #CoglFrameCallback and associated user
463
* data. A #CoglFrameClosure pointer will be returned from
464
* cogl_onscreen_add_frame_callback() and it allows you to remove a
465
* callback later using cogl_onscreen_remove_frame_callback().
468
* Stability: unstable
470
typedef struct _CoglClosure CoglFrameClosure;
472
#ifdef COGL_HAS_GTYPE_SUPPORT
474
* cogl_frame_closure_get_gtype:
476
* Returns: a #GType that can be used with the GLib type system.
478
GType cogl_frame_closure_get_gtype (void);
482
* cogl_onscreen_add_frame_callback:
483
* @onscreen: A #CoglOnscreen framebuffer
484
* @callback: (scope notified): A callback function to call for frame events
485
* @user_data: (closure): A private pointer to be passed to @callback
486
* @destroy: (allow-none): An optional callback to destroy @user_data
487
* when the @callback is removed or @onscreen is freed.
489
* Installs a @callback function that will be called for significant
490
* events relating to the given @onscreen framebuffer.
492
* The @callback will be used to notify when the system compositor is
493
* ready for this application to render a new frame. In this case
494
* %COGL_FRAME_EVENT_SYNC will be passed as the event argument to the
495
* given @callback in addition to the #CoglFrameInfo corresponding to
496
* the frame beeing acknowledged by the compositor.
498
* The @callback will also be called to notify when the frame has
499
* ended. In this case %COGL_FRAME_EVENT_COMPLETE will be passed as
500
* the event argument to the given @callback in addition to the
501
* #CoglFrameInfo corresponding to the newly presented frame. The
502
* meaning of "ended" here simply means that no more timing
503
* information will be collected within the corresponding
504
* #CoglFrameInfo and so this is a good opportunity to analyse the
505
* given info. It does not necessarily mean that the GPU has finished
506
* rendering the corresponding frame.
508
* We highly recommend throttling your application according to
509
* %COGL_FRAME_EVENT_SYNC events so that your application can avoid
510
* wasting resources, drawing more frames than your system compositor
513
* Return value: a #CoglFrameClosure pointer that can be used to
514
* remove the callback and associated @user_data later.
516
* Stability: unstable
519
cogl_onscreen_add_frame_callback (CoglOnscreen *onscreen,
520
CoglFrameCallback callback,
522
CoglUserDataDestroyCallback destroy);
525
* cogl_onscreen_remove_frame_callback:
526
* @onscreen: A #CoglOnscreen
527
* @closure: A #CoglFrameClosure returned from
528
* cogl_onscreen_add_frame_callback()
530
* Removes a callback and associated user data that were previously
531
* registered using cogl_onscreen_add_frame_callback().
533
* If a destroy callback was passed to
534
* cogl_onscreen_add_frame_callback() to destroy the user data then
535
* this will get called.
538
* Stability: unstable
541
cogl_onscreen_remove_frame_callback (CoglOnscreen *onscreen,
542
CoglFrameClosure *closure);
544
typedef void (*CoglSwapBuffersNotify) (CoglFramebuffer *framebuffer,
548
* cogl_onscreen_add_swap_buffers_callback:
549
* @onscreen: A #CoglOnscreen framebuffer
550
* @callback: (scope notified): A callback function to call when a swap
552
* @user_data: (closure): A private pointer to be passed to @callback
554
* Installs a @callback function that should be called whenever a swap buffers
555
* request (made using cogl_onscreen_swap_buffers()) for the given
556
* @onscreen completes.
558
* <note>Applications should check for the %COGL_FEATURE_ID_SWAP_BUFFERS_EVENT
559
* feature before using this API. It's currently undefined when and if
560
* registered callbacks will be called if this feature is not supported.</note>
562
* We recommend using this mechanism when available to manually throttle your
563
* applications (in conjunction with cogl_onscreen_set_swap_throttled()) so
564
* your application will be able to avoid long blocks in the driver caused by
565
* throttling when you request to swap buffers too quickly.
567
* Return value: a unique identifier that can be used to remove to remove
568
* the callback later.
570
* Stability: unstable
571
* Deprecated: 1.14: Use cogl_onscreen_add_frame_callback() instead
573
COGL_DEPRECATED_IN_1_14_FOR (cogl_onscreen_add_frame_callback)
575
cogl_onscreen_add_swap_buffers_callback (CoglOnscreen *onscreen,
576
CoglSwapBuffersNotify callback,
580
* cogl_onscreen_remove_swap_buffers_callback:
581
* @onscreen: A #CoglOnscreen framebuffer
582
* @id: An identifier returned from cogl_onscreen_add_swap_buffers_callback()
584
* Removes a callback that was previously registered
585
* using cogl_onscreen_add_swap_buffers_callback().
588
* Stability: unstable
589
* Deprecated: 1.14: Use cogl_onscreen_remove_frame_callback() instead
592
COGL_DEPRECATED_IN_1_14_FOR (cogl_onscreen_remove_frame_callback)
594
cogl_onscreen_remove_swap_buffers_callback (CoglOnscreen *onscreen,
598
* cogl_onscreen_set_resizable:
599
* @onscreen: A #CoglOnscreen framebuffer
601
* Lets you request Cogl to mark an @onscreen framebuffer as
604
* By default, if possible, a @onscreen will be created by Cogl
605
* as non resizable, but it is not guaranteed that this is always
606
* possible for all window systems.
608
* <note>Cogl does not know whether marking the @onscreen framebuffer
609
* is truly meaningful for your current window system (consider
610
* applications being run fullscreen on a phone or TV) so this
611
* function may not have any useful effect. If you are running on a
612
* multi windowing system such as X11 or Win32 or OSX then Cogl will
613
* request to the window system that users be allowed to resize the
614
* @onscreen, although it's still possible that some other window
615
* management policy will block this possibility.</note>
617
* <note>Whenever an @onscreen framebuffer is resized the viewport
618
* will be automatically updated to match the new size of the
619
* framebuffer with an origin of (0,0). If your application needs more
620
* specialized control of the viewport it will need to register a
621
* resize handler using cogl_onscreen_add_resize_callback() so that it
622
* can track when the viewport has been changed automatically.</note>
627
cogl_onscreen_set_resizable (CoglOnscreen *onscreen,
631
* cogl_onscreen_get_resizable:
632
* @onscreen: A #CoglOnscreen framebuffer
634
* Lets you query whether @onscreen has been marked as resizable via
635
* the cogl_onscreen_set_resizable() api.
637
* By default, if possible, a @onscreen will be created by Cogl
638
* as non resizable, but it is not guaranteed that this is always
639
* possible for all window systems.
641
* <note>If cogl_onscreen_set_resizable(@onscreen, %TRUE) has been
642
* previously called then this function will return %TRUE, but it's
643
* possible that the current windowing system being used does not
644
* support window resizing (consider fullscreen windows on a phone or
645
* a TV). This function is not aware of whether resizing is truly
646
* meaningful with your window system, only whether the @onscreen has
647
* been marked as resizable.</note>
649
* Return value: Returns whether @onscreen has been marked as
654
cogl_onscreen_get_resizable (CoglOnscreen *onscreen);
657
* CoglOnscreenResizeCallback:
658
* @onscreen: A #CoglOnscreen framebuffer that was resized
659
* @width: The new width of @onscreen
660
* @height: The new height of @onscreen
661
* @user_data: The private passed to
662
* cogl_onscreen_add_resize_callback()
664
* Is a callback type used with the
665
* cogl_onscreen_add_resize_callback() allowing applications to be
666
* notified whenever an @onscreen framebuffer is resized.
668
* <note>Cogl automatically updates the viewport of an @onscreen
669
* framebuffer that is resized so this callback is also an indication
670
* that the viewport has been modified too</note>
672
* <note>A resize callback will only ever be called while dispatching
673
* Cogl events from the system mainloop; so for example during
674
* cogl_poll_renderer_dispatch(). This is so that callbacks shouldn't
675
* occur while an application might have arbitrary locks held for
680
typedef void (*CoglOnscreenResizeCallback) (CoglOnscreen *onscreen,
686
* CoglOnscreenResizeClosure:
688
* An opaque type that tracks a #CoglOnscreenResizeCallback and
689
* associated user data. A #CoglOnscreenResizeClosure pointer will be
690
* returned from cogl_onscreen_add_resize_callback() and it allows you
691
* to remove a callback later using
692
* cogl_onscreen_remove_resize_callback().
695
* Stability: unstable
697
typedef struct _CoglClosure CoglOnscreenResizeClosure;
699
#ifdef COGL_HAS_GTYPE_SUPPORT
701
* cogl_onscreen_resize_closure_get_gtype:
703
* Returns: a #GType that can be used with the GLib type system.
705
GType cogl_onscreen_resize_closure_get_gtype (void);
709
* cogl_onscreen_add_resize_callback:
710
* @onscreen: A #CoglOnscreen framebuffer
711
* @callback: (scope notified): A #CoglOnscreenResizeCallback to call when
712
* the @onscreen changes size.
713
* @user_data: (closure): Private data to be passed to @callback.
714
* @destroy: (allow-none): An optional callback to destroy @user_data
715
* when the @callback is removed or @onscreen is freed.
717
* Registers a @callback with @onscreen that will be called whenever
718
* the @onscreen framebuffer changes size.
720
* The @callback can be removed using
721
* cogl_onscreen_remove_resize_callback() passing the returned closure
724
* <note>Since Cogl automatically updates the viewport of an @onscreen
725
* framebuffer that is resized, a resize callback can also be used to
726
* track when the viewport has been changed automatically by Cogl in
727
* case your application needs more specialized control over the
730
* <note>A resize callback will only ever be called while dispatching
731
* Cogl events from the system mainloop; so for example during
732
* cogl_poll_renderer_dispatch(). This is so that callbacks shouldn't
733
* occur while an application might have arbitrary locks held for
736
* Return value: a #CoglOnscreenResizeClosure pointer that can be used to
737
* remove the callback and associated @user_data later.
740
CoglOnscreenResizeClosure *
741
cogl_onscreen_add_resize_callback (CoglOnscreen *onscreen,
742
CoglOnscreenResizeCallback callback,
744
CoglUserDataDestroyCallback destroy);
747
* cogl_onscreen_remove_resize_callback:
748
* @onscreen: A #CoglOnscreen framebuffer
749
* @closure: An identifier returned from cogl_onscreen_add_resize_callback()
751
* Removes a resize @callback and @user_data pair that were previously
752
* associated with @onscreen via cogl_onscreen_add_resize_callback().
757
cogl_onscreen_remove_resize_callback (CoglOnscreen *onscreen,
758
CoglOnscreenResizeClosure *closure);
761
* CoglOnscreenDirtyInfo:
762
* @x: Left edge of the dirty rectangle
763
* @y: Top edge of the dirty rectangle, measured from the top of the window
764
* @width: Width of the dirty rectangle
765
* @height: Height of the dirty rectangle
767
* A structure passed to callbacks registered using
768
* cogl_onscreen_add_dirty_callback(). The members describe a
769
* rectangle within the onscreen buffer that should be redrawn.
772
* Stability: unstable
774
typedef struct _CoglOnscreenDirtyInfo CoglOnscreenDirtyInfo;
776
struct _CoglOnscreenDirtyInfo
783
* CoglOnscreenDirtyCallback:
784
* @onscreen: The onscreen that the frame is associated with
785
* @info: A #CoglOnscreenDirtyInfo struct containing the details of the
787
* @user_data: The user pointer passed to
788
* cogl_onscreen_add_frame_callback()
790
* Is a callback that can be registered via
791
* cogl_onscreen_add_dirty_callback() to be called when the windowing
792
* system determines that a region of the onscreen window has been
793
* lost and the application should redraw it.
796
* Stability: unstable
798
typedef void (*CoglOnscreenDirtyCallback) (CoglOnscreen *onscreen,
799
const CoglOnscreenDirtyInfo *info,
803
* CoglOnscreenDirtyClosure:
805
* An opaque type that tracks a #CoglOnscreenDirtyCallback and associated
806
* user data. A #CoglOnscreenDirtyClosure pointer will be returned from
807
* cogl_onscreen_add_dirty_callback() and it allows you to remove a
808
* callback later using cogl_onscreen_remove_dirty_callback().
811
* Stability: unstable
813
typedef struct _CoglClosure CoglOnscreenDirtyClosure;
815
#ifdef COGL_HAS_GTYPE_SUPPORT
817
* cogl_onscreen_dirty_closure_get_gtype:
819
* Returns: a #GType that can be used with the GLib type system.
821
GType cogl_onscreen_dirty_closure_get_gtype (void);
825
* cogl_onscreen_add_dirty_callback:
826
* @onscreen: A #CoglOnscreen framebuffer
827
* @callback: (scope notified): A callback function to call for dirty events
828
* @user_data: (closure): A private pointer to be passed to @callback
829
* @destroy: (allow-none): An optional callback to destroy @user_data when the
830
* @callback is removed or @onscreen is freed.
832
* Installs a @callback function that will be called whenever the
833
* window system has lost the contents of a region of the onscreen
834
* buffer and the application should redraw it to repair the buffer.
835
* For example this may happen in a window system without a compositor
836
* if a window that was previously covering up the onscreen window has
837
* been moved causing a region of the onscreen to be exposed.
839
* The @callback will be passed a #CoglOnscreenDirtyInfo struct which
840
* decribes a rectangle containing the newly dirtied region. Note that
841
* this may be called multiple times to describe a non-rectangular
842
* region composed of multiple smaller rectangles.
844
* The dirty events are separate from %COGL_FRAME_EVENT_SYNC events so
845
* the application should also listen for this event before rendering
846
* the dirty region to ensure that the framebuffer is actually ready
849
* Return value: a #CoglOnscreenDirtyClosure pointer that can be used to
850
* remove the callback and associated @user_data later.
852
* Stability: unstable
854
CoglOnscreenDirtyClosure *
855
cogl_onscreen_add_dirty_callback (CoglOnscreen *onscreen,
856
CoglOnscreenDirtyCallback callback,
858
CoglUserDataDestroyCallback destroy);
861
* cogl_onscreen_remove_dirty_callback:
862
* @onscreen: A #CoglOnscreen
863
* @closure: A #CoglOnscreenDirtyClosure returned from
864
* cogl_onscreen_add_dirty_callback()
866
* Removes a callback and associated user data that were previously
867
* registered using cogl_onscreen_add_dirty_callback().
869
* If a destroy callback was passed to
870
* cogl_onscreen_add_dirty_callback() to destroy the user data then
871
* this will also get called.
874
* Stability: unstable
877
cogl_onscreen_remove_dirty_callback (CoglOnscreen *onscreen,
878
CoglOnscreenDirtyClosure *closure);
882
* @object: A #CoglObject pointer
884
* Gets whether the given object references a #CoglOnscreen.
886
* Return value: %TRUE if the object references a #CoglOnscreen
887
* and %FALSE otherwise.
889
* Stability: unstable
892
cogl_is_onscreen (void *object);
895
* cogl_onscreen_get_frame_counter:
897
* Gets the value of the framebuffers frame counter. This is
898
* a counter that increases by one each time
899
* cogl_onscreen_swap_buffers() or cogl_onscreen_swap_region()
902
* Return value: the current frame counter value
904
* Stability: unstable
907
cogl_onscreen_get_frame_counter (CoglOnscreen *onscreen);
911
#endif /* __COGL_ONSCREEN_H */
added
removed
cogl/cogl/cogl-onscreen.h
