Note: very little of this is set in stone, and most of these ideas will be reviewed and revised before work starts on them, but this can be used as a starting point for discussions and a place to evolve the design

Index

Click the titles to link to pages with more detailed information

CoglRenderer

application owned toplevel object representing the choice of GPU hardware, driver and window system to use.

CoglDisplay 

describes a display pipeline for a CoglRenderer

CoglContext / CoglApplicationContext? 

One per application, created by the toolkit/framework layer its role is to sandbox all top-level Cogl state. Since Cogl avoids the statemachine style API of OpenGL very little goes here, but for example it ties together a CoglDisplay, the current CoglPipeline and the current CoglFramebuffer.

CoglFramebuffer 

abstract class representing optional depth and stencil buffers plus N color buffers for rendering too

• CoglOnscreen - represents a window system framebuffer, such as an X Window
• CoglOffscreen - represents a private application framebuffer for offscreen rendering
• CoglColorBuffer - A single color buffer that may be attached and moved between CoglFramebuffers

CoglBuffer

a GPU memory allocation, usable for pixel, vertex and vertex index data

• CoglPixelArray - A GPU memory allocation for storing image data. (It doesn't understand the layout just the fact that it's image data)
• CoglVertexArray - A GPU memory allocation for storing vertex attribute data. (It doesn't understand the layout just the fact that it's vertex data)
  • CoglVertexAttribute - Describes the layout of a vertex attribute within a CoglVertexArray allocation.
    • CoglPrimitive: Groups together a set of CoglVertexAttributes and holds enough information that it can be retained (e.g. in a renderlist or journal) and drawn later.
• CoglIndexArray - Another subclass of CoglBuffer for GPU allocations storing array index data.
  • CoglIndices: Defines a single range of vertex indices in a CoglIndexArray, similar to how a CoglVertexAttribute defines the details of a CoglVertexArray range.

CoglTranscoder 

Replaces CoglBitmap and deals with alpha premultiplication and format conversions

CoglTexture 

abstract base class for different texture types:

• CoglTexture1D
• CoglTexture2D - 2D textures with normalized coordinates, constrained to power of two sizes on some platforms.
• CoglTextureRectangle - Non power of two texture with non-normalized texture coordinates
• CoglTexture3D - 3D textures with normalized coordinates, constrained to power of two sizes on some platforms.
• CoglTexturePixmapX11 - Textures corresponding to an X11 Window.
• CoglTextureSub - similar to OpenVG style images they can derive from a sub-region of another parent texture.
• CoglTextureAtlas - An infrastructure to manage a collection of sub textures that all have a common parent.
• CoglTexture2DSliced - handles textures larger than HW limits or power of two sizes on hardware that doesn't natively support it.
  • We're considering a rename to CoglAutoTexture, or something similar.
• May support implementing CoglTextures subclasses in the public API

CoglMaterial CoglPipeline

top level object representing the full vertex transform, fragment process and blend pipeline

• PointSprites a work in progress to add point sprite support to CoglMaterial

CoglProgram

A multi language shader API (arbfp, glsl, hlsl?, Cg?, C?)

CoglFX

A Format to describe effects and multiple alternative to implement them

CoglResourceManager

a means for orthogonal components to share resources such as the depth buffer, stencil buffer

Math utilities

• CoglMatrix - An opaque 4x4 - column major - matrix type and supporting API
• CoglColor - An opaque type for passing colours around.
• CoglVector3
• CoglQuaternion
• CoglEuler

Code Examples

So we can get a feel for the design in practice this section can be used to show more complete examples of how the APIs designed above would be used

Initializing Cogl

XXX: FIXME - this is probably out of sync with the design and needs updating

/****** application ******/

cogl_init (&argc, &argv);

/****** usually toolkit ******/

CoglRenderer *renderer = cogl_renderer_new ();
/* special renderer configuration can optionally be done here */
if (!cogl_renderer_connect (renderer, &error))
  g_critical ("Failed to connect to a renderer: %s", error->message);

/****** toolkit *******/

CoglDisplay *dpy = cogl_display_new (renderer);
cogl_display_require_depth_support (dpy, TRUE, NULL);
cogl_display_require_stencil_support (dpy, TRUE, NULL);
cogl_display_require_alpha_component (dpy, TRUE, NULL);
/* special display configuration can optionally be done here */
if (!cogl_display_setup (dpy, &error))
  g_critical ("Failed to setup a display: %s", error->message);

CoglContext *ctx = cogl_context_new (renderer, display);
cogl_set_context (ctx);

CoglOnscreen *onscreen = cogl_onscreen_new_with_size (128, 128);
cogl_onscreen_require_depth_support (onscreen, FALSE, NULL);
/* special framebuffer configuration can optionally be done here */
if (!cogl_framebuffer_allocate (COGL_FRAMEBUFFER (onscreen), &error))
  g_critical ("Failed to allocate onscreen framebuffer: %s", error->message);

/****** application *******/

CoglOffscreen *offscreen;
CoglColorBuffer cb;
GError **error;

cb = cogl_color_buffer_new (128, 128, COGL_PIXEL_FORMAT_RGBA_8888);
cogl_color_buffer_allocate (cb, NULL);

offscreen = cogl_offscreen_new ();
cogl_framebuffer_attach_color_buffer (fb, cb, NULL);
cogl_framebuffer_require_stencil_bits (fb, 8, &error);
cogl_framebuffer_request_depth_bits (fb, 16, &error);

if (!cogl_framebuffer_allocate (fb, &error))
  g_critical ("Failed to allocate offscreen framebuffer: %s", error->message);

cogl_push_framebuffer (fb);

/* draw stuff */

cogl_pop_framebuffer ();