Commit Graph

26 Commits

Author SHA1 Message Date
Robert Bragg
6436cd073d Declare interface types as void and remove cast macros
This declares the interface types CoglFramebuffer, CoglBuffer,
CoglTexture, CoglMetaTexture and CoglPrimitiveTexture as void when
including the public cogl.h header so that users don't have to use lots
of C type casts between instance types and interface types.

This also removes all of the COGL_XYZ() type cast macros since they do
nothing more than compile time type casting but it's less readable if
you haven't seen that coding pattern before.

Unlike with gobject based apis that use per-type macros for casting and
performing runtime type checking we instead prefer to do our runtime
type checking internally within the front-end public apis when objects
are passed into Cogl. This greatly reduces the verbosity for users of
the api and may help reduce the chance of excessive runtime type
checking that can sometimes be a problem.

(cherry picked from commit 248a76f5eac7e5ae4fb45208577f9a55360812a7)

Since we can't break the 1.x api this version of the patch actually
defines compatible NOP macros within deprecated/cogl-type-casts.h
2013-11-27 19:33:44 +00:00
Lionel Landwerlin
84bdd679df buffer: add missing transfer annotations
Reviewed-by: Robert Bragg <robert@linux.intel.com>
2013-09-23 15:02:31 +01:00
Damien Lespiau
5912ee9997 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)
2013-01-22 17:48:16 +00:00
Robert Bragg
f53fb5e2e0 Allow propogation of OOM errors to apps
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.
2013-01-22 17:48:07 +00:00
Neil Roberts
4f6fe6f0e2 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)
2013-01-22 17:48:05 +00:00
Neil Roberts
ec03357e88 Add cogl_buffer_map_range()
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)
2013-01-22 17:48:03 +00:00
Tomeu Vizoso
93d0de1d9a Mass rename CLUTTER_COMPILATION to COGL_COMPILATION
Reviewed-by: Neil Roberts <neil@linux.intel.com>

(cherry picked from commit a99512e5798e48ffa3a9a1a7eb98bc55647ee1b6)
2012-08-06 14:27:45 +01:00
Robert Bragg
54735dec84 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-08-06 14:27:39 +01:00
Neil Roberts
f1d65e58b3 buffer: Remove const from cogl_is_buffer (const void *)
None of the other cogl_is_blah functions have a const pointer so this
is just for consistency. It helps if someone is trying to have an
array of type-check function pointers to determine the Cogl object
type because in that case all of the functions would have to have the
same prototype.

Reviewed-by: Robert Bragg <robert@linux.intel.com>
2012-03-14 13:48:11 +00:00
Jasper St. Pierre
e98f279712 Fix some doc issues
Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-14 20:42:10 +00:00
Robert Bragg
c6528c4b6c 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>
2012-01-05 21:00:17 +00:00
Robert Bragg
f3a4d21187 buffer: make the COGL_BUFFER casting macro public
The CoglBuffer api is available as experimental 2.0 api but we forgot to
exposed the COGL_BUFFER casting macro.

Reviewed-by: Neil Roberts <neil@linux.intel.com>
2011-08-12 15:28:43 +01:00
Robert Bragg
b9d7181f03 buffer: Improve the CoglBuffer API description
This improves the gtk-doc overview for the CoglBuffer interface.

Signed-off-by: Neil Roberts <neil@linux.intel.com>
2011-06-30 14:33:12 +01:00
Emmanuele Bassi
aa4f63338c docs: Fixes for the Cogl API reference 2010-12-22 09:52:35 +00:00
Neil Roberts
6027aa04a4 cogl-buffer: Use void* instead of guint8* for map and set_data
Unless the CoglBuffer is being used for texture data then it's
relatively unlikely that the data will contain an array of bytes. For
example if it's used as a vertex array then it's more likely to be
floats or some vertex struct. In that case it's much more convenient
if set_data and map use void* pointers so that we can avoid a cast.
2010-11-04 18:04:03 +00:00
Emmanuele Bassi
71f62ca500 Enumeration value should be on the same line
The glib-mkenums script is not clever enough to deal with

  FLAGS_VALUE = FLAGS_A |
                FLAGS_B

And since this breaks the enumeration GType and the introspection data,
we cannot really wait for it to be fixed.

See: https://bugzilla.gnome.org/show_bug.cgi?id=629741

