[material] Reduce the material API in preperation for releasing Clutter 1.0

There were a number of functions intended to support creating of new
primitives using materials, but at this point they aren't used outside of
Cogl so until someone has a usecase and we can get feedback on this
API, it's being removed before we release Clutter 1.0.
This commit is contained in:
Robert Bragg 2009-05-23 17:42:10 +01:00
parent f28d5e481b
commit f322da3794
12 changed files with 174 additions and 173 deletions

View File

@ -600,34 +600,6 @@ void cogl_material_set_layer_matrix (CoglHandle material,
int layer_index,
CoglMatrix *matrix);
/**
* SECTION:cogl-material-internals
* @short_description: Functions for creating custom primitives that make use
* of Cogl materials for filling.
*
* Normally you shouldn't need to use this API directly, but if you need to
* developing a custom/specialised primitive - probably using raw OpenGL - then
* this API aims to expose enough of the material internals to support being
* able to fill your geometry according to a given Cogl material.
*/
/**
* cogl_material_get_cogl_enable_flags:
* @material: A CoglMaterial object
*
* This determines what flags need to be passed to cogl_enable before this
* material can be used. Normally you shouldn't need to use this function
* directly since Cogl will do this internally, but if you are developing
* custom primitives directly with OpenGL you may want to use this.
*
* Note: This API is hopfully just a stop-gap solution. Ideally cogl_enable
* will be replaced.
*/
/* TODO: find a nicer solution! */
gulong
cogl_material_get_cogl_enable_flags (CoglHandle handle);
/**
* cogl_material_get_layers:
* @material: A CoglMaterial object
@ -635,24 +607,15 @@ cogl_material_get_cogl_enable_flags (CoglHandle handle);
* This function lets you access a materials internal list of layers
* for iteration.
*
* Note: Normally you shouldn't need to use this function directly since
* Cogl will do this internally, but if you are developing custom primitives
* directly with OpenGL, you will need to iterate the layers that you want
* to texture with.
*
* Note: This function may return more layers than OpenGL can use at once
* so it's your responsability limit yourself to
* CGL_MAX_COMBINED_TEXTURE_IMAGE_UNITS.
*
* Note: It's a bit out of the ordinary to return a const GList *, but it
* was considered sensible to try and avoid list manipulation for every
* primitive emitted in a scene, every frame.
* Returns: A list of #CoglHandle<!-- -->'s that can be passed to the
* cogl_material_layer_* functions.
*/
const GList *cogl_material_get_layers (CoglHandle material_handle);
/**
* CoglMaterialLayerType:
* @COGL_MATERIAL_LAYER_TYPE_TEXTURE: The layer represents a CoglTexture
* @COGL_MATERIAL_LAYER_TYPE_TEXTURE: The layer represents a
* <link linkend="cogl-Textures">Cogl texture</link>
*/
typedef enum _CoglMaterialLayerType
{
@ -661,17 +624,12 @@ typedef enum _CoglMaterialLayerType
/**
* cogl_material_layer_get_type:
* @layer_handle: A CoglMaterialLayer handle
* @layer_handle: A Cogl material layer handle
*
* Currently there is only one type of layer defined:
* COGL_MATERIAL_LAYER_TYPE_TEXTURE, but considering we may add purely GLSL
* based layers in the future, you should write code that checks the type
* first.
*
* Note: Normally you shouldn't need to use this function directly since
* Cogl will do this internally, but if you are developing custom primitives
* directly with OpenGL, you will need to iterate the layers that you want
* to texture with, and thus should be checking the layer types.
*/
CoglMaterialLayerType cogl_material_layer_get_type (CoglHandle layer_handle);
@ -679,75 +637,24 @@ CoglMaterialLayerType cogl_material_layer_get_type (CoglHandle layer_handle);
* cogl_material_layer_get_texture:
* @layer_handle: A CoglMaterialLayer handle
*
* This lets you extract a CoglTexture handle for a specific layer. Normally
* you shouldn't need to use this function directly since Cogl will do this
* internally, but if you are developing custom primitives directly with
* OpenGL you may need this.
* This lets you extract a CoglTexture handle for a specific layer.
*
* Note: In the future, we may support purely GLSL based layers which will
* likley return COGL_INVALID_HANDLE if you try to get the texture.
* Considering this, you should always call cogl_material_layer_get_type
* first, to check it is of type COGL_MATERIAL_LAYER_TYPE_TEXTURE.
* likely return COGL_INVALID_HANDLE if you try to get the texture.
* Considering this, you can call cogl_material_layer_get_type first,
* to check it is of type COGL_MATERIAL_LAYER_TYPE_TEXTURE.
*
* Note: It is possible for a layer object of type
* COGL_MATERIAL_LAYER_TYPE_TEXTURE to be realized before a texture
* object has been associated with the layer. For example this happens
* if you setup layer combining for a given layer index before calling
* cogl_material_set_layer for that index.
*
* Returns: A CoglHandle to the layers texture object or COGL_INVALID_HANDLE
* if a texture has not been set yet.
*/
CoglHandle cogl_material_layer_get_texture (CoglHandle layer_handle);
/**
* CoglMaterialLayerFlags:
* @COGL_MATERIAL_LAYER_FLAG_USER_MATRIX: Means the user has supplied a
* custom texture matrix.
*/
typedef enum _CoglMaterialLayerFlags
{
COGL_MATERIAL_LAYER_FLAG_HAS_USER_MATRIX = 1L<<0
} CoglMaterialLayerFlags;
/* XXX: NB: if you add flags here you will need to update
* CoglMaterialLayerPrivFlags!!! */
/**
* cogl_material_layer_get_flags:
* @layer_handle: A CoglMaterialLayer layer handle
*
* This lets you get a number of flag attributes about the layer. Normally
* you shouldn't need to use this function directly since Cogl will do this
* internally, but if you are developing custom primitives directly with
* OpenGL you may need this.
*/
gulong cogl_material_layer_get_flags (CoglHandle layer_handle);
/**
* CoglMaterialFlushOption:
* @COGL_MATERIAL_FLUSH_FALLBACK_MASK: Follow this by a guin32 mask
* of the layers that can't be supported with the user supplied texture
* and need to be replaced with fallback textures. (1 = fallback, and the
* least significant bit = layer 0)
* @COGL_MATERIAL_FLUSH_DISABLE_MASK: Follow this by a guint32 mask
* of the layers that you want to completly disable texturing for
* (1 = fallback, and the least significant bit = layer 0)
* @COGL_MATERIAL_FLUSH_LAYER0_OVERRIDE: Follow this by a GLuint OpenGL texture
* name to override the texture used for layer 0 of the material. This is
* intended for dealing with sliced textures where you will need to point
* to each of the texture slices in turn when drawing your geometry.
* Passing a value of 0 is the same as not passing the option at all.
*/
typedef enum _CoglMaterialFlushOption
{
COGL_MATERIAL_FLUSH_FALLBACK_MASK = 1,
COGL_MATERIAL_FLUSH_DISABLE_MASK,
COGL_MATERIAL_FLUSH_LAYER0_OVERRIDE,
} CoglMaterialFlushOption;
/**
* cogl_material_flush_gl_state:
* @material: A CoglMaterial object
* @...: A NULL terminated list of (CoglMaterialFlushOption, data) pairs
*
* This function commits the state of the specified CoglMaterial - including
* the texture state for all the layers - to the OpenGL[ES] driver.
*
* Since 1.0
*/
void cogl_material_flush_gl_state (CoglHandle material,
...) G_GNUC_NULL_TERMINATED;
G_END_DECLS

View File

@ -82,7 +82,7 @@ typedef struct _CoglHandleObject
static CoglHandleClass _cogl_##type_name##_class; \
\
static GQuark \
_cogl_##type_name##_get_type (void) \
_cogl_handle_##type_name##_get_type (void) \
{ \
static GQuark type = 0; \
if (!type) \
@ -99,13 +99,13 @@ _cogl_##type_name##_handle_new (Cogl##TypeName *new_obj) \
obj->klass = &_cogl_##type_name##_class; \
if (!obj->klass->type) \
{ \
obj->klass->type = _cogl_##type_name##_get_type (); \
obj->klass->virt_free = _cogl_##type_name##_free; \
} \
obj->klass->type = _cogl_handle_##type_name##_get_type ();\
obj->klass->virt_free = _cogl_##type_name##_free; \
} \
\
_COGL_HANDLE_DEBUG_NEW (TypeName, obj); \
return (CoglHandle) new_obj; \
} \
_COGL_HANDLE_DEBUG_NEW (TypeName, obj); \
return (CoglHandle) new_obj; \
} \
\
Cogl##TypeName * \
_cogl_##type_name##_pointer_from_handle (CoglHandle handle) \
@ -121,7 +121,8 @@ cogl_is_##type_name (CoglHandle handle) \
if (handle == COGL_INVALID_HANDLE) \
return FALSE; \
\
return (obj->klass->type == _cogl_##type_name##_get_type ()); \
return (obj->klass->type == \
_cogl_handle_##type_name##_get_type ()); \
} \
\
CoglHandle G_GNUC_DEPRECATED \

View File

@ -129,5 +129,91 @@ struct _CoglMaterial
GList *layers;
};
/*
* SECTION:cogl-material-internals
* @short_description: Functions for creating custom primitives that make use
* of Cogl materials for filling.
*
* Normally you shouldn't need to use this API directly, but if you need to
* developing a custom/specialised primitive - probably using raw OpenGL - then
* this API aims to expose enough of the material internals to support being
* able to fill your geometry according to a given Cogl material.
*/
/*
* cogl_material_get_cogl_enable_flags:
* @material: A CoglMaterial object
*
* This determines what flags need to be passed to cogl_enable before this
* material can be used. Normally you shouldn't need to use this function
* directly since Cogl will do this internally, but if you are developing
* custom primitives directly with OpenGL you may want to use this.
*
* Note: This API is hopfully just a stop-gap solution. Ideally cogl_enable
* will be replaced.
*/
/* TODO: find a nicer solution! */
gulong _cogl_material_get_cogl_enable_flags (CoglHandle handle);
/*
* CoglMaterialLayerFlags:
* @COGL_MATERIAL_LAYER_FLAG_USER_MATRIX: Means the user has supplied a
* custom texture matrix.
*/
typedef enum _CoglMaterialLayerFlags
{
COGL_MATERIAL_LAYER_FLAG_HAS_USER_MATRIX = 1L<<0
} CoglMaterialLayerFlags;
/* XXX: NB: if you add flags here you will need to update
* CoglMaterialLayerPrivFlags!!! */
/*
* cogl_material_layer_get_flags:
* @layer_handle: A CoglMaterialLayer layer handle
*
* This lets you get a number of flag attributes about the layer. Normally
* you shouldn't need to use this function directly since Cogl will do this
* internally, but if you are developing custom primitives directly with
* OpenGL you may need this.
*/
gulong _cogl_material_layer_get_flags (CoglHandle layer_handle);
/*
* CoglMaterialFlushOption:
* @COGL_MATERIAL_FLUSH_FALLBACK_MASK: Follow this by a guin32 mask
* of the layers that can't be supported with the user supplied texture
* and need to be replaced with fallback textures. (1 = fallback, and the
* least significant bit = layer 0)
* @COGL_MATERIAL_FLUSH_DISABLE_MASK: Follow this by a guint32 mask
* of the layers that you want to completly disable texturing for
* (1 = fallback, and the least significant bit = layer 0)
* @COGL_MATERIAL_FLUSH_LAYER0_OVERRIDE: Follow this by a GLuint OpenGL texture
* name to override the texture used for layer 0 of the material. This is
* intended for dealing with sliced textures where you will need to point
* to each of the texture slices in turn when drawing your geometry.
* Passing a value of 0 is the same as not passing the option at all.
*/
typedef enum _CoglMaterialFlushOption
{
COGL_MATERIAL_FLUSH_FALLBACK_MASK = 1,
COGL_MATERIAL_FLUSH_DISABLE_MASK,
COGL_MATERIAL_FLUSH_LAYER0_OVERRIDE,
} CoglMaterialFlushOption;
/*
* cogl_material_flush_gl_state:
* @material: A CoglMaterial object
* @...: A NULL terminated list of (CoglMaterialFlushOption, data) pairs
*
* This function commits the state of the specified CoglMaterial - including
* the texture state for all the layers - to the OpenGL[ES] driver.
*
* Since 1.0
*/
void _cogl_material_flush_gl_state (CoglHandle material,
...) G_GNUC_NULL_TERMINATED;
#endif /* __COGL_MATERIAL_PRIVATE_H */

