/* * Cogl * * An object oriented GL/GLES Abstraction/Utility Layer * * Copyright (C) 2008,2009 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 . * * */ #ifndef __COGL_H__ #define __COGL_H__ #include #define __COGL_H_INSIDE__ #ifdef COGL_ENABLE_EXPERIMENTAL_2_0_API #ifndef COGL_ENABLE_EXPERIMENTAL_API #define COGL_ENABLE_EXPERIMENTAL_API #endif #endif /* We currently keep gtype integration delimited in case we eventually * want to split it out into a separate utility library when Cogl * becomes a standalone project. (like cairo-gobject.so) */ #define _COGL_SUPPORTS_GTYPE_INTEGRATION #include #include #include #include #include #include #include #include #include #ifdef COGL_ENABLE_EXPERIMENTAL_2_0_API #include #include #else #include #include #endif #include #include #include #include #include #include typedef struct _CoglFramebuffer CoglFramebuffer; #if defined (COGL_ENABLE_EXPERIMENTAL_API) #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #if defined (COGL_HAS_EGL_PLATFORM_WAYLAND_SUPPORT) #include #endif #if COGL_HAS_WIN32_SUPPORT #include #endif /* XXX: This will definitly go away once all the Clutter winsys * code has been migrated down into Cogl! */ #include #endif G_BEGIN_DECLS /** * SECTION:cogl * @short_description: General purpose API * * 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. * * * 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, /*< private > */ _COGL_N_FEATURE_IDS } CoglFeatureID; #ifdef COGL_ENABLE_EXPERIMENTAL_2_0_API #define cogl_has_feature cogl_has_feature_EXP /** * 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); #define cogl_has_features cogl_has_features_EXP /** * 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); #define cogl_foreach_feature cogl_foreach_feature_EXP /** * 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 #define cogl_clip_push_primitive cogl_clip_push_primitive_EXP /** * 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__ */