mutter/cogl/cogl-internal.h

134 lines
4.5 KiB
C
Raw Normal View History

/*
* Cogl
*
* An object oriented GL/GLES Abstraction/Utility Layer
*
cogl: improves header and coding style consistency We've had complaints that our Cogl code/headers are a bit "special" so this is a first pass at tidying things up by giving them some consistency. These changes are all consistent with how new code in Cogl is being written, but the style isn't consistently applied across all code yet. There are two parts to this patch; but since each one required a large amount of effort to maintain tidy indenting it made sense to combine the changes to reduce the time spent re indenting the same lines. The first change is to use a consistent style for declaring function prototypes in headers. Cogl headers now consistently use this style for prototypes: return_type cogl_function_name (CoglType arg0, CoglType arg1); Not everyone likes this style, but it seems that most of the currently active Cogl developers agree on it. The second change is to constrain the use of redundant glib data types in Cogl. Uses of gint, guint, gfloat, glong, gulong and gchar have all been replaced with int, unsigned int, float, long, unsigned long and char respectively. When talking about pixel data; use of guchar has been replaced with guint8, otherwise unsigned char can be used. The glib types that we continue to use for portability are gboolean, gint{8,16,32,64}, guint{8,16,32,64} and gsize. The general intention is that Cogl should look palatable to the widest range of C programmers including those outside the Gnome community so - especially for the public API - we want to minimize the number of foreign looking typedefs.
2010-02-10 01:57:32 +00:00
* Copyright (C) 2007,2008,2009,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 <http://www.gnu.org/licenses/>.
*
*
*/
#ifndef __COGL_INTERNAL_H
#define __COGL_INTERNAL_H
#include "cogl-bitmask.h"
#include "cogl-gl-header.h"
#ifdef COGL_HAS_XLIB_SUPPORT
#include <X11/Xutil.h>
#endif
#ifdef COGL_GL_DEBUG
cogl: improves header and coding style consistency We've had complaints that our Cogl code/headers are a bit "special" so this is a first pass at tidying things up by giving them some consistency. These changes are all consistent with how new code in Cogl is being written, but the style isn't consistently applied across all code yet. There are two parts to this patch; but since each one required a large amount of effort to maintain tidy indenting it made sense to combine the changes to reduce the time spent re indenting the same lines. The first change is to use a consistent style for declaring function prototypes in headers. Cogl headers now consistently use this style for prototypes: return_type cogl_function_name (CoglType arg0, CoglType arg1); Not everyone likes this style, but it seems that most of the currently active Cogl developers agree on it. The second change is to constrain the use of redundant glib data types in Cogl. Uses of gint, guint, gfloat, glong, gulong and gchar have all been replaced with int, unsigned int, float, long, unsigned long and char respectively. When talking about pixel data; use of guchar has been replaced with guint8, otherwise unsigned char can be used. The glib types that we continue to use for portability are gboolean, gint{8,16,32,64}, guint{8,16,32,64} and gsize. The general intention is that Cogl should look palatable to the widest range of C programmers including those outside the Gnome community so - especially for the public API - we want to minimize the number of foreign looking typedefs.
2010-02-10 01:57:32 +00:00
const char *
_cogl_gl_error_to_string (GLenum error_code);
#define GE(ctx, x) G_STMT_START { \
GLenum __err; \
(ctx)->x; \
while ((__err = (ctx)->glGetError ()) != GL_NO_ERROR) \
{ \
g_warning ("%s: GL error (%d): %s\n", \
G_STRLOC, \
__err, \
_cogl_gl_error_to_string (__err)); \
} } G_STMT_END
#define GE_RET(ret, ctx, x) G_STMT_START { \
GLenum __err; \
ret = (ctx)->x; \
while ((__err = (ctx)->glGetError ()) != GL_NO_ERROR) \
{ \
g_warning ("%s: GL error (%d): %s\n", \
G_STRLOC, \
__err, \
_cogl_gl_error_to_string (__err)); \
} } G_STMT_END
#else /* !COGL_GL_DEBUG */
#define GE(ctx, x) ((ctx)->x)
#define GE_RET(ret, ctx, x) (ret = ((ctx)->x))
#endif /* COGL_GL_DEBUG */
CoglMaterial: Implements sparse materials design This is a complete overhaul of the data structures used to manage CoglMaterial state. We have these requirements that were aiming to meet: (Note: the references to "renderlists" correspond to the effort to support scenegraph level shuffling of Clutter actor primitives so we can minimize GPU state changes) Sparse State: We wanted a design that allows sparse descriptions of state so it scales well as we make CoglMaterial responsible for more and more state. It needs to scale well in terms of memory usage and the cost of operations we need to apply to materials such as comparing, copying and flushing their state. I.e. we would rather have these things scale by the number of real changes a material represents not by how much overall state CoglMaterial becomes responsible for. Cheap Copies: As we add support for renderlists in Clutter we will need to be able to get an immutable handle for a given material's current state so that we can retain a record of a primitive with its associated material without worrying that changes to the original material will invalidate that record. No more flush override options: We want to get rid of the flush overrides mechanism we currently use to deal with texture fallbacks, wrap mode changes and to handle the use of highlevel CoglTextures that need to be resolved into lowlevel textures before flushing the material state. The flush options structure has been expanding in size and the structure is logged with every journal entry so it is not an approach that scales well at all. It also makes flushing material state that much more complex. Weak Materials: Again for renderlists we need a way to create materials derived from other materials but without the strict requirement that modifications to the original material wont affect the derived ("weak") material. The only requirement is that its possible to later check if the original material has been changed. A summary of the new design: A CoglMaterial now basically represents a diff against its parent. Each material has a single parent and a mask of state that it changes. Each group of state (such as the blending state) has an "authority" which is found by walking up from a given material through its ancestors checking the difference mask until a match for that group is found. There is only one root node to the graph of all materials, which is the default material first created when Cogl is being initialized. All the groups of state are divided into two types, such that infrequently changed state belongs in a separate "BigState" structure that is only allocated and attached to a material when necessary. CoglMaterialLayers are another sparse structure. Like CoglMaterials they represent a diff against their parent and all the layers are part of another graph with the "default_layer_0" layer being the root node that Cogl creates during initialization. Copying a material is now basically just a case of slice allocating a CoglMaterial, setting the parent to be the source being copied and zeroing the mask of changes. Flush overrides should now be handled by simply relying on the cheapness of copying a material and making changes to it. (This will be done in a follow on commit) Weak material support will be added in a follow on commit.
2010-04-08 11:21:04 +00:00
#define COGL_ENABLE_ALPHA_TEST (1<<1)
#define COGL_ENABLE_VERTEX_ARRAY (1<<2)
#define COGL_ENABLE_COLOR_ARRAY (1<<3)
cogl: improves header and coding style consistency We've had complaints that our Cogl code/headers are a bit "special" so this is a first pass at tidying things up by giving them some consistency. These changes are all consistent with how new code in Cogl is being written, but the style isn't consistently applied across all code yet. There are two parts to this patch; but since each one required a large amount of effort to maintain tidy indenting it made sense to combine the changes to reduce the time spent re indenting the same lines. The first change is to use a consistent style for declaring function prototypes in headers. Cogl headers now consistently use this style for prototypes: return_type cogl_function_name (CoglType arg0, CoglType arg1); Not everyone likes this style, but it seems that most of the currently active Cogl developers agree on it. The second change is to constrain the use of redundant glib data types in Cogl. Uses of gint, guint, gfloat, glong, gulong and gchar have all been replaced with int, unsigned int, float, long, unsigned long and char respectively. When talking about pixel data; use of guchar has been replaced with guint8, otherwise unsigned char can be used. The glib types that we continue to use for portability are gboolean, gint{8,16,32,64}, guint{8,16,32,64} and gsize. The general intention is that Cogl should look palatable to the widest range of C programmers including those outside the Gnome community so - especially for the public API - we want to minimize the number of foreign looking typedefs.
2010-02-10 01:57:32 +00:00
void
_cogl_enable (unsigned long flags);
cogl: improves header and coding style consistency We've had complaints that our Cogl code/headers are a bit "special" so this is a first pass at tidying things up by giving them some consistency. These changes are all consistent with how new code in Cogl is being written, but the style isn't consistently applied across all code yet. There are two parts to this patch; but since each one required a large amount of effort to maintain tidy indenting it made sense to combine the changes to reduce the time spent re indenting the same lines. The first change is to use a consistent style for declaring function prototypes in headers. Cogl headers now consistently use this style for prototypes: return_type cogl_function_name (CoglType arg0, CoglType arg1); Not everyone likes this style, but it seems that most of the currently active Cogl developers agree on it. The second change is to constrain the use of redundant glib data types in Cogl. Uses of gint, guint, gfloat, glong, gulong and gchar have all been replaced with int, unsigned int, float, long, unsigned long and char respectively. When talking about pixel data; use of guchar has been replaced with guint8, otherwise unsigned char can be used. The glib types that we continue to use for portability are gboolean, gint{8,16,32,64}, guint{8,16,32,64} and gsize. The general intention is that Cogl should look palatable to the widest range of C programmers including those outside the Gnome community so - especially for the public API - we want to minimize the number of foreign looking typedefs.
2010-02-10 01:57:32 +00:00
unsigned long
_cogl_get_enable (void);
void
_cogl_transform_point (const CoglMatrix *matrix_mv,
const CoglMatrix *matrix_p,
const float *viewport,
float *x,
float *y);
#define COGL_DRIVER_ERROR (_cogl_driver_error_quark ())
typedef enum { /*< prefix=COGL_DRIVER_ERROR >*/
COGL_DRIVER_ERROR_UNKNOWN_VERSION,
Dynamically load the GL or GLES library The GL or GLES library is now dynamically loaded by the CoglRenderer so that it can choose between GL, GLES1 and GLES2 at runtime. The library is loaded by the renderer because it needs to be done before calling eglInitialize. There is a new environment variable called COGL_DRIVER to choose between gl, gles1 or gles2. The #ifdefs for HAVE_COGL_GL, HAVE_COGL_GLES and HAVE_COGL_GLES2 have been changed so that they don't assume the ifdefs are mutually exclusive. They haven't been removed entirely so that it's possible to compile the GLES backends without the the enums from the GL headers. When using GLX the winsys additionally dynamically loads libGL because that also contains the GLX API. It can't be linked in directly because that would probably conflict with the GLES API if the EGL is selected. When compiling with EGL support the library links directly to libEGL because it doesn't contain any GL API so it shouldn't have any conflicts. When building for WGL or OSX Cogl still directly links against the GL API so there is a #define in config.h so that Cogl won't try to dlopen the library. Cogl-pango previously had a #ifdef to detect when the GL backend is used so that it can sneakily pass GL_QUADS to cogl_vertex_buffer_draw. This is now changed so that it queries the CoglContext for the backend. However to get this to work Cogl now needs to export the _cogl_context_get_default symbol and cogl-pango needs some extra -I flags to so that it can include cogl-context-private.h
2011-07-07 19:44:56 +00:00
COGL_DRIVER_ERROR_INVALID_VERSION,
COGL_DRIVER_ERROR_NO_SUITABLE_DRIVER_FOUND,
COGL_DRIVER_ERROR_FAILED_TO_LOAD_LIBRARY
} CoglDriverError;
typedef enum
{
COGL_PRIVATE_FEATURE_TEXTURE_2D_FROM_EGL_IMAGE = 1L<<0,
COGL_PRIVATE_FEATURE_MESA_PACK_INVERT = 1L<<1,
COGL_PRIVATE_FEATURE_STENCIL_BUFFER = 1L<<2,
COGL_PRIVATE_FEATURE_OFFSCREEN_BLIT = 1L<<3,
COGL_PRIVATE_FEATURE_FOUR_CLIP_PLANES = 1L<<4,
COGL_PRIVATE_FEATURE_PBOS = 1L<<5,
COGL_PRIVATE_FEATURE_VBOS = 1L<<6,
COGL_PRIVATE_FEATURE_EXT_PACKED_DEPTH_STENCIL = 1L<<7,
COGL_PRIVATE_FEATURE_OES_PACKED_DEPTH_STENCIL = 1L<<8,
COGL_PRIVATE_FEATURE_TEXTURE_FORMAT_BGRA8888 = 1L<<9,
Use GL_ARB_sampler_objects GL_ARB_sampler_objects provides a GL object which overrides the sampler state part of a texture object with different values. The sampler state that Cogl currently exposes is the wrap modes and filters. Cogl exposes the state as part of the pipeline layer state but without this extension GL only exposes it as part of the texture object state. This means that it won't work to use a single texture multiple times in one primitive with different sampler states. It also makes switching between different sampler states with a single texture not terribly efficient because it has to change the texture object state every time. This patch adds a cache for sampler states in a shared hash table attached to the CoglContext. The entire set of parameters for the sampler state is used as the key for the hash table. When a unique state is encountered the sampler cache will create a new entry, otherwise it will return a const pointer to an existing entry. That means we can have a single pointer to represent any combination of sampler state. Pipeline layers now just store this single pointer rather than storing all of the sampler state. The two separate state flags for wrap modes and filters have now been combined into one. It should be faster to compare the sampler state now because instead of comparing each value it can just compare the pointers to the cached sampler entries. The hash table of cached sampler states should only need to perform its more expensive hash on the state when a property is changed on a pipeline, not every time it is flushed. When the sampler objects extension is available each cached sampler state will also get a sampler object to represent it. The common code to flush the GL state will now simply bind this object to a unit instead of flushing the state though the CoglTexture when possible. Reviewed-by: Robert Bragg <robert@linux.intel.com>
2012-04-04 21:20:04 +00:00
COGL_PRIVATE_FEATURE_UNPACK_SUBIMAGE = 1L<<10,
Add a GL 3 driver This adds a new CoglDriver for GL 3 called COGL_DRIVER_GL3. When requested, the GLX, EGL and SDL2 winsyss will set the necessary attributes to request a forward-compatible core profile 3.1 context. That means it will have no deprecated features. To simplify the explosion of checks for specific combinations of context->driver, many of these conditionals have now been replaced with private feature flags that are checked instead. The GL and GLES drivers now initialise these private feature flags depending on which driver is used. The fixed function backends now explicitly check whether the fixed function private feature is available which means the GL3 driver will fall back to always using the GLSL progend. Since Rob's latest patches the GLSL progend no longer uses any fixed function API anyway so it should just work. The driver is currently lower priority than COGL_DRIVER_GL so it will not be used unless it is specificly requested. We may want to change this priority at some point because apparently Mesa can make some memory savings if a core profile context is used. In GL 3, getting the combined extensions string with glGetString is deprecated so this patch changes it to use glGetStringi to build up an array of extensions instead. _cogl_context_get_gl_extensions now returns this array instead of trying to return a const string. The caller is expected to free the array. Some issues with this patch: • GL 3 does not support GL_ALPHA format textures. We should probably make this a feature flag or something. Cogl uses this to render text which currently just throws a GL error and breaks so it's pretty important to do something about this before considering the GL3 driver to be stable. • GL 3 doesn't support client side vertex buffers. This probably doesn't matter because CoglBuffer won't normally use malloc'd buffers if VBOs are available, but it might but worth making malloc'd buffers a private feature and forcing it not to use them. • GL 3 doesn't support the default vertex array object. This patch just makes it create and bind a single non-default vertex array object which gets used just like the normal default object. Ideally it would be good to use vertex array objects properly and attach them to a CoglPrimitive to cache the state. Reviewed-by: Robert Bragg <robert@linux.intel.com> (cherry picked from commit 66c9db993595b3a22e63f4c201ea468bc9b88cb6)
2012-09-26 19:32:36 +00:00
COGL_PRIVATE_FEATURE_SAMPLER_OBJECTS = 1L<<11,
COGL_PRIVATE_FEATURE_FIXED_FUNCTION = 1L<<12,
COGL_PRIVATE_FEATURE_READ_PIXELS_ANY_FORMAT = 1L<<13,
COGL_PRIVATE_FEATURE_ANY_GL = 1L<<14,
COGL_PRIVATE_FEATURE_ALPHA_TEST = 1L<<15,
COGL_PRIVATE_FEATURE_FORMAT_CONVERSION = 1L<<16,
COGL_PRIVATE_FEATURE_QUADS = 1L<<17,
COGL_PRIVATE_FEATURE_BLEND_CONSTANT = 1L<<18,
COGL_PRIVATE_FEATURE_QUERY_FRAMEBUFFER_BITS = 1L<<19,
COGL_PRIVATE_FEATURE_BUILTIN_POINT_SIZE_UNIFORM = 1L<<20,
Use GL_ARB_texture_swizzle to emulate GL_ALPHA textures The core profile of GL3 has removed support for component-alpha textures. Previously the GL3 driver would just ignore this and try to create them anyway. This would generate a GL error on Mesa. To fix this the GL texture driver will now create a GL_RED texture when GL_ALPHA textures are not supported natively. It will then set a texture swizzle using the GL_ARB_texture_swizzle extension so that the alpha component will be taken from the red component of the texture. The swizzle is part of the texture object state so it only needs to be set once when the texture is created. The ‘gen’ virtual function of the texture driver has been changed to also take the internal format as a parameter. The GL driver will now set the swizzle as appropriate here. The GL3 driver now reports an error if the texture swizzle extension is not available because Cogl can't really work properly without out it. The extension is part of GL 3.3 so it is quite likely that it has wide support from drivers. Eventually we could get rid of this requirement if we have our own GLSL front-end and we could generate the swizzle ourselves. When uploading or downloading texture data to or from a component-alpha texture, we can no longer rely on GL to do the conversion. The swizzle doesn't have any effect on the texture data functions. In these cases Cogl will now force an intermediate buffer to be used and it will manually do the conversion as it does for the GLES drivers. Reviewed-by: Robert Bragg <robert@linux.intel.com> (cherry picked from commit 32bacf81ebaa3be21a8f26af07d8f6eed6607652)
2012-11-19 17:28:52 +00:00
COGL_PRIVATE_FEATURE_QUERY_TEXTURE_PARAMETERS = 1L<<21,
COGL_PRIVATE_FEATURE_ALPHA_TEXTURES = 1L<<22,
COGL_PRIVATE_FEATURE_TEXTURE_SWIZZLE = 1L<<23
} CoglPrivateFeatureFlags;
/* Sometimes when evaluating pipelines, either during comparisons or
* if calculating a hash value we need to tweak the evaluation
* semantics */
typedef enum _CoglPipelineEvalFlags
{
COGL_PIPELINE_EVAL_FLAG_NONE = 0
} CoglPipelineEvalFlags;
Adds CoglError api Although we use GLib internally in Cogl we would rather not leak GLib api through Cogl's own api, except through explicitly namespaced cogl_glib_ / cogl_gtype_ feature apis. One of the benefits we see to not leaking GLib through Cogl's public API is that documentation for Cogl won't need to first introduce the Glib API to newcomers, thus hopefully lowering the barrier to learning Cogl. This patch provides a Cogl specific typedef for reporting runtime errors which by no coincidence matches the typedef for GError exactly. If Cogl is built with --enable-glib (default) then developers can even safely assume that a CoglError is a GError under the hood. This patch also enforces a consistent policy for when NULL is passed as an error argument and an error is thrown. In this case we log the error and abort the application, instead of silently ignoring it. In common cases where nothing has been implemented to handle a particular error and/or where applications are just printing the error and aborting themselves then this saves some typing. This also seems more consistent with language based exceptions which usually cause a program to abort if they are not explicitly caught (which passing a non-NULL error signifies in this case) Since this policy for NULL error pointers is stricter than the standard GError convention, there is a clear note in the documentation to warn developers that are used to using the GError api. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit b068d5ea09ab32c37e8c965fc8582c85d1b2db46) Note: Since we can't change the Cogl 1.x api the patch was changed to not rename _error_quark() functions to be _error_domain() functions and although it's a bit ugly, instead of providing our own CoglError type that's compatible with GError we simply #define CoglError to GError unless Cogl is built with glib disabled. Note: this patch does technically introduce an API break since it drops the cogl_error_get_type() symbol generated by glib-mkenum (Since the CoglError enum was replaced by a CoglSystemError enum) but for now we are assuming that this will not affect anyone currently using the Cogl API. If this does turn out to be a problem in practice then we would be able to fix this my manually copying an implementation of cogl_error_get_type() generated by glib-mkenum into a compatibility source file and we could also define the original COGL_ERROR_ enums for compatibility too. Note: another minor concern with cherry-picking this patch to the 1.14 branch is that an api scanner would be lead to believe that some APIs have changed, and for example the gobject-introspection parser which understands the semantics of GError will not understand the semantics of CoglError. We expect most people that have tried to use gobject-introspection with Cogl already understand though that it is not well suited to generating bindings of the Cogl api anyway and we aren't aware or anyone depending on such bindings for apis involving GErrors. (GnomeShell only makes very-very minimal use of Cogl via the gjs bindings for the cogl_rectangle and cogl_color apis.) The main reason we have cherry-picked this patch to the 1.14 branch even given the above concerns is that without it it would become very awkward for us to cherry-pick other beneficial patches from master.
2012-08-31 18:28:27 +00:00
uint32_t
_cogl_driver_error_quark (void);
#endif /* __COGL_INTERNAL_H */