isa/mutter
1
0
Fork 0
mirror of https://github.com/brl/mutter.git synced 2024-12-25 20:32:16 +00:00
Code Issues Packages Projects Releases Wiki Activity
e1dfcdee3d
mutter/cogl/cogl-context.h

374 lines
13 KiB
C
Raw Normal View History

cogl: Adds experimental cogl_context_new() API This adds a new experimental function (you need to define COGL_ENABLE_EXPERIMENTAL_API to access it) which takes us towards being able to have a standalone Cogl API. This is really a minor aesthetic change for now since all the GL context creation code still lives in Clutter but it's a step forward none the less. Since our current designs introduce a CoglDisplay object as something that would be passed to the context constructor this provides a stub cogl-display.h with CoglDisplay typedef. _cogl_context_get_default() which Clutter uses to access the Cogl context has been modified to use cogl_context_new() to initialize the default context. There is one rather nasty hack used in this patch which is that the implementation of cogl_context_new() has to forcibly make the allocated context become the default context because currently all the code in Cogl assumes it can access the context using _COGL_GET_CONTEXT including code used to initialize the context.
2010-11-05 00:00:25 +00:00
/*
* Cogl
*
* An object oriented GL/GLES Abstraction/Utility Layer
*
* Copyright (C) 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/>.
*
* Authors:
* Robert Bragg <robert@linux.intel.com>
*
*/
Mass rename CLUTTER_COMPILATION to COGL_COMPILATION Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit a99512e5798e48ffa3a9a1a7eb98bc55647ee1b6)
2012-06-20 17:49:08 +00:00
#if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION)
cogl: Adds experimental cogl_context_new() API This adds a new experimental function (you need to define COGL_ENABLE_EXPERIMENTAL_API to access it) which takes us towards being able to have a standalone Cogl API. This is really a minor aesthetic change for now since all the GL context creation code still lives in Clutter but it's a step forward none the less. Since our current designs introduce a CoglDisplay object as something that would be passed to the context constructor this provides a stub cogl-display.h with CoglDisplay typedef. _cogl_context_get_default() which Clutter uses to access the Cogl context has been modified to use cogl_context_new() to initialize the default context. There is one rather nasty hack used in this patch which is that the implementation of cogl_context_new() has to forcibly make the allocated context become the default context because currently all the code in Cogl assumes it can access the context using _COGL_GET_CONTEXT including code used to initialize the context.
2010-11-05 00:00:25 +00:00
#error "Only <cogl/cogl.h> can be included directly."
#endif
#ifndef __COGL_CONTEXT_H__
#define __COGL_CONTEXT_H__
Move all types/prototypes from cogl.h -> cogl[1]-context.h So we can get to the point where cogl.h is merely an aggregation of header includes for the 1.x api this moves all the function prototypes and type definitions into a cogl-context.h and a new cogl1-context.h. Ideally no code internally should ever need to include cogl.h as it just represents the public facing header for accessing the 1.x api which should only be used by Clutter. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-17 21:46:39 +00:00
/* We forward declare the CoglContext type here to avoid some circular
* dependency issues with the following headers.
*/
typedef struct _CoglContext CoglContext;
gles1: Include GLES/egl.h or EGL/egl.h depending on the implementation Early implementations provided only a GLES/egl.h while Khronos's implementer guide now states EGL/egl.h is the One. Some implementations keep a GLES/egl.h wrapper around EGL/egl.h for backward compatibility while others provide EGL/egl.h only. Also took the opportunity to factorize a bit this inclusion in cogl-defines.h.
2011-05-13 07:04:47 +00:00
#include <cogl/cogl-defines.h>
cogl: Adds experimental cogl_context_new() API This adds a new experimental function (you need to define COGL_ENABLE_EXPERIMENTAL_API to access it) which takes us towards being able to have a standalone Cogl API. This is really a minor aesthetic change for now since all the GL context creation code still lives in Clutter but it's a step forward none the less. Since our current designs introduce a CoglDisplay object as something that would be passed to the context constructor this provides a stub cogl-display.h with CoglDisplay typedef. _cogl_context_get_default() which Clutter uses to access the Cogl context has been modified to use cogl_context_new() to initialize the default context. There is one rather nasty hack used in this patch which is that the implementation of cogl_context_new() has to forcibly make the allocated context become the default context because currently all the code in Cogl assumes it can access the context using _COGL_GET_CONTEXT including code used to initialize the context.
2010-11-05 00:00:25 +00:00
#include <cogl/cogl-display.h>
Move all types/prototypes from cogl.h -> cogl[1]-context.h So we can get to the point where cogl.h is merely an aggregation of header includes for the 1.x api this moves all the function prototypes and type definitions into a cogl-context.h and a new cogl1-context.h. Ideally no code internally should ever need to include cogl.h as it just represents the public facing header for accessing the 1.x api which should only be used by Clutter. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-17 21:46:39 +00:00
#include <cogl/cogl-primitive.h>
android: Add support for an EGL/Android winsys The native window type of the EGL/Android winsys is ANativeWinow*. The Android NDK gives you a pointer to this ANativeWindow and you just need to configure that window using the EGLConfig you are choosing when creating the context. This means you have to know the ANativeWindow* window before creating the context. This is solved here by just having a global variable you can set with cogl_android_set_native_window() before creating the context. This is a bit ugly though, and it conceptually belongs to the OnScreen creation to know which ANativeWindow* to use. This would need a "lazy context creation" mechanism, waiting for the user to create the OnScreen to initialize the GL context.
2011-05-16 15:43:30 +00:00
#ifdef COGL_HAS_EGL_PLATFORM_ANDROID_SUPPORT
#include <android/native_window.h>
#endif
cogl: Adds experimental cogl_context_new() API This adds a new experimental function (you need to define COGL_ENABLE_EXPERIMENTAL_API to access it) which takes us towards being able to have a standalone Cogl API. This is really a minor aesthetic change for now since all the GL context creation code still lives in Clutter but it's a step forward none the less. Since our current designs introduce a CoglDisplay object as something that would be passed to the context constructor this provides a stub cogl-display.h with CoglDisplay typedef. _cogl_context_get_default() which Clutter uses to access the Cogl context has been modified to use cogl_context_new() to initialize the default context. There is one rather nasty hack used in this patch which is that the implementation of cogl_context_new() has to forcibly make the allocated context become the default context because currently all the code in Cogl assumes it can access the context using _COGL_GET_CONTEXT including code used to initialize the context.
2010-11-05 00:00:25 +00:00
Fixes for --disable-glib This fixes some problems which were stopping --disable-glib from working properly: • A lot of the public headers were including glib.h. This shouldn't be necessary because the API doesn't expose any glib types. Otherwise any apps would require glib in order to get the header. • The public headers were using G_BEGIN_DECLS. There is now a replacement macro called COGL_BEGIN_DECLS which is defined in cogl-types.h. • A similar fix has been done for G_GNUC_NULL_TERMINATED and G_GNUC_DEPRECATED. • The CFLAGS were not including $(builddir)/deps/glib which was preventing it finding the generated glibconfig.h when building out of tree. Reviewed-by: Robert Bragg <robert@linux.intel.com> (cherry picked from commit 4138b3141c2f39cddaea3d72bfc04342ed5092d0)
2012-11-22 18:01:10 +00:00
COGL_BEGIN_DECLS
cogl: Adds experimental cogl_context_new() API This adds a new experimental function (you need to define COGL_ENABLE_EXPERIMENTAL_API to access it) which takes us towards being able to have a standalone Cogl API. This is really a minor aesthetic change for now since all the GL context creation code still lives in Clutter but it's a step forward none the less. Since our current designs introduce a CoglDisplay object as something that would be passed to the context constructor this provides a stub cogl-display.h with CoglDisplay typedef. _cogl_context_get_default() which Clutter uses to access the Cogl context has been modified to use cogl_context_new() to initialize the default context. There is one rather nasty hack used in this patch which is that the implementation of cogl_context_new() has to forcibly make the allocated context become the default context because currently all the code in Cogl assumes it can access the context using _COGL_GET_CONTEXT including code used to initialize the context.
2010-11-05 00:00:25 +00:00
/**
* SECTION:cogl-context
* @short_description: The top level application context.
*
Start removing _EXP defines and improves some docs Originally we decided to use #define tricks to rename all experimental symbols so that they had an _EXP suffix so it would be a bit clearer for those wanting to check for ABI changes that they shouldn't worry about these experimental symbols. We feel now though that the defines are a bit more hassle than they are really worth, since they are one extra thing to remember when coding, they make using gdb slightly more awkward since you have to use the real symbol name to set breakpoints and we already have a mechanism for declaring symbols as experimental via gtk-doc that can be used by anyone wanting to check for ABI changes. Instead of just using a script to remove all the #defines we are going to go through them manually because we need to make sure the symbols are marked as unstable via gtk-doc. This patch does a first batch of define removals and in fact some of the symbols didn't have any documentation at all so that needed to be added too. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2011-12-16 15:07:25 +00:00
* A #CoglContext is the top most sandbox of Cogl state for an
* application or toolkit. Its main purpose is to act as a sandbox
* for the memory management of state objects. Normally an application
* will only create a single context since there is no way to share
* resources between contexts.
*
* For those familiar with OpenGL or perhaps Cairo it should be
* understood that unlike these APIs a Cogl context isn't a rendering
* context as such. In other words Cogl doesn't aim to provide a state
* machine style model for configuring rendering parameters. Most
* rendering state in Cogl is directly associated with user managed
* objects called pipelines and geometry is drawn with a specific
* pipeline object to a framebuffer object and those 3 things fully
* define the state for drawing. This is an important part of Cogl's
* design since it helps you write orthogonal rendering components
* that can all access the same GPU without having to worry about
* what state other components have left you with.
Don't take internal references on the context We want applications to fully control the lifetime of a CoglContext without having to worry that internal resources (such as the default 2d,3d and rectangle textures, or any caches we maintain) could result in circular references that keep the context alive. We also want to avoid making CoglContext into a special kind of object that isn't ref-counted or that can't be used with object apis such as cogl_object_set_user_data. Being able to reliably destroy the context is important on platforms such as Android where you may be required bring-up and tear-down a CoglContext numerous times throughout the applications lifetime. A dissadvantage of this policy is that it is now possible to leave other object such as framebuffers in an inconsistent state if the context is unreferenced and destroyed. The documentation states that all objects that directly or indirectly depend on a context that has been destroyed will be left in an inconsistent state and must not be accessed thereafter. Applications (such as Android applications) that need to cleanly destroy and re-create Cogl resources should make sure to manually unref these dependant objects before destroying the context. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 23ce51beba1bb739a224e47614a59327dfbb65af)
2012-09-10 10:26:17 +00:00
*
doc: Generate a valid cogl-context.xml The automagic paragraph support of gtk-doc is way too simple to support things like multi-paragraphs <note>s. Let's trick gtk-doc and make it generate a valid docbook snippet for cogl-context. Without this, cogl-context remains absent of the reference documentation, how sad is this?! (cherry picked from commit 606b472d91450e3221da6631020f534892e866a9)
2012-12-29 20:12:13 +00:00
* <note><para>Cogl does not maintain internal references to the context for
Don't take internal references on the context We want applications to fully control the lifetime of a CoglContext without having to worry that internal resources (such as the default 2d,3d and rectangle textures, or any caches we maintain) could result in circular references that keep the context alive. We also want to avoid making CoglContext into a special kind of object that isn't ref-counted or that can't be used with object apis such as cogl_object_set_user_data. Being able to reliably destroy the context is important on platforms such as Android where you may be required bring-up and tear-down a CoglContext numerous times throughout the applications lifetime. A dissadvantage of this policy is that it is now possible to leave other object such as framebuffers in an inconsistent state if the context is unreferenced and destroyed. The documentation states that all objects that directly or indirectly depend on a context that has been destroyed will be left in an inconsistent state and must not be accessed thereafter. Applications (such as Android applications) that need to cleanly destroy and re-create Cogl resources should make sure to manually unref these dependant objects before destroying the context. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 23ce51beba1bb739a224e47614a59327dfbb65af)
2012-09-10 10:26:17 +00:00
* resources that depend on the context so applications. This is to
* help applications control the lifetime a context without us needing to
* introduce special api to handle the breakup of internal circular
* references due to internal resources and caches associated with the
* context.
*
* One a context has been destroyed then all directly or indirectly
* dependant resources will be in an inconsistent state and should not
* be manipulated or queried in any way.
*
* For applications that rely on the operating system to clean up
* resources this policy shouldn't affect them, but for applications
* that need to carefully destroy and re-create Cogl contexts multiple
* times throughout their lifetime (such as Android applications) they
* should be careful to destroy all context dependant resources, such as
* framebuffers or textures etc before unrefing and destroying the
doc: Generate a valid cogl-context.xml The automagic paragraph support of gtk-doc is way too simple to support things like multi-paragraphs <note>s. Let's trick gtk-doc and make it generate a valid docbook snippet for cogl-context. Without this, cogl-context remains absent of the reference documentation, how sad is this?! (cherry picked from commit 606b472d91450e3221da6631020f534892e866a9)
2012-12-29 20:12:13 +00:00
* context.</para></note>
cogl: Adds experimental cogl_context_new() API This adds a new experimental function (you need to define COGL_ENABLE_EXPERIMENTAL_API to access it) which takes us towards being able to have a standalone Cogl API. This is really a minor aesthetic change for now since all the GL context creation code still lives in Clutter but it's a step forward none the less. Since our current designs introduce a CoglDisplay object as something that would be passed to the context constructor this provides a stub cogl-display.h with CoglDisplay typedef. _cogl_context_get_default() which Clutter uses to access the Cogl context has been modified to use cogl_context_new() to initialize the default context. There is one rather nasty hack used in this patch which is that the implementation of cogl_context_new() has to forcibly make the allocated context become the default context because currently all the code in Cogl assumes it can access the context using _COGL_GET_CONTEXT including code used to initialize the context.
2010-11-05 00:00:25 +00:00
*/
Move all types/prototypes from cogl.h -> cogl[1]-context.h So we can get to the point where cogl.h is merely an aggregation of header includes for the 1.x api this moves all the function prototypes and type definitions into a cogl-context.h and a new cogl1-context.h. Ideally no code internally should ever need to include cogl.h as it just represents the public facing header for accessing the 1.x api which should only be used by Clutter. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-17 21:46:39 +00:00
#ifdef COGL_ENABLE_EXPERIMENTAL_API
cogl: Adds experimental cogl_context_new() API This adds a new experimental function (you need to define COGL_ENABLE_EXPERIMENTAL_API to access it) which takes us towards being able to have a standalone Cogl API. This is really a minor aesthetic change for now since all the GL context creation code still lives in Clutter but it's a step forward none the less. Since our current designs introduce a CoglDisplay object as something that would be passed to the context constructor this provides a stub cogl-display.h with CoglDisplay typedef. _cogl_context_get_default() which Clutter uses to access the Cogl context has been modified to use cogl_context_new() to initialize the default context. There is one rather nasty hack used in this patch which is that the implementation of cogl_context_new() has to forcibly make the allocated context become the default context because currently all the code in Cogl assumes it can access the context using _COGL_GET_CONTEXT including code used to initialize the context.
2010-11-05 00:00:25 +00:00
#define COGL_CONTEXT(OBJECT) ((CoglContext *)OBJECT)
Start removing _EXP defines and improves some docs Originally we decided to use #define tricks to rename all experimental symbols so that they had an _EXP suffix so it would be a bit clearer for those wanting to check for ABI changes that they shouldn't worry about these experimental symbols. We feel now though that the defines are a bit more hassle than they are really worth, since they are one extra thing to remember when coding, they make using gdb slightly more awkward since you have to use the real symbol name to set breakpoints and we already have a mechanism for declaring symbols as experimental via gtk-doc that can be used by anyone wanting to check for ABI changes. Instead of just using a script to remove all the #defines we are going to go through them manually because we need to make sure the symbols are marked as unstable via gtk-doc. This patch does a first batch of define removals and in fact some of the symbols didn't have any documentation at all so that needed to be added too. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2011-12-16 15:07:25 +00:00
/**
* cogl_context_new:
* @display: A #CoglDisplay pointer
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
* @error: A CoglError return location.
Start removing _EXP defines and improves some docs Originally we decided to use #define tricks to rename all experimental symbols so that they had an _EXP suffix so it would be a bit clearer for those wanting to check for ABI changes that they shouldn't worry about these experimental symbols. We feel now though that the defines are a bit more hassle than they are really worth, since they are one extra thing to remember when coding, they make using gdb slightly more awkward since you have to use the real symbol name to set breakpoints and we already have a mechanism for declaring symbols as experimental via gtk-doc that can be used by anyone wanting to check for ABI changes. Instead of just using a script to remove all the #defines we are going to go through them manually because we need to make sure the symbols are marked as unstable via gtk-doc. This patch does a first batch of define removals and in fact some of the symbols didn't have any documentation at all so that needed to be added too. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2011-12-16 15:07:25 +00:00
*
* Creates a new #CoglContext which acts as an application sandbox
* for any state objects that are allocated.
*
* Return value: (transfer full): A newly allocated #CoglContext
* Since: 1.8
* Stability: unstable
*/
cogl: Adds experimental cogl_context_new() API This adds a new experimental function (you need to define COGL_ENABLE_EXPERIMENTAL_API to access it) which takes us towards being able to have a standalone Cogl API. This is really a minor aesthetic change for now since all the GL context creation code still lives in Clutter but it's a step forward none the less. Since our current designs introduce a CoglDisplay object as something that would be passed to the context constructor this provides a stub cogl-display.h with CoglDisplay typedef. _cogl_context_get_default() which Clutter uses to access the Cogl context has been modified to use cogl_context_new() to initialize the default context. There is one rather nasty hack used in this patch which is that the implementation of cogl_context_new() has to forcibly make the allocated context become the default context because currently all the code in Cogl assumes it can access the context using _COGL_GET_CONTEXT including code used to initialize the context.
2010-11-05 00:00:25 +00:00
CoglContext *
Moves all GLX code down from Clutter to Cogl This migrates all the GLX window system code down from the Clutter backend code into a Cogl winsys. Moving OpenGL window system binding code down from Clutter into Cogl is the biggest blocker to having Cogl become a standalone 3D graphics library, so this is an important step in that direction.
2010-11-05 12:28:33 +00:00
cogl_context_new (CoglDisplay *display,
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
CoglError **error);
Moves all GLX code down from Clutter to Cogl This migrates all the GLX window system code down from the Clutter backend code into a Cogl winsys. Moving OpenGL window system binding code down from Clutter into Cogl is the biggest blocker to having Cogl become a standalone 3D graphics library, so this is an important step in that direction.
2010-11-05 12:28:33 +00:00
Start removing _EXP defines and improves some docs Originally we decided to use #define tricks to rename all experimental symbols so that they had an _EXP suffix so it would be a bit clearer for those wanting to check for ABI changes that they shouldn't worry about these experimental symbols. We feel now though that the defines are a bit more hassle than they are really worth, since they are one extra thing to remember when coding, they make using gdb slightly more awkward since you have to use the real symbol name to set breakpoints and we already have a mechanism for declaring symbols as experimental via gtk-doc that can be used by anyone wanting to check for ABI changes. Instead of just using a script to remove all the #defines we are going to go through them manually because we need to make sure the symbols are marked as unstable via gtk-doc. This patch does a first batch of define removals and in fact some of the symbols didn't have any documentation at all so that needed to be added too. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2011-12-16 15:07:25 +00:00
/**
* cogl_context_get_display:
* @context: A #CoglContext pointer
*
* Retrieves the #CoglDisplay that is internally associated with the
* given @context. This will return the same #CoglDisplay that was
* passed to cogl_context_new() or if %NULL was passed to
* cogl_context_new() then this function returns a pointer to the
* display that was automatically setup internally.
*
* Return value: (transfer none): The #CoglDisplay associated with the
* given @context.
* Since: 1.8
* Stability: unstable
*/
context: Add an accessor to get display associated with the context https://bugzilla.gnome.org/show_bug.cgi?id=657347 Reviewed-by: Robert Bragg <robert@linux.intel.com>
2011-08-25 16:39:35 +00:00
CoglDisplay *
cogl_context_get_display (CoglContext *context);
Move event polling into CoglRenderer This updates the cogl_poll_ apis to allow dispatching events before we have a CoglContext and to also enables pollfd state to be changed in a more add-hoc way by different Cogl components by replacing the winsys->get_poll_info with _cogl_poll_renderer_add/remove_fd functions and a winsys->get_dispatch_timeout vfunc. One of the intentions here is that applications should be able to run their mainloop before creating a CoglContext to potentially get events relating to CoglOutputs. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 667e58c9cb2662aef5f44e580a9eda42dc8d0176)
2013-04-16 22:46:03 +00:00
/**
* cogl_context_get_renderer:
* @context: A #CoglContext pointer
*
* Retrieves the #CoglRenderer that is internally associated with the
* given @context. This will return the same #CoglRenderer that was
* passed to cogl_display_new() or if %NULL was passed to
* cogl_display_new() or cogl_context_new() then this function returns
* a pointer to the renderer that was automatically connected
* internally.
*
* Return value: (transfer none): The #CoglRenderer associated with the
* given @context.
* Since: 1.16
* Stability: unstable
*/
CoglRenderer *
cogl_context_get_renderer (CoglContext *context);
android: Add support for an EGL/Android winsys The native window type of the EGL/Android winsys is ANativeWinow*. The Android NDK gives you a pointer to this ANativeWindow and you just need to configure that window using the EGLConfig you are choosing when creating the context. This means you have to know the ANativeWindow* window before creating the context. This is solved here by just having a global variable you can set with cogl_android_set_native_window() before creating the context. This is a bit ugly though, and it conceptually belongs to the OnScreen creation to know which ANativeWindow* to use. This would need a "lazy context creation" mechanism, waiting for the user to create the OnScreen to initialize the GL context.
2011-05-16 15:43:30 +00:00
#ifdef COGL_HAS_EGL_PLATFORM_ANDROID_SUPPORT
Start removing _EXP defines and improves some docs Originally we decided to use #define tricks to rename all experimental symbols so that they had an _EXP suffix so it would be a bit clearer for those wanting to check for ABI changes that they shouldn't worry about these experimental symbols. We feel now though that the defines are a bit more hassle than they are really worth, since they are one extra thing to remember when coding, they make using gdb slightly more awkward since you have to use the real symbol name to set breakpoints and we already have a mechanism for declaring symbols as experimental via gtk-doc that can be used by anyone wanting to check for ABI changes. Instead of just using a script to remove all the #defines we are going to go through them manually because we need to make sure the symbols are marked as unstable via gtk-doc. This patch does a first batch of define removals and in fact some of the symbols didn't have any documentation at all so that needed to be added too. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2011-12-16 15:07:25 +00:00
/**
* cogl_android_set_native_window:
* @window: A native Android window
*
* Allows Android applications to inform Cogl of the native window
* that they have been given which Cogl can render too. On Android
* this API must be used before creating a #CoglRenderer, #CoglDisplay
* and #CoglContext.
*
* Since: 1.8
* Stability: unstable
*/
android: Add support for an EGL/Android winsys The native window type of the EGL/Android winsys is ANativeWinow*. The Android NDK gives you a pointer to this ANativeWindow and you just need to configure that window using the EGLConfig you are choosing when creating the context. This means you have to know the ANativeWindow* window before creating the context. This is solved here by just having a global variable you can set with cogl_android_set_native_window() before creating the context. This is a bit ugly though, and it conceptually belongs to the OnScreen creation to know which ANativeWindow* to use. This would need a "lazy context creation" mechanism, waiting for the user to create the OnScreen to initialize the GL context.
2011-05-16 15:43:30 +00:00
void
cogl_android_set_native_window (ANativeWindow *window);
#endif
Add the missing cogl_is_context() function This was missing from the CoglContext header. Reviewed-by: Robert Bragg <robert@linux.intel.com>
2012-01-04 16:55:25 +00:00
/**
* cogl_is_context:
* @object: An object or %NULL
*
* Gets whether the given object references an existing context object.
*
Removes all remaining use of CoglHandle Removing CoglHandle has been an on going goal for quite a long time now and finally this patch removes the last remaining uses of the CoglHandle type and the cogl_handle_ apis. Since the big remaining users of CoglHandle were the cogl_program_ and cogl_shader_ apis which have replaced with the CoglSnippets api this patch removes both of these apis. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 6ed3aaf4be21d605a1ed3176b3ea825933f85cf0) Since the original patch was done after removing deprecated API this back ported patch doesn't affect deprecated API and so actually this cherry-pick doesn't remove all remaining use of CoglHandle as it did for the master branch of Cogl.
2012-04-16 13:14:10 +00:00
* Return value: %TRUE if the @object references a #CoglContext,
Add the missing cogl_is_context() function This was missing from the CoglContext header. Reviewed-by: Robert Bragg <robert@linux.intel.com>
2012-01-04 16:55:25 +00:00
* %FALSE otherwise
*
* Since: 1.10
* Stability: Unstable
*/
Switch use of primitive glib types to c99 equivalents The coding style has for a long time said to avoid using redundant glib data types such as gint or gchar etc because we feel that they make the code look unnecessarily foreign to developers coming from outside of the Gnome developer community. Note: When we tried to find the historical rationale for the types we just found that they were apparently only added for consistent syntax highlighting which didn't seem that compelling. Up until now we have been continuing to use some of the platform specific type such as gint{8,16,32,64} and gsize but this patch switches us over to using the standard c99 equivalents instead so we can further ensure that our code looks familiar to the widest range of C developers who might potentially contribute to Cogl. So instead of using the gint{8,16,32,64} and guint{8,16,32,64} types this switches all Cogl code to instead use the int{8,16,32,64}_t and uint{8,16,32,64}_t c99 types instead. Instead of gsize we now use size_t For now we are not going to use the c99 _Bool type and instead we have introduced a new CoglBool type to use instead of gboolean. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 5967dad2400d32ca6319cef6cb572e81bf2c15f0)
2012-04-16 20:56:40 +00:00
CoglBool
Add the missing cogl_is_context() function This was missing from the CoglContext header. Reviewed-by: Robert Bragg <robert@linux.intel.com>
2012-01-04 16:55:25 +00:00
cogl_is_context (void *object);
Move all types/prototypes from cogl.h -> cogl[1]-context.h So we can get to the point where cogl.h is merely an aggregation of header includes for the 1.x api this moves all the function prototypes and type definitions into a cogl-context.h and a new cogl1-context.h. Ideally no code internally should ever need to include cogl.h as it just represents the public facing header for accessing the 1.x api which should only be used by Clutter. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-17 21:46:39 +00:00
#endif /* COGL_ENABLE_EXPERIMENTAL_2_0_API */
context: Enable new feature testing on COGL_ENABLE_EXPERIMENTAL_API The 2.0 API for querying features (cogl_has_feature etc) does not conflict with the old 1.0 API (cogl_features_available) so we might as well enable it when the experimental API is requested without requesting the 2.0-only API. Reviewed-by: Robert Bragg <robert@linux.intel.com>
2012-03-12 17:06:46 +00:00
/* XXX: not guarded by the EXPERIMENTAL_API defines to avoid
Move all types/prototypes from cogl.h -> cogl[1]-context.h So we can get to the point where cogl.h is merely an aggregation of header includes for the 1.x api this moves all the function prototypes and type definitions into a cogl-context.h and a new cogl1-context.h. Ideally no code internally should ever need to include cogl.h as it just represents the public facing header for accessing the 1.x api which should only be used by Clutter. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-17 21:46:39 +00:00
* 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
doc: Fix the remaining broken internal cross-references Symbols changed names, %1 makes gtk-doc sad and some referenced symbols were missing in the -sections.txt file. (cherry picked from commit c12919c321186ac7b223bc4f82c588ca2f199d67)
2012-12-31 23:26:11 +00:00
* %COGL_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE respectively.
Move all types/prototypes from cogl.h -> cogl[1]-context.h So we can get to the point where cogl.h is merely an aggregation of header includes for the 1.x api this moves all the function prototypes and type definitions into a cogl-context.h and a new cogl1-context.h. Ideally no code internally should ever need to include cogl.h as it just represents the public facing header for accessing the 1.x api which should only be used by Clutter. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-17 21:46:39 +00:00
* @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
doc: Fix the remaining broken internal cross-references Symbols changed names, %1 makes gtk-doc sad and some referenced symbols were missing in the -sections.txt file. (cherry picked from commit c12919c321186ac7b223bc4f82c588ca2f199d67)
2012-12-31 23:26:11 +00:00
* %COGL_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE are supported by the
Move all types/prototypes from cogl.h -> cogl[1]-context.h So we can get to the point where cogl.h is merely an aggregation of header includes for the 1.x api this moves all the function prototypes and type definitions into a cogl-context.h and a new cogl1-context.h. Ideally no code internally should ever need to include cogl.h as it just represents the public facing header for accessing the 1.x api which should only be used by Clutter. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-17 21:46:39 +00:00
* 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
doc: Fix the remaining broken internal cross-references Symbols changed names, %1 makes gtk-doc sad and some referenced symbols were missing in the -sections.txt file. (cherry picked from commit c12919c321186ac7b223bc4f82c588ca2f199d67)
2012-12-31 23:26:11 +00:00
* %COGL_INDICES_TYPE_UNSIGNED_INT is supported in
Move all types/prototypes from cogl.h -> cogl[1]-context.h So we can get to the point where cogl.h is merely an aggregation of header includes for the 1.x api this moves all the function prototypes and type definitions into a cogl-context.h and a new cogl1-context.h. Ideally no code internally should ever need to include cogl.h as it just represents the public facing header for accessing the 1.x api which should only be used by Clutter. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-17 21:46:39 +00:00
* 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.
Add support for per-vertex point sizes This adds a new function to enable per-vertex point size on a pipeline. This can be set with cogl_pipeline_set_per_vertex_point_size(). Once enabled the point size can be set either by drawing with an attribute named 'cogl_point_size_in' or by writing to the 'cogl_point_size_out' builtin from a snippet. There is a feature flag which must be checked for before using per-vertex point sizes. This will only be set on GL >= 2.0 or on GLES 2.0. GL will only let you set a per-vertex point size from GLSL by writing to gl_PointSize. This is only available in GL2 and not in the older GLSL extensions. The per-vertex point size has its own pipeline state flag so that it can be part of the state that affects vertex shader generation. Having to enable the per vertex point size with a separate function is a bit awkward. Ideally it would work like the color attribute where you can just set it for every vertex in your primitive with cogl_pipeline_set_color or set it per-vertex by just using the attribute. This is harder to get working with the point size because we need to generate a different vertex shader depending on what attributes are bound. I think if we wanted to make this work transparently we would still want to internally have a pipeline property describing whether the shader was generated with per-vertex support so that it would work with the shader cache correctly. Potentially we could make the per-vertex property internal and automatically make a weak pipeline whenever the attribute is bound. However we would then also need to automatically detect when an application is writing to cogl_point_size_out from a snippet. Reviewed-by: Robert Bragg <robert@linux.intel.com> (cherry picked from commit 8495d9c1c15ce389885a9356d965eabd97758115) Conflicts: cogl/cogl-context.c cogl/cogl-pipeline-private.h cogl/cogl-pipeline.c cogl/cogl-private.h cogl/driver/gl/cogl-pipeline-progend-fixed.c cogl/driver/gl/gl/cogl-pipeline-progend-fixed-arbfp.c
2012-11-08 16:56:02 +00:00
* @COGL_FEATURE_ID_PER_VERTEX_POINT_SIZE: Whether cogl_point_size_in
* can be used as an attribute to set a per-vertex point size.
Move all types/prototypes from cogl.h -> cogl[1]-context.h So we can get to the point where cogl.h is merely an aggregation of header includes for the 1.x api this moves all the function prototypes and type definitions into a cogl-context.h and a new cogl1-context.h. Ideally no code internally should ever need to include cogl.h as it just represents the public facing header for accessing the 1.x api which should only be used by Clutter. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-17 21:46:39 +00:00
* @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.
* @COGL_FEATURE_ID_SWAP_BUFFERS_EVENT:
* Available if the window system supports reporting an event
* for swap buffer completions.
Adds initial GLES2 integration support This makes it possible to integrate existing GLES2 code with applications using Cogl as the rendering api. Currently all GLES2 usage is handled with separate GLES2 contexts to ensure that GLES2 api usage doesn't interfere with Cogl's own use of OpenGL[ES]. The api has been designed though so we can provide tighter integration later. The api would allow us to support GLES2 virtualized on top of an OpenGL/GLX driver as well as GLES2 virtualized on the core rendering api of Cogl itself. Virtualizing the GLES2 support on Cogl will allow us to take advantage of Cogl debugging facilities as well as let us optimize the cost of allocating multiple GLES2 contexts and switching between them which can both be very expensive with many drivers. As as a side effect of this patch Cogl can also now be used as a portable window system binding API for GLES2 as an alternative to EGL. Parts of this patch are based on work done by Tomeu Vizoso <tomeu.vizoso@collabora.com> who did the first iteration of adding GLES2 API support to Cogl so that WebGL support could be added to webkit-clutter. This patch adds a very minimal cogl-gles2-context example that shows how to create a gles2 context, clear the screen to a random color and also draw a triangle with the cogl api. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 4bb6eff3dbd50d8fef7d6bdbed55c5aaa70036a8)
2012-03-06 03:21:30 +00:00
* @COGL_FEATURE_ID_GLES2_CONTEXT: Whether creating new GLES2 contexts is
* suported.
framebuffer: Support texture based depth buffers This commit introduces some new framebuffer api to be able to enable texture based depth buffers for a framebuffer (currently only supported for offscreen framebuffers) and once allocated to be able to retrieve the depth buffer as a texture for further usage, say, to implement shadow mapping. The API works as follow: * Before the framebuffer is allocated, you can request that a depth texture is created with cogl_framebuffer_set_depth_texture_enabled() * cogl_framebuffer_get_depth_texture() can then be used to grab a CoglTexture once the framebuffer has been allocated.
2012-05-23 17:19:29 +00:00
* @COGL_FEATURE_ID_DEPTH_TEXTURE: Whether #CoglFramebuffer support rendering
* the depth buffer to a texture.
onscreen: Add CoglFrameInfo and _add_frame_callback() api Add a CoglFrameInfo object that tracks timing information for frames that are drawn. We track a frame counter and frame timing information for each CoglOnscreen. Internally a CoglFrameInfo is automatically created for each frame, delimited by cogl_onscreen_swap_buffers() or cogl_onscreen_swap_region() calls. CoglFrameInfos are delivered to applications via frame event callbacks that can be registered with a new cogl_onscreen_add_frame_callback() api. Two initial event types (dispatched on all platforms) have been defined; a _SYNC event used for throttling the frame rate of applications and a _COMPLETE event used so signify the end of a frame. Note: This new _add_frame_callback() api makes the cogl_onscreen_add_swap_complete_callback() api redundant and so it should be considered deprecated. Since the _add_swap_complete_callback() api is still experimental api, we will be looking to quickly migrate users to the new api so we can remove the old api. Reviewed-by: Robert Bragg <robert@linux.intel.com> (cherry picked from commit 700401667db2522045e4623d78797b17f9184501)
2012-11-12 16:58:10 +00:00
* @COGL_FEATURE_ID_PRESENTATION_TIME: Whether frame presentation
* time stamps will be recorded in #CoglFrameInfo objects.
Move all types/prototypes from cogl.h -> cogl[1]-context.h So we can get to the point where cogl.h is merely an aggregation of header includes for the 1.x api this moves all the function prototypes and type definitions into a cogl-context.h and a new cogl1-context.h. Ideally no code internally should ever need to include cogl.h as it just represents the public facing header for accessing the 1.x api which should only be used by Clutter. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-17 21:46:39 +00:00
*
* 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,
COGL_FEATURE_ID_SWAP_BUFFERS_EVENT,
Adds initial GLES2 integration support This makes it possible to integrate existing GLES2 code with applications using Cogl as the rendering api. Currently all GLES2 usage is handled with separate GLES2 contexts to ensure that GLES2 api usage doesn't interfere with Cogl's own use of OpenGL[ES]. The api has been designed though so we can provide tighter integration later. The api would allow us to support GLES2 virtualized on top of an OpenGL/GLX driver as well as GLES2 virtualized on the core rendering api of Cogl itself. Virtualizing the GLES2 support on Cogl will allow us to take advantage of Cogl debugging facilities as well as let us optimize the cost of allocating multiple GLES2 contexts and switching between them which can both be very expensive with many drivers. As as a side effect of this patch Cogl can also now be used as a portable window system binding API for GLES2 as an alternative to EGL. Parts of this patch are based on work done by Tomeu Vizoso <tomeu.vizoso@collabora.com> who did the first iteration of adding GLES2 API support to Cogl so that WebGL support could be added to webkit-clutter. This patch adds a very minimal cogl-gles2-context example that shows how to create a gles2 context, clear the screen to a random color and also draw a triangle with the cogl api. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 4bb6eff3dbd50d8fef7d6bdbed55c5aaa70036a8)
2012-03-06 03:21:30 +00:00
COGL_FEATURE_ID_GLES2_CONTEXT,
framebuffer: Support texture based depth buffers This commit introduces some new framebuffer api to be able to enable texture based depth buffers for a framebuffer (currently only supported for offscreen framebuffers) and once allocated to be able to retrieve the depth buffer as a texture for further usage, say, to implement shadow mapping. The API works as follow: * Before the framebuffer is allocated, you can request that a depth texture is created with cogl_framebuffer_set_depth_texture_enabled() * cogl_framebuffer_get_depth_texture() can then be used to grab a CoglTexture once the framebuffer has been allocated.
2012-05-23 17:19:29 +00:00
COGL_FEATURE_ID_DEPTH_TEXTURE,
onscreen: Add CoglFrameInfo and _add_frame_callback() api Add a CoglFrameInfo object that tracks timing information for frames that are drawn. We track a frame counter and frame timing information for each CoglOnscreen. Internally a CoglFrameInfo is automatically created for each frame, delimited by cogl_onscreen_swap_buffers() or cogl_onscreen_swap_region() calls. CoglFrameInfos are delivered to applications via frame event callbacks that can be registered with a new cogl_onscreen_add_frame_callback() api. Two initial event types (dispatched on all platforms) have been defined; a _SYNC event used for throttling the frame rate of applications and a _COMPLETE event used so signify the end of a frame. Note: This new _add_frame_callback() api makes the cogl_onscreen_add_swap_complete_callback() api redundant and so it should be considered deprecated. Since the _add_swap_complete_callback() api is still experimental api, we will be looking to quickly migrate users to the new api so we can remove the old api. Reviewed-by: Robert Bragg <robert@linux.intel.com> (cherry picked from commit 700401667db2522045e4623d78797b17f9184501)
2012-11-12 16:58:10 +00:00
COGL_FEATURE_ID_PRESENTATION_TIME,
Add fence API cogl_framebuffer_add_fence creates a synchronisation fence, which will invoke a user-specified callback when the GPU has finished executing all commands provided to it up to that point in time. Support is currently provided for GL 3.x's GL_ARB_sync extension, and EGL's EGL_KHR_fence_sync (when used with OpenGL ES). Signed-off-by: Daniel Stone <daniel@fooishbar.org> Reviewed-by: Neil Roberts <neil@linux.intel.com> Reviewed-by: Robert Bragg <robert@linux.intel.com> https://bugzilla.gnome.org/show_bug.cgi?id=691752 (cherry picked from commit e6d37470da9294adc1554c0a8c91aa2af560ed9f)
2013-01-11 01:13:34 +00:00
COGL_FEATURE_ID_FENCE,
Add support for per-vertex point sizes This adds a new function to enable per-vertex point size on a pipeline. This can be set with cogl_pipeline_set_per_vertex_point_size(). Once enabled the point size can be set either by drawing with an attribute named 'cogl_point_size_in' or by writing to the 'cogl_point_size_out' builtin from a snippet. There is a feature flag which must be checked for before using per-vertex point sizes. This will only be set on GL >= 2.0 or on GLES 2.0. GL will only let you set a per-vertex point size from GLSL by writing to gl_PointSize. This is only available in GL2 and not in the older GLSL extensions. The per-vertex point size has its own pipeline state flag so that it can be part of the state that affects vertex shader generation. Having to enable the per vertex point size with a separate function is a bit awkward. Ideally it would work like the color attribute where you can just set it for every vertex in your primitive with cogl_pipeline_set_color or set it per-vertex by just using the attribute. This is harder to get working with the point size because we need to generate a different vertex shader depending on what attributes are bound. I think if we wanted to make this work transparently we would still want to internally have a pipeline property describing whether the shader was generated with per-vertex support so that it would work with the shader cache correctly. Potentially we could make the per-vertex property internal and automatically make a weak pipeline whenever the attribute is bound. However we would then also need to automatically detect when an application is writing to cogl_point_size_out from a snippet. Reviewed-by: Robert Bragg <robert@linux.intel.com> (cherry picked from commit 8495d9c1c15ce389885a9356d965eabd97758115) Conflicts: cogl/cogl-context.c cogl/cogl-pipeline-private.h cogl/cogl-pipeline.c cogl/cogl-private.h cogl/driver/gl/cogl-pipeline-progend-fixed.c cogl/driver/gl/gl/cogl-pipeline-progend-fixed-arbfp.c
2012-11-08 16:56:02 +00:00
COGL_FEATURE_ID_PER_VERTEX_POINT_SIZE,
Move all types/prototypes from cogl.h -> cogl[1]-context.h So we can get to the point where cogl.h is merely an aggregation of header includes for the 1.x api this moves all the function prototypes and type definitions into a cogl-context.h and a new cogl1-context.h. Ideally no code internally should ever need to include cogl.h as it just represents the public facing header for accessing the 1.x api which should only be used by Clutter. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-17 21:46:39 +00:00
context: Re-add /<* private *>/ for _COGL_N_FEATURE_IDS Turns out gtk-doc really needs 'private' and glib-mkenums needs 'skip'. So let's have both. Reviewed-by: Robert Bragg <robert@linux.intel.com> (cherry picked from commit e51206b2a9c9a582ac83fb71290524c99a8dbbb6)
2012-10-08 14:04:33 +00:00
/*< private >*/
context: glib-mkenums chokes on /*< private >*/ but supports /*< skip >*/ The private option is really part of gtk-doc, glib-mkenums does not support it. Use skip instead. Reviewed-by: Robert Bragg <robert@linux.intel.com> (cherry picked from commit 015c36af27a8ce68d60f8aab6a10acdc48c5f38c)
2012-10-06 00:25:27 +00:00
_COGL_N_FEATURE_IDS /*< skip >*/
Move all types/prototypes from cogl.h -> cogl[1]-context.h So we can get to the point where cogl.h is merely an aggregation of header includes for the 1.x api this moves all the function prototypes and type definitions into a cogl-context.h and a new cogl1-context.h. Ideally no code internally should ever need to include cogl.h as it just represents the public facing header for accessing the 1.x api which should only be used by Clutter. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-17 21:46:39 +00:00
} CoglFeatureID;
context: Enable new feature testing on COGL_ENABLE_EXPERIMENTAL_API The 2.0 API for querying features (cogl_has_feature etc) does not conflict with the old 1.0 API (cogl_features_available) so we might as well enable it when the experimental API is requested without requesting the 2.0-only API. Reviewed-by: Robert Bragg <robert@linux.intel.com>
2012-03-12 17:06:46 +00:00
#ifdef COGL_ENABLE_EXPERIMENTAL_API
Move all types/prototypes from cogl.h -> cogl[1]-context.h So we can get to the point where cogl.h is merely an aggregation of header includes for the 1.x api this moves all the function prototypes and type definitions into a cogl-context.h and a new cogl1-context.h. Ideally no code internally should ever need to include cogl.h as it just represents the public facing header for accessing the 1.x api which should only be used by Clutter. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-17 21:46:39 +00:00
/**
* 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
*/
Switch use of primitive glib types to c99 equivalents The coding style has for a long time said to avoid using redundant glib data types such as gint or gchar etc because we feel that they make the code look unnecessarily foreign to developers coming from outside of the Gnome developer community. Note: When we tried to find the historical rationale for the types we just found that they were apparently only added for consistent syntax highlighting which didn't seem that compelling. Up until now we have been continuing to use some of the platform specific type such as gint{8,16,32,64} and gsize but this patch switches us over to using the standard c99 equivalents instead so we can further ensure that our code looks familiar to the widest range of C developers who might potentially contribute to Cogl. So instead of using the gint{8,16,32,64} and guint{8,16,32,64} types this switches all Cogl code to instead use the int{8,16,32,64}_t and uint{8,16,32,64}_t c99 types instead. Instead of gsize we now use size_t For now we are not going to use the c99 _Bool type and instead we have introduced a new CoglBool type to use instead of gboolean. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 5967dad2400d32ca6319cef6cb572e81bf2c15f0)
2012-04-16 20:56:40 +00:00
CoglBool
Move all types/prototypes from cogl.h -> cogl[1]-context.h So we can get to the point where cogl.h is merely an aggregation of header includes for the 1.x api this moves all the function prototypes and type definitions into a cogl-context.h and a new cogl1-context.h. Ideally no code internally should ever need to include cogl.h as it just represents the public facing header for accessing the 1.x api which should only be used by Clutter. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-17 21:46:39 +00:00
cogl_has_feature (CoglContext *context, CoglFeatureID feature);
/**
* cogl_has_features:
* @context: A #CoglContext pointer
* @...: A 0 terminated list of CoglFeatureID<!-- -->s
*
* 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
*/
Switch use of primitive glib types to c99 equivalents The coding style has for a long time said to avoid using redundant glib data types such as gint or gchar etc because we feel that they make the code look unnecessarily foreign to developers coming from outside of the Gnome developer community. Note: When we tried to find the historical rationale for the types we just found that they were apparently only added for consistent syntax highlighting which didn't seem that compelling. Up until now we have been continuing to use some of the platform specific type such as gint{8,16,32,64} and gsize but this patch switches us over to using the standard c99 equivalents instead so we can further ensure that our code looks familiar to the widest range of C developers who might potentially contribute to Cogl. So instead of using the gint{8,16,32,64} and guint{8,16,32,64} types this switches all Cogl code to instead use the int{8,16,32,64}_t and uint{8,16,32,64}_t c99 types instead. Instead of gsize we now use size_t For now we are not going to use the c99 _Bool type and instead we have introduced a new CoglBool type to use instead of gboolean. Reviewed-by: Neil Roberts <neil@linux.intel.com> (cherry picked from commit 5967dad2400d32ca6319cef6cb572e81bf2c15f0)
2012-04-16 20:56:40 +00:00
CoglBool
Move all types/prototypes from cogl.h -> cogl[1]-context.h So we can get to the point where cogl.h is merely an aggregation of header includes for the 1.x api this moves all the function prototypes and type definitions into a cogl-context.h and a new cogl1-context.h. Ideally no code internally should ever need to include cogl.h as it just represents the public facing header for accessing the 1.x api which should only be used by Clutter. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-17 21:46:39 +00:00
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: 0.10
* Stability: unstable
*/
typedef void (*CoglFeatureCallback) (CoglFeatureID feature, void *user_data);
/**
* 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);
Add cogl_get_clock_time() Add an API to get the current time in the time system that Cogl is reporting timestamps. This is to be used to convert timestamps into a different time system. Reviewed-by: Robert Bragg <robert@linux.intel.com> (cherry picked from commit 9f3735a0c37adcfcffa485f81699b53a4cc0caf8)
2013-01-28 17:22:57 +00:00
/**
* cogl_get_clock_time:
* @context: a #CoglContext pointer
*
* Returns the current time value from Cogl's internal clock. This
* clock is used for measuring times such as the presentation time
* in a #CoglFrameInfo.
*
* This method is meant for converting timestamps retrieved from Cogl
* to other time systems, and is not meant to be used as a standalone
* timing system. For that reason, if this function is called without
* having retrieved a valid (non-zero) timestamp from Cogl first, it
* may return 0 to indicate that Cogl has no active internal clock.
*
* Return value: the time value for the Cogl clock, in nanoseconds
* from an arbitrary point in time, or 0 if Cogl doesn't have an
* active internal clock.
* Since: 1.14
* Stability: unstable
*/
int64_t
cogl_get_clock_time (CoglContext *context);
context: Enable new feature testing on COGL_ENABLE_EXPERIMENTAL_API The 2.0 API for querying features (cogl_has_feature etc) does not conflict with the old 1.0 API (cogl_features_available) so we might as well enable it when the experimental API is requested without requesting the 2.0-only API. Reviewed-by: Robert Bragg <robert@linux.intel.com>
2012-03-12 17:06:46 +00:00
#endif /* COGL_ENABLE_EXPERIMENTAL_API */
Move all types/prototypes from cogl.h -> cogl[1]-context.h So we can get to the point where cogl.h is merely an aggregation of header includes for the 1.x api this moves all the function prototypes and type definitions into a cogl-context.h and a new cogl1-context.h. Ideally no code internally should ever need to include cogl.h as it just represents the public facing header for accessing the 1.x api which should only be used by Clutter. Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-17 21:46:39 +00:00
Fixes for --disable-glib This fixes some problems which were stopping --disable-glib from working properly: • A lot of the public headers were including glib.h. This shouldn't be necessary because the API doesn't expose any glib types. Otherwise any apps would require glib in order to get the header. • The public headers were using G_BEGIN_DECLS. There is now a replacement macro called COGL_BEGIN_DECLS which is defined in cogl-types.h. • A similar fix has been done for G_GNUC_NULL_TERMINATED and G_GNUC_DEPRECATED. • The CFLAGS were not including $(builddir)/deps/glib which was preventing it finding the generated glibconfig.h when building out of tree. Reviewed-by: Robert Bragg <robert@linux.intel.com> (cherry picked from commit 4138b3141c2f39cddaea3d72bfc04342ed5092d0)
2012-11-22 18:01:10 +00:00
COGL_END_DECLS
cogl: Adds experimental cogl_context_new() API This adds a new experimental function (you need to define COGL_ENABLE_EXPERIMENTAL_API to access it) which takes us towards being able to have a standalone Cogl API. This is really a minor aesthetic change for now since all the GL context creation code still lives in Clutter but it's a step forward none the less. Since our current designs introduce a CoglDisplay object as something that would be passed to the context constructor this provides a stub cogl-display.h with CoglDisplay typedef. _cogl_context_get_default() which Clutter uses to access the Cogl context has been modified to use cogl_context_new() to initialize the default context. There is one rather nasty hack used in this patch which is that the implementation of cogl_context_new() has to forcibly make the allocated context become the default context because currently all the code in Cogl assumes it can access the context using _COGL_GET_CONTEXT including code used to initialize the context.
2010-11-05 00:00:25 +00:00
#endif /* __COGL_CONTEXT_H__ */
Reference in New Issue Copy Permalink