Go to file
Robert Bragg aa1a2cb661 Adds renderer,display,onscreen-template and swap-chain stubs
As part of the process of splitting Cogl out as a standalone graphics
API we need to introduce some API concepts that will allow us to
initialize a new CoglContext when Clutter isn't there to handle that for
us...

The new objects roughly in the order that they are (optionally) involved
in constructing a context are: CoglRenderer, CoglOnscreenTemplate,
CoglSwapChain and CoglDisplay.

Conceptually a CoglRenderer represents a means for rendering.  Cogl
supports rendering via OpenGL or OpenGL ES 1/2.0 and those APIs are
accessed through a number of different windowing APIs such as GLX, EGL,
SDL or WGL and more. Potentially in the future Cogl could render using
D3D or even by using libdrm and directly banging the hardware. All these
choices are wrapped up in the configuration of a CoglRenderer.

Conceptually a CoglDisplay represents a display pipeline for a renderer.
Although Cogl doesn't aim to provide a detailed abstraction of display
hardware, on some platforms we can give control over multiple display
planes (On TV platforms for instance video content may be on one plane
and 3D would be on another so a CoglDisplay lets you select the plane
up-front.)

Another aspect of CoglDisplay is that it lets us negotiate a display
pipeline that best supports the type of CoglOnscreen framebuffers we are
planning to create. For instance if you want transparent CoglOnscreen
framebuffers then we have to be sure the display pipeline wont discard
the alpha component of your framebuffers. Or if you want to use
double/tripple buffering that requires support from the display
pipeline.

CoglOnscreenTemplate and CoglSwapChain are how we describe our default
CoglOnscreen framebuffer configuration which can affect the
configuration of the display pipeline.

The default/simple way we expect most CoglContexts to be constructed
will be via something like:

 if (!cogl_context_new (NULL, &error))
   g_error ("Failed to construct a CoglContext: %s", error->message);

Where that NULL is for an optional "display" parameter and NULL says to
Cogl "please just try to do something sensible".

If you want some more control though you can manually construct a
CoglDisplay something like:

 display = cogl_display_new (NULL, NULL);
 cogl_gdl_display_set_plane (display, plane);
 if (!cogl_display_setup (display, &error))
   g_error ("Failed to setup a CoglDisplay: %s", error->message);

And in a similar fashion to cogl_context_new() you can optionally pass
a NULL "renderer" and/or a NULL "onscreen template" so Cogl will try to
just do something sensible.

If you need to change the CoglOnscreen defaults you can provide a
template something like:
  chain = cogl_swap_chain_new ();
  cogl_swap_chain_set_has_alpha (chain, TRUE);
  cogl_swap_chain_set_length (chain, 3);

  onscreen_template = cogl_onscreen_template_new (chain);
  cogl_onscreen_template_set_pixel_format (onscreen_template,
                                           COGL_PIXEL_FORMAT_RGB565);

  display = cogl_display_new (NULL, onscreen_template);
  if (!cogl_display_setup (display, &error))
    g_error ("Failed to setup a CoglDisplay: %s", error->message);
2011-04-11 17:54:35 +01:00
build build: Fix typo in the docs URI variable name 2011-04-07 15:09:15 +01:00
clutter Adds renderer,display,onscreen-template and swap-chain stubs 2011-04-11 17:54:35 +01:00
doc docs: Remove checks for whether an effect is disabled 2011-03-17 15:56:55 +00:00
po Czech translation 2011-04-07 18:28:06 +02:00
tests Removes the addition of the .exe extension to unit-test scripts, on win32. 2011-04-01 17:08:25 +01:00
.gitignore build: Generate README 2011-02-14 17:27:25 +00:00
AUTHORS AUTHORS: Note that the file is unmaintained 2011-03-14 14:16:16 +00:00
autogen.sh autogen.sh: make autoreconf use automake-1.11 when available 2010-12-30 12:08:28 +00:00
ChangeLog.pre-git-import Add a notice of deprecation in the pre-Git ChangeLog 2010-01-14 15:24:15 +00:00
clutter.doap doap: Update the project information 2011-04-04 15:33:24 +01:00
configure.ac build: Look for sed 2011-04-04 22:33:31 +01:00
COPYING Merge gobject-branch into trunk 2006-05-29 08:59:36 +00:00
Makefile.am build: Remove maintainer-clean rule 2011-02-22 18:32:01 +00:00
NEWS Release Clutter 1.6.6 (stable) 2011-02-21 12:47:09 +00:00
README.in docs: Mention the cookbook in the README 2011-02-21 16:41:28 +00:00
README.md README.md: fix a dumb typo 2011-03-14 14:00:12 +00:00

