/* * Clutter COGL * * A basic GL/GLES Abstraction/Utility Layer * * Authored By Matthew Allum * * Copyright (C) 2007 OpenedHand * * 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, write to the * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ #ifndef __COGL_H__ #define __COGL_H__ #define __COGL_H_INSIDE__ #include #include #include #include #include #include #include #include #include #include G_BEGIN_DECLS /** * SECTION:cogl * @short_description: General purpose API * * General utility functions for COGL. */ /* Context manipulation */ /** * cogl_create_context: * * FIXME */ gboolean cogl_create_context (void); /** * cogl_destroy_context: * * FIXME */ void cogl_destroy_context (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 gchar *name); /** * cogl_check_extension: * @name: extension to check for * @ext: list of extensions * * Check whether @name occurs in list of extensions in @ext. * * Returns: %TRUE if the extension occurs in the list, %FALSE otherwize. */ gboolean cogl_check_extension (const gchar *name, const gchar *ext); /** * cogl_get_bitmasks: * @red: Return location for the number of red bits or %NULL * @green: Return location for the number of green bits or %NULL * @blue: Return location for the number of blue bits or %NULL * @alpha: 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 (gint *red, gint *green, gint *blue, gint *alpha); /** * cogl_perspective: * @fovy: Vertical of view angle in degrees. * @aspect: Aspect ratio of diesplay * @z_near: Nearest visible point * @z_far: Furthest visible point along the z-axis * * Replaces the current projection matrix with a perspective matrix * based on the provided values. */ void cogl_perspective (CoglFixed fovy, CoglFixed aspect, CoglFixed z_near, CoglFixed z_far); /** * cogl_frustum: * @left: Left clipping plane * @right: Right clipping plane * @bottom: Bottom clipping plane * @top: Top clipping plane * @z_near: Nearest visible point * @z_far: Furthest visible point along the z-axis * * Replaces the current projection matrix with a perspective matrix * for the given viewing frustum. * * Since: 0.8.2 */ void cogl_frustum (CoglFixed left, CoglFixed right, CoglFixed bottom, CoglFixed top, CoglFixed z_near, CoglFixed z_far); /** * cogl_setup_viewport: * @width: Width of the viewport * @height: Height of the viewport * @fovy: Field of view angle in degrees * @aspect: Aspect ratio to determine the field of view along the x-axis * @z_near: Nearest visible point along the z-axis * @z_far: Furthest visible point along the z-axis * * Replaces the current viewport and projection matrix with the given * values. The viewport is placed at the top left corner of the window * with the given width and height. The projection matrix is replaced * with one that has a viewing angle of @fovy along the y-axis and a * view scaled according to @aspect along the x-axis. The view is * clipped according to @z_near and @z_far on the z-axis. */ void cogl_setup_viewport (guint width, guint height, CoglFixed fovy, CoglFixed aspect, CoglFixed z_near, CoglFixed z_far); /** * cogl_viewport: * @width: Width of the viewport * @height: Height of the viewport * * Replace the current viewport with the given values. * * Since: 0.8.2 */ void cogl_viewport (guint width, guint height); /** * cogl_push_matrix: * * Store 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: * * Restore 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 * * Multiplies the current model-view matrix by one that scales the x * and y axes by the given values. */ void cogl_scale (CoglFixed x, CoglFixed y); /** * cogl_translatex: * @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_translatex (CoglFixed x, CoglFixed y, CoglFixed 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 * * Integer version of cogl_translatex(). Multiplies the current * model-view matrix by one that translates the model along all three * axes according to the given values. */ void cogl_translate (gint x, gint y, gint z); /** * cogl_rotatex: * @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_rotatex (CoglFixed angle, gint x, gint y, gint 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. * * Integer version of cogl_rotatex(). Multiplies the current * model-view matrix by one that rotates the model around the vertex * specified by @x, @y and @z. */ void cogl_rotate (gint angle, gint x, gint y, gint z); /** * cogl_get_modelview_matrix: * @m: pointer to a 4x4 array of #CoglFixeds to receive the matrix * * Stores the current model-view matrix in @m. The matrix is in * column-major order. */ void cogl_get_modelview_matrix (CoglFixed m[16]); /** * cogl_get_projection_matrix: * @m: pointer to a 4x4 array of #CoglFixeds to receive the matrix * * Stores the current projection matrix in @m. The matrix is in * column-major order. */ void cogl_get_projection_matrix (CoglFixed m[16]); /** * cogl_get_viewport: * @v: pointer to a 4 element array of #CoglFixeds 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 (CoglFixed v[4]); /** * cogl_clip_set: * @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. */ void cogl_clip_set (CoglFixed x_offset, CoglFixed y_offset, CoglFixed width, CoglFixed height); /** * cogl_clip_unset: * * Removes the current clipping rectangle so that all drawing * operations extend to full size of the viewport again. */ void cogl_clip_unset (void); /** * 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_set() after this * must be matched by a call to cogl_clip_unset() before calling * cogl_clip_stack_restore(). * * Since: 0.8.2 */ void cogl_clip_stack_save (void); /** * cogl_clip_stack_restore: * * Restore the state of the clipping stack that was previously saved * by cogl_clip_stack_save(). * * Since: 0.8.2 */ void cogl_clip_stack_restore (void); /** * cogl_enable_depth_test: * @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. */ void cogl_enable_depth_test (gboolean setting); /** * cogl_enable_backface_culling: * @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. Only * calls to cogl_texture_rectangle() and cogl_texture_polygon() are * affected. Backface culling is disabled by default. */ void cogl_enable_backface_culling (gboolean setting); /** * cogl_alpha_func: * @func: the comparison function to use, one of CGL_NEVER, CGL_LESS, * CGL_EQUAL, CGL_LEQUAL, CGL_GREATER, CGL_NOTEQUAL, CGL_GEQUAL and GL_ALWAYS. * @ref: reference value. * * Changes the alpha test to use the specified function specified in @func, * comparing with the value in @ref. The default function is CGL_ALWAYS the * initial reference value is 1.0. */ void cogl_alpha_func (COGLenum func, CoglFixed ref); /** * cogl_fog_set: * @fog_color: The color of the fog * @density: Ignored * @z_near: Position along z-axis where no fogging should be applied * @z_far: Position along z-axes 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 * 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 the next call to * cogl_paint_init(). */ void cogl_fog_set (const CoglColor *fog_color, CoglFixed density, CoglFixed z_near, CoglFixed z_far); /** * cogl_paint_init: * @color: Background color to clear to * * Clears the color buffer to @color. The depth buffer and stencil * buffers are also cleared and fogging and lighting are disabled. */ void cogl_paint_init (const CoglColor *color); G_END_DECLS #undef __COGL_H_INSIDE__ #endif /* __COGL_H__ */