[Cogl] [PATCH] Adds CoglError api

[Neil Roberts]

Robert Bragg <robert at sixbynine.org> writes:

> I guess I tend to find myself wanting the abort on error semantics
> more often than not but I'm sure you're right that there are times
> when that's not the most convenient approach. My hunch a.t.m is that
> the aborting behaviour is more useful but it's hard to know for sure I
> suppose.

After discussing this with Rob a bit more in RL™ I think I agree. The
constructor for CoglContext is quite a compelling example which every
application is going to use and not very many of them will be able to do
anything if the constructor fails. In that case it's a lot more
convenient for the application to just abort.

The other example for setting the depth state where Cogl is using an
error to report missing support for a feature is probably not that
useful in practice because it's relatively easy to just check the
feature flag instead.

However I think it's quite important that we make it clear that
CoglError has diverged from the GError semantics here so we should put a
clear notice in the documentation for people used to GLib.

Currently it's the norm in a GLib API that if a function can throw a
GError it will also have a separate mechanism to return the error status
(such as return FALSE). We also discussed potentially removing this
idiom in CoglError because if you always have to pass a CoglError
pointer to handle the error anyway then it makes less sense to have a
second way to report the error. Removing the return value would also
serve as a way to signal to people porting an application from Cogl 1.x
that something has changed. However I think we decided not to bother
doing this because most of the functions that can throw a CoglError
are actually constructors that return a pointer to a resource. We'd have
to return NULL from those functions anyway so it would be difficult to
make the idiom consistent.

If we find that ignoring the details of an error turns out to be really
important in some cases we can just add COGL_IGNORE_ERROR as Rob
suggested so we won't really have lost any performance by switching to
this approach.

Reviewed-by: Neil Roberts <neil at linux.intel.com>

Regards,
- Neil