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.
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.
cogl_framebuffer_set_{projection,modelview}_matrix don't need to read
from the matrix argument so they should probably take a const pointer.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
(cherry picked from commit 710d6af053aca97935b54f9ff68858ef51f4482b)
This adds the following new functions to apply a rotation described by
a euler or a quaternion to either a CoglMatrix or directly to the
modelview stack of a framebuffer:
cogl_matrix_rotate_quaternion
cogl_matrix_rotate_euler
cogl_framebuffer_rotate_quaternion
cogl_framebuffer_rotate_euler
The direct framebuffer functions have corresponding functions in the
CoglMatrixStack to store an entry describing the rotation.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
(cherry picked from commit 5064315678b496395e1d01f266f322d73e55e324)
The existing functions for stroking and filling a path depend on the
global framebuffer and source stacks. These are now replaced with
cogl_framebuffer_{stroke,fill}_path which get explicitly passed the
framebuffer and pipeline.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
(cherry picked from commit 713a8f8160bc5884b091c69eb7a84b069e0950e6)
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)
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>
• The documentation for the framebuffer and texture interfaces had a
mis-matching open and close <note> tag so DocBook got upset and the
whole documentation disappeared.
• A lot of symbols from the cogl_framebuffer_* interface were missing
from the cogl-2.0-experimental-sections.txt file.
• cogl_framebuffer_frustum had the wrong version in its Since tag:
Reviewed-by: Robert Bragg <robert@linux.intel.com>
This adds experimental 2.0 api replacements for the cogl_rectangle[_*]
functions that don't depend on having a current pipeline set on the
context via cogl_{set,push}_source() or having a current framebuffer set
on the context via cogl_push_framebuffer(). The aim for 2.0 is to switch
away from having a statefull context that affects drawing to having
framebuffer drawing apis that are explicitly passed a framebuffer and
pipeline.
To test this change several of the conformance tests were updated to use
this api instead of cogl_rectangle and
cogl_rectangle_with_texture_coords. Since it's quite laborious going
through all of the conformance tests the opportunity was taken to make
other clean ups in the conformance tests to replace other uses of
1.x api with experimental 2.0 api so long as that didn't affect what was
being tested.
This was causing the DocBook for the documentation to be invalid so
all of the framebuffer documentation disappeared.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
This adds a public convenience wrapper around
cogl_framebuffer_read_pixels_into_bitmap which allocates a temporary
CoglBitmap to read into the application's own buffer. This can only be
used for the 99% common case where the rowstride is exactly the
bpp*width and the source is the color buffer.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
This option to GCC makes it give a warning whenever a global function
is defined without a declaration. This should catch cases were we've
defined a function but forgot to put it in a header. In that case it
is either only used within one file so we should make it static or we
should declare it in a header.
The following changes where made to fix problems:
• Some functions were made static
• cogl-path.h (the one containing the 1.0 API) was split into two
files, one defining the functions and one defining the enums so that
cogl-path.c can include the enum and function declarations from the
2.0 API as well as the function declarations from the 1.0 API.
• cogl2-clip-state has been removed. This only had one experimental
function called cogl_clip_push_from_path but as this is unstable we
might as well remove it favour of the equivalent cogl_framebuffer_*
API.
• The GLX, SDL and WGL winsys's now have a private header to define
their get_vtable function instead of directly declaring in the C
file where it is called.
• All places that were calling COGL_OBJECT_DEFINE need to have the
cogl_is_whatever function declared so these have been added either
as a public function or in a private header.
• Some files that were not including the header containing their
function declarations have been fixed to do so.
• Any unused error quark functions have been removed. If we later want
them we should add them back one by one and add a declaration for
them in a header.
• _cogl_is_framebuffer has been renamed to cogl_is_framebuffer and
made a public function with a declaration in cogl-framebuffer.h
• Similarly for CoglOnscreen.
• cogl_vdraw_indexed_attributes is called
cogl_framebuffer_vdraw_indexed_attributes in the header. The
definition has been changed to match the header.
• cogl_index_buffer_allocate has been removed. This had no declaration
and I'm not sure what it's supposed to do.
• CoglJournal has been changed to use the internal CoglObject macro so
that it won't define an exported cogl_is_journal symbol.
• The _cogl_blah_pointer_from_handle functions have been removed.
CoglHandle isn't used much anymore anyway and in the few places
where it is used I think it's safe to just use the implicit cast
from void* to the right type.
• The test-utils.h header for the conformance tests explicitly
disables the -Wmissing-declaration option using a pragma because all
of the tests declare their main function without a header. Any
mistakes relating to missing declarations aren't really important
for the tests.
• cogl_quaternion_init_from_quaternion and init_from_matrix have been
given declarations in cogl-quaternion.h
Reviewed-by: Robert Bragg <robert@linux.intel.com>
This adds a public function to read pixels from a framebuffer into a
CoglBitmap. This replaces the internal function
_cogl_read_pixels_with_rowstride because a CoglBitmap contains a
rowstride so it can be used for the same purpose. A CoglBitmap already
has public API to make one that points to a CoglPixelBuffer so this
function can be used to read pixels into a PBO. It also avoids the
need to push the framebuffer on to the context's stack so it provides
a function which can be used in the 2.0 API after the stack is
removed.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
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>
This adds cogl_framebuffer_ apis for drawing attributes and primitives
that replace corresponding apis that depend on the default CoglContext.
This is part of the on going effort to adapt the Cogl api so it no
longer depends on a global context variable.
All the new drawing functions also take an explicit pipeline argument
since we are also aiming to avoid being a stateful api like Cairo and
OpenGL. Being stateless makes it easier for orthogonal components to
share access to the GPU. Being stateless should also minimize any
impedance miss-match for those wanting to build higher level stateless
apis on top of Cogl.
Note: none of the legacy, global state options such as
cogl_set_depth_test_enabled(), cogl_set_backface_culling_enabled() or
cogl_program_use() are supported by these new drawing apis and if set
will simply be silently ignored.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
We are in the process of removing all _EXP suffix mangling for
experimental APIs (Ref: c6528c4b6c) and adding missing gtk-doc
comments so that we can instead rely on the "Stability: unstable"
markers in the gtk-doc comments. This patch tackles the cogl framebuffer
symbols.
This adds CoglFramebuffer methods for accessing the clip stack. We plan
on making some optimizations to how framebuffer state is flushed which
will require us to track when a framebuffer's clip state has changed.
This api also ties in to the longer term goal of removing the need for a
default global CoglContext since these methods are all implicitly
related to a specific context via their framebuffer argument.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
This adds a cogl_framebuffer_identity_matrix() method that can be used
to reset the current modelview matrix to the identity matrix.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
This adds cogl_framebuffer_ methods to update the modelview and
projection matrix stacks to replace functions like cogl_translate(),
cogl_rotate() and cogl_scale() etc.
This is part of the on-going effort to get rid of the global CoglContext
pointer since the existing methods don't take an explicit pointer to a
CoglContext. All the methods are now related to a context via the
framebuffer.
We added framebuffer methods instead of direct context methods because
the matrix stacks are per-framebuffer and as well as removing the global
CoglContext we would rather aim for a more direct state access API
design than, say, cairo or OpenGL, so we'd like to avoid needing the
cogl_push/pop_framebuffer(). We anticipate that Cogl will mostly be
consumed by middleware graphics layers such as toolkits or game engines
and feel that a more stateless model will avoid impedance mismatches if
higher levels want to expose a stateless model to their developers and
statefullness can still be added by higher levels if really desired.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
It's useful to be able to query back the number of
point_samples_per_pixel that may have previously be chosen using
cogl_framebuffer_set_samples_per_pixel().
Reviewed-by: Neil Roberts <neil@linux.intel.com>
This factors out the CoglOnscreen code from cogl-framebuffer.c so we now
have cogl-onscreen.c, cogl-onscreen.h and cogl-onscreen-private.h.
Notably some of the functions pulled out are currently namespaced as
cogl_framebuffer but we know we are planning on renaming them to be in
the cogl_onscreen namespace; such as cogl_framebuffer_swap_buffers().
Reviewed-by: Neil Roberts <neil@linux.intel.com>
This adds a new experimental function, cogl_framebuffer_finish(), which
can be used to explicitly synchronize the CPU with the GPU. It's rare
that this level of explicit synchronization is desirable but for example
it can be useful during performance analysys to make sure measurements
reflect the working time of the GPU not just the time to queue commands.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
This adds support for multisample rendering to offscreen framebuffers.
After an offscreen framebuffer is first instantiated using
cogl_offscreen_new_to_texture() it is then possible to use
cogl_framebuffer_set_samples_per_pixel() to request multisampling before
the framebuffer is allocated. This also adds
cogl_framebuffer_resolve_samples() for explicitly resolving point
samples into pixels. Even though we currently only support the
IMG_multisampled_render_to_texture extension which doesn't require an
explicit resolve, the plan is to also support the
EXT_framebuffer_multisample extension which uses the framebuffer_blit
extension to issue an explicit resolve.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
This adds cogl_framebuffer_discard_buffers API that allows applications
to explicitly discard depth and stencil buffers which really helps when
using a tile based GPU architexture by potentially avoiding the need to
save the results of depth and stencil buffer changes to system memory
between frames since these can usually be handled directly with on-chip
memory instead.
The semantics for cogl_framebuffer_swap_buffers and
cogl_framebuffer_swap_region are now documented to include an implicit
discard of all buffers, including the color buffer.
We now recommend that all rendering to a CoglOffscreen framebuffer
should be followed by a call like:
cogl_framebuffer_discard_buffers (fb,
COGL_BUFFER_BIT_DEPTH|
COGL_BUFFER_BIT_STENCIL);
Reviewed-by: Neil Roberts <neil@linux.intel.com>
This adds a new function, cogl_framebuffer_get_color_format() to be able
to query the common pixel format for any color buffers attached to a
given CoglFramebuffer. For example an offscreen framebuffer created
using cogl_offscreen_new_to_texture() would have a format matching the
texture.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
Cogl aims to consistently put the origin of 2D objects at the top-left
instead of the bottom left as OpenGL does, but there was an oversight
and the experimental cogl_framebuffer_swap_region API was accepting
coordinates relative to the bottom left. Cogl will now flip the user's
given rectangles to be relative to the bottom of the framebufffer before
sending them to APIs like glXCopySubBuffer and glBlitFramebuffer.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
This makes cogl_framebuffer_clear and cogl_framebuffer_clear4f public as
experimental API. Since these functions take explicit framebuffer
pointers you don't need to push/pop a framebuffer just to clear it. Also
these functions are implicitly tied to a specific CoglContext via the
framebuffer pointer unlike cogl_clear.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
This adds a function to query what CoglContext a given framebuffer
belongs too. This can be useful if you pass framebuffer pointers around
and at some point you want to create another framebuffer as part of the
same context as a given framebuffer without assuming there is a single
default context.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
The cogl_framebuffer_get_blue_bits was defined 2 times-fix to use the
correct define for cogl_framebuffer_get_alpha_bits
Reviewed-by: Neil Roberts <neil@linux.intel.com>
This adds CoglPipeline and CoglFramebuffer support for setting a color
mask which is a bit mask defining which color channels should be written
to the current framebuffer.
The final color mask is the intersection of the framebuffer color mask
and the pipeline color mask. The framebuffer mask affects all rendering
to the framebuffer while the pipeline masks can be used to affect
individual primitives.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
This adds a getter and setter for requesting dithering to be enabled.
Dithering is a hardware dependent technique to increase the visible
color resolution beyond what the underlying hardware supports by playing
tricks with the colors placed into the framebuffer to give the illusion
of other colors. (For example this can be compared to half-toning used
by some news papers to show varying levels of grey even though their may
only be black and white are available).
The results of enabling dithering are platform dependent and may have no
effect.
Signed-off-by: Neil Roberts <neil@linux.intel.com>
There were several CoglOnscreen functions named like:
cogl_onscreen_<platform>_blah instead of cogl_<platform>_onscreen_blah
so this patch updates those to be consistent with other platform
specific apis we have in cogl.
Signed-off-by: Neil Roberts <neil@linux.intel.com>
This adds a description for the cogl-framebuffer section and adds lots
of missing symbols to the 2.0 reference manual.
Signed-off-by: Neil Roberts <neil@linux.intel.com>
This exposes the previously internal only
_cogl_framebuffer_get_red/green/blue/alpha_bits() functions as 2.0
experimental API.
Signed-off-by: Neil Roberts <neil@linux.intel.com>
This exposes experimental cogl_framebuffer APIs for getting and setting
a viewport without having to refer to the implicit CoglContext. It adds
the following experimental API:
cogl_framebuffer_set_viewport
cogl_framebuffer_get_viewport4fv
cogl_framebuffer_get_viewport_x
cogl_framebuffer_get_viewport_y
cogl_framebuffer_get_viewport_width
cogl_framebuffer_get_viewport_height
Signed-off-by: Neil Roberts <neil@linux.intel.com>
To support toolkits targeting wayland and using Cogl we allow toolkits
to be responsible for connecting to a wayland display and asking Cogl to
use the toolkit owned display and compositor object. Note: eventually
the plan is that wayland will allow retrospective querying of objects so
we won't need the foreign compositor API when Cogl can simply query it
from the foreign display.
Some places were using COGL_HAS_WIN32 but the only macro defined is
COGL_HAS_WIN32_SUPPORT. The similar macros such as COGL_HAS_XLIB are
only defined for compatibility with existing code but COGL_HAS_WIN32
was never defined so there's no need to support it.
One of the places was including the non-existant cogl-win32.h. This
has been removed because the file only temporarily existed during
development of the backend.
This extends cogl_onscreen_x11_set_foreign_xid to take a callback to a
function that details the event mask the Cogl requires the application
to select on foreign windows. This is required because Cogl, for
example, needs to track size changes of a window and may also in the
future want other notifications such as map/unmap.
Most applications wont need to use the foreign xwindow apis, but those
that do are required to pass a valid callback and update the event mask
of their window according to Cogl's requirements.
This adds Cogl API to show and hide onscreen framebuffers. We don't want
to go too far down the road of abstracting window system APIs with Cogl
since that would be out of its scope but the previous idea that we would
automatically map framebuffers on allocation except for those made from
foreign windows wasn't good enough. The problem is that we don't want to
make Clutter always create stages from foreign windows but with the
automatic map semantics then Clutter doesn't get an opportunity to
select for all the events it requires before mapping. This meant that we
wouldn't be delivered a mouse enter event for windows mapped underneath
the cursor which would break Clutters handling of button press events.
It's generally useful to be able to query the width and height of a
framebuffer and we expect to need this in Clutter when we move the
eglnative backend code into Cogl since Clutter will need to read back
the fixed size of the framebuffer when realizing the stage.
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.
