mutter/cogl/cogl-framebuffer.h
Robert Bragg 8b34a39319 Adds ColorMask support to Cogl
This adds CoglPipeline and CoglFramebuffer support for setting a color
mask which is a bit mask defining which color channels should be written
to the current framebuffer.

The final color mask is the intersection of the framebuffer color mask
and the pipeline color mask. The framebuffer mask affects all rendering
to the framebuffer while the pipeline masks can be used to affect
individual primitives.

Reviewed-by: Neil Roberts <neil@linux.intel.com>
2011-07-19 19:27:09 +01:00

454 lines
15 KiB
C

/*
* Cogl
*
* An object oriented GL/GLES Abstraction/Utility Layer
*
* Copyright (C) 2011 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>
*/
#ifndef __COGL_FRAMEBUFFER_H
#define __COGL_FRAMEBUFFER_H
#include <glib.h>
#ifdef COGL_HAS_WIN32_SUPPORT
#include <windows.h>
#endif /* COGL_HAS_WIN32_SUPPORT */
#if COGL_HAS_EGL_PLATFORM_WAYLAND_SUPPORT
#include <wayland-client.h>
#endif /* COGL_HAS_EGL_PLATFORM_WAYLAND_SUPPORT */
G_BEGIN_DECLS
/**
* SECTION:cogl-framebuffer
* @short_description: A common interface for manipulating framebuffers
*
* Framebuffers are a collection of buffers that can be rendered too.
* A framebuffer may be comprised of one or more color buffers, an
* optional depth buffer and an optional stencil buffer. Other
* configuration parameters are associated with framebuffers too such
* as whether the framebuffer supports multi-sampling (an anti-aliasing
* technique) or dithering.
*
* There are two kinds of framebuffer in Cogl, #CoglOnscreen
* framebuffers and #CoglOffscreen framebuffers. As the names imply
* offscreen framebuffers are for rendering something offscreen
* (perhaps to a texture which is bound as one of the color buffers).
* The exact semantics of onscreen framebuffers depends on the window
* system backend that you are using, but typically you can expect
* rendering to a #CoglOnscreen framebuffer will be immediately
* visible to the user.
*
* If you want to create a new framebuffer then you should start by
* looking at the #CoglOnscreen and #CoglOffscreen constructor
* functions, such as cogl_offscreen_new_to_texture() or
* cogl_onscreen_new(). The #CoglFramebuffer interface deals with
* all aspects that are common between those two types of framebuffer.
*
* Setup of a new CoglFramebuffer happens in two stages. There is a
* configuration stage where you specify all the options and ancillary
* buffers you want associated with your framebuffer and then when you
* are happy with the configuration you can "allocate" the framebuffer
* using cogl_framebuffer_allocate (). Technically explicitly calling
* cogl_framebuffer_allocate () is optional for convenience and the
* framebuffer will automatically be allocated when you first try to
* draw to it, but if you do the allocation manually then you can
* also catch any possible errors that may arise from your
* configuration.
*/
#ifdef COGL_ENABLE_EXPERIMENTAL_API
#define cogl_onscreen_new cogl_onscreen_new_EXP
#define COGL_FRAMEBUFFER(X) ((CoglFramebuffer *)(X))
#define cogl_framebuffer_allocate cogl_framebuffer_allocate_EXP
gboolean
cogl_framebuffer_allocate (CoglFramebuffer *framebuffer,
GError **error);
#define cogl_framebuffer_get_width cogl_framebuffer_get_width_EXP
int
cogl_framebuffer_get_width (CoglFramebuffer *framebuffer);
#define cogl_framebuffer_get_height cogl_framebuffer_get_height_EXP
int
cogl_framebuffer_get_height (CoglFramebuffer *framebuffer);
#define cogl_framebuffer_set_viewport cogl_framebuffer_set_viewport_EXP
void
cogl_framebuffer_set_viewport (CoglFramebuffer *framebuffer,
float x,
float y,
float width,
float height);
#define cogl_framebuffer_get_viewport_x cogl_framebuffer_get_viewport_x_EXP
float
cogl_framebuffer_get_viewport_x (CoglFramebuffer *framebuffer);
#define cogl_framebuffer_get_viewport_y cogl_framebuffer_get_viewport_y_EXP
float
cogl_framebuffer_get_viewport_y (CoglFramebuffer *framebuffer);
#define cogl_framebuffer_get_viewport_width cogl_framebuffer_get_viewport_width_EXP
float
cogl_framebuffer_get_viewport_width (CoglFramebuffer *framebuffer);
#define cogl_framebuffer_get_viewport_height cogl_framebuffer_get_viewport_height_EXP
float
cogl_framebuffer_get_viewport_height (CoglFramebuffer *framebuffer);
#define cogl_framebuffer_get_viewport4fv cogl_framebuffer_get_viewport4fv_EXP
void
cogl_framebuffer_get_viewport4fv (CoglFramebuffer *framebuffer,
float *viewport);
/**
* cogl_framebuffer_get_red_bits:
* @framebuffer: a pointer to a #CoglFramebuffer
*
* Retrieves the number of red bits of @framebuffer
*
* Return value: the number of bits
*
* Since: 1.8
* Stability: unstable
*/
#define cogl_framebuffer_get_red_bits cogl_framebuffer_get_red_bits_EXP
int
cogl_framebuffer_get_red_bits (CoglFramebuffer *framebuffer);
/**
* cogl_framebuffer_get_green_bits:
* @framebuffer: a pointer to a #CoglFramebuffer
*
* Retrieves the number of green bits of @framebuffer
*
* Return value: the number of bits
*
* Since: 1.8
* Stability: unstable
*/
#define cogl_framebuffer_get_green_bits cogl_framebuffer_get_green_bits_EXP
int
cogl_framebuffer_get_green_bits (CoglFramebuffer *framebuffer);
/**
* cogl_framebuffer_get_blue_bits:
* @framebuffer: a pointer to a #CoglFramebuffer
*
* Retrieves the number of blue bits of @framebuffer
*
* Return value: the number of bits
*
* Since: 1.8
* Stability: unstable
*/
#define cogl_framebuffer_get_blue_bits cogl_framebuffer_get_blue_bits_EXP
int
cogl_framebuffer_get_blue_bits (CoglFramebuffer *framebuffer);
/**
* cogl_framebuffer_get_alpha_bits:
* @framebuffer: a pointer to a #CoglFramebuffer
*
* Retrieves the number of alpha bits of @framebuffer
*
* Return value: the number of bits
*
* Since: 1.8
* Stability: unstable
*/
#define cogl_framebuffer_get_blue_bits cogl_framebuffer_get_blue_bits_EXP
int
cogl_framebuffer_get_alpha_bits (CoglFramebuffer *framebuffer);
/**
* cogl_framebuffer_get_dither_enabled:
* @framebuffer: a pointer to a #CoglFramebuffer
*
* Returns whether dithering has been requested for the given @framebuffer.
* See cogl_framebuffer_set_dither_enabled() for more details about dithering.
*
* <note>This may return %TRUE even when the underlying @framebuffer
* display pipeline does not support dithering. This value only represents
* the user's request for dithering.</note>
*
* Return value: %TRUE if dithering has been requested or %FALSE if not.
*/
gboolean
cogl_framebuffer_get_dither_enabled (CoglFramebuffer *framebuffer);
/**
* cogl_framebuffer_set_dither_enabled:
* @framebuffer: a pointer to a #CoglFramebuffer
* @dither_enabled: %TRUE to enable dithering or %FALSE to disable
*
* Enables or disabled dithering if supported by the hardware.
*
* Dithering is a hardware dependent technique to increase the visible
* color resolution beyond what the underlying hardware supports by playing
* tricks with the colors placed into the framebuffer to give the illusion
* of other colors. (For example this can be compared to half-toning used
* by some news papers to show varying levels of grey even though their may
* only be black and white are available).
*
* If the current display pipeline for @framebuffer does not support dithering
* then this has no affect.
*
* Dithering is enabled by default.
*
* Since: 1.8
* Stability: unstable
*/
void
cogl_framebuffer_set_dither_enabled (CoglFramebuffer *framebuffer,
gboolean dither_enabled);
#define cogl_framebuffer_get_color_mask cogl_framebuffer_get_color_mask_EXP
/**
* cogl_framebuffer_get_color_mask:
* @framebuffer: a pointer to a #CoglFramebuffer
*
* Gets the current #CoglColorMask of which channels would be written to the
* current framebuffer. Each bit set in the mask means that the
* corresponding color would be written.
*
* Returns: A #CoglColorMask
* Since: 1.8
* Stability: unstable
*/
CoglColorMask
cogl_framebuffer_get_color_mask (CoglFramebuffer *framebuffer);
#define cogl_framebuffer_set_color_mask cogl_framebuffer_set_color_mask_EXP
/**
* cogl_framebuffer_set_color_mask:
* @framebuffer: a pointer to a #CoglFramebuffer
* @color_mask: A #CoglColorMask of which color channels to write to
* the current framebuffer.
*
* Defines a bit mask of which color channels should be written to the
* given @framebuffer. If a bit is set in @color_mask that means that
* color will be written.
*
* Since: 1.8
* Stability: unstable
*/
void
cogl_framebuffer_set_color_mask (CoglFramebuffer *framebuffer,
CoglColorMask color_mask);
#define cogl_framebuffer_swap_buffers cogl_framebuffer_swap_buffers_EXP
void
cogl_framebuffer_swap_buffers (CoglFramebuffer *framebuffer);
#define cogl_framebuffer_swap_region cogl_framebuffer_swap_region_EXP
void
cogl_framebuffer_swap_region (CoglFramebuffer *framebuffer,
int *rectangles,
int n_rectangles);
typedef void (*CoglSwapBuffersNotify) (CoglFramebuffer *framebuffer,
void *user_data);
#define cogl_framebuffer_add_swap_buffers_callback \
cogl_framebuffer_add_swap_buffers_callback_EXP
unsigned int
cogl_framebuffer_add_swap_buffers_callback (CoglFramebuffer *framebuffer,
CoglSwapBuffersNotify callback,
void *user_data);
#define cogl_framebuffer_remove_swap_buffers_callback \
cogl_framebuffer_remove_swap_buffers_callback_EXP
void
cogl_framebuffer_remove_swap_buffers_callback (CoglFramebuffer *framebuffer,
unsigned int id);
typedef struct _CoglOnscreen CoglOnscreen;
#define COGL_ONSCREEN(X) ((CoglOnscreen *)(X))
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
*/
#define cogl_x11_onscreen_set_foreign_window_xid \
cogl_x11_onscreen_set_foreign_window_xid_EXP
void
cogl_x11_onscreen_set_foreign_window_xid (CoglOnscreen *onscreen,
guint32 xid,
CoglOnscreenX11MaskCallback update,
void *user_data);
#define cogl_x11_onscreen_get_window_xid cogl_x11_onscreen_get_window_xid_EXP
guint32
cogl_x11_onscreen_get_window_xid (CoglOnscreen *onscreen);
#define cogl_x11_onscreen_get_visual_xid cogl_x11_onscreen_get_visual_xid_EXP
guint32
cogl_x11_onscreen_get_visual_xid (CoglOnscreen *onscreen);
#endif /* COGL_HAS_X11 */
#ifdef COGL_HAS_WIN32_SUPPORT
#define cogl_win32_onscreen_set_foreign_window \
cogl_win32_onscreen_set_foreign_window_EXP
void
cogl_win32_onscreen_set_foreign_window (CoglOnscreen *onscreen,
HWND hwnd);
#define cogl_win32_onscreen_get_window cogl_win32_onscreen_get_window_EXP
HWND
cogl_win32_onscreen_get_window (CoglOnscreen *onscreen);
#endif /* COGL_HAS_WIN32_SUPPORT */
#if COGL_HAS_EGL_PLATFORM_WAYLAND_SUPPORT
struct wl_surface *
cogl_wayland_onscreen_get_surface (CoglOnscreen *onscreen);
#endif /* COGL_HAS_EGL_PLATFORM_WAYLAND_SUPPORT */
#define cogl_onscreen_set_swap_throttled cogl_onscreen_set_swap_throttled_EXP
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
*/
#define cogl_onscreen_show cogl_onscreen_show_EXP
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
*/
#define cogl_onscreen_hide cogl_onscreen_hide_EXP
void
cogl_onscreen_hide (CoglOnscreen *onscreen);
#define cogl_get_draw_framebuffer cogl_get_draw_framebuffer_EXP
CoglFramebuffer *
cogl_get_draw_framebuffer (void);
#endif /* COGL_ENABLE_EXPERIMENTAL_API */
G_END_DECLS
#endif /* __COGL_FRAMEBUFFER_H */