http://bugzilla.clutter-project.org/show_bug.cgi?id=2238
2010-09-15 11:56:59 +01:00
Robert Bragg
f8d58446a8 cogl-buffer: consider it an error to free a mapped buffer
Explicitly warn if we detect that a CoglBuffer is being freed while it
is still mapped. Previously we silently unmapped the buffer, but it's
not something we want to encourage.
2010-07-07 14:08:11 +01:00
Robert Bragg
92d0322766 pixel-array: Allow passing of hints to cogl_buffer_map
This allows you to tell Cogl that you are planning to replace all the
buffer's data once it is mapped with cogl_buffer_map. This means if the
buffer is currently being accessed by the GPU then the driver doesn't
have to stall and wait for it to finish before it can access it from the
CPU and can instead potentially allocate a new buffer with undefined
data and map that.
2010-07-06 12:07:28 +01:00
Robert Bragg
cafeb02531 cogl-buffer: make the COGL_BUFFER_USAGE_HINT private
The usage hint should be implied by the CoglBuffer subclass type so the
public getter and setter APIs for manually changing the usage hint of a
CoglBuffer have now been removed.
2010-07-05 15:20:04 +01:00
Robert Bragg
1000c80444 cogl: declare experimental symbols consistently
We had several different ways of exposing experimental API, in one case
the symbols had no special suffix, in two other ways the symbols were
given an _EXP suffix but in different ways.

This makes all experimental API have an _EXP suffix which is handled
using #defines in the header so the prototypes in the .c and .h files
don't have the suffix.

The documented reason for the suffix is so that anyone watching Cogl for
ABI changes who sees symbols disappear will hopefully understand what's
going on.
2010-06-30 18:51:31 +01:00
Robert Bragg
3aaef72e50 buffer: Remove use of CoglHandle in the CoglBuffer API
This replaces the use of CoglHandle with strongly type CoglBuffer *
pointers instead. The only function not converted for now is
cogl_is_buffer which will be done in a later commit.
2010-05-28 18:42:33 +01:00
Emmanuele Bassi
72f4ddf532 Remove mentions of the FSF address
Since using addresses that might change is something that finally
the FSF acknowledge as a plausible scenario (after changing address
twice), the license blurb in the source files should use the URI
for getting the license in case the library did not come with it.

Not that URIs cannot possibly change, but at least it's easier to
set up a redirection at the same place.

As a side note: this commit closes the oldes bug in Clutter's bug
report tool.

http://bugzilla.openedhand.com/show_bug.cgi?id=521
2010-03-01 12:56:10 +00:00
Robert Bragg
0f5f4e8645 cogl: improves header and coding style consistency
We've had complaints that our Cogl code/headers are a bit "special" so
this is a first pass at tidying things up by giving them some
consistency. These changes are all consistent with how new code in Cogl
is being written, but the style isn't consistently applied across all
code yet.

There are two parts to this patch; but since each one required a large
amount of effort to maintain tidy indenting it made sense to combine the
changes to reduce the time spent re indenting the same lines.

The first change is to use a consistent style for declaring function
prototypes in headers. Cogl headers now consistently use this style for
prototypes:

 return_type
 cogl_function_name (CoglType arg0,
                     CoglType arg1);

Not everyone likes this style, but it seems that most of the currently
active Cogl developers agree on it.

The second change is to constrain the use of redundant glib data types
in Cogl. Uses of gint, guint, gfloat, glong, gulong and gchar have all
been replaced with int, unsigned int, float, long, unsigned long and char
respectively. When talking about pixel data; use of guchar has been
replaced with guint8, otherwise unsigned char can be used.

The glib types that we continue to use for portability are gboolean,
gint{8,16,32,64}, guint{8,16,32,64} and gsize.

The general intention is that Cogl should look palatable to the widest
range of C programmers including those outside the Gnome community so
- especially for the public API - we want to minimize the number of
foreign looking typedefs.
2010-02-12 14:05:00 +00:00
Emmanuele Bassi
2674a1ead2 docs: Fixes for Cogl API reference
98% symbol docs coverage.
  335 symbols documented.
  0 symbols incomplete.
  8 not documented.

Not bad, if I may say so.
2010-02-09 14:41:37 +00:00
Damien Lespiau
23717452bf cogl-buffer: Use TEXTURE as the only value for CoglBufferUsageHint
We should try to use more explicit defines than GL for our hints. For
now we only support using a CoglBuffer to generate textures.
2010-02-08 17:14:49 +00:00
Damien Lespiau
40b73a8c0c cogl-buffer: add an abstract class around openGL's buffer objects
Buffer objects are cool! This abstracts the buffer API first introduced
by GL_ARB_vertex_buffer_object and then extended to other objects.

The coglBuffer abstract class is intended to be the base class of all
the buffer objects, letting the user map() buffers. If the underlying
implementation does not support buffer objects (or only support VBO but
not FBO for instance), fallback paths should be provided.
2010-02-08 17:14:49 +00:00