View File

@ -921,7 +921,7 @@ cogl_material_remove_layer (CoglHandle material_handle,
/* XXX: This API is hopfully just a stop-gap solution. Ideally cogl_enable
* will be replaced. */
gulong
cogl_material_get_cogl_enable_flags (CoglHandle material_handle)
_cogl_material_get_cogl_enable_flags (CoglHandle material_handle)
{
CoglMaterial *material;
gulong enable_flags = 0;
@ -979,7 +979,7 @@ cogl_material_layer_get_texture (CoglHandle layer_handle)
}
gulong
cogl_material_layer_get_flags (CoglHandle layer_handle)
_cogl_material_layer_get_flags (CoglHandle layer_handle)
{
CoglMaterialLayer *layer;
@ -1393,7 +1393,7 @@ _cogl_material_flush_base_gl_state (CoglMaterial *material)
}
void
cogl_material_flush_gl_state (CoglHandle handle, ...)
_cogl_material_flush_gl_state (CoglHandle handle, ...)
{
CoglMaterial *material;
va_list ap;

View File

@ -29,7 +29,7 @@
#include "cogl-internal.h"
#include "cogl-context.h"
#include "cogl-texture-private.h"
#include "cogl-material.h"
#include "cogl-material-private.h"
#include <string.h>
#include <gmodule.h>
@ -112,16 +112,16 @@ _cogl_journal_flush_quad_batch (CoglJournalEntry *batch_start,
disable_mask = (1 << batch_start->n_layers) - 1;
disable_mask = ~disable_mask;
cogl_material_flush_gl_state (ctx->source_material,
COGL_MATERIAL_FLUSH_FALLBACK_MASK,
batch_start->fallback_mask,
COGL_MATERIAL_FLUSH_DISABLE_MASK,
disable_mask,
/* Redundant when dealing with unsliced
* textures but does no harm... */
COGL_MATERIAL_FLUSH_LAYER0_OVERRIDE,
batch_start->layer0_override_texture,
NULL);
_cogl_material_flush_gl_state (ctx->source_material,
COGL_MATERIAL_FLUSH_FALLBACK_MASK,
batch_start->fallback_mask,
COGL_MATERIAL_FLUSH_DISABLE_MASK,
disable_mask,
/* Redundant when dealing with unsliced
* textures but does no harm... */
COGL_MATERIAL_FLUSH_LAYER0_OVERRIDE,
batch_start->layer0_override_texture,
NULL);
for (i = 0; i < batch_start->n_layers; i++)
{
@ -140,7 +140,7 @@ _cogl_journal_flush_quad_batch (CoglJournalEntry *batch_start,
/* FIXME: This api is a bit yukky, ideally it will be removed if we
* re-work the cogl_enable mechanism */
enable_flags |= cogl_material_get_cogl_enable_flags (ctx->source_material);
enable_flags |= _cogl_material_get_cogl_enable_flags (ctx->source_material);
if (ctx->enable_backface_culling)
enable_flags |= COGL_ENABLE_BACKFACE_CULLING;
@ -177,7 +177,7 @@ _cogl_journal_flush_quad_batch (CoglJournalEntry *batch_start,
color == 1 ? 0xff : 0x00,
color == 2 ? 0xff : 0x00,
0xff);
cogl_material_flush_gl_state (outline, NULL);
_cogl_material_flush_gl_state (outline, NULL);
_cogl_current_matrix_state_flush ();
GE( glDrawArrays (GL_LINE_LOOP, 4 * i, 4) );
}
@ -791,7 +791,7 @@ _cogl_rectangles_with_multitexture_coords (
/* We don't support multi texturing using textures with any waste if the
* user has supplied a custom texture matrix, since we don't know if
* the result will end up trying to texture from the waste area. */
flags = cogl_material_layer_get_flags (layer);
flags = _cogl_material_layer_get_flags (layer);
if (flags & COGL_MATERIAL_LAYER_FLAG_HAS_USER_MATRIX
&& _cogl_texture_span_has_waste (texture, 0, 0))
{
@ -1041,13 +1041,13 @@ _cogl_texture_sliced_polygon (CoglTextureVertex *vertices,
v += stride;
}
cogl_material_flush_gl_state (ctx->source_material,
COGL_MATERIAL_FLUSH_DISABLE_MASK,
(guint32)~1, /* disable all except the
_cogl_material_flush_gl_state (ctx->source_material,
COGL_MATERIAL_FLUSH_DISABLE_MASK,
(guint32)~1, /* disable all except the
first layer */
COGL_MATERIAL_FLUSH_LAYER0_OVERRIDE,
gl_handle,
NULL);
COGL_MATERIAL_FLUSH_LAYER0_OVERRIDE,
gl_handle,
NULL);
_cogl_current_matrix_state_flush ();
GE( glDrawArrays (GL_TRIANGLE_FAN, 0, n_vertices) );
@ -1136,10 +1136,10 @@ _cogl_multitexture_unsliced_polygon (CoglTextureVertex *vertices,
c[3] = cogl_color_get_alpha_float (&vertices[i].color);
}
cogl_material_flush_gl_state (ctx->source_material,
COGL_MATERIAL_FLUSH_FALLBACK_MASK,
fallback_mask,
NULL);
_cogl_material_flush_gl_state (ctx->source_material,
COGL_MATERIAL_FLUSH_FALLBACK_MASK,
fallback_mask,
NULL);
_cogl_current_matrix_state_flush ();
GE (glDrawArrays (GL_TRIANGLE_FAN, 0, n_vertices));
@ -1254,7 +1254,7 @@ cogl_polygon (CoglTextureVertex *vertices,
/* Prepare GL state */
enable_flags = COGL_ENABLE_VERTEX_ARRAY;
enable_flags |= cogl_material_get_cogl_enable_flags (ctx->source_material);
enable_flags |= _cogl_material_get_cogl_enable_flags (ctx->source_material);
if (ctx->enable_backface_culling)
enable_flags |= COGL_ENABLE_BACKFACE_CULLING;

View File

@ -136,6 +136,7 @@
#include "cogl-handle.h"
#include "cogl-vertex-buffer-private.h"
#include "cogl-texture-private.h"
#include "cogl-material-private.h"
#define PAD_FOR_ALIGNMENT(VAR, TYPE_SIZE) \
(VAR = TYPE_SIZE + ((VAR - 1) & ~(TYPE_SIZE - 1)))
@ -1638,14 +1639,14 @@ enable_state_for_drawing_buffer (CoglVertexBuffer *buffer)
}
}
cogl_material_flush_gl_state (ctx->source_material,
COGL_MATERIAL_FLUSH_FALLBACK_MASK,
fallback_mask,
COGL_MATERIAL_FLUSH_DISABLE_MASK,
disable_mask,
NULL);
_cogl_material_flush_gl_state (ctx->source_material,
COGL_MATERIAL_FLUSH_FALLBACK_MASK,
fallback_mask,
COGL_MATERIAL_FLUSH_DISABLE_MASK,
disable_mask,
NULL);
enable_flags |= cogl_material_get_cogl_enable_flags (ctx->source_material);
enable_flags |= _cogl_material_get_cogl_enable_flags (ctx->source_material);
if (ctx->enable_backface_culling)
enable_flags |= COGL_ENABLE_BACKFACE_CULLING;

View File

@ -42,6 +42,7 @@ typedef CoglFuncPtr (*GLXGetProcAddressProc) (const guint8 *procName);
#include "cogl-internal.h"
#include "cogl-util.h"
#include "cogl-context.h"
#include "cogl-material-private.h"
#if defined (HAVE_COGL_GLES2) || defined (HAVE_COGL_GLES)
#include "cogl-gles2-wrapper.h"
@ -375,7 +376,7 @@ _cogl_add_stencil_clip (float x_offset,
{
_COGL_GET_CONTEXT (ctx, NO_RETVAL);
cogl_material_flush_gl_state (ctx->stencil_material, NULL);
_cogl_material_flush_gl_state (ctx->stencil_material, NULL);
if (first)
{

View File

@ -166,9 +166,9 @@ cogl_create_context ()
default_texture_data);
cogl_set_source (_context->default_material);
cogl_material_flush_gl_state (_context->source_material, NULL);
_cogl_material_flush_gl_state (_context->source_material, NULL);
enable_flags =
cogl_material_get_cogl_enable_flags (_context->source_material);
_cogl_material_get_cogl_enable_flags (_context->source_material);
cogl_enable (enable_flags);
return TRUE;

View File

@ -29,6 +29,7 @@
#include "cogl-internal.h"
#include "cogl-context.h"
#include "cogl-clip-stack.h"
#include "cogl-material-private.h"
#include <string.h>
#include <gmodule.h>
@ -78,13 +79,13 @@ _cogl_path_stroke_nodes ()
_COGL_GET_CONTEXT (ctx, NO_RETVAL);
enable_flags |= cogl_material_get_cogl_enable_flags (ctx->source_material);
enable_flags |= _cogl_material_get_cogl_enable_flags (ctx->source_material);
cogl_enable (enable_flags);
cogl_material_flush_gl_state (ctx->source_material,
COGL_MATERIAL_FLUSH_DISABLE_MASK,
(guint32)~0, /* disable all texture layers */
NULL);
_cogl_material_flush_gl_state (ctx->source_material,
COGL_MATERIAL_FLUSH_DISABLE_MASK,
(guint32)~0, /* disable all texture layers */
NULL);
_cogl_current_matrix_state_flush ();
while (path_start < ctx->path_nodes->len)
@ -133,10 +134,10 @@ _cogl_add_path_to_stencil_buffer (floatVec2 nodes_min,
_COGL_GET_CONTEXT (ctx, NO_RETVAL);
/* Just setup a simple material that doesn't use texturing... */
cogl_material_flush_gl_state (ctx->stencil_material, NULL);
_cogl_material_flush_gl_state (ctx->stencil_material, NULL);
enable_flags |=
cogl_material_get_cogl_enable_flags (ctx->source_material);
_cogl_material_get_cogl_enable_flags (ctx->source_material);
cogl_enable (enable_flags);
_cogl_path_get_bounds (nodes_min, nodes_max,

View File

@ -124,9 +124,9 @@ cogl_create_context ()
default_texture_data);
cogl_set_source (_context->default_material);
cogl_material_flush_gl_state (_context->source_material, NULL);
_cogl_material_flush_gl_state (_context->source_material, NULL);
enable_flags =
cogl_material_get_cogl_enable_flags (_context->source_material);
_cogl_material_get_cogl_enable_flags (_context->source_material);
cogl_enable (enable_flags);
return TRUE;

View File

@ -29,6 +29,7 @@
#include "cogl-internal.h"
#include "cogl-context.h"
#include "cogl-clip-stack.h"
#include "cogl-material-private.h"
#include <string.h>
#include <gmodule.h>
@ -78,13 +79,13 @@ _cogl_path_stroke_nodes ()
_COGL_GET_CONTEXT (ctx, NO_RETVAL);
enable_flags |= cogl_material_get_cogl_enable_flags (ctx->source_material);
enable_flags |= _cogl_material_get_cogl_enable_flags (ctx->source_material);
cogl_enable (enable_flags);
cogl_material_flush_gl_state (ctx->source_material,
COGL_MATERIAL_FLUSH_DISABLE_MASK,
(guint32)~0, /* disable all texture layers */
NULL);
_cogl_material_flush_gl_state (ctx->source_material,
COGL_MATERIAL_FLUSH_DISABLE_MASK,
(guint32)~0, /* disable all texture layers */
NULL);
_cogl_current_matrix_state_flush ();
while (path_start < ctx->path_nodes->len)
@ -139,10 +140,10 @@ _cogl_add_path_to_stencil_buffer (floatVec2 nodes_min,
_COGL_GET_CONTEXT (ctx, NO_RETVAL);
/* Just setup a simple material that doesn't use texturing... */
cogl_material_flush_gl_state (ctx->stencil_material, NULL);
_cogl_material_flush_gl_state (ctx->stencil_material, NULL);
enable_flags |=
cogl_material_get_cogl_enable_flags (ctx->source_material);
_cogl_material_get_cogl_enable_flags (ctx->source_material);
cogl_enable (enable_flags);
_cogl_path_get_bounds (nodes_min, nodes_max,

View File

@ -359,6 +359,9 @@ cogl_material_remove_layer
cogl_material_set_layer_combine
cogl_material_set_layer_combine_constant
cogl_material_set_layer_matrix
cogl_material_get_layers
cogl_material_layer_get_type
cogl_material_layer_get_texture
<SUBSECTION Private>
CoglMaterial
CoglMaterialFlags