brl/mutter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
890a75ab06
mutter/cogl/cogl-onscreen.h
Neil Roberts 185630085c Add -Wmissing-declarations to maintainer flags and fix problems 
This option to GCC makes it give a warning whenever a global function
is defined without a declaration. This should catch cases were we've
defined a function but forgot to put it in a header. In that case it
is either only used within one file so we should make it static or we
should declare it in a header.

The following changes where made to fix problems:

• Some functions were made static

• cogl-path.h (the one containing the 1.0 API) was split into two
  files, one defining the functions and one defining the enums so that
  cogl-path.c can include the enum and function declarations from the
  2.0 API as well as the function declarations from the 1.0 API.

• cogl2-clip-state has been removed. This only had one experimental
  function called cogl_clip_push_from_path but as this is unstable we
  might as well remove it favour of the equivalent cogl_framebuffer_*
  API.

• The GLX, SDL and WGL winsys's now have a private header to define
  their get_vtable function instead of directly declaring in the C
  file where it is called.

• All places that were calling COGL_OBJECT_DEFINE need to have the
  cogl_is_whatever function declared so these have been added either
  as a public function or in a private header.

• Some files that were not including the header containing their
  function declarations have been fixed to do so.

• Any unused error quark functions have been removed. If we later want
  them we should add them back one by one and add a declaration for
  them in a header.

• _cogl_is_framebuffer has been renamed to cogl_is_framebuffer and
  made a public function with a declaration in cogl-framebuffer.h

• Similarly for CoglOnscreen.

• cogl_vdraw_indexed_attributes is called
  cogl_framebuffer_vdraw_indexed_attributes in the header. The
  definition has been changed to match the header.

• cogl_index_buffer_allocate has been removed. This had no declaration
  and I'm not sure what it's supposed to do.

• CoglJournal has been changed to use the internal CoglObject macro so
  that it won't define an exported cogl_is_journal symbol.

• The _cogl_blah_pointer_from_handle functions have been removed.
  CoglHandle isn't used much anymore anyway and in the few places
  where it is used I think it's safe to just use the implicit cast
  from void* to the right type.

• The test-utils.h header for the conformance tests explicitly
  disables the -Wmissing-declaration option using a pragma because all
  of the tests declare their main function without a header. Any
  mistakes relating to missing declarations aren't really important
  for the tests.

• cogl_quaternion_init_from_quaternion and init_from_matrix have been
  given declarations in cogl-quaternion.h

Reviewed-by: Robert Bragg <robert@linux.intel.com>
2012-03-06 18:45:44 +00:00

400 lines
14 KiB
C
Raw Blame History

/*
* Cogl
*
* An object oriented GL/GLES Abstraction/Utility Layer
*
* Copyright (C) 2011,2012 Intel Corporation.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library. If not, see
* <http://www.gnu.org/licenses/>.
*
*
*
* Authors:
* Robert Bragg <robert@linux.intel.com>
*/
#if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
#error "Only <cogl/cogl.h> can be included directly."
#endif
#ifndef __COGL_ONSCREEN_H
#define __COGL_ONSCREEN_H
#include <cogl/cogl-context.h>
#include <cogl/cogl-framebuffer.h>
#include <glib.h>
G_BEGIN_DECLS
typedef struct _CoglOnscreen CoglOnscreen;
#define COGL_ONSCREEN(X) ((CoglOnscreen *)(X))
/**
* cogl_onscreen_new:
* @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: 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,
guint32 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.
*
* 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,
* guint32 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,
guint32 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
*/
guint32
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. */
guint32
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_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 x offset for the new framebuffer
*
* Queues a resize of the given @onscreen framebuffer which will be applied
* during the next swap buffers request. 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.
*
* If cogl_wayland_onscreen_resize() is called multiple times 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 #CoglOncsreen framebuffer
* @throttled: Whether swap throttling is wanted or not.
*
* Requests that the given @onscreen framebuffer should have swap buffer
* requests (made using cogl_framebuffer_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,
gboolean 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.
*
* <note>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.</note>
*
* 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.
*
* <note>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.</note>
*
* 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.
*
* Since: 1.10
* Stability: unstable
*/
void
cogl_onscreen_swap_buffers (CoglOnscreen *onscreen);
/**
* 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_onscreen_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);
typedef void (*CoglSwapBuffersNotify) (CoglFramebuffer *framebuffer,
void *user_data);
/**
* cogl_onscreen_add_swap_buffers_callback:
* @onscreen: A #CoglOnscreen framebuffer
* @callback: A callback function to call when a swap has completed
* @user_data: 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.
*
* <note>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.</note>
*
* 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
*/
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
*/
void
cogl_onscreen_remove_swap_buffers_callback (CoglOnscreen *onscreen,
unsigned int id);
/**
* 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
*/
gboolean
cogl_is_onscreen (void *object);
G_END_DECLS
#endif /* __COGL_ONSCREEN_H */
Reference in New Issue View Git Blame Copy Permalink