gtk-doc needs the types in -sections.txt to be able to do
cross-references. Add all those currently generating warnings.
(cherry picked from commit e57a21d2608f0885e6f2eb3a017feb7dffb7a63c)
I just added the general types creating warnings in the current state of the
documentation (ie the ones references by already documented functions)
and moved the section from the 'Utility' section to the 'General'
section which I believe is a better fit as they are used by more than
one type and not really utilities.
(cherry picked from commit c51b147789763863ef32482d7ffa936160ed7c93)
Various changes have led to the current, separate from the pipeline,
depth state, this commit fixes the remaining waring around that.
(cherry picked from commit 111e687e722ad67a0e1c09f881c6282ccb06410b)
Types need to be declare to be cross-referenceable. Use the opportunity
to reorganise the symbols in subsections.
(cherry picked from commit 95be47bc2aeea208c28d7df0b82aa63cc132f71e)
We have found several times now when writing code using Cogl that it
would really help if Cogl's matrix stack api was public as a utility
api. In Rig for example we want to avoid redundant arithmetic when
deriving the matrices of entities used to render and we aren't able
to simply use the framebuffer's matrix stack to achieve this. Also when
implementing cairo-cogl we found that it would be really useful if we
could have a matrix stack utility api.
(cherry picked from commit d17a01fd935d88fab96fe6cc0b906c84026c0067)
This allows apps to catch out-of-memory errors when allocating textures.
Textures can be pretty huge at times and so it's quite possible for an
application to try and allocate more memory than is available. It's also
very possible that the application can take some action in response to
reduce memory pressure (such as freeing up texture caches perhaps) so
we shouldn't just automatically abort like we do for trivial heap
allocations.
These public functions now take a CoglError argument so applications can
catch out of memory errors:
cogl_buffer_map
cogl_buffer_map_range
cogl_buffer_set_data
cogl_framebuffer_read_pixels_into_bitmap
cogl_pixel_buffer_new
cogl_texture_new_from_data
cogl_texture_new_from_bitmap
Note: we've been quite conservative with how many apis we let throw OOM
CoglErrors since we don't really want to put a burdon on developers to
be checking for errors with every cogl api call. So long as there is
some lower level api for apps to use that let them catch OOM errors
for everything necessary that's enough and we don't have to make more
convenient apis more awkward to use.
The main focus is on bitmaps and texture allocations since they
can be particularly large and prone to failing.
A new cogl_attribute_buffer_new_with_size() function has been added in
case developers need to catch OOM errors when allocating attribute buffers
whereby they can first use _buffer_new_with_size() (which doesn't take a
CoglError) followed by cogl_buffer_set_data() which will lazily allocate
the buffer storage and report OOM errors.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
(cherry picked from commit f7735e141ad537a253b02afa2a8238f96340b978)
Note: since we can't break the API for Cogl 1.x then actually the main
purpose of cherry picking this patch is to keep in-line with changes
on the master branch so that we can easily cherry-pick patches.
All the api changes relating stable apis released on the 1.12 branch
have been reverted as part of cherry-picking this patch so this most
just applies all the internal plumbing changes that enable us to
correctly propagate OOM errors.
This adds a function to get a pointer to the SDL_Window associated
with a CoglOnscreen when using the SDL2 winsys.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
(cherry picked from commit 071f4b80daa8a2f967746a30b3acf014d74f781a)
This adds a buffer method to map a subregion of the buffer. This works
using the GL_ARB_map_buffer_range extension. If the extension is not
available then it will fallback to using glMapBuffer to map the entire
buffer and then just add the offset to the returned pointer.
cogl_buffer_map() is now just a wrapper which maps the entire range of
the buffer. The driver backend functions have been renamed to
map_range and they now all take the offset and size arguments.
When the COGL_BUFFER_MAP_HINT_DISCARD hint is used and the map range
extension is available instead of using glBufferData to invalidate the
buffer it will instead pass the new GL_MAP_HINT_INVALIDATE_BUFFER
flag. There is now additionally a COGL_BUFFER_MAP_HINT_DISCARD_REGION
hint which can be used if the application only wants to discard the
small region that is mapped. glMapBufferRange is always used if it is
available even if the entire buffer is being mapped because it seems
more robust to pass those flags then to call glBufferData.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
(cherry picked from commit 55ca02b5ca9cafc750251ec974e0d6a536cb80b8)
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.
You had a mismatch between the file name in -sections.txt and
-docs.xml.in. Chose cogl-sdl.xml.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
(cherry picked from commit 8b61963f3015e11bd5fbe225ec566ac6e354acc1)
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)
This creates a matrix to represent the given euler rotation. This
should be more efficient than creating the matrix by doing three
separate rotations because no separate intermediate matrices are
created and no matrix multiplication is needed.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
(cherry picked from commit e66d9965897999a4889063f6df9a20ea6abf97fe)
cogl_framebuffer_{get,set}_point_samples_per_pixel() have lost the
'point_' part.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
(cherry picked from commit 3c8bcf391090ad0c5f65f300458bfc901fd62800)
Several little changes were needed to make the CoglEuler documentation
appear:
• Fix the embeded docbook snippet in the CoglEuler section header
• Add the xinclude directive to the main document
• Add the missing <SECTION> in -sections.txt
Reviewed-by: Robert Bragg <robert@linux.intel.com>
(cherry picked from commit c7f6e07f7b8ba0d7dc9604e888c8a46165ec3ed4)
This allows people to initialize a matrix with a translation
transformation. The options to do it at the moment were:
* init_from_array() but it give cogl no information about the type of
matrix.
* init_indentity() and then translate() but it means doing a lot of
computations for no reason.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
(cherry picked from commit 068b3b59221e405dc288d434b0008464684a7c12)
This adds a version header which contains macros to define which
version of Cogl the application is being compiled against. This helps
applications that want to support multiple incompatible versions of
Cogl at compile time.
The macros are called COGL_VERSION_{MAJOR,MINOR,MICRO}. This does not
match Clutter which names them CLUTTER_{MAJOR,MINOR,MICRO}_VERSION but
I think the former is nicer and it at least matches Cairo and Pango.
The values of the macro are defined to COGL_VERSION_*_INTERNAL which
is generated by the configure script into cogl-defines.h.
There is also a macro for the entire version as a string called
COGL_VERSION_STRING.
The internal utility macros for encoding a 3 part version number into
a single integer have been moved into the new header so they can be
used publicly as a convenient way to check if the version is within a
particular range. There is also a COGL_VERSION_CHECK macro for the
very common case that a feature will be used since a particular
version of Cogl. There is a macro called COGL_VERSION which contains
the pre-encoded version of Cogl being compiled against for
convenience.
Unlike in Clutter this patch does not add any runtime version
identification mechanism.
A test case is also added which just contains static asserts to sanity
check the macros.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
(cherry picked from commit 3480cf140dc355fa87ab3fbcf0aeeb0124798a8f)
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)
This re-works the SDL integration api to simplify the integration for
application developers and also allow Cogl to know when the application
is about to go idle waiting for events so it can perform idle
book-keeping work.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
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>
This interface represents any textures that are backed by a single
texture in GL and that can be used directly with the
cogl_framebuffer_draw_attributes family of functions. This currently
equates to CoglTexture2D, CoglTexture3D and CoglTextureRectangle.
The interface currently has only one method called
cogl_primitive_set_auto_mipmap. This replaces the
COGL_TEXTURE_NO_AUTO_MIPMAP flag from the CoglTextureFlags parameter
in the constructors. None of the other flags in CoglTextureFlags make
sense for primitive textures so it doesn't seem like a good idea to
need them for primitive constructors.
There is a boolean in the vtable to mark whether a texture type is
primitive which the new cogl_is_primitive function uses. There is also
a new texture virtual called set_auto_mipmap which is only required to
be implemented for primitive textures.
Reviewed-by: Robert Bragg <robert@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 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>
The idea is that CoglPixelBuffer should just be a buffer that can be
used for pixel data and it has no idea about the details of any images
that are stored in it. This is analogous to CoglAttributeBuffer which
itself does not have any information about the attributes. When you
want to use a pixel buffer you should create a CoglBitmap which points
to a region of the attribute buffer and provides the extra needed
information such as the width, height and format. That way it is also
possible to use a single CoglPixelBuffer with multiple bitmaps.
The changes that are made are:
• cogl_pixel_buffer_new_with_size has been removed and in its place is
cogl_bitmap_new_with_size. This will create a pixel buffer at the
right size and rowstride for the given width/height/format and
immediately create a single CoglBitmap to point into it. The old
function had an out-parameter for the stride of the image but with
the new API this should be queriable from the bitmap (although there
is no function for this yet).
• There is now a public cogl_pixel_buffer_new constructor. This takes
a size in bytes and data pointer similarly to
cogl_attribute_buffer_new.
• cogl_texture_new_from_buffer has been removed. If you want to create
a texture from a pixel buffer you should wrap it up in a bitmap
first. There is already API to create a texture from a bitmap.
This patch also does a bit of header juggling because cogl-context.h
was including cogl-texture.h and cogl-framebuffer.h which were causing
some circular dependencies when cogl-bitmap.h includes cogl-context.h.
These weren't actually needed in cogl-context.h itself but a few other
headers were relying on them being included so this adds the #includes
where necessary.
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>
Although these are in the public headers we should assume that no one is
using them since they were never documented so no could know what they
are useful for.
If you were to guess you'd be forgiven for thinking they were bitmasks
for checking some flags to see if a format is 24 or 32 bits. If you
looked further you might instead be forgiven for thinking that if you
masked of the least significant nibble of a pixel-format then you could
check the value against these defines. Neither of the previous
operations are reliable ways to check if a format is 24 or 32bit and
instead code must use then internal
_cogl_pixel_format_get_bytes_per_pixel() api if they want to know the
pixel size for a given format which relies on a 16 entry lookup table
using the least significant nibble of a pixel-format.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
Although it's in a public header nothing should be using this define
since it's not documented what it could be used for. The cases where we
were using it internally were quite fragile because they were trying to
mask information from the least significant nibble of CoglPixelFormat
but really that nibble just has to be dealt with using lookup tables.
The least significant nibble of a pixel format gives information about
the bytes per pixel and whether the components are byte aligned but the
information needs to be accessed using
_cogl_pixel_format_get_byes_per_pixel() and
_cogl_pixel_format_is_endian_dependant().
Reviewed-by: Neil Roberts <neil@linux.intel.com>
Since (A & ~COGL_PREMULT_BIT) is basically as readable as (A &
COGL_UNPREMULT_MASK) this patch removes the mask define. Without the
mask the code is slightly more explicit and there's less risk in error
caused by us forgetting to update the COGL_UNPREMULT_MASK if the way
CoglPixelFormat is defined evolves.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
This adds a public function to replace the texture for a layer with
the default white texture. It is equivalent to calling
cogl_pipeline_set_layer_texture with NULL for the texture object
except that it also lets you choose a type for the texture. The idea
is that applications using a base pipeline to make multiple copies
that can share the generated shaders can use this function to make the
layer come into existence with the right texture type. Previously the
idiom would be to create a 1x1 dummy texture of the right type but
this ends up creating lots of redundant little textures.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
This adds an internal function to get the type of the underlying
hardware texture for any CoglTexture. It can return one of three
values to represent 2D textures, 3D textures or rectangle textures.
The idea is that this can be used as a replacement for
cogl_texture_get_gl_texture when only the target is required to make
it a bit less GL-centric. The implementation adds a new virtual
function which all of the texture backends now implement.
The enum is in a public header because a later patch will want to use
it from the CoglPipeline API. We may want to consider making the
function public too later.
Reviewed-by: Robert Bragg <robert@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>
This adds a public function to iterate the attributes of a
CoglPrimitive. Previously there was no way to query back the
attributes but there was methods to query back all of the other
properties.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
This adds a public function to make a copy of a primitive. The copy is
shallow which means it will share the same attributes and attribute
buffers. This could be useful for code that wants to have multiple
similar primitives with slightly modified properties.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
Previously we had functions named like
cogl_primitive_new_with_xyz_attributes() but at some point we renamed
them all to functions named like cogl_primitive_new_xyz() instead. This
updates the -sections.txt symbol listing to list the new names.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
The GSource is created using cogl_glib_source_new which takes a
pointer to a CoglContext. The source calls cogl_poll_get_info() in its
prepare function and cogl_poll_dispatch() in its dispatch
function. The poll FDs on the source are updated according to what
Cogl reports.
The header is only included and the source only compiled if Cogl is
configured with GLib support.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
This adds two new functions:
void
cogl_poll_get_info (CoglContext *context,
CoglPollFD **poll_fds,
int *n_poll_fds,
gint64 *timeout);
void
cogl_poll_dispatch (CoglContext *context,
const CoglPollFD *poll_fds,
int n_poll_fds);
The application is expected to call the first function whenever it is
about to block to go idle, and the second function whenever it comes
out of idle. This gives Cogl winsys's the ability poll file
descriptors for events. For example when handing swap complete
notifications, it can report that it needs to block on a file
descriptor.
The two functions are backed by winsys virtual functions. There are
currently no implementations. The default handler for get_info just
reports no file descriptors and an infinite timeout.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
This adds a documentation section for CoglSnippet which gives an
overview of how to use them. It also fixes some syntax errors in the
existing documentation and adds the missing pipeline functions for
adding snippets to the documentation sections file.
Reviewed-by: Robert Bragg <robert@linux.intel.com>