Clutter

What is Clutter?

Clutter is an open source software library for creating fast, compelling, portable, and dynamic graphical user interfaces.

Requirements

Clutter currently requires:

Clutter also has optional dependencies:

On X11, Clutter depends on the following extensions:

  • XComposite
  • XDamage
  • XExt
  • XFixes
  • XInput (1.x or 2.x)
  • XKB

If you are building the API reference you will also need:

If you are building the additional documentation you will also need:

  • xsltproc
  • jw (optional, for generating PDFs)

If you are building the Introspection data you will also need:

If you want support for profiling Clutter you will also need:

Resources

The official Clutter website is:

    http://www.clutter-project.org/

The API references for the latest stable release are available at:

    http://docs.clutter-project.org/docs/clutter/stable/
    http://docs.clutter-project.org/docs/cogl/stable/
    http://docs.clutter-project.org/docs/cally/stable/

The Clutter Cookbook is available at:

    http://docs.clutter-project.org/docs/clutter-cookbook/

New releases of Clutter are available at:

    http://source.clutter-project.org/sources/clutter/

The Clutter blog is available at:

    http://www.clutter-project.org/blog/

To subscribe to the Clutter mailing lists and read the archives, use the Mailman web interface available at:

    http://lists.clutter-project.org/

New bug page on Bugzilla:

    http://bugzilla.clutter-project.org/enter_bug.cgi?product=clutter
    http://bugzilla.clutter-project.org/enter_bug.cgi?product=cogl

Clutter is licensed under the terms of the GNU Lesser General Public License, version 2.1 or (at your option) later: see the COPYING file for more information.

Building and Installation

To build Clutter from a release tarball, the usual autotool triad should be followed:

  1. ./configure
  2. make
  3. make install

To build Clutter from a Git clone, run the autogen.sh script instead of the configure one. The autogen.sh script will run the configure script for you, unless the NOCONFIGURE environment variable is set to a non-empty value.

See also the BuildingClutter page on the wiki.

Versioning

Clutter uses the common "Linux kernel" versioning system, where even-numbered minor versions are stable and odd-numbered minor versions are development snapshots.

Different major versions break both API and ABI but are parallel installable. The same major version with differing minor version is expected to be ABI compatible with other minor versions; differing micro versions are meant just for bug fixing. On odd minor versions the newly added API might still change.

The micro version indicates the origin of the release: even micro numbers are only used for released archives; odd micro numbers are only used on the Git repository.

Contributing

If you want to hack on and improve Clutter check the HACKING file for general implementation guidelines, and the HACKING.backends for backend-specific implementation issues.

The CODING_STYLE file contains the rules for writing code conformant to the style guidelines used throughout Clutter. Remember: the coding style is mandatory; patches not conforming to it will be rejected by default.

The usual workflow for contributions should be:

  1. Fork the repository
  2. Create a branch (git checkout -b my_work)
  3. Commit your changes (git commit -am "Added my awesome feature")
  4. Push to the branch (git push origin my_work)
  5. Create an Issue with a link to your branch
  6. Sit back, relax and wait for feedback and eventual merge

Bugs

Bugs should be reported to the Clutter Bugzilla at:

    http://bugzilla.clutter-project.org/enter_bug.cgi?product=clutter
    http://bugzilla.clutter-project.org/enter_bug.cgi?product=cogl

You will need a Bugzilla account.

In the report you should include:

  • what system you're running Clutter on;
  • which version of Clutter you are using;
  • which version of GLib and OpenGL (or OpenGL ES) you are using;
  • which video card and which drivers you are using, including output of glxinfo and xdpyinfo (if applicable);
  • how to reproduce the bug.

If you cannot reproduce the bug with one of the tests that come with Clutter source code, you should include a small test case displaying the bad behaviour.

If the bug exposes a crash, the exact text printed out and a stack trace obtained using gdb are greatly appreciated.