isa/mutter
1
0
Fork 0
mirror of https://github.com/brl/mutter.git synced 2024-11-26 10:00:45 -05:00
Code Issues Packages Projects Releases Wiki Activity
ba2257973e
mutter/cogl.h.in
Robert Bragg 61b8cc1874 Adds a CoglMaterial abstraction, which includes support for multi-texturing 
My previous work to provide muti-texturing support has been extended into
a CoglMaterial abstraction that adds control over the texture combine
functions (controlling how multiple texture layers are blended together),
the gl blend function (used for blending the final primitive with the
framebuffer), the alpha function (used to discard fragments based on
their alpha channel), describing attributes such as a diffuse, ambient and
specular color (for use with the standard OpenGL lighting model), and
per layer rotations. (utilizing the new CoglMatrix utility API)

For now the only way this abstraction is exposed is via a new
cogl_material_rectangle function, that is similar to cogl_texture_rectangle
but doesn't take a texture handle (the source material is pulled from
the context), and the array of texture coordinates is extended to be able
to supply coordinates for each layer.

Note: this function doesn't support sliced textures; supporting sliced
textures is a non trivial problem, considering the ability to rotate layers.
Note: cogl_material_rectangle, has quite a few workarounds, for a number of
other limitations within Cogl a.t.m.
Note: The GLES1/2 multi-texturing support has yet to be updated to use
the material abstraction.
2008-12-22 16:35:52 +00:00

483 lines
16 KiB
C
Raw Blame History

/*
* Clutter COGL
*
* A basic GL/GLES Abstraction/Utility Layer
*
* Authored By Matthew Allum <mallum@openedhand.com>
*
* 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 <glib.h>
#include <cogl/cogl-defines-@CLUTTER_COGL@.h>
#include <cogl/cogl-mesh.h>
#include <cogl/cogl-matrix.h>
#include <cogl/cogl-fixed.h>
#include <cogl/cogl-color.h>
#include <cogl/cogl-offscreen.h>
#include <cogl/cogl-material.h>
#include <cogl/cogl-path.h>
#include <cogl/cogl-shader.h>
#include <cogl/cogl-texture.h>
#include <cogl/cogl-types.h>
#include <cogl/cogl-deprecated.h>
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 #CoglFixed<!-- -->s 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 #CoglFixed<!-- -->s 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 #CoglFixed<!-- -->s 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.
*
* The rectangle is intersected with the current clip region. To undo
* the effect of this function, call cogl_clip_unset().
*/
void cogl_clip_set (CoglFixed x_offset,
CoglFixed y_offset,
CoglFixed width,
CoglFixed height);
/**
* cogl_clip_set_from_path:
*
* 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_unset().
*
* Since: 1.0
*/
void cogl_clip_set_from_path (void);
/**
* cogl_clip_set_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_unset().
*
* Since: 1.0
*/
void cogl_clip_set_from_path_preserve (void);
/**
* cogl_clip_unset:
*
* Reverts the clipping region to the state before the last call to
* cogl_clip_set().
*/
void cogl_clip_unset (void);
/**
* 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.
*
* Since: 1.0
*/
void cogl_clip_ensure (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__ */
Reference in New Issue View Git Blame Copy Permalink