This adds much more comprehensive support for gobject-introspection
based bindings by registering all objects as fundamental types that
inherit from CoglObject, and all structs as boxed types.
Co-Author: Robert Bragg <robert@linux.intel.com>
Reviewed-by: Neil Roberts <neil@linux.intel.com>
Since the Cogl 1.18 branch is actively maintained in parallel with the
master branch; this is a counter part to commit 1b83ef938fc16b which
re-licensed the master branch to use the MIT license.
This re-licensing is a follow up to the proposal that was sent to the
Cogl mailing list:
http://lists.freedesktop.org/archives/cogl/2013-December/001465.html
Note: there was a copyright assignment policy in place for Clutter (and
therefore Cogl which was part of Clutter at the time) until the 11th of
June 2010 and so we only checked the details after that point (commit
0bbf50f905)
For each file, authors were identified via this Git command:
$ git blame -p -C -C -C20 -M -M10 0bbf50f905..HEAD
We received blanket approvals for re-licensing all Red Hat and Collabora
contributions which reduced how many people needed to be contacted
individually:
- http://lists.freedesktop.org/archives/cogl/2013-December/001470.html
- http://lists.freedesktop.org/archives/cogl/2014-January/001536.html
Individual approval requests were sent to all the other identified authors
who all confirmed the re-license on the Cogl mailinglist:
http://lists.freedesktop.org/archives/cogl/2014-January
As well as updating the copyright header in all sources files, the
COPYING file has been updated to reflect the license change and also
document the other licenses used in Cogl such as the SGI Free Software
License B, version 2.0 and the 3-clause BSD license.
This patch was not simply cherry-picked from master; but the same
methodology was used to check the source files.
Texture allocation is now consistently handled lazily such that the
internal format can now be controlled using
cogl_texture_set_components() and cogl_texture_set_premultiplied()
before allocating the texture with cogl_texture_allocate(). This means
that the internal_format arguments to texture constructors are now
redundant and since most of the texture constructors now can't ever fail
the error arguments are also redundant. This now means we no longer
use CoglPixelFormat in the public api for describing the internal format
of textures which had been bad solution originally due to how specific
CoglPixelFormat is which is missleading when we don't support such
explicit control over the internal format.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
(cherry picked from commit 99a53c82e9ab0a1e5ee35941bf83dc334b1fbe87)
Note: there are numerous API changes for functions currently marked
as 'unstable' which we don't think are in use by anyone depending on
a stable 1.x api. Compared to the original patch though this avoids
changing the cogl_texture_rectangle_new_with_size() api which we know
is used by Mutter.
This introduces the internal idea of texture loaders that track the
state for loading and allocating a texture. This defers a lot more work
until the texture is allocated.
There are several intentions to this change:
- provides a means for extending how textures are allocated without
requiring all the parameters to be supplied in a single _texture_new()
function call.
- allow us to remove the internal_format argument from all
_texture_new() apis since using CoglPixelFormat is bad way of
expressing the internal format constraints because it is too specific.
For now the internal_format arguments haven't actually been removed
but this patch does introduce replacement apis for controlling the
internal format:
cogl_texture_set_components() lets you specify what components your
texture needs when it is allocated.
cogl_texture_set_premultiplied() lets you specify whether a texture
data should be interpreted as premultiplied or not.
- Enable us to support asynchronous texture loading + allocation in the
future.
Of note, the _new_from_data() texture constructors all continue to
allocate textures immediately so that existing code doesn't need to be
adapted to manage the lifetime of the data being uploaded.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
(cherry picked from commit 6a83de9ef4210f380a31f410797447b365a8d02c)
Note: Compared to the original patch, the ->premultipled state for
textures isn't forced to be %TRUE in _cogl_texture_init since that
effectively ignores the users explicitly given internal_format which was
a mistake and on master that change should have been made in the patch
that followed. The gtk-doc comments for cogl_texture_set_premultiplied()
and cogl_texture_set_components() have also been updated in-line with
this fix.
This adds a cogl_texture_2d_new_from_file() api since we are planning to
remove cogl_texture_new_from_file() but don't want to loose the
convenience it had.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
(cherry picked from commit 10e91aa513123ed277a8d45976f8d75445d7dc9c)
Consistent with how we lazily allocate framebuffers this patch allows us
to instantiate textures but still specify constraints and requirements
before allocating storage so that we can be sure to allocate the most
appropriate/efficient storage.
This adds a cogl_texture_allocate() function that is analogous to
cogl_framebuffer_allocate() which can optionally be called to explicitly
allocate storage and catch any errors. If this function isn't used
explicitly then Cogl will implicitly ensure textures are allocated
before the storage is needed.
It is generally recommended to rely on lazy storage allocation or at
least perform explicit allocation as late as possible so Cogl can be
fully informed about the best way to allocate storage.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
(cherry picked from commit 1fa7c0f10a8a03043e3c75cb079a49625df098b7)
Note: This reverts the cogl_texture_rectangle_new_with_size API change
that dropped the CoglError argument and keeps the semantics of
allocating the texture immediately. This is because Mutter currently
uses this API so we will probably look at updating this later once
we have a corresponding Mutter patch prepared. The other API changes
were kept since they only affected experimental api.
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)
This factors out all of the OpenGL specific code in cogl-texture-2d.c
into cogl-texture-2d-gl.c and where necessary adds indirection through
the CoglDriver vtable so that we can eventually start to experiment with
non-OpenGL backends for Cogl.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
(cherry picked from commit ec57588671696bbe7ce714bdfe7324236146c9c0)
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.
To delimit which symbols were considered experimental we used to use
some preprocessor defines to gives experimental symbols an _EXP suffix
so that anyone monitoring the ABI for changes would easily be able to
discount changes made to clearly experimental functions.
These days we simply rely on the gtk-doc "Stability: unstable"
annotation to serve this purpose because changing the actual symbol name
made it slightly more awkward to debug Cogl using GDB and was an extra
mechanical step we decided we could do without.
This patch removes the last remaining _EXP suffix defines in Cogl
(cherry picked from commit 5a1c4a979e00accd492097cfb8f6a8d0fd8331bc)
The header guard for cogl-texture-2d-private.h was
__COGL_TEXTURE_2D_H. This would conflict with the header guard for
cogl-texture-2d.h except there a small typo ('TEXURE') so that it
was subtly different. This fixes them both to make more sense.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
(cherry picked from commit 222ec4d009973cb62020a9da05f72dea41460b33)
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)
This adds public constructors which take a CoglBitmap to all primitive
texture types. This constructor should be considered the canonical
constructor for initializing the texture with data because it should
be possible to wrap any type of data in a CoglBitmap. Having at least
this single constructor avoids the need to have an explosion of
constructors such as new_from_data, new_from_pixel_buffer and
new_from_file etc.
The already available internal bitmap constructor for CoglTexture2D
has had its flags parameter removed under the assumption that flags do
not make sense for primitive textures. The meta constructor
cogl_texture_new_from_bitmap now just explicitly calls set_auto_mipmap
after constructing the texture depending on the value of the
COGL_TEXTURE_NO_AUTO_MIPMAP flag.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
Because the wayland-client-protocol.h header defines symbols that
collide with the wayland-server-protocol.h header we allow applications
to explicitly ensure that they are only including one at a time by
exposing corresponding <cogl/cogl-wayland-client.h> and
<cogl/cogl-wayland-server.h> headers. This also adds a missing guard to
cogl-texture-2d.h that it isn't included directly.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
Currently features are represented as bits in a 32bit mask so we
obviously can't have more than 32 features with that approach. The new
approach is to use the COGL_FLAGS_ macros which lets us handle bitmasks
without a size limit and we change the public api to accept individual
feature enums instead of a mask. This way there is no limit on the
number of features we can add to Cogl.
Instead of using cogl_features_available() there is a new
cogl_has_feature() function and for checking multiple features there is
cogl_has_features() which takes a zero terminated vararg list of
features.
In addition to being able to check for individual features this also
adds a way to query all the features currently available via
cogl_foreach_feature() which will call a callback for each feature.
Since the new functions take an explicit context pointer there is also
no longer any ambiguity over when users can first start to query
features.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
All our experimental Cogl symbols have a corresponding #define to add
"_EXP" to the end of the symbol name, but those defines are often
positioned right after the corresponding gtk-doc comment and before
the symbol definition which means the generated documentation ends up
refering to the define and not the real definition. This tidies up
cogl-texture-2d.h and moves all the defines to be be before the gtk-doc
comments.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
This adds internal API to be able to wrap a wayland buffer as a
CoglTexture2D. There is a --enable-wayland-egl-server option to decide
if Cogl should support this feature and potentially any EGL based winsys
could support this through the EGL_KHR_image_base and
EGL_WL_bind_display extensions.
This exposes a CoglTexture2D typedef and adds the following experimental
API:
cogl_is_texture_2d
cogl_texture_2d_new_with_size
cogl_texture_2d_new_from_data
cogl_texture_2d_new_from_foreign
Since this is experimental API you need to define
COGL_ENABLE_EXPERIMENTAL_API before including cogl.h.
Note: With these new entrypoints we now expect a CoglContext pointer to
be passed in, instead of assuming there is a default context. The aim is
that for Cogl 2.0 we won't have a default context so this is a step in
that direction.
