b11f6c9e11
The README file is generated by the configure script so that it can include the required dependency version numbers. However there was no corresponding AC_SUBST calls for the versions so the README would be left with @THESE_MARKERS@.
165 lines
5.4 KiB
Plaintext
165 lines
5.4 KiB
Plaintext
README for Cogl @COGL_VERSION@
|
|
===============================================================================
|
|
|
|
Note: This file is delimited with -- markers so it is possible to split
|
|
sections out for other purposes, such as for release notes.
|
|
|
|
--
|
|
DESCRIPTION
|
|
-------------------------------------------------------------------------------
|
|
|
|
Cogl is a small open source library for using 3D graphics hardware to draw
|
|
pretty pictures. The API departs from the flat state machine style of
|
|
OpenGL and is designed to make it easy to write orthogonal components that
|
|
can render without stepping on each others toes.
|
|
|
|
As well aiming for a nice API, we think having a single library as opposed
|
|
to an API specification like OpenGL has a few advantages too; like being
|
|
able to paper over the inconsistencies/bugs of different OpenGL
|
|
implementations in a centralized place, not to mention the myriad of OpenGL
|
|
extensions. It also means we are in a better position to provide utility
|
|
APIs that help software developers since they only need to be implemented
|
|
once and there is no risk of inconsistency between implementations.
|
|
|
|
Having other backends, besides OpenGL, such as drm, Gallium or D3D are
|
|
options we are interested in for the future.
|
|
|
|
--
|
|
REQUIREMENTS
|
|
-------------------------------------------------------------------------------
|
|
|
|
Cogl currently only requires:
|
|
|
|
• GLib ≥ @GLIB_REQ_VERSION@
|
|
• OpenGL ≥ 1.3 (or 1.2 + multitexturing), or OpenGL ES 2.0 (or 1.1)
|
|
• GLX, AGL, WGL or an EGL implementation
|
|
|
|
Cogl also has optional dependencies:
|
|
|
|
• GDK-Pixbuf ≥ @GDK_PIXBUF_REQ_VERSION@
|
|
- for image loading
|
|
• Cairo ≥ @CAIRO_REQ_VERSION@
|
|
- for debugging texture atlasing (debug builds only)
|
|
|
|
The optional Cogl Pango library requires:
|
|
• Cairo ≥ @CAIRO_REQ_VERSION@
|
|
• PangoCairo ≥ @PANGOCAIRO_REQ_VERSION@
|
|
|
|
On X11, Cogl depends on the following extensions
|
|
|
|
• XComposite ≥ @XCOMPOSITE_REQ_VERSION@
|
|
• XDamage
|
|
• XExt
|
|
• XFixes ≥ @XFIXES_REQ_VERSION@
|
|
|
|
When running with OpenGL, Cogl requires at least version 1.3
|
|
or 1.2 with the multitexturing extension. However to build Cogl
|
|
you will need the latest GL headers which can be obtained from:
|
|
|
|
http://www.khronos.org
|
|
|
|
If you are building the API reference you will also need:
|
|
|
|
• GTK-Doc ≥ @GTK_DOC_REQ_VERSION@
|
|
|
|
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:
|
|
|
|
• GObject-Introspection ≥ @GI_REQ_VERSION@
|
|
|
|
GObject-Introspection is available from:
|
|
|
|
git://git.gnome.org/gobject-introspection
|
|
|
|
If you want support for profiling Cogl you will also need:
|
|
|
|
• UProf ≥ @UPROF_REQ_VERSION@
|
|
|
|
UProf is available from:
|
|
|
|
git://github.com/rib/UProf.git
|
|
|
|
--
|
|
DOCUMENTATION
|
|
-------------------------------------------------------------------------------
|
|
|
|
The API references for the latest stable release are available at:
|
|
|
|
http://docs.clutter-project.org/docs/cogl/stable/
|
|
|
|
The experimental 2.0 API can be found here:
|
|
|
|
http://docs.clutter-project.org/docs/cogl-2.0-experimental/stable/
|
|
|
|
Note: The conflicting "stable" at the end refers to the fact
|
|
to overall Cogl release status, not the documentation specifically.
|
|
|
|
--
|
|
LICENSE
|
|
-------------------------------------------------------------------------------
|
|
|
|
Most of Cogl is licensed under the terms of the GNU Lesser General Public
|
|
License, version 2.1 or (at your option) later. Some files are licensed under
|
|
more permissive licenses MIT or BSD style licenses though so please see
|
|
individual files for details.
|
|
|
|
--
|
|
BUILDING AND INSTALLATION
|
|
-------------------------------------------------------------------------------
|
|
|
|
Please refer to the INSTALL document.
|
|
|
|
--
|
|
BUGS
|
|
-------------------------------------------------------------------------------
|
|
|
|
Please report bugs here:
|
|
|
|
http://bugzilla.gnome.org/enter_bug.cgi?product=clutter
|
|
|
|
You will need a Bugzilla account.
|
|
|
|
Please include the following in bug reports:
|
|
|
|
• what system you're running Cogl on;
|
|
• which version of Cogl 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
|
|
Cogl's source code, it can help a lot to 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.
|
|
|
|
--
|
|
CONTRIBUTING
|
|
-------------------------------------------------------------------------------
|
|
|
|
The CODING_STYLE file describes the coding style we use throughout Cogl,
|
|
please try your best to conform to this style because the consistency
|
|
really helps keep the code maintainable.
|
|
|
|
We can accept contributions in several ways:
|
|
• Either as patches attached to bugs on bugzilla
|
|
- For this you may be interested in using git-bz.
|
|
|
|
See http://git.fishsoup.net/man/git-bz.html for details
|
|
• You can email us patches
|
|
- For this we recommend using git-send-email
|
|
|
|
• You can create a remote branch and ask us to pull from that for more
|
|
substantial changes.
|
|
- For this we recommend using github.
|
|
|
|
Ideally standalone patches should be created using git format-patch since
|
|
that makes it easiest to import the patch with a commit message into a
|
|
git repository.
|