Contents 1 Cogl 2.0 API Changes 1.1 The implementation plan 1.2 Open Issues 1.3 Outline of things we want to fix in 2.0

Cogl 2.0 API Changes

A list of API warts that should be fixed when we change the API for 2.0

The implementation plan

The current plan for Cogl 2.0 is to break the API but maintain a backwards compatible ABI.

So the way we are aiming to do this is by:

1. Allowing users to define COGL_USE_VERSION_2_0 on a per-c-file basis, before including any Cogl headers.
2. Namespacing incompatible public symbols with "cogl2_" instead of "cogl_"
3. Providing macros to hide the underlying "cogl2_" namespace from users.
4. Providing a cogl-{gl,gles}-2.0.pc that will add -DCOGL_USE_VERSION_2_0 to your CFLAGS

The constraints of this approach are that we can't add anything to the 2.0 that is fundamentally at odds with anything in 1.0. We have to keep in mind that it's valid to change the version on a per file basis, and since we don't expect everyone will switch to using the Cogl 2.0 API over night, any particular application or library will be mixing use of both versions.

A big advantage of this approach is that we can fix a number of warts we've identified in the Cogl API without affecting the API or ABI of Clutter which depends on Cogl to implement custom actors.

Open Issues

How will we handle the documentation? How will this interact with gobject introspection?

Outline of things we want to fix in 2.0

Remove all functions marked as deprecated

Remove CoglColor, there aren't many functions that expect a CoglColor and it would be easy to make alternative functions that just take 4 floats directly as arguments. Since utility APIs for manupilating colors on the CPU is rather out of scope for Cogl there doesn't really seem like much need for the typedef.

Rename CoglMaterial -> CoglPipeline. "CoglMaterial" as a name has confused multiple third party users of the implications. E.g. "material" is used in some game engines to imply a multi-pass effect, or just because it tends to imply that it is constrained to fragment processing and can be considered to be a bit like a highlevel/dynamic texturing abstraction. Actually the scope of CoglMaterial includes the full vertex transform, rasterize, fragment process, depth test and blend pipeline. It's more like "graphics context" but we can't call it CoglContext since the name is taken (we actually need a higher level context that tracks the current framebuffer + pipeline + GPU/display choices). I've struggled to find a good name for this, but so far "pipeline" seems the best to me. This is consistent with terminology used when teaching people how a GPU works. You would usually provide diagrams etc explaining each of the pipeline stages and so I think the name will be quite intuitive to new users.

Get rid of cogl_texture_get_rowstride. This function makes no sense.

Make all of the cogl_path_* functions take a Cogl path handle and remove the concept of the 'current path'

Make functions that conceptually act on or query the current context take an explicit CoglContext * argument.

Remove the cogl_vertex_buffer API

Remove the CoglSimpleVertex typedef and cogl_polygon

Remove cogl_get_bitmask

Remove cogl_set_source_texture

Fix the namespacing for CoglTexture. Currently we have some cogl_texture_ symbols that conceptually belong to the CoglTexture abstract base class but also have other cogl_texture_ symbols that conceptually belong to the cogl_texture_2d_sliced/cogl_auto_texture backend.

Remove all cogl_material_layer_ functions

cogl_program_ was originally defined as *very* thin wrapper around the GL shader APIs. We are planning on evolving cogl_program, but whatever remains of the original thin wrapper should be removed.

"Argh I hate OpenGL! glOrtho: why aren't near/far clip plane coordinates like the other args‽ Worse still why did I copy this in Cogl :-/"

see also Clutter/Clutter20Changes