diff --git a/cogl/Makefile.am b/cogl/Makefile.am index 366a6a88e..2a5dcfa6b 100644 --- a/cogl/Makefile.am +++ b/cogl/Makefile.am @@ -58,6 +58,7 @@ DISTCLEANFILES += $(pc_files) # public 1.x api headers cogl_1_public_h = \ + $(srcdir)/cogl1-context.h \ $(srcdir)/cogl-bitmap.h \ $(srcdir)/cogl-color.h \ $(srcdir)/cogl-fixed.h \ diff --git a/cogl/cogl-atlas-texture.c b/cogl/cogl-atlas-texture.c index 06aed4af4..dbf80bc52 100644 --- a/cogl/cogl-atlas-texture.c +++ b/cogl/cogl-atlas-texture.c @@ -43,6 +43,7 @@ #include "cogl-journal-private.h" #include "cogl-pipeline-opengl-private.h" #include "cogl-atlas.h" +#include "cogl1-context.h" #include diff --git a/cogl/cogl-attribute-buffer.h b/cogl/cogl-attribute-buffer.h index d7860f2dd..aa180efec 100644 --- a/cogl/cogl-attribute-buffer.h +++ b/cogl/cogl-attribute-buffer.h @@ -31,6 +31,11 @@ #ifndef __COGL_ATTRIBUTE_BUFFER_H__ #define __COGL_ATTRIBUTE_BUFFER_H__ +/* We forward declare the CoglAttributeBuffer type here to avoid some circular + * dependency issues with the following headers. + */ +typedef struct _CoglAttributeBuffer CoglAttributeBuffer; + #include G_BEGIN_DECLS @@ -43,8 +48,6 @@ G_BEGIN_DECLS * FIXME */ -typedef struct _CoglAttributeBuffer CoglAttributeBuffer; - /** * cogl_attribute_buffer_new: * @context: A #CoglContext diff --git a/cogl/cogl-attribute.h b/cogl/cogl-attribute.h index a9ec03efa..b59402cb3 100644 --- a/cogl/cogl-attribute.h +++ b/cogl/cogl-attribute.h @@ -31,6 +31,11 @@ #ifndef __COGL_ATTRIBUTE_H__ #define __COGL_ATTRIBUTE_H__ +/* We forward declare the CoglAttribute type here to avoid some circular + * dependency issues with the following headers. + */ +typedef struct _CoglAttribute CoglAttribute; + #include #include @@ -44,8 +49,6 @@ G_BEGIN_DECLS * FIXME */ -typedef struct _CoglAttribute CoglAttribute; - /** * cogl_attribute_new: * @attribute_buffer: The #CoglAttributeBuffer containing the actual diff --git a/cogl/cogl-blit.c b/cogl/cogl-blit.c index 2ab14455e..8f695bf33 100644 --- a/cogl/cogl-blit.c +++ b/cogl/cogl-blit.c @@ -37,6 +37,7 @@ #include "cogl-framebuffer-private.h" #include "cogl-texture-2d-private.h" #include "cogl-private.h" +#include "cogl1-context.h" static const CoglBlitMode *_cogl_blit_default_mode = NULL; diff --git a/cogl/cogl-clip-stack.c b/cogl/cogl-clip-stack.c index 418debb2a..b493e5d83 100644 --- a/cogl/cogl-clip-stack.c +++ b/cogl/cogl-clip-stack.c @@ -45,6 +45,7 @@ #include "cogl-pipeline-opengl-private.h" #include "cogl-attribute-private.h" #include "cogl-primitive-private.h" +#include "cogl1-context.h" #ifndef GL_CLIP_PLANE0 #define GL_CLIP_PLANE0 0x3000 diff --git a/cogl/cogl-context.c b/cogl/cogl-context.c index e773006fd..0c2788609 100644 --- a/cogl/cogl-context.c +++ b/cogl/cogl-context.c @@ -47,6 +47,7 @@ #include "cogl-onscreen-private.h" #include "cogl2-path.h" #include "cogl-attribute-private.h" +#include "cogl1-context.h" #include diff --git a/cogl/cogl-context.h b/cogl/cogl-context.h index 75c0702ce..86c746b66 100644 --- a/cogl/cogl-context.h +++ b/cogl/cogl-context.h @@ -31,8 +31,16 @@ #ifndef __COGL_CONTEXT_H__ #define __COGL_CONTEXT_H__ +/* We forward declare the CoglContext type here to avoid some circular + * dependency issues with the following headers. + */ +typedef struct _CoglContext CoglContext; + #include #include +#include +#include +#include #ifdef COGL_HAS_EGL_PLATFORM_ANDROID_SUPPORT #include #endif @@ -62,7 +70,7 @@ G_BEGIN_DECLS * what state other components have left you with. */ -typedef struct _CoglContext CoglContext; +#ifdef COGL_ENABLE_EXPERIMENTAL_API #define COGL_CONTEXT(OBJECT) ((CoglContext *)OBJECT) @@ -150,6 +158,161 @@ cogl_android_set_native_window (ANativeWindow *window); gboolean cogl_is_context (void *object); +#endif /* COGL_ENABLE_EXPERIMENTAL_2_0_API */ + +/* XXX: not guarded by the EXPERIMENTAL_2_0_API defines to avoid + * upsetting glib-mkenums, but this can still be considered implicitly + * experimental since it's only useable with experimental API... */ +/** + * CoglFeatureID: + * @COGL_FEATURE_ID_TEXTURE_NPOT_BASIC: The hardware supports non power + * of two textures, but you also need to check the + * %COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP and %COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT + * features to know if the hardware supports npot texture mipmaps + * or repeat modes other than + * %COGL_RENDERER_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE respectively. + * @COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP: Mipmapping is supported in + * conjuntion with non power of two textures. + * @COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT: Repeat modes other than + * %COGL_RENDERER_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE are supported by the + * hardware. + * @COGL_FEATURE_ID_TEXTURE_NPOT: Non power of two textures are supported + * by the hardware. This is a equivalent to the + * %COGL_FEATURE_ID_TEXTURE_NPOT_BASIC, %COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP + * and %COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT features combined. + * @COGL_FEATURE_ID_TEXTURE_RECTANGLE: Support for rectangular + * textures with non-normalized texture coordinates. + * @COGL_FEATURE_ID_TEXTURE_3D: 3D texture support + * @COGL_FEATURE_ID_OFFSCREEN: Offscreen rendering support + * @COGL_FEATURE_ID_OFFSCREEN_MULTISAMPLE: Multisample support for + * offscreen framebuffers + * @COGL_FEATURE_ID_ONSCREEN_MULTIPLE: Multiple onscreen framebuffers + * supported. + * @COGL_FEATURE_ID_GLSL: GLSL support + * @COGL_FEATURE_ID_ARBFP: ARBFP support + * @COGL_FEATURE_ID_UNSIGNED_INT_INDICES: Set if + * %COGL_RENDERER_INDICES_TYPE_UNSIGNED_INT is supported in + * cogl_indices_new(). + * @COGL_FEATURE_ID_DEPTH_RANGE: cogl_pipeline_set_depth_range() support + * @COGL_FEATURE_ID_POINT_SPRITE: Whether + * cogl_pipeline_set_layer_point_sprite_coords_enabled() is supported. + * @COGL_FEATURE_ID_MAP_BUFFER_FOR_READ: Whether cogl_buffer_map() is + * supported with CoglBufferAccess including read support. + * @COGL_FEATURE_ID_MAP_BUFFER_FOR_WRITE: Whether cogl_buffer_map() is + * supported with CoglBufferAccess including write support. + * @COGL_FEATURE_ID_MIRRORED_REPEAT: Whether + * %COGL_PIPELINE_WRAP_MODE_MIRRORED_REPEAT is supported. + * @COGL_FEATURE_ID_SWAP_BUFFERS_EVENT: + * Available if the window system supports reporting an event + * for swap buffer completions. + * + * All the capabilities that can vary between different GPUs supported + * by Cogl. Applications that depend on any of these features should explicitly + * check for them using cogl_has_feature() or cogl_has_features(). + * + * Since: 1.10 + */ +typedef enum _CoglFeatureID +{ + COGL_FEATURE_ID_TEXTURE_NPOT_BASIC = 1, + COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP, + COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT, + COGL_FEATURE_ID_TEXTURE_NPOT, + COGL_FEATURE_ID_TEXTURE_RECTANGLE, + COGL_FEATURE_ID_TEXTURE_3D, + COGL_FEATURE_ID_GLSL, + COGL_FEATURE_ID_ARBFP, + COGL_FEATURE_ID_OFFSCREEN, + COGL_FEATURE_ID_OFFSCREEN_MULTISAMPLE, + COGL_FEATURE_ID_ONSCREEN_MULTIPLE, + COGL_FEATURE_ID_UNSIGNED_INT_INDICES, + COGL_FEATURE_ID_DEPTH_RANGE, + COGL_FEATURE_ID_POINT_SPRITE, + COGL_FEATURE_ID_MAP_BUFFER_FOR_READ, + COGL_FEATURE_ID_MAP_BUFFER_FOR_WRITE, + COGL_FEATURE_ID_MIRRORED_REPEAT, + COGL_FEATURE_ID_SWAP_BUFFERS_EVENT, + + /*< private > */ + _COGL_N_FEATURE_IDS +} CoglFeatureID; + + +#ifdef COGL_ENABLE_EXPERIMENTAL_2_0_API + +/** + * cogl_has_feature: + * @context: A #CoglContext pointer + * @feature: A #CoglFeatureID + * + * Checks if a given @feature is currently available + * + * Cogl does not aim to be a lowest common denominator API, it aims to + * expose all the interesting features of GPUs to application which + * means applications have some responsibility to explicitly check + * that certain features are available before depending on them. + * + * Returns: %TRUE if the @feature is currently supported or %FALSE if + * not. + * + * Since: 1.10 + * Stability: unstable + */ +gboolean +cogl_has_feature (CoglContext *context, CoglFeatureID feature); + +/** + * cogl_has_features: + * @context: A #CoglContext pointer + * @...: A 0 terminated list of CoglFeatureIDs + * + * Checks if a list of features are all currently available. + * + * This checks all of the listed features using cogl_has_feature() and + * returns %TRUE if all the features are available or %FALSE + * otherwise. + * + * Return value: %TRUE if all the features are available, %FALSE + * otherwise. + * + * Since: 1.10 + * Stability: unstable + */ +gboolean +cogl_has_features (CoglContext *context, ...); + +/** + * CoglFeatureCallback: + * @feature: A single feature currently supported by Cogl + * @user_data: A private pointer passed to cogl_foreach_feature(). + * + * A callback used with cogl_foreach_feature() for enumerating all + * context level features supported by Cogl. + * + * Since: 0.10 + * Stability: unstable + */ +typedef void (*CoglFeatureCallback) (CoglFeatureID feature, void *user_data); + +/** + * cogl_foreach_feature: + * @context: A #CoglContext pointer + * @callback: A #CoglFeatureCallback called for each supported feature + * @user_data: Private data to pass to the callback + * + * Iterates through all the context level features currently supported + * for a given @context and for each feature @callback is called. + * + * Since: 1.10 + * Stability: unstable + */ +void +cogl_foreach_feature (CoglContext *context, + CoglFeatureCallback callback, + void *user_data); + +#endif /* COGL_ENABLE_EXPERIMENTAL_2_0_API */ + G_END_DECLS #endif /* __COGL_CONTEXT_H__ */ diff --git a/cogl/cogl-euler.c b/cogl/cogl-euler.c index 4718e354a..614e763cc 100644 --- a/cogl/cogl-euler.c +++ b/cogl/cogl-euler.c @@ -24,6 +24,10 @@ * Robert Bragg */ +#ifdef HAVE_CONFIG_H +#include "config.h" +#endif + #include #include #include diff --git a/cogl/cogl-framebuffer.c b/cogl/cogl-framebuffer.c index ccefc4926..882972604 100644 --- a/cogl/cogl-framebuffer.c +++ b/cogl/cogl-framebuffer.c @@ -42,6 +42,8 @@ #include "cogl-pipeline-state-private.h" #include "cogl-matrix-private.h" #include "cogl-primitive-private.h" +#include "cogl-offscreen.h" +#include "cogl1-context.h" #ifndef GL_FRAMEBUFFER #define GL_FRAMEBUFFER 0x8D40 diff --git a/cogl/cogl-framebuffer.h b/cogl/cogl-framebuffer.h index f57334b50..1fbd23d42 100644 --- a/cogl/cogl-framebuffer.h +++ b/cogl/cogl-framebuffer.h @@ -28,8 +28,6 @@ #ifndef __COGL_FRAMEBUFFER_H #define __COGL_FRAMEBUFFER_H -#include - #include #ifdef COGL_HAS_WIN32_SUPPORT @@ -40,6 +38,15 @@ #include #endif /* COGL_HAS_EGL_PLATFORM_WAYLAND_SUPPORT */ +#ifdef COGL_ENABLE_EXPERIMENTAL_2_0_API +#include +#else +#include +#endif + +#include +#include + G_BEGIN_DECLS /** @@ -80,6 +87,8 @@ G_BEGIN_DECLS * configuration. */ +typedef struct _CoglFramebuffer CoglFramebuffer; + #ifdef COGL_ENABLE_EXPERIMENTAL_API #define COGL_FRAMEBUFFER(X) ((CoglFramebuffer *)(X)) diff --git a/cogl/cogl-indices.h b/cogl/cogl-indices.h index 58c2671b6..010edd3f5 100644 --- a/cogl/cogl-indices.h +++ b/cogl/cogl-indices.h @@ -31,6 +31,11 @@ #ifndef __COGL_INDICES_H__ #define __COGL_INDICES_H__ +/* We forward declare the CoglIndices type here to avoid some circular + * dependency issues with the following headers. + */ +typedef struct _CoglIndices CoglIndices; + #include G_BEGIN_DECLS @@ -94,8 +99,6 @@ G_BEGIN_DECLS * for drawing quads as above. */ -typedef struct _CoglIndices CoglIndices; - CoglIndices * cogl_indices_new (CoglContext *context, CoglIndicesType type, diff --git a/cogl/cogl-journal.c b/cogl/cogl-journal.c index 5d0cf05ce..06dc1b963 100644 --- a/cogl/cogl-journal.c +++ b/cogl/cogl-journal.c @@ -39,6 +39,7 @@ #include "cogl-attribute-private.h" #include "cogl-point-in-poly-private.h" #include "cogl-private.h" +#include "cogl1-context.h" #include #include diff --git a/cogl/cogl-onscreen.c b/cogl/cogl-onscreen.c index 7c81ec008..103baf950 100644 --- a/cogl/cogl-onscreen.c +++ b/cogl/cogl-onscreen.c @@ -31,6 +31,7 @@ #include "cogl-onscreen-template-private.h" #include "cogl-context-private.h" #include "cogl-object-private.h" +#include "cogl1-context.h" static void _cogl_onscreen_free (CoglOnscreen *onscreen); diff --git a/cogl/cogl-pipeline.c b/cogl/cogl-pipeline.c index b94b16e05..da76a3ef5 100644 --- a/cogl/cogl-pipeline.c +++ b/cogl/cogl-pipeline.c @@ -46,6 +46,7 @@ #include "cogl-util.h" #include "cogl-profile.h" #include "cogl-depth-state-private.h" +#include "cogl1-context.h" #include #include diff --git a/cogl/cogl-primitive.h b/cogl/cogl-primitive.h index af114f6f1..134bb87cf 100644 --- a/cogl/cogl-primitive.h +++ b/cogl/cogl-primitive.h @@ -31,6 +31,11 @@ #ifndef __COGL_PRIMITIVE_H__ #define __COGL_PRIMITIVE_H__ +/* We forward declare the CoglPrimitive type here to avoid some circular + * dependency issues with the following headers. + */ +typedef struct _CoglPrimitive CoglPrimitive; + #include /* for CoglVerticesMode */ #include @@ -44,8 +49,6 @@ G_BEGIN_DECLS * FIXME */ -typedef struct _CoglPrimitive CoglPrimitive; - /** * CoglVertexP2: * @x: The x component of a position attribute diff --git a/cogl/cogl-primitives.c b/cogl/cogl-primitives.c index 3bea1b0f0..5a25cd60c 100644 --- a/cogl/cogl-primitives.c +++ b/cogl/cogl-primitives.c @@ -39,6 +39,7 @@ #include "cogl-private.h" #include "cogl-meta-texture.h" #include "cogl-framebuffer-private.h" +#include "cogl1-context.h" #include #include diff --git a/cogl/cogl-quaternion.c b/cogl/cogl-quaternion.c index d55275aec..a49b8133a 100644 --- a/cogl/cogl-quaternion.c +++ b/cogl/cogl-quaternion.c @@ -34,6 +34,10 @@ * 3D Maths Primer for Graphics and Game Development ISBN-10: 1556229119 */ +#ifdef HAVE_CONFIG_H +#include "config.h" +#endif + #include #include #include diff --git a/cogl/cogl-texture.c b/cogl/cogl-texture.c index 6f6f96303..bb3567761 100644 --- a/cogl/cogl-texture.c +++ b/cogl/cogl-texture.c @@ -52,6 +52,7 @@ #include "cogl-object-private.h" #include "cogl-primitives.h" #include "cogl-framebuffer-private.h" +#include "cogl1-context.h" #include #include diff --git a/cogl/cogl-texture.h b/cogl/cogl-texture.h index 36fde2a21..5bbd06af4 100644 --- a/cogl/cogl-texture.h +++ b/cogl/cogl-texture.h @@ -28,6 +28,11 @@ #ifndef __COGL_TEXTURE_H__ #define __COGL_TEXTURE_H__ +/* We forward declare the CoglTexture type here to avoid some circular + * dependency issues with the following headers. + */ +typedef struct _CoglTexture CoglTexture; + #include #include #if defined (COGL_ENABLE_EXPERIMENTAL_API) @@ -46,7 +51,6 @@ G_BEGIN_DECLS * loading and manipulating textures. */ -typedef struct _CoglTexture CoglTexture; #define COGL_TEXTURE(X) ((CoglTexture *)X) #define COGL_TEXTURE_MAX_WASTE 127 diff --git a/cogl/cogl-types.h b/cogl/cogl-types.h index b8edb695e..d60c4acc0 100644 --- a/cogl/cogl-types.h +++ b/cogl/cogl-types.h @@ -717,6 +717,34 @@ typedef enum COGL_WINDING_COUNTER_CLOCKWISE } CoglWinding; +/** + * CoglBufferBit: + * @COGL_BUFFER_BIT_COLOR: Selects the primary color buffer + * @COGL_BUFFER_BIT_DEPTH: Selects the depth buffer + * @COGL_BUFFER_BIT_STENCIL: Selects the stencil buffer + * + * Types of auxiliary buffers + * + * Since: 1.0 + */ +typedef enum { + COGL_BUFFER_BIT_COLOR = 1L<<0, + COGL_BUFFER_BIT_DEPTH = 1L<<1, + COGL_BUFFER_BIT_STENCIL = 1L<<2 +} CoglBufferBit; + +/** + * CoglReadPixelsFlags: + * @COGL_READ_PIXELS_COLOR_BUFFER: Read from the color buffer + * + * Flags for cogl_read_pixels() + * + * Since: 1.0 + */ +typedef enum { /*< prefix=COGL_READ_PIXELS >*/ + COGL_READ_PIXELS_COLOR_BUFFER = 1L << 0 +} CoglReadPixelsFlags; + G_END_DECLS #endif /* __COGL_TYPES_H__ */ diff --git a/cogl/cogl-vector.c b/cogl/cogl-vector.c index d0205fb8b..4246ddfcb 100644 --- a/cogl/cogl-vector.c +++ b/cogl/cogl-vector.c @@ -24,6 +24,10 @@ * Robert Bragg */ +#ifdef HAVE_CONFIG_H +#include "config.h" +#endif + #include #include #include diff --git a/cogl/cogl-vertex-buffer.c b/cogl/cogl-vertex-buffer.c index 31a67ce51..9aec04761 100644 --- a/cogl/cogl-vertex-buffer.c +++ b/cogl/cogl-vertex-buffer.c @@ -108,6 +108,7 @@ #include "cogl-primitives.h" #include "cogl-framebuffer-private.h" #include "cogl-journal-private.h" +#include "cogl1-context.h" #define PAD_FOR_ALIGNMENT(VAR, TYPE_SIZE) \ (VAR = TYPE_SIZE + ((VAR - 1) & ~(TYPE_SIZE - 1))) diff --git a/cogl/cogl.c b/cogl/cogl.c index cba3de7aa..8ed44592c 100644 --- a/cogl/cogl.c +++ b/cogl/cogl.c @@ -50,6 +50,7 @@ #include "cogl-renderer-private.h" #include "cogl-config-private.h" #include "cogl-private.h" +#include "cogl1-context.h" #ifndef GL_PACK_INVERT_MESA #define GL_PACK_INVERT_MESA 0x8758 diff --git a/cogl/cogl.h b/cogl/cogl.h index ab46eeb05..efe948fb7 100644 --- a/cogl/cogl.h +++ b/cogl/cogl.h @@ -44,6 +44,7 @@ #include #include +#include #include #include #include @@ -67,8 +68,6 @@ #include -typedef struct _CoglFramebuffer CoglFramebuffer; - #if defined (COGL_ENABLE_EXPERIMENTAL_API) #include #include @@ -115,8 +114,6 @@ typedef struct _CoglFramebuffer CoglFramebuffer; #include #endif -G_BEGIN_DECLS - /** * SECTION:cogl * @short_description: General purpose API @@ -124,1311 +121,6 @@ G_BEGIN_DECLS * General utility functions for COGL. */ -/** - * cogl_get_option_group: - * - * Retrieves the #GOptionGroup used by COGL to parse the command - * line options. Clutter uses this to handle the COGL command line - * options during its initialization process. - * - * Return value: a #GOptionGroup - * - * Since: 1.0 - */ -GOptionGroup * -cogl_get_option_group (void); - -/* Misc */ -/** - * cogl_get_features: - * - * Returns all of the features supported by COGL. - * - * Return value: A logical OR of all the supported COGL features. - * - * Since: 0.8 - */ -CoglFeatureFlags -cogl_get_features (void); - -/** - * cogl_features_available: - * @features: A bitmask of features to check for - * - * Checks whether the given COGL features are available. Multiple - * features can be checked for by or-ing them together with the '|' - * operator. %TRUE is only returned if all of the requested features - * are available. - * - * Return value: %TRUE if the features are available, %FALSE otherwise. - */ -gboolean -cogl_features_available (CoglFeatureFlags features); - -/* XXX: not guarded by the EXPERIMENTAL_2_0_API defines to avoid - * upsetting glib-mkenums, but this can still be considered implicitly - * experimental since it's only useable with experimental API... */ -/** - * CoglFeatureID: - * @COGL_FEATURE_ID_TEXTURE_NPOT_BASIC: The hardware supports non power - * of two textures, but you also need to check the - * %COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP and %COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT - * features to know if the hardware supports npot texture mipmaps - * or repeat modes other than - * %COGL_RENDERER_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE respectively. - * @COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP: Mipmapping is supported in - * conjuntion with non power of two textures. - * @COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT: Repeat modes other than - * %COGL_RENDERER_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE are supported by the - * hardware. - * @COGL_FEATURE_ID_TEXTURE_NPOT: Non power of two textures are supported - * by the hardware. This is a equivalent to the - * %COGL_FEATURE_ID_TEXTURE_NPOT_BASIC, %COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP - * and %COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT features combined. - * @COGL_FEATURE_ID_TEXTURE_RECTANGLE: Support for rectangular - * textures with non-normalized texture coordinates. - * @COGL_FEATURE_ID_TEXTURE_3D: 3D texture support - * @COGL_FEATURE_ID_OFFSCREEN: Offscreen rendering support - * @COGL_FEATURE_ID_OFFSCREEN_MULTISAMPLE: Multisample support for - * offscreen framebuffers - * @COGL_FEATURE_ID_ONSCREEN_MULTIPLE: Multiple onscreen framebuffers - * supported. - * @COGL_FEATURE_ID_GLSL: GLSL support - * @COGL_FEATURE_ID_ARBFP: ARBFP support - * @COGL_FEATURE_ID_UNSIGNED_INT_INDICES: Set if - * %COGL_RENDERER_INDICES_TYPE_UNSIGNED_INT is supported in - * cogl_indices_new(). - * @COGL_FEATURE_ID_DEPTH_RANGE: cogl_pipeline_set_depth_range() support - * @COGL_FEATURE_ID_POINT_SPRITE: Whether - * cogl_pipeline_set_layer_point_sprite_coords_enabled() is supported. - * @COGL_FEATURE_ID_MAP_BUFFER_FOR_READ: Whether cogl_buffer_map() is - * supported with CoglBufferAccess including read support. - * @COGL_FEATURE_ID_MAP_BUFFER_FOR_WRITE: Whether cogl_buffer_map() is - * supported with CoglBufferAccess including write support. - * @COGL_FEATURE_ID_MIRRORED_REPEAT: Whether - * %COGL_PIPELINE_WRAP_MODE_MIRRORED_REPEAT is supported. - * @COGL_FEATURE_ID_SWAP_BUFFERS_EVENT: - * Available if the window system supports reporting an event - * for swap buffer completions. - * - * All the capabilities that can vary between different GPUs supported - * by Cogl. Applications that depend on any of these features should explicitly - * check for them using cogl_has_feature() or cogl_has_features(). - * - * Since: 1.10 - */ -typedef enum _CoglFeatureID -{ - COGL_FEATURE_ID_TEXTURE_NPOT_BASIC = 1, - COGL_FEATURE_ID_TEXTURE_NPOT_MIPMAP, - COGL_FEATURE_ID_TEXTURE_NPOT_REPEAT, - COGL_FEATURE_ID_TEXTURE_NPOT, - COGL_FEATURE_ID_TEXTURE_RECTANGLE, - COGL_FEATURE_ID_TEXTURE_3D, - COGL_FEATURE_ID_GLSL, - COGL_FEATURE_ID_ARBFP, - COGL_FEATURE_ID_OFFSCREEN, - COGL_FEATURE_ID_OFFSCREEN_MULTISAMPLE, - COGL_FEATURE_ID_ONSCREEN_MULTIPLE, - COGL_FEATURE_ID_UNSIGNED_INT_INDICES, - COGL_FEATURE_ID_DEPTH_RANGE, - COGL_FEATURE_ID_POINT_SPRITE, - COGL_FEATURE_ID_MAP_BUFFER_FOR_READ, - COGL_FEATURE_ID_MAP_BUFFER_FOR_WRITE, - COGL_FEATURE_ID_MIRRORED_REPEAT, - COGL_FEATURE_ID_SWAP_BUFFERS_EVENT, - - /*< private > */ - _COGL_N_FEATURE_IDS -} CoglFeatureID; - - -#ifdef COGL_ENABLE_EXPERIMENTAL_2_0_API - -/** - * cogl_has_feature: - * @context: A #CoglContext pointer - * @feature: A #CoglFeatureID - * - * Checks if a given @feature is currently available - * - * Cogl does not aim to be a lowest common denominator API, it aims to - * expose all the interesting features of GPUs to application which - * means applications have some responsibility to explicitly check - * that certain features are available before depending on them. - * - * Returns: %TRUE if the @feature is currently supported or %FALSE if - * not. - * - * Since: 1.10 - * Stability: unstable - */ -gboolean -cogl_has_feature (CoglContext *context, CoglFeatureID feature); - -/** - * cogl_has_features: - * @context: A #CoglContext pointer - * @...: A 0 terminated list of CoglFeatureIDs - * - * Checks if a list of features are all currently available. - * - * This checks all of the listed features using cogl_has_feature() and - * returns %TRUE if all the features are available or %FALSE - * otherwise. - * - * Return value: %TRUE if all the features are available, %FALSE - * otherwise. - * - * Since: 1.10 - * Stability: unstable - */ -gboolean -cogl_has_features (CoglContext *context, ...); - -/** - * CoglFeatureCallback: - * @feature: A single feature currently supported by Cogl - * @user_data: A private pointer passed to cogl_foreach_feature(). - * - * A callback used with cogl_foreach_feature() for enumerating all - * context level features supported by Cogl. - * - * Since: 1.10 - * Stability: unstable - */ -typedef void (*CoglFeatureCallback) (CoglFeatureID feature, void *user_data); - -/** - * cogl_foreach_feature: - * @context: A #CoglContext pointer - * @callback: A #CoglFeatureCallback called for each supported feature - * @user_data: Private data to pass to the callback - * - * Iterates through all the context level features currently supported - * for a given @context and for each feature @callback is called. - * - * Since: 1.10 - * Stability: unstable - */ -void -cogl_foreach_feature (CoglContext *context, - CoglFeatureCallback callback, - void *user_data); - -#endif /* COGL_ENABLE_EXPERIMENTAL_2_0_API */ - -/** - * cogl_get_proc_address: - * @name: the name of the function. - * - * Gets a pointer to a given GL or GL ES extension function. This acts - * as a wrapper around glXGetProcAddress() or whatever is the - * appropriate function for the current backend. - * - * Return value: a pointer to the requested function or %NULL if the - * function is not available. - */ -CoglFuncPtr -cogl_get_proc_address (const char *name); - -#ifndef COGL_DISABLE_DEPRECATED - -/** - * cogl_check_extension: - * @name: extension to check for - * @ext: list of extensions - * - * Check whether @name occurs in list of extensions in @ext. - * - * Return value: %TRUE if the extension occurs in the list, %FALSE otherwise. - * - * Deprecated: 1.2: OpenGL is an implementation detail for Cogl and so it's - * not appropriate to expose OpenGL extensions through the Cogl API. This - * function can be replaced by the following equivalent code: - * |[ - * gboolean retval = (strstr (ext, name) != NULL) ? TRUE : FALSE; - * ]| - */ -gboolean -cogl_check_extension (const char *name, - const char *ext) G_GNUC_DEPRECATED; - -#endif /* COGL_DISABLE_DEPRECATED */ - -/** - * cogl_get_bitmasks: - * @red: (out): Return location for the number of red bits or %NULL - * @green: (out): Return location for the number of green bits or %NULL - * @blue: (out): Return location for the number of blue bits or %NULL - * @alpha: (out): Return location for the number of alpha bits or %NULL - * - * Gets the number of bitplanes used for each of the color components - * in the color buffer. Pass %NULL for any of the arguments if the - * value is not required. - */ -void -cogl_get_bitmasks (int *red, - int *green, - int *blue, - int *alpha); - -/** - * cogl_perspective: - * @fovy: Vertical field of view angle in degrees. - * @aspect: The (width over height) aspect ratio for display - * @z_near: The distance to the near clipping plane (Must be positive) - * @z_far: The distance to the far clipping plane (Must be positive) - * - * Replaces the current projection matrix with a perspective matrix - * based on the provided values. - * - * You should be careful not to have to great a @z_far / @z_near - * ratio since that will reduce the effectiveness of depth testing - * since there wont be enough precision to identify the depth of - * objects near to each other. - */ -void -cogl_perspective (float fovy, - float aspect, - float z_near, - float z_far); - -/** - * cogl_frustum: - * @left: X position of the left clipping plane where it - * intersects the near clipping plane - * @right: X position of the right clipping plane where it - * intersects the near clipping plane - * @bottom: Y position of the bottom clipping plane where it - * intersects the near clipping plane - * @top: Y position of the top clipping plane where it intersects - * the near clipping plane - * @z_near: The distance to the near clipping plane (Must be positive) - * @z_far: The distance to the far clipping plane (Must be positive) - * - * Replaces the current projection matrix with a perspective matrix - * for a given viewing frustum defined by 4 side clip planes that - * all cross through the origin and 2 near and far clip planes. - * - * Since: 0.8.2 - */ -void -cogl_frustum (float left, - float right, - float bottom, - float top, - float z_near, - float z_far); - -/** - * cogl_ortho: - * @left: The coordinate for the left clipping plane - * @right: The coordinate for the right clipping plane - * @bottom: The coordinate for the bottom clipping plane - * @top: The coordinate for the top clipping plane - * @near: The distance to the near clipping - * plane (negative if the plane is behind the viewer) - * @far: The distance for the far clipping - * plane (negative if the plane is behind the viewer) - * - * Replaces the current projection matrix with an orthographic projection - * matrix. See to see how the matrix is - * calculated. - * - *
- * - * - *
- * - * This function copies the arguments from OpenGL's glOrtho() even - * though they are unnecessarily confusing due to the z near and z far - * arguments actually being a "distance" from the origin, where - * negative values are behind the viewer, instead of coordinates for - * the z clipping planes which would have been consistent with the - * left, right bottom and top arguments. - * - * Since: 1.0 - */ -void -cogl_ortho (float left, - float right, - float bottom, - float top, - float near, - float far); - -#ifndef COGL_DISABLE_DEPRECATED - -/** - * cogl_viewport: - * @width: Width of the viewport - * @height: Height of the viewport - * - * Replace the current viewport with the given values. - * - * Since: 0.8.2 - * - * Deprecated: 1.2: Use cogl_set_viewport() instead - */ -void -cogl_viewport (unsigned int width, - unsigned int height) G_GNUC_DEPRECATED; - -#endif /* COGL_DISABLE_DEPRECATED */ - -/** - * cogl_set_viewport: - * @x: X offset of the viewport - * @y: Y offset of the viewport - * @width: Width of the viewport - * @height: Height of the viewport - * - * Replaces the current viewport with the given values. - * - * Since: 1.2 - */ -void -cogl_set_viewport (int x, - int y, - int width, - int height); - -/** - * cogl_push_matrix: - * - * Stores the current model-view matrix on the matrix stack. The matrix - * can later be restored with cogl_pop_matrix(). - */ -void -cogl_push_matrix (void); - -/** - * cogl_pop_matrix: - * - * Restores the current model-view matrix from the matrix stack. - */ -void -cogl_pop_matrix (void); - -/** - * cogl_scale: - * @x: Amount to scale along the x-axis - * @y: Amount to scale along the y-axis - * @z: Amount to scale along the z-axis - * - * Multiplies the current model-view matrix by one that scales the x, - * y and z axes by the given values. - */ -void -cogl_scale (float x, - float y, - float z); - -/** - * cogl_translate: - * @x: Distance to translate along the x-axis - * @y: Distance to translate along the y-axis - * @z: Distance to translate along the z-axis - * - * Multiplies the current model-view matrix by one that translates the - * model along all three axes according to the given values. - */ -void -cogl_translate (float x, - float y, - float z); - -/** - * cogl_rotate: - * @angle: Angle in degrees to rotate. - * @x: X-component of vertex to rotate around. - * @y: Y-component of vertex to rotate around. - * @z: Z-component of vertex to rotate around. - * - * Multiplies the current model-view matrix by one that rotates the - * model around the vertex specified by @x, @y and @z. The rotation - * follows the right-hand thumb rule so for example rotating by 10 - * degrees about the vertex (0, 0, 1) causes a small counter-clockwise - * rotation. - */ -void -cogl_rotate (float angle, - float x, - float y, - float z); - -/** - * cogl_transform: - * @matrix: the matrix to multiply with the current model-view - * - * Multiplies the current model-view matrix by the given matrix. - * - * Since: 1.4 - */ -void -cogl_transform (const CoglMatrix *matrix); - -/** - * cogl_get_modelview_matrix: - * @matrix: (out): return location for the model-view matrix - * - * Stores the current model-view matrix in @matrix. - */ -void -cogl_get_modelview_matrix (CoglMatrix *matrix); - -/** - * cogl_set_modelview_matrix: - * @matrix: the new model-view matrix - * - * Loads @matrix as the new model-view matrix. - */ -void -cogl_set_modelview_matrix (CoglMatrix *matrix); - -/** - * cogl_get_projection_matrix: - * @matrix: (out): return location for the projection matrix - * - * Stores the current projection matrix in @matrix. - */ -void -cogl_get_projection_matrix (CoglMatrix *matrix); - -/** - * cogl_set_projection_matrix: - * @matrix: the new projection matrix - * - * Loads matrix as the new projection matrix. - */ -void -cogl_set_projection_matrix (CoglMatrix *matrix); - -/** - * cogl_get_viewport: - * @v: (out) (array fixed-size=4): pointer to a 4 element array - * of #floats to receive the viewport dimensions. - * - * Stores the current viewport in @v. @v[0] and @v[1] get the x and y - * position of the viewport and @v[2] and @v[3] get the width and - * height. - */ -void -cogl_get_viewport (float v[4]); - -/** - * cogl_set_depth_test_enabled: - * @setting: %TRUE to enable depth testing or %FALSE to disable. - * - * Sets whether depth testing is enabled. If it is disabled then the - * order that actors are layered on the screen depends solely on the - * order specified using clutter_actor_raise() and - * clutter_actor_lower(), otherwise it will also take into account the - * actor's depth. Depth testing is disabled by default. - * - * Deprecated: 1.4: Use cogl_material_set_depth_test_enabled() - * instead. - */ -void -cogl_set_depth_test_enabled (gboolean setting); - -/** - * cogl_get_depth_test_enabled: - * - * Queries if depth testing has been enabled via cogl_set_depth_test_enable() - * - * Return value: %TRUE if depth testing is enabled, and %FALSE otherwise - * - * Deprecated: 1.4: Use cogl_material_get_depth_test_enabled() - * instead. - */ -gboolean -cogl_get_depth_test_enabled (void); - -/** - * cogl_set_backface_culling_enabled: - * @setting: %TRUE to enable backface culling or %FALSE to disable. - * - * Sets whether textures positioned so that their backface is showing - * should be hidden. This can be used to efficiently draw two-sided - * textures or fully closed cubes without enabling depth testing. This - * only affects calls to the cogl_rectangle* family of functions and - * cogl_vertex_buffer_draw*. Backface culling is disabled by default. - */ -void -cogl_set_backface_culling_enabled (gboolean setting); - -/** - * cogl_get_backface_culling_enabled: - * - * Queries if backface culling has been enabled via - * cogl_set_backface_culling_enabled() - * - * Return value: %TRUE if backface culling is enabled, and %FALSE otherwise - */ -gboolean -cogl_get_backface_culling_enabled (void); - -/** - * cogl_set_fog: - * @fog_color: The color of the fog - * @mode: A #CoglFogMode that determines the equation used to calculate the - * fogging blend factor. - * @density: Used by %COGL_FOG_MODE_EXPONENTIAL and by - * %COGL_FOG_MODE_EXPONENTIAL_SQUARED equations. - * @z_near: Position along Z axis where no fogging should be applied - * @z_far: Position along Z axis where full fogging should be applied - * - * Enables fogging. Fogging causes vertices that are further away from the eye - * to be rendered with a different color. The color is determined according to - * the chosen fog mode; at it's simplest the color is linearly interpolated so - * that vertices at @z_near are drawn fully with their original color and - * vertices at @z_far are drawn fully with @fog_color. Fogging will remain - * enabled until you call cogl_disable_fog(). - * - * The fogging functions only work correctly when primitives use - * unmultiplied alpha colors. By default Cogl will premultiply textures - * and cogl_set_source_color() will premultiply colors, so unless you - * explicitly load your textures requesting an unmultiplied internal format - * and use cogl_material_set_color() you can only use fogging with fully - * opaque primitives. This might improve in the future when we can depend - * on fragment shaders. - */ -void -cogl_set_fog (const CoglColor *fog_color, - CoglFogMode mode, - float density, - float z_near, - float z_far); - -/** - * cogl_disable_fog: - * - * This function disables fogging, so primitives drawn afterwards will not be - * blended with any previously set fog color. - */ -void -cogl_disable_fog (void); - -/** - * CoglBufferBit: - * @COGL_BUFFER_BIT_COLOR: Selects the primary color buffer - * @COGL_BUFFER_BIT_DEPTH: Selects the depth buffer - * @COGL_BUFFER_BIT_STENCIL: Selects the stencil buffer - * - * Types of auxiliary buffers - * - * Since: 1.0 - */ -typedef enum { - COGL_BUFFER_BIT_COLOR = 1L<<0, - COGL_BUFFER_BIT_DEPTH = 1L<<1, - COGL_BUFFER_BIT_STENCIL = 1L<<2 -} CoglBufferBit; - -/** - * cogl_clear: - * @color: Background color to clear to - * @buffers: A mask of #CoglBufferBit's identifying which auxiliary - * buffers to clear - * - * Clears all the auxiliary buffers identified in the @buffers mask, and if - * that includes the color buffer then the specified @color is used. - */ -void -cogl_clear (const CoglColor *color, - unsigned long buffers); - -/** - * cogl_set_source: - * @material: A #CoglMaterial - * - * This function changes the material at the top of the source stack. - * The material at the top of this stack defines the GPU state used to - * process subsequent primitives, such as rectangles drawn with - * cogl_rectangle() or vertices drawn using cogl_vertex_buffer_draw(). - * - * Since: 1.0 - */ -void -cogl_set_source (void *material); - -/** - * cogl_get_source: - * - * Returns the current source material as previously set using - * cogl_set_source(). - * - * You should typically consider the returned material immutable - * and not try to change any of its properties unless you own a - * reference to that material. At times you may be able to get a - * reference to an internally managed materials and the result of - * modifying such materials is undefined. - * - * Return value: The current source material. - * - * Since: 1.6 - */ -void * -cogl_get_source (void); - -/** - * cogl_push_source: - * @material: A #CoglMaterial - * - * Pushes the given @material to the top of the source stack. The - * material at the top of this stack defines the GPU state used to - * process later primitives as defined by cogl_set_source(). - * - * Since: 1.6 - */ -void -cogl_push_source (void *material); - -/** - * cogl_pop_source: - * - * Removes the material at the top of the source stack. The material - * at the top of this stack defines the GPU state used to process - * later primitives as defined by cogl_set_source(). - * - * Since: 1.6 - */ -void -cogl_pop_source (void); - -/** - * cogl_set_source_color: - * @color: a #CoglColor - * - * This is a convenience function for creating a solid fill source material - * from the given color. This color will be used for any subsequent drawing - * operation. - * - * The color will be premultiplied by Cogl, so the color should be - * non-premultiplied. For example: use (1.0, 0.0, 0.0, 0.5) for - * semi-transparent red. - * - * See also cogl_set_source_color4ub() and cogl_set_source_color4f() - * if you already have the color components. - * - * Since: 1.0 - */ -void -cogl_set_source_color (const CoglColor *color); - -/** - * cogl_set_source_color4ub: - * @red: value of the red channel, between 0 and 255 - * @green: value of the green channel, between 0 and 255 - * @blue: value of the blue channel, between 0 and 255 - * @alpha: value of the alpha channel, between 0 and 255 - * - * This is a convenience function for creating a solid fill source material - * from the given color using unsigned bytes for each component. This - * color will be used for any subsequent drawing operation. - * - * The value for each component is an unsigned byte in the range - * between 0 and 255. - * - * Since: 1.0 - */ -void -cogl_set_source_color4ub (guint8 red, - guint8 green, - guint8 blue, - guint8 alpha); - -/** - * cogl_set_source_color4f: - * @red: value of the red channel, between 0 and %1.0 - * @green: value of the green channel, between 0 and %1.0 - * @blue: value of the blue channel, between 0 and %1.0 - * @alpha: value of the alpha channel, between 0 and %1.0 - * - * This is a convenience function for creating a solid fill source material - * from the given color using normalized values for each component. This color - * will be used for any subsequent drawing operation. - * - * The value for each component is a fixed point number in the range - * between 0 and %1.0. If the values passed in are outside that - * range, they will be clamped. - * - * Since: 1.0 - */ -void -cogl_set_source_color4f (float red, - float green, - float blue, - float alpha); - -/** - * cogl_set_source_texture: - * @texture: The #CoglTexture you want as your source - * - * This is a convenience function for creating a material with the first - * layer set to @texture and setting that material as the source with - * cogl_set_source. - * - * Note: There is no interaction between calls to cogl_set_source_color - * and cogl_set_source_texture. If you need to blend a texture with a color then - * you can create a simple material like this: - * - * material = cogl_material_new (); - * cogl_material_set_color4ub (material, 0xff, 0x00, 0x00, 0x80); - * cogl_material_set_layer (material, 0, tex_handle); - * cogl_set_source (material); - * - * - * Since: 1.0 - */ -void -cogl_set_source_texture (CoglTexture *texture); - -/** - * SECTION:cogl-clipping - * @short_description: Fuctions for manipulating a stack of clipping regions - * - * To support clipping your geometry to rectangles or paths Cogl exposes a - * stack based API whereby each clip region you push onto the stack is - * intersected with the previous region. - */ - -#ifndef COGL_DISABLE_DEPRECATED - -/** - * cogl_clip_push_window_rect: - * @x_offset: left edge of the clip rectangle in window coordinates - * @y_offset: top edge of the clip rectangle in window coordinates - * @width: width of the clip rectangle - * @height: height of the clip rectangle - * - * Specifies a rectangular clipping area for all subsequent drawing - * operations. Any drawing commands that extend outside the rectangle - * will be clipped so that only the portion inside the rectangle will - * be displayed. The rectangle dimensions are not transformed by the - * current model-view matrix. - * - * The rectangle is intersected with the current clip region. To undo - * the effect of this function, call cogl_clip_pop(). - * - * Deprecated: 1.2: Use cogl_clip_push_window_rectangle() instead - */ -void -cogl_clip_push_window_rect (float x_offset, - float y_offset, - float width, - float height) G_GNUC_DEPRECATED; - -#endif /* COGL_DISABLE_DEPRECATED */ - -/** - * cogl_clip_push_window_rectangle: - * @x_offset: left edge of the clip rectangle in window coordinates - * @y_offset: top edge of the clip rectangle in window coordinates - * @width: width of the clip rectangle - * @height: height of the clip rectangle - * - * Specifies a rectangular clipping area for all subsequent drawing - * operations. Any drawing commands that extend outside the rectangle - * will be clipped so that only the portion inside the rectangle will - * be displayed. The rectangle dimensions are not transformed by the - * current model-view matrix. - * - * The rectangle is intersected with the current clip region. To undo - * the effect of this function, call cogl_clip_pop(). - * - * Since: 1.2 - */ -void -cogl_clip_push_window_rectangle (int x_offset, - int y_offset, - int width, - int height); - -#ifndef COGL_DISABLE_DEPRECATED - -/** - * cogl_clip_push: - * @x_offset: left edge of the clip rectangle - * @y_offset: top edge of the clip rectangle - * @width: width of the clip rectangle - * @height: height of the clip rectangle - * - * Specifies a rectangular clipping area for all subsequent drawing - * operations. Any drawing commands that extend outside the rectangle - * will be clipped so that only the portion inside the rectangle will - * be displayed. The rectangle dimensions are transformed by the - * current model-view matrix. - * - * The rectangle is intersected with the current clip region. To undo - * the effect of this function, call cogl_clip_pop(). - * - * Deprecated: 1.2: The x, y, width, height arguments are inconsistent - * with other API that specify rectangles in model space, and when used - * with a coordinate space that puts the origin at the center and y+ - * extending up, it's awkward to use. Please use cogl_clip_push_rectangle() - * instead - */ -void -cogl_clip_push (float x_offset, - float y_offset, - float width, - float height) G_GNUC_DEPRECATED; - -#endif /* COGL_DISABLE_DEPRECATED */ - -/** - * cogl_clip_push_rectangle: - * @x0: x coordinate for top left corner of the clip rectangle - * @y0: y coordinate for top left corner of the clip rectangle - * @x1: x coordinate for bottom right corner of the clip rectangle - * @y1: y coordinate for bottom right corner of the clip rectangle - * - * Specifies a rectangular clipping area for all subsequent drawing - * operations. Any drawing commands that extend outside the rectangle - * will be clipped so that only the portion inside the rectangle will - * be displayed. The rectangle dimensions are transformed by the - * current model-view matrix. - * - * The rectangle is intersected with the current clip region. To undo - * the effect of this function, call cogl_clip_pop(). - * - * Since: 1.2 - */ -void -cogl_clip_push_rectangle (float x0, - float y0, - float x1, - float y1); - -/** - * cogl_clip_push_from_path_preserve: - * - * Sets a new clipping area using the current path. The current path - * is then cleared. The clipping area is intersected with the previous - * clipping area. To restore the previous clipping area, call - * cogl_clip_pop(). - * - * Since: 1.0 - */ -void -cogl_clip_push_from_path_preserve (void); - -#ifdef COGL_ENABLE_EXPERIMENTAL_2_0_API -/** - * cogl_clip_push_primitive: - * @primitive: A #CoglPrimitive describing a flat 2D shape - * @bounds_x1: x coordinate for the top-left corner of the primitives - * bounds - * @bounds_y1: y coordinate for the top-left corner of the primitives - * bounds - * @bounds_x2: x coordinate for the top-left corner of the primitives - * bounds - * @bounds_y2: x coordinate for the bottom-right corner of the - * primitives bounds. - * @bounds_x1: y coordinate for the bottom-right corner of the - * primitives bounds. - * - * Sets a new clipping area using a 2D shaped described with a - * #CoglPrimitive. The shape must not contain self overlapping - * geometry and must lie on a single 2D plane. A bounding box of the - * 2D shape in local coordinates (the same coordinates used to - * describe the shape) must be given. It is acceptable for the bounds - * to be larger than the true bounds but behaviour is undefined if the - * bounds are smaller than the true bounds. - * - * The primitive is transformed by the current model-view matrix and - * the silhouette is intersected with the previous clipping area. To - * restore the previous clipping area, call - * cogl_clip_pop(). - * - * Since: 1.10 - * Stability: unstable - */ -void -cogl_clip_push_primitive (CoglPrimitive *primitive, - float bounds_x1, - float bounds_y1, - float bounds_x2, - float bounds_y2); -#endif - -/** - * cogl_clip_pop: - * - * Reverts the clipping region to the state before the last call to - * cogl_clip_push(). - */ -void -cogl_clip_pop (void); - -#ifndef COGL_DISABLE_DEPRECATED - -/** - * cogl_clip_ensure: - * - * Ensures that the current clipping region has been set in GL. This - * will automatically be called before any Cogl primitives but it - * maybe be neccessary to call if you are using raw GL calls with - * clipping. - * - * Deprecated: 1.2: Calling this function has no effect - * - * Since: 1.0 - */ -void -cogl_clip_ensure (void) G_GNUC_DEPRECATED; - -/** - * cogl_clip_stack_save: - * - * Save the entire state of the clipping stack and then clear all - * clipping. The previous state can be returned to with - * cogl_clip_stack_restore(). Each call to cogl_clip_push() after this - * must be matched by a call to cogl_clip_pop() before calling - * cogl_clip_stack_restore(). - * - * Deprecated: 1.2: This was originally added to allow us to save the - * clip stack when switching to an offscreen framebuffer, but it's - * not necessary anymore given that framebuffers now own separate - * clip stacks which will be automatically switched between when a - * new buffer is set. Calling this function has no effect - * - * Since: 0.8.2 - */ -void -cogl_clip_stack_save (void) G_GNUC_DEPRECATED; - -/** - * cogl_clip_stack_restore: - * - * Restore the state of the clipping stack that was previously saved - * by cogl_clip_stack_save(). - * - * Deprecated: 1.2: This was originally added to allow us to restore - * the clip stack when switching back from an offscreen framebuffer, - * but it's not necessary anymore given that framebuffers now own - * separate clip stacks which will be automatically switched between - * when a new buffer is set. Calling this function has no effect - * - * Since: 0.8.2 - */ -void -cogl_clip_stack_restore (void) G_GNUC_DEPRECATED; - -#endif /* COGL_DISABLE_DEPRECATED */ - -/** - * cogl_set_framebuffer: - * @buffer: A #CoglFramebuffer object, either onscreen or offscreen. - * - * This redirects all subsequent drawing to the specified framebuffer. This can - * either be an offscreen buffer created with cogl_offscreen_new_to_texture () - * or in the future it may be an onscreen framebuffers too. - * - * Since: 1.2 - */ -void -cogl_set_framebuffer (CoglFramebuffer *buffer); - -/** - * cogl_push_framebuffer: - * @buffer: A #CoglFramebuffer object, either onscreen or offscreen. - * - * Redirects all subsequent drawing to the specified framebuffer. This can - * either be an offscreen buffer created with cogl_offscreen_new_to_texture () - * or in the future it may be an onscreen framebuffer too. - * - * You should understand that a framebuffer owns the following state: - * - * The projection matrix - * The modelview matrix stack - * The viewport - * The clip stack - * - * So these items will automatically be saved and restored when you - * push and pop between different framebuffers. - * - * Also remember a newly allocated framebuffer will have an identity matrix for - * the projection and modelview matrices which gives you a coordinate space - * like OpenGL with (-1, -1) corresponding to the top left of the viewport, - * (1, 1) corresponding to the bottom right and +z coming out towards the - * viewer. - * - * If you want to set up a coordinate space like Clutter does with (0, 0) - * corresponding to the top left and (framebuffer_width, framebuffer_height) - * corresponding to the bottom right you can do so like this: - * - * |[ - * static void - * setup_viewport (unsigned int width, - * unsigned int height, - * float fovy, - * float aspect, - * float z_near, - * float z_far) - * { - * float z_camera; - * CoglMatrix projection_matrix; - * CoglMatrix mv_matrix; - * - * cogl_set_viewport (0, 0, width, height); - * cogl_perspective (fovy, aspect, z_near, z_far); - * - * cogl_get_projection_matrix (&projection_matrix); - * z_camera = 0.5 * projection_matrix.xx; - * - * cogl_matrix_init_identity (&mv_matrix); - * cogl_matrix_translate (&mv_matrix, -0.5f, -0.5f, -z_camera); - * cogl_matrix_scale (&mv_matrix, 1.0f / width, -1.0f / height, 1.0f / width); - * cogl_matrix_translate (&mv_matrix, 0.0f, -1.0 * height, 0.0f); - * cogl_set_modelview_matrix (&mv_matrix); - * } - * - * static void - * my_init_framebuffer (ClutterStage *stage, - * CoglFramebuffer *framebuffer, - * unsigned int framebuffer_width, - * unsigned int framebuffer_height) - * { - * ClutterPerspective perspective; - * - * clutter_stage_get_perspective (stage, &perspective); - * - * cogl_push_framebuffer (framebuffer); - * setup_viewport (framebuffer_width, - * framebuffer_height, - * perspective.fovy, - * perspective.aspect, - * perspective.z_near, - * perspective.z_far); - * } - * ]| - * - * The previous framebuffer can be restored by calling cogl_pop_framebuffer() - * - * Since: 1.2 - */ -void -cogl_push_framebuffer (CoglFramebuffer *buffer); - -/** - * cogl_pop_framebuffer: - * - * Restores the framebuffer that was previously at the top of the stack. - * All subsequent drawing will be redirected to this framebuffer. - * - * Since: 1.2 - */ -void -cogl_pop_framebuffer (void); - -#ifndef COGL_DISABLE_DEPRECATED - -/** - * cogl_set_draw_buffer: - * @target: A #CoglBufferTarget that specifies what kind of framebuffer you - * are setting as the render target. - * @offscreen: If you are setting a framebuffer of type COGL_OFFSCREEN_BUFFER - * then this is a CoglHandle for the offscreen buffer. - * - * Redirects all subsequent drawing to the specified framebuffer. This - * can either be an offscreen buffer created with - * cogl_offscreen_new_to_texture () or you can revert to your original - * on screen window buffer. - * - * Deprecated: 1.2: The target argument was redundant since we could look at - * the type of CoglHandle given instead. - */ -void -cogl_set_draw_buffer (CoglBufferTarget target, - CoglHandle offscreen) G_GNUC_DEPRECATED; - -/** - * cogl_push_draw_buffer: - * - * Save cogl_set_draw_buffer() state. - * - * Deprecated: 1.2: The draw buffer API was replaced with a framebuffer API - */ -void -cogl_push_draw_buffer (void) G_GNUC_DEPRECATED; - -/** - * cogl_pop_draw_buffer: - * - * Restore cogl_set_draw_buffer() state. - * - * Deprecated: 1.2: The draw buffer API was replaced with a framebuffer API - */ -void -cogl_pop_draw_buffer (void) G_GNUC_DEPRECATED; - -#endif /* COGL_DISABLE_DEPRECATED */ - -/** - * CoglReadPixelsFlags: - * @COGL_READ_PIXELS_COLOR_BUFFER: Read from the color buffer - * - * Flags for cogl_read_pixels() - * - * Since: 1.0 - */ -typedef enum { /*< prefix=COGL_READ_PIXELS >*/ - COGL_READ_PIXELS_COLOR_BUFFER = 1L << 0 -} CoglReadPixelsFlags; - -/** - * cogl_read_pixels: - * @x: The window x position to start reading from - * @y: The window y position to start reading from - * @width: The width of the rectangle you want to read - * @height: The height of the rectangle you want to read - * @source: Identifies which auxillary buffer you want to read - * (only COGL_READ_PIXELS_COLOR_BUFFER supported currently) - * @format: The pixel format you want the result in - * (only COGL_PIXEL_FORMAT_RGBA_8888 supported currently) - * @pixels: The location to write the pixel data. - * - * This reads a rectangle of pixels from the current framebuffer where - * position (0, 0) is the top left. The pixel at (x, y) is the first - * read, and the data is returned with a rowstride of (width * 4). - * - * Currently Cogl assumes that the framebuffer is in a premultiplied - * format so if @format is non-premultiplied it will convert it. To - * read the pixel values without any conversion you should either - * specify a format that doesn't use an alpha channel or use one of - * the formats ending in PRE. - */ -void -cogl_read_pixels (int x, - int y, - int width, - int height, - CoglReadPixelsFlags source, - CoglPixelFormat format, - guint8 *pixels); - -/** - * cogl_flush: - * - * This function should only need to be called in exceptional circumstances. - * - * As an optimization Cogl drawing functions may batch up primitives - * internally, so if you are trying to use raw GL outside of Cogl you stand a - * better chance of being successful if you ask Cogl to flush any batched - * geometry before making your state changes. - * - * It only ensure that the underlying driver is issued all the commands - * necessary to draw the batched primitives. It provides no guarantees about - * when the driver will complete the rendering. - * - * This provides no guarantees about the GL state upon returning and to avoid - * confusing Cogl you should aim to restore any changes you make before - * resuming use of Cogl. - * - * If you are making state changes with the intention of affecting Cogl drawing - * primitives you are 100% on your own since you stand a good chance of - * conflicting with Cogl internals. For example clutter-gst which currently - * uses direct GL calls to bind ARBfp programs will very likely break when Cogl - * starts to use ARBfb programs itself for the material API. - * - * Since: 1.0 - */ -void -cogl_flush (void); - -/** - * cogl_begin_gl: - * - * We do not advise nor reliably support the interleaving of raw GL drawing and - * Cogl drawing functions, but if you insist, cogl_begin_gl() and cogl_end_gl() - * provide a simple mechanism that may at least give you a fighting chance of - * succeeding. - * - * Note: this doesn't help you modify the behaviour of Cogl drawing functions - * through the modification of GL state; that will never be reliably supported, - * but if you are trying to do something like: - * - * |[ - * { - * - setup some OpenGL state. - * - draw using OpenGL (e.g. glDrawArrays() ) - * - reset modified OpenGL state. - * - continue using Cogl to draw - * } - * ]| - * - * You should surround blocks of drawing using raw GL with cogl_begin_gl() - * and cogl_end_gl(): - * - * |[ - * { - * cogl_begin_gl (); - * - setup some OpenGL state. - * - draw using OpenGL (e.g. glDrawArrays() ) - * - reset modified OpenGL state. - * cogl_end_gl (); - * - continue using Cogl to draw - * } - * ]| - * - * Don't ever try and do: - * - * |[ - * { - * - setup some OpenGL state. - * - use Cogl to draw - * - reset modified OpenGL state. - * } - * ]| - * - * When the internals of Cogl evolves, this is very liable to break. - * - * This function will flush all batched primitives, and subsequently flush - * all internal Cogl state to OpenGL as if it were going to draw something - * itself. - * - * The result is that the OpenGL modelview matrix will be setup; the state - * corresponding to the current source material will be set up and other world - * state such as backface culling, depth and fogging enabledness will be sent - * to OpenGL. - * - * No special material state is flushed, so if you want Cogl to setup a - * simplified material state it is your responsibility to set a simple source - * material before calling cogl_begin_gl(). E.g. by calling - * cogl_set_source_color4ub(). - * - * It is your responsibility to restore any OpenGL state that you modify - * to how it was after calling cogl_begin_gl() if you don't do this then the - * result of further Cogl calls is undefined. - * - * You can not nest begin/end blocks. - * - * Again we would like to stress, we do not advise the use of this API and if - * possible we would prefer to improve Cogl than have developers require raw - * OpenGL. - * - * Since: 1.0 - */ -void -cogl_begin_gl (void); - -/** - * cogl_end_gl: - * - * This is the counterpart to cogl_begin_gl() used to delimit blocks of drawing - * code using raw OpenGL. Please refer to cogl_begin_gl() for full details. - * - * Since: 1.0 - */ -void -cogl_end_gl (void); - -G_END_DECLS - #undef __COGL_H_INSIDE__ #endif /* __COGL_H__ */ diff --git a/cogl/cogl1-context.h b/cogl/cogl1-context.h new file mode 100644 index 000000000..c59bd691e --- /dev/null +++ b/cogl/cogl1-context.h @@ -0,0 +1,1167 @@ +/* + * Cogl + * + * An object oriented GL/GLES Abstraction/Utility Layer + * + * Copyright (C) 2010 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 + * . + * + * Authors: + * Robert Bragg + * + */ + +#if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION) +#error "Only can be included directly." +#endif + +#ifndef __COGL_1_CONTEXT_H__ +#define __COGL_1_CONTEXT_H__ + +#include + +#include +#include +#include + +G_BEGIN_DECLS + +/** + * cogl_get_option_group: + * + * Retrieves the #GOptionGroup used by Cogl to parse the command + * line options. Clutter uses this to handle the Cogl command line + * options during its initialization process. + * + * Return value: a #GOptionGroup + * + * Since: 1.0 + */ +GOptionGroup * +cogl_get_option_group (void); + +/* Misc */ +/** + * cogl_get_features: + * + * Returns all of the features supported by COGL. + * + * Return value: A logical OR of all the supported COGL features. + * + * Since: 0.8 + */ +CoglFeatureFlags +cogl_get_features (void); + +/** + * cogl_features_available: + * @features: A bitmask of features to check for + * + * Checks whether the given COGL features are available. Multiple + * features can be checked for by or-ing them together with the '|' + * operator. %TRUE is only returned if all of the requested features + * are available. + * + * Return value: %TRUE if the features are available, %FALSE otherwise. + */ +gboolean +cogl_features_available (CoglFeatureFlags features); + +/** + * cogl_get_proc_address: + * @name: the name of the function. + * + * Gets a pointer to a given GL or GL ES extension function. This acts + * as a wrapper around glXGetProcAddress() or whatever is the + * appropriate function for the current backend. + * + * Return value: a pointer to the requested function or %NULL if the + * function is not available. + */ +CoglFuncPtr +cogl_get_proc_address (const char *name); + +#ifndef COGL_DISABLE_DEPRECATED + +/** + * cogl_check_extension: + * @name: extension to check for + * @ext: list of extensions + * + * Check whether @name occurs in list of extensions in @ext. + * + * Return value: %TRUE if the extension occurs in the list, %FALSE otherwise. + * + * Deprecated: 1.2: OpenGL is an implementation detail for Cogl and so it's + * not appropriate to expose OpenGL extensions through the Cogl API. This + * function can be replaced by the following equivalent code: + * |[ + * gboolean retval = (strstr (ext, name) != NULL) ? TRUE : FALSE; + * ]| + */ +gboolean +cogl_check_extension (const char *name, + const char *ext) G_GNUC_DEPRECATED; + +#endif /* COGL_DISABLE_DEPRECATED */ + +/** + * cogl_get_bitmasks: + * @red: (out): Return location for the number of red bits or %NULL + * @green: (out): Return location for the number of green bits or %NULL + * @blue: (out): Return location for the number of blue bits or %NULL + * @alpha: (out): Return location for the number of alpha bits or %NULL + * + * Gets the number of bitplanes used for each of the color components + * in the color buffer. Pass %NULL for any of the arguments if the + * value is not required. + */ +void +cogl_get_bitmasks (int *red, + int *green, + int *blue, + int *alpha); + +/** + * cogl_perspective: + * @fovy: Vertical field of view angle in degrees. + * @aspect: The (width over height) aspect ratio for display + * @z_near: The distance to the near clipping plane (Must be positive) + * @z_far: The distance to the far clipping plane (Must be positive) + * + * Replaces the current projection matrix with a perspective matrix + * based on the provided values. + * + * You should be careful not to have to great a @z_far / @z_near + * ratio since that will reduce the effectiveness of depth testing + * since there wont be enough precision to identify the depth of + * objects near to each other. + */ +void +cogl_perspective (float fovy, + float aspect, + float z_near, + float z_far); + +/** + * cogl_frustum: + * @left: X position of the left clipping plane where it + * intersects the near clipping plane + * @right: X position of the right clipping plane where it + * intersects the near clipping plane + * @bottom: Y position of the bottom clipping plane where it + * intersects the near clipping plane + * @top: Y position of the top clipping plane where it intersects + * the near clipping plane + * @z_near: The distance to the near clipping plane (Must be positive) + * @z_far: The distance to the far clipping plane (Must be positive) + * + * Replaces the current projection matrix with a perspective matrix + * for a given viewing frustum defined by 4 side clip planes that + * all cross through the origin and 2 near and far clip planes. + * + * Since: 0.8.2 + */ +void +cogl_frustum (float left, + float right, + float bottom, + float top, + float z_near, + float z_far); + +/** + * cogl_ortho: + * @left: The coordinate for the left clipping plane + * @right: The coordinate for the right clipping plane + * @bottom: The coordinate for the bottom clipping plane + * @top: The coordinate for the top clipping plane + * @near: The distance to the near clipping + * plane (negative if the plane is behind the viewer) + * @far: The distance for the far clipping + * plane (negative if the plane is behind the viewer) + * + * Replaces the current projection matrix with an orthographic projection + * matrix. See to see how the matrix is + * calculated. + * + *
+ * + * + *
+ * + * This function copies the arguments from OpenGL's glOrtho() even + * though they are unnecessarily confusing due to the z near and z far + * arguments actually being a "distance" from the origin, where + * negative values are behind the viewer, instead of coordinates for + * the z clipping planes which would have been consistent with the + * left, right bottom and top arguments. + * + * Since: 1.0 + */ +void +cogl_ortho (float left, + float right, + float bottom, + float top, + float near, + float far); + +#ifndef COGL_DISABLE_DEPRECATED + +/** + * cogl_viewport: + * @width: Width of the viewport + * @height: Height of the viewport + * + * Replace the current viewport with the given values. + * + * Since: 0.8.2 + * + * Deprecated: 1.2: Use cogl_set_viewport() instead + */ +void +cogl_viewport (unsigned int width, + unsigned int height) G_GNUC_DEPRECATED; + +#endif /* COGL_DISABLE_DEPRECATED */ + +/** + * cogl_set_viewport: + * @x: X offset of the viewport + * @y: Y offset of the viewport + * @width: Width of the viewport + * @height: Height of the viewport + * + * Replaces the current viewport with the given values. + * + * Since: 1.2 + */ +void +cogl_set_viewport (int x, + int y, + int width, + int height); + +/** + * cogl_push_matrix: + * + * Stores the current model-view matrix on the matrix stack. The matrix + * can later be restored with cogl_pop_matrix(). + */ +void +cogl_push_matrix (void); + +/** + * cogl_pop_matrix: + * + * Restores the current model-view matrix from the matrix stack. + */ +void +cogl_pop_matrix (void); + +/** + * cogl_scale: + * @x: Amount to scale along the x-axis + * @y: Amount to scale along the y-axis + * @z: Amount to scale along the z-axis + * + * Multiplies the current model-view matrix by one that scales the x, + * y and z axes by the given values. + */ +void +cogl_scale (float x, + float y, + float z); + +/** + * cogl_translate: + * @x: Distance to translate along the x-axis + * @y: Distance to translate along the y-axis + * @z: Distance to translate along the z-axis + * + * Multiplies the current model-view matrix by one that translates the + * model along all three axes according to the given values. + */ +void +cogl_translate (float x, + float y, + float z); + +/** + * cogl_rotate: + * @angle: Angle in degrees to rotate. + * @x: X-component of vertex to rotate around. + * @y: Y-component of vertex to rotate around. + * @z: Z-component of vertex to rotate around. + * + * Multiplies the current model-view matrix by one that rotates the + * model around the vertex specified by @x, @y and @z. The rotation + * follows the right-hand thumb rule so for example rotating by 10 + * degrees about the vertex (0, 0, 1) causes a small counter-clockwise + * rotation. + */ +void +cogl_rotate (float angle, + float x, + float y, + float z); + +/** + * cogl_transform: + * @matrix: the matrix to multiply with the current model-view + * + * Multiplies the current model-view matrix by the given matrix. + * + * Since: 1.4 + */ +void +cogl_transform (const CoglMatrix *matrix); + +/** + * cogl_get_modelview_matrix: + * @matrix: (out): return location for the model-view matrix + * + * Stores the current model-view matrix in @matrix. + */ +void +cogl_get_modelview_matrix (CoglMatrix *matrix); + +/** + * cogl_set_modelview_matrix: + * @matrix: the new model-view matrix + * + * Loads @matrix as the new model-view matrix. + */ +void +cogl_set_modelview_matrix (CoglMatrix *matrix); + +/** + * cogl_get_projection_matrix: + * @matrix: (out): return location for the projection matrix + * + * Stores the current projection matrix in @matrix. + */ +void +cogl_get_projection_matrix (CoglMatrix *matrix); + +/** + * cogl_set_projection_matrix: + * @matrix: the new projection matrix + * + * Loads matrix as the new projection matrix. + */ +void +cogl_set_projection_matrix (CoglMatrix *matrix); + +/** + * cogl_get_viewport: + * @v: (out) (array fixed-size=4): pointer to a 4 element array + * of #floats to receive the viewport dimensions. + * + * Stores the current viewport in @v. @v[0] and @v[1] get the x and y + * position of the viewport and @v[2] and @v[3] get the width and + * height. + */ +void +cogl_get_viewport (float v[4]); + +/** + * cogl_set_depth_test_enabled: + * @setting: %TRUE to enable depth testing or %FALSE to disable. + * + * Sets whether depth testing is enabled. If it is disabled then the + * order that actors are layered on the screen depends solely on the + * order specified using clutter_actor_raise() and + * clutter_actor_lower(), otherwise it will also take into account the + * actor's depth. Depth testing is disabled by default. + * + * Deprecated: 1.4: Use cogl_material_set_depth_test_enabled() + * instead. + */ +void +cogl_set_depth_test_enabled (gboolean setting); + +/** + * cogl_get_depth_test_enabled: + * + * Queries if depth testing has been enabled via cogl_set_depth_test_enable() + * + * Return value: %TRUE if depth testing is enabled, and %FALSE otherwise + * + * Deprecated: 1.4: Use cogl_material_get_depth_test_enabled() + * instead. + */ +gboolean +cogl_get_depth_test_enabled (void); + +/** + * cogl_set_backface_culling_enabled: + * @setting: %TRUE to enable backface culling or %FALSE to disable. + * + * Sets whether textures positioned so that their backface is showing + * should be hidden. This can be used to efficiently draw two-sided + * textures or fully closed cubes without enabling depth testing. This + * only affects calls to the cogl_rectangle* family of functions and + * cogl_vertex_buffer_draw*. Backface culling is disabled by default. + */ +void +cogl_set_backface_culling_enabled (gboolean setting); + +/** + * cogl_get_backface_culling_enabled: + * + * Queries if backface culling has been enabled via + * cogl_set_backface_culling_enabled() + * + * Return value: %TRUE if backface culling is enabled, and %FALSE otherwise + */ +gboolean +cogl_get_backface_culling_enabled (void); + +/** + * cogl_set_fog: + * @fog_color: The color of the fog + * @mode: A #CoglFogMode that determines the equation used to calculate the + * fogging blend factor. + * @density: Used by %COGL_FOG_MODE_EXPONENTIAL and by + * %COGL_FOG_MODE_EXPONENTIAL_SQUARED equations. + * @z_near: Position along Z axis where no fogging should be applied + * @z_far: Position along Z axis where full fogging should be applied + * + * Enables fogging. Fogging causes vertices that are further away from the eye + * to be rendered with a different color. The color is determined according to + * the chosen fog mode; at it's simplest the color is linearly interpolated so + * that vertices at @z_near are drawn fully with their original color and + * vertices at @z_far are drawn fully with @fog_color. Fogging will remain + * enabled until you call cogl_disable_fog(). + * + * The fogging functions only work correctly when primitives use + * unmultiplied alpha colors. By default Cogl will premultiply textures + * and cogl_set_source_color() will premultiply colors, so unless you + * explicitly load your textures requesting an unmultiplied internal format + * and use cogl_material_set_color() you can only use fogging with fully + * opaque primitives. This might improve in the future when we can depend + * on fragment shaders. + */ +void +cogl_set_fog (const CoglColor *fog_color, + CoglFogMode mode, + float density, + float z_near, + float z_far); + +/** + * cogl_disable_fog: + * + * This function disables fogging, so primitives drawn afterwards will not be + * blended with any previously set fog color. + */ +void +cogl_disable_fog (void); + +/** + * cogl_clear: + * @color: Background color to clear to + * @buffers: A mask of #CoglBufferBit's identifying which auxiliary + * buffers to clear + * + * Clears all the auxiliary buffers identified in the @buffers mask, and if + * that includes the color buffer then the specified @color is used. + */ +void +cogl_clear (const CoglColor *color, + unsigned long buffers); + +/** + * cogl_set_source: + * @material: A #CoglMaterial + * + * This function changes the material at the top of the source stack. + * The material at the top of this stack defines the GPU state used to + * process subsequent primitives, such as rectangles drawn with + * cogl_rectangle() or vertices drawn using cogl_vertex_buffer_draw(). + * + * Since: 1.0 + */ +void +cogl_set_source (void *material); + +/** + * cogl_get_source: + * + * Returns the current source material as previously set using + * cogl_set_source(). + * + * You should typically consider the returned material immutable + * and not try to change any of its properties unless you own a + * reference to that material. At times you may be able to get a + * reference to an internally managed materials and the result of + * modifying such materials is undefined. + * + * Return value: The current source material. + * + * Since: 1.6 + */ +void * +cogl_get_source (void); + +/** + * cogl_push_source: + * @material: A #CoglMaterial + * + * Pushes the given @material to the top of the source stack. The + * material at the top of this stack defines the GPU state used to + * process later primitives as defined by cogl_set_source(). + * + * Since: 1.6 + */ +void +cogl_push_source (void *material); + +/** + * cogl_pop_source: + * + * Removes the material at the top of the source stack. The material + * at the top of this stack defines the GPU state used to process + * later primitives as defined by cogl_set_source(). + * + * Since: 1.6 + */ +void +cogl_pop_source (void); + +/** + * cogl_set_source_color: + * @color: a #CoglColor + * + * This is a convenience function for creating a solid fill source material + * from the given color. This color will be used for any subsequent drawing + * operation. + * + * The color will be premultiplied by Cogl, so the color should be + * non-premultiplied. For example: use (1.0, 0.0, 0.0, 0.5) for + * semi-transparent red. + * + * See also cogl_set_source_color4ub() and cogl_set_source_color4f() + * if you already have the color components. + * + * Since: 1.0 + */ +void +cogl_set_source_color (const CoglColor *color); + +/** + * cogl_set_source_color4ub: + * @red: value of the red channel, between 0 and 255 + * @green: value of the green channel, between 0 and 255 + * @blue: value of the blue channel, between 0 and 255 + * @alpha: value of the alpha channel, between 0 and 255 + * + * This is a convenience function for creating a solid fill source material + * from the given color using unsigned bytes for each component. This + * color will be used for any subsequent drawing operation. + * + * The value for each component is an unsigned byte in the range + * between 0 and 255. + * + * Since: 1.0 + */ +void +cogl_set_source_color4ub (guint8 red, + guint8 green, + guint8 blue, + guint8 alpha); + +/** + * cogl_set_source_color4f: + * @red: value of the red channel, between 0 and %1.0 + * @green: value of the green channel, between 0 and %1.0 + * @blue: value of the blue channel, between 0 and %1.0 + * @alpha: value of the alpha channel, between 0 and %1.0 + * + * This is a convenience function for creating a solid fill source material + * from the given color using normalized values for each component. This color + * will be used for any subsequent drawing operation. + * + * The value for each component is a fixed point number in the range + * between 0 and %1.0. If the values passed in are outside that + * range, they will be clamped. + * + * Since: 1.0 + */ +void +cogl_set_source_color4f (float red, + float green, + float blue, + float alpha); + +/** + * cogl_set_source_texture: + * @texture: The #CoglTexture you want as your source + * + * This is a convenience function for creating a material with the first + * layer set to @texture and setting that material as the source with + * cogl_set_source. + * + * Note: There is no interaction between calls to cogl_set_source_color + * and cogl_set_source_texture. If you need to blend a texture with a color then + * you can create a simple material like this: + * + * material = cogl_material_new (); + * cogl_material_set_color4ub (material, 0xff, 0x00, 0x00, 0x80); + * cogl_material_set_layer (material, 0, tex_handle); + * cogl_set_source (material); + * + * + * Since: 1.0 + */ +void +cogl_set_source_texture (CoglTexture *texture); + + +/** + * SECTION:cogl-clipping + * @short_description: Fuctions for manipulating a stack of clipping regions + * + * To support clipping your geometry to rectangles or paths Cogl exposes a + * stack based API whereby each clip region you push onto the stack is + * intersected with the previous region. + */ + +#ifndef COGL_DISABLE_DEPRECATED + +/** + * cogl_clip_push_window_rect: + * @x_offset: left edge of the clip rectangle in window coordinates + * @y_offset: top edge of the clip rectangle in window coordinates + * @width: width of the clip rectangle + * @height: height of the clip rectangle + * + * Specifies a rectangular clipping area for all subsequent drawing + * operations. Any drawing commands that extend outside the rectangle + * will be clipped so that only the portion inside the rectangle will + * be displayed. The rectangle dimensions are not transformed by the + * current model-view matrix. + * + * The rectangle is intersected with the current clip region. To undo + * the effect of this function, call cogl_clip_pop(). + * + * Deprecated: 1.2: Use cogl_clip_push_window_rectangle() instead + */ +void +cogl_clip_push_window_rect (float x_offset, + float y_offset, + float width, + float height) G_GNUC_DEPRECATED; + +#endif /* COGL_DISABLE_DEPRECATED */ + +/** + * cogl_clip_push_window_rectangle: + * @x_offset: left edge of the clip rectangle in window coordinates + * @y_offset: top edge of the clip rectangle in window coordinates + * @width: width of the clip rectangle + * @height: height of the clip rectangle + * + * Specifies a rectangular clipping area for all subsequent drawing + * operations. Any drawing commands that extend outside the rectangle + * will be clipped so that only the portion inside the rectangle will + * be displayed. The rectangle dimensions are not transformed by the + * current model-view matrix. + * + * The rectangle is intersected with the current clip region. To undo + * the effect of this function, call cogl_clip_pop(). + * + * Since: 1.2 + */ +void +cogl_clip_push_window_rectangle (int x_offset, + int y_offset, + int width, + int height); + +#ifndef COGL_DISABLE_DEPRECATED + +/** + * cogl_clip_push: + * @x_offset: left edge of the clip rectangle + * @y_offset: top edge of the clip rectangle + * @width: width of the clip rectangle + * @height: height of the clip rectangle + * + * Specifies a rectangular clipping area for all subsequent drawing + * operations. Any drawing commands that extend outside the rectangle + * will be clipped so that only the portion inside the rectangle will + * be displayed. The rectangle dimensions are transformed by the + * current model-view matrix. + * + * The rectangle is intersected with the current clip region. To undo + * the effect of this function, call cogl_clip_pop(). + * + * Deprecated: 1.2: The x, y, width, height arguments are inconsistent + * with other API that specify rectangles in model space, and when used + * with a coordinate space that puts the origin at the center and y+ + * extending up, it's awkward to use. Please use cogl_clip_push_rectangle() + * instead + */ +void +cogl_clip_push (float x_offset, + float y_offset, + float width, + float height) G_GNUC_DEPRECATED; + +#endif /* COGL_DISABLE_DEPRECATED */ + +/** + * cogl_clip_push_rectangle: + * @x0: x coordinate for top left corner of the clip rectangle + * @y0: y coordinate for top left corner of the clip rectangle + * @x1: x coordinate for bottom right corner of the clip rectangle + * @y1: y coordinate for bottom right corner of the clip rectangle + * + * Specifies a rectangular clipping area for all subsequent drawing + * operations. Any drawing commands that extend outside the rectangle + * will be clipped so that only the portion inside the rectangle will + * be displayed. The rectangle dimensions are transformed by the + * current model-view matrix. + * + * The rectangle is intersected with the current clip region. To undo + * the effect of this function, call cogl_clip_pop(). + * + * Since: 1.2 + */ +void +cogl_clip_push_rectangle (float x0, + float y0, + float x1, + float y1); + +/** + * cogl_clip_push_from_path_preserve: + * + * Sets a new clipping area using the current path. The current path + * is then cleared. The clipping area is intersected with the previous + * clipping area. To restore the previous clipping area, call + * cogl_clip_pop(). + * + * Since: 1.0 + */ +void +cogl_clip_push_from_path_preserve (void); + +#ifdef COGL_ENABLE_EXPERIMENTAL_2_0_API +/** + * cogl_clip_push_primitive: + * @primitive: A #CoglPrimitive describing a flat 2D shape + * @bounds_x1: x coordinate for the top-left corner of the primitives + * bounds + * @bounds_y1: y coordinate for the top-left corner of the primitives + * bounds + * @bounds_x2: x coordinate for the top-left corner of the primitives + * bounds + * @bounds_y2: x coordinate for the bottom-right corner of the + * primitives bounds. + * @bounds_x1: y coordinate for the bottom-right corner of the + * primitives bounds. + * + * Sets a new clipping area using a 2D shaped described with a + * #CoglPrimitive. The shape must not contain self overlapping + * geometry and must lie on a single 2D plane. A bounding box of the + * 2D shape in local coordinates (the same coordinates used to + * describe the shape) must be given. It is acceptable for the bounds + * to be larger than the true bounds but behaviour is undefined if the + * bounds are smaller than the true bounds. + * + * The primitive is transformed by the current model-view matrix and + * the silhouette is intersected with the previous clipping area. To + * restore the previous clipping area, call + * cogl_clip_pop(). + * + * Since: 1.10 + * Stability: unstable + */ +void +cogl_clip_push_primitive (CoglPrimitive *primitive, + float bounds_x1, + float bounds_y1, + float bounds_x2, + float bounds_y2); +#endif + +/** + * cogl_clip_pop: + * + * Reverts the clipping region to the state before the last call to + * cogl_clip_push(). + */ +void +cogl_clip_pop (void); + +#ifndef COGL_DISABLE_DEPRECATED + +/** + * cogl_clip_ensure: + * + * Ensures that the current clipping region has been set in GL. This + * will automatically be called before any Cogl primitives but it + * maybe be neccessary to call if you are using raw GL calls with + * clipping. + * + * Deprecated: 1.2: Calling this function has no effect + * + * Since: 1.0 + */ +void +cogl_clip_ensure (void) G_GNUC_DEPRECATED; + +/** + * cogl_clip_stack_save: + * + * Save the entire state of the clipping stack and then clear all + * clipping. The previous state can be returned to with + * cogl_clip_stack_restore(). Each call to cogl_clip_push() after this + * must be matched by a call to cogl_clip_pop() before calling + * cogl_clip_stack_restore(). + * + * Deprecated: 1.2: This was originally added to allow us to save the + * clip stack when switching to an offscreen framebuffer, but it's + * not necessary anymore given that framebuffers now own separate + * clip stacks which will be automatically switched between when a + * new buffer is set. Calling this function has no effect + * + * Since: 0.8.2 + */ +void +cogl_clip_stack_save (void) G_GNUC_DEPRECATED; + +/** + * cogl_clip_stack_restore: + * + * Restore the state of the clipping stack that was previously saved + * by cogl_clip_stack_save(). + * + * Deprecated: 1.2: This was originally added to allow us to restore + * the clip stack when switching back from an offscreen framebuffer, + * but it's not necessary anymore given that framebuffers now own + * separate clip stacks which will be automatically switched between + * when a new buffer is set. Calling this function has no effect + * + * Since: 0.8.2 + */ +void +cogl_clip_stack_restore (void) G_GNUC_DEPRECATED; + +#endif /* COGL_DISABLE_DEPRECATED */ + +/** + * cogl_set_framebuffer: + * @buffer: A #CoglFramebuffer object, either onscreen or offscreen. + * + * This redirects all subsequent drawing to the specified framebuffer. This can + * either be an offscreen buffer created with cogl_offscreen_new_to_texture () + * or in the future it may be an onscreen framebuffers too. + * + * Since: 1.2 + */ +void +cogl_set_framebuffer (CoglFramebuffer *buffer); + +/** + * cogl_push_framebuffer: + * @buffer: A #CoglFramebuffer object, either onscreen or offscreen. + * + * Redirects all subsequent drawing to the specified framebuffer. This can + * either be an offscreen buffer created with cogl_offscreen_new_to_texture () + * or in the future it may be an onscreen framebuffer too. + * + * You should understand that a framebuffer owns the following state: + * + * The projection matrix + * The modelview matrix stack + * The viewport + * The clip stack + * + * So these items will automatically be saved and restored when you + * push and pop between different framebuffers. + * + * Also remember a newly allocated framebuffer will have an identity matrix for + * the projection and modelview matrices which gives you a coordinate space + * like OpenGL with (-1, -1) corresponding to the top left of the viewport, + * (1, 1) corresponding to the bottom right and +z coming out towards the + * viewer. + * + * If you want to set up a coordinate space like Clutter does with (0, 0) + * corresponding to the top left and (framebuffer_width, framebuffer_height) + * corresponding to the bottom right you can do so like this: + * + * |[ + * static void + * setup_viewport (unsigned int width, + * unsigned int height, + * float fovy, + * float aspect, + * float z_near, + * float z_far) + * { + * float z_camera; + * CoglMatrix projection_matrix; + * CoglMatrix mv_matrix; + * + * cogl_set_viewport (0, 0, width, height); + * cogl_perspective (fovy, aspect, z_near, z_far); + * + * cogl_get_projection_matrix (&projection_matrix); + * z_camera = 0.5 * projection_matrix.xx; + * + * cogl_matrix_init_identity (&mv_matrix); + * cogl_matrix_translate (&mv_matrix, -0.5f, -0.5f, -z_camera); + * cogl_matrix_scale (&mv_matrix, 1.0f / width, -1.0f / height, 1.0f / width); + * cogl_matrix_translate (&mv_matrix, 0.0f, -1.0 * height, 0.0f); + * cogl_set_modelview_matrix (&mv_matrix); + * } + * + * static void + * my_init_framebuffer (ClutterStage *stage, + * CoglFramebuffer *framebuffer, + * unsigned int framebuffer_width, + * unsigned int framebuffer_height) + * { + * ClutterPerspective perspective; + * + * clutter_stage_get_perspective (stage, &perspective); + * + * cogl_push_framebuffer (framebuffer); + * setup_viewport (framebuffer_width, + * framebuffer_height, + * perspective.fovy, + * perspective.aspect, + * perspective.z_near, + * perspective.z_far); + * } + * ]| + * + * The previous framebuffer can be restored by calling cogl_pop_framebuffer() + * + * Since: 1.2 + */ +void +cogl_push_framebuffer (CoglFramebuffer *buffer); + +/** + * cogl_pop_framebuffer: + * + * Restores the framebuffer that was previously at the top of the stack. + * All subsequent drawing will be redirected to this framebuffer. + * + * Since: 1.2 + */ +void +cogl_pop_framebuffer (void); + +#ifndef COGL_DISABLE_DEPRECATED + +/** + * cogl_set_draw_buffer: + * @target: A #CoglBufferTarget that specifies what kind of framebuffer you + * are setting as the render target. + * @offscreen: If you are setting a framebuffer of type COGL_OFFSCREEN_BUFFER + * then this is a CoglHandle for the offscreen buffer. + * + * Redirects all subsequent drawing to the specified framebuffer. This + * can either be an offscreen buffer created with + * cogl_offscreen_new_to_texture () or you can revert to your original + * on screen window buffer. + * + * Deprecated: 1.2: The target argument was redundant since we could look at + * the type of CoglHandle given instead. + */ +void +cogl_set_draw_buffer (CoglBufferTarget target, + CoglHandle offscreen) G_GNUC_DEPRECATED; + +/** + * cogl_push_draw_buffer: + * + * Save cogl_set_draw_buffer() state. + * + * Deprecated: 1.2: The draw buffer API was replaced with a framebuffer API + */ +void +cogl_push_draw_buffer (void) G_GNUC_DEPRECATED; + +/** + * cogl_pop_draw_buffer: + * + * Restore cogl_set_draw_buffer() state. + * + * Deprecated: 1.2: The draw buffer API was replaced with a framebuffer API + */ +void +cogl_pop_draw_buffer (void) G_GNUC_DEPRECATED; + +#endif /* COGL_DISABLE_DEPRECATED */ + +/** + * cogl_read_pixels: + * @x: The window x position to start reading from + * @y: The window y position to start reading from + * @width: The width of the rectangle you want to read + * @height: The height of the rectangle you want to read + * @source: Identifies which auxillary buffer you want to read + * (only COGL_READ_PIXELS_COLOR_BUFFER supported currently) + * @format: The pixel format you want the result in + * (only COGL_PIXEL_FORMAT_RGBA_8888 supported currently) + * @pixels: The location to write the pixel data. + * + * This reads a rectangle of pixels from the current framebuffer where + * position (0, 0) is the top left. The pixel at (x, y) is the first + * read, and the data is returned with a rowstride of (width * 4). + * + * Currently Cogl assumes that the framebuffer is in a premultiplied + * format so if @format is non-premultiplied it will convert it. To + * read the pixel values without any conversion you should either + * specify a format that doesn't use an alpha channel or use one of + * the formats ending in PRE. + */ +void +cogl_read_pixels (int x, + int y, + int width, + int height, + CoglReadPixelsFlags source, + CoglPixelFormat format, + guint8 *pixels); + +/** + * cogl_flush: + * + * This function should only need to be called in exceptional circumstances. + * + * As an optimization Cogl drawing functions may batch up primitives + * internally, so if you are trying to use raw GL outside of Cogl you stand a + * better chance of being successful if you ask Cogl to flush any batched + * geometry before making your state changes. + * + * It only ensure that the underlying driver is issued all the commands + * necessary to draw the batched primitives. It provides no guarantees about + * when the driver will complete the rendering. + * + * This provides no guarantees about the GL state upon returning and to avoid + * confusing Cogl you should aim to restore any changes you make before + * resuming use of Cogl. + * + * If you are making state changes with the intention of affecting Cogl drawing + * primitives you are 100% on your own since you stand a good chance of + * conflicting with Cogl internals. For example clutter-gst which currently + * uses direct GL calls to bind ARBfp programs will very likely break when Cogl + * starts to use ARBfb programs itself for the material API. + * + * Since: 1.0 + */ +void +cogl_flush (void); + +/** + * cogl_begin_gl: + * + * We do not advise nor reliably support the interleaving of raw GL drawing and + * Cogl drawing functions, but if you insist, cogl_begin_gl() and cogl_end_gl() + * provide a simple mechanism that may at least give you a fighting chance of + * succeeding. + * + * Note: this doesn't help you modify the behaviour of Cogl drawing functions + * through the modification of GL state; that will never be reliably supported, + * but if you are trying to do something like: + * + * |[ + * { + * - setup some OpenGL state. + * - draw using OpenGL (e.g. glDrawArrays() ) + * - reset modified OpenGL state. + * - continue using Cogl to draw + * } + * ]| + * + * You should surround blocks of drawing using raw GL with cogl_begin_gl() + * and cogl_end_gl(): + * + * |[ + * { + * cogl_begin_gl (); + * - setup some OpenGL state. + * - draw using OpenGL (e.g. glDrawArrays() ) + * - reset modified OpenGL state. + * cogl_end_gl (); + * - continue using Cogl to draw + * } + * ]| + * + * Don't ever try and do: + * + * |[ + * { + * - setup some OpenGL state. + * - use Cogl to draw + * - reset modified OpenGL state. + * } + * ]| + * + * When the internals of Cogl evolves, this is very liable to break. + * + * This function will flush all batched primitives, and subsequently flush + * all internal Cogl state to OpenGL as if it were going to draw something + * itself. + * + * The result is that the OpenGL modelview matrix will be setup; the state + * corresponding to the current source material will be set up and other world + * state such as backface culling, depth and fogging enabledness will be sent + * to OpenGL. + * + * No special material state is flushed, so if you want Cogl to setup a + * simplified material state it is your responsibility to set a simple source + * material before calling cogl_begin_gl(). E.g. by calling + * cogl_set_source_color4ub(). + * + * It is your responsibility to restore any OpenGL state that you modify + * to how it was after calling cogl_begin_gl() if you don't do this then the + * result of further Cogl calls is undefined. + * + * You can not nest begin/end blocks. + * + * Again we would like to stress, we do not advise the use of this API and if + * possible we would prefer to improve Cogl than have developers require raw + * OpenGL. + * + * Since: 1.0 + */ +void +cogl_begin_gl (void); + +/** + * cogl_end_gl: + * + * This is the counterpart to cogl_begin_gl() used to delimit blocks of drawing + * code using raw OpenGL. Please refer to cogl_begin_gl() for full details. + * + * Since: 1.0 + */ +void +cogl_end_gl (void); + +G_END_DECLS + +#endif /* __COGL_1_CONTEXT_H__ */ diff --git a/cogl/cogl2-path.c b/cogl/cogl2-path.c index 6e86ab81b..e01bbedaf 100644 --- a/cogl/cogl2-path.c +++ b/cogl/cogl2-path.c @@ -44,6 +44,7 @@ #include "cogl-primitives-private.h" #include "cogl-private.h" #include "cogl-attribute-private.h" +#include "cogl1-context.h" #include "tesselator/tesselator.h" #include diff --git a/doc/reference/cogl/Makefile.am b/doc/reference/cogl/Makefile.am index 8c5d71034..303b2e7a3 100644 --- a/doc/reference/cogl/Makefile.am +++ b/doc/reference/cogl/Makefile.am @@ -95,7 +95,6 @@ IGNORE_HFILES=\ cogl-vertex-buffer-private.h \ cogl-blend-string.h \ cogl-clip-stack.h \ - cogl-context.h \ cogl-debug.h \ cogl-defines.h \ cogl-deprecated.h \