936 lines
38 KiB
Plaintext
936 lines
38 KiB
Plaintext
Clutter - README
|
|
===============================================================================
|
|
|
|
Clutter is an open source software library for creating portable, fast,
|
|
visually rich and animated graphical user interfaces.
|
|
|
|
REQUIREMENTS
|
|
-------------------------------------------------------------------------------
|
|
|
|
Clutter currently requires:
|
|
|
|
• GLib >= 2.18.0
|
|
• Atk >= 1.17
|
|
• Cairo >= 1.6
|
|
• PangoCairo >= 1.20
|
|
• OpenGL >= 1.3 or 1.2+multitexturing, OpenGL ES 1.1 or OpenGL ES 2.0
|
|
• GLX, SDL, WGL or an EGL Implementation
|
|
|
|
Clutter also has optional dependencies:
|
|
|
|
• JSON-GLib >= 0.10 (optional, see --with-json below)
|
|
• GDK-Pixbuf >= 2.0 (optional, see --with-imagebackend below)
|
|
|
|
On X11, Clutter depends on the following extensions
|
|
|
|
• XComposite
|
|
• XDamage
|
|
• XExt
|
|
• XFixes
|
|
• XInput 1.x (if --enable-xinput is passed to configure)
|
|
• XKB
|
|
|
|
When running the OpenGL flavor, Clutter requires at least version 1.3
|
|
or 1.2 with the multitexturing extension. However to build Clutter
|
|
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 >= 1.13
|
|
|
|
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 >= 0.6.7
|
|
|
|
If you want support for profiling Clutter you will also need:
|
|
|
|
• UProf >= 0.2
|
|
|
|
UProf is available from:
|
|
|
|
git://git.moblin.org/uprof.git
|
|
|
|
RESOURCES
|
|
-------------------------------------------------------------------------------
|
|
|
|
The official Clutter website is:
|
|
|
|
http://www.clutter-project.org/
|
|
|
|
The API reference for the latest stable release and unstable developers
|
|
snapshot are available at:
|
|
|
|
http://docs.clutter-project.org/docs/clutter/stable/
|
|
http://docs.clutter-project.org/docs/clutter/unstable/
|
|
|
|
New releases of Clutter are available at:
|
|
|
|
http://source.clutter-project.org/sources/clutter/
|
|
|
|
The Clutter blog is 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
|
|
|
|
Clutter is licensed under the terms of the GNU Lesser General Public
|
|
License, version 2.1 or (at your option) later.
|
|
|
|
BUILDING AND INSTALLATION
|
|
-------------------------------------------------------------------------------
|
|
|
|
See the INSTALL file.
|
|
|
|
Clutter has additional command line options for the configure script:
|
|
|
|
--enable-debug=[no/minimum/yes]
|
|
Controls Clutter debugging level:
|
|
|
|
yes:
|
|
All GLib asserts, checks and support for runtime Clutter
|
|
debugging notes through CLUTTER_DEBUG. This is the default
|
|
value for developers snapshots.
|
|
|
|
minimum:
|
|
Just GType cast checks and support for runtime Clutter
|
|
debugging notes through CLUTTER_DEBUG. This is the default
|
|
for stable releases.
|
|
|
|
no:
|
|
No GLib asserts or checks and no support for runtime Clutter
|
|
debugging notes. Only use in extreme performance and/or size
|
|
optimization cases, though it is strongly discouraged.
|
|
|
|
--enable-cogl-debug=[no/minimum/yes]
|
|
Controls COGL debugging level (default=minimum):
|
|
|
|
yes:
|
|
Support for COGL debugging notes through COGL_DEBUG and
|
|
error checking for each GL primitive. This is useful mostly
|
|
to debug COGL itself.
|
|
|
|
minimum:
|
|
Support for COGL debugging notes through COGL_DEBUG. This is
|
|
the default for developers snapshots.
|
|
|
|
no:
|
|
Disable support for COGL runtime debugging notes.
|
|
|
|
--enable-maintainer-flags=[no/yes]
|
|
Use strict compiler flags. This defaults to 'yes' for developers
|
|
snapshots and to 'no' for stable releases.
|
|
|
|
--enable-gtk-doc
|
|
use gtk-doc to build API documentation (default=no). Requires gtk-doc
|
|
present on the target system.
|
|
|
|
--enable-docs=[no/yes]
|
|
Build additional documentation. Requires xsltproc for DocBook
|
|
conversion, and optionally jw for PDF generation.
|
|
|
|
--enable-gcov=[no/yes]
|
|
Build Clutter with coverage report support, provided by gcov. This
|
|
feature only works with the GNU Compiler Suite and gcov installed.
|
|
|
|
--enable-profile=[no/yes]
|
|
Build Clutter with profiling instrumentation. Requires the GNU
|
|
C Compiler and the UProf library.
|
|
|
|
--enable-conform=[yes/no]
|
|
Build the Clutter conformance test suite.
|
|
|
|
--with-flavour=[glx/eglx/eglnative/osx/win32/fruity]
|
|
Select the Clutter backend: (default=glx)
|
|
|
|
glx:
|
|
Fully featured GLX backend. Using Open GL.
|
|
|
|
eglx:
|
|
EGL/Open GL ES backend for EGL on X windows implementations
|
|
|
|
eglnative:
|
|
EGL/Open GL ES backend on 'native windowing system' - i.e
|
|
raw framebuffer. Expects the EGL implementation to provide
|
|
a createNativeWindow() call. Also it optionally supports
|
|
tslib for touchscreen events.
|
|
|
|
osx:
|
|
OS X backend. (EXPERIMENTAL)
|
|
|
|
win32:
|
|
Microsoft Windows(tm) WGL backend
|
|
|
|
fruity:
|
|
Apple iPod Touch(tm)/iPhone(tm) backend (EXPERIMENTAL)
|
|
|
|
--with-imagebackend=[gdk-pixbuf/quartz/internal]
|
|
Select the image loading backend used by COGL
|
|
|
|
gdk-pixbuf:
|
|
Depend on gdk-pixbuf-2.0 (default for the glx, eglx,
|
|
eglnative, win32 flavours and recommended)
|
|
|
|
quartz:
|
|
Depend on CoreGraphics (default for the osx flavour)
|
|
|
|
internal:
|
|
Internal JPEG and PNG loader. Should only be used
|
|
for testing on new platforms
|
|
|
|
--with-gles=[1.1/2.0]
|
|
Select the GLES version (for EGL backends) (default=1.1)
|
|
|
|
--with-json=[internal/check/system]
|
|
Select the JSON-GLib copy to use (default=check)
|
|
|
|
internal:
|
|
Use the internal copy of JSON-GLib for ClutterScript
|
|
|
|
check:
|
|
Check for the existence of a system copy of JSON-GLib
|
|
and if it is available, make Clutter depend on it
|
|
|
|
system:
|
|
Only use the system copy of JSON-GLib and warn if not found
|
|
|
|
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.
|
|
|
|
HACKING
|
|
-------------------------------------------------------------------------------
|
|
|
|
If you want to hack on and improve Clutter, check the contained TODO file for
|
|
pending tasks, 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.
|
|
|
|
BUGS
|
|
-------------------------------------------------------------------------------
|
|
|
|
Bugs should be reported to the Clutter Bugzilla at:
|
|
|
|
http://bugzilla.clutter-project.org/enter_bug.cgi?product=clutter
|
|
|
|
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.
|
|
|
|
CONTRIBUTING
|
|
-------------------------------------------------------------------------------
|
|
|
|
Patches should be submitted using Bugzilla. Patches fixing a bug should be
|
|
attached to the bug report; patches for new features or for fixing bugs not
|
|
yet reported should be attached to a newly opened bug. Patches should always
|
|
be in the unified diff format, using:
|
|
|
|
diff -Nuarp clutter.source clutter.patched > clutter-patch.diff
|
|
|
|
If diffing against the Git repository, you should use:
|
|
|
|
git diff > clutter-patch.diff
|
|
|
|
Or, better, commit locally and use `git format-patch` to generate a patch
|
|
containing authorship details, so that members of the Clutter development
|
|
team can credit your contribution properly.
|
|
|
|
RELEASE NOTES
|
|
-------------------------------------------------------------------------------
|
|
|
|
Relevant information for developers with existing Clutter applications
|
|
wanting to port to newer releases (see NEWS for general information on new
|
|
features).
|
|
|
|
Release Notes for Clutter 1.4
|
|
-------------------------------------------------------------------------------
|
|
|
|
* ClutterLayoutManager sub-classes overriding the set_container() virtual
|
|
function should chain up to the parent class's implementation.
|
|
|
|
Release Notes for Clutter 1.2
|
|
-------------------------------------------------------------------------------
|
|
|
|
* ClutterStageManager is now publicly available and documented API.
|
|
|
|
* Clutter now depends on the system copy of JSON-GLib, and will fall
|
|
back to the internal copy only if JSON-GLib is not installed.
|
|
|
|
* ClutterActor:opacity is now defined using GParamSpecUint instead of
|
|
GParamSpecUchar; the same interval of [ 0, 255 ] applies, and GValue
|
|
has internal transformation functions for converting between G_TYPE_UINT
|
|
and G_TYPE_UCHAR, so this change should be fully transparent to the
|
|
user of the code.
|
|
|
|
* On X11 Clutter will emulate XKB's detectable key auto-repeat; this means
|
|
that when holding down a key, Clutter will emit multiple CLUTTER_KEY_PRESS
|
|
events and a single CLUTTER_KEY_RELEASE event instead of a list of
|
|
CLUTTER_KEY_PRESS and CLUTTER_KEY_RELEASE pairs.
|
|
|
|
* On X11 and Win32 the default Stage is created when
|
|
clutter_stage_get_default() is called for the first time, and not as
|
|
part of the stage initialization.
|
|
|
|
Cogl API changes for Clutter 1.2
|
|
-------------------------------------------------------------------------------
|
|
|
|
* cogl_viewport is now deprecated in favour of cogl_set_viewport which
|
|
accepts a viewport offset.
|
|
|
|
* cogl_clip_push() is now deprecated and new code should use
|
|
cogl_clip_push_rectangle() instead. The old API wasn't consistent with other
|
|
Cogl APIs that specify model space rectangles using (x0,y0)(x1,y1) pairs.
|
|
|
|
* cogl_clip_push_window_rect() is now deprecated and new code should use
|
|
cogl_clip_push_window_rectangle(). The old API shouldn't have been defined
|
|
to take floats and the abbreviation wasn't consistent with other Cogl API.
|
|
|
|
* cogl_clip_stack_save() and cogl_clip_stack_restore() are deprecated, as
|
|
the functionality is redundant now that offscreen draw buffers own their
|
|
clip state and switching to/from offscreen rendering will automatically
|
|
save and restore the clip state.
|
|
|
|
* cogl_material_copy() was added. It is advised that developers use
|
|
this instead of cogl_material_new() when creating a material that is in some
|
|
way derived from another. This will allow Cogl to track material
|
|
ancestries/similarities and reduce the cost of GPU state changes.
|
|
|
|
* cogl_push_draw_buffer, cogl_set_draw_buffer and cogl_pop_draw_buffer are now
|
|
deprecated and new code should use the cogl_framebuffer_* API instead.
|
|
Code that previously did:
|
|
cogl_push_draw_buffer ();
|
|
cogl_set_draw_buffer (COGL_OFFSCREEN_BUFFER, buffer);
|
|
/* draw */
|
|
cogl_pop_draw_buffer ();
|
|
can now be re-written as:
|
|
cogl_push_framebuffer (buffer);
|
|
/* draw */
|
|
cogl_pop_framebuffer ();
|
|
|
|
* All cogl_<type>_ref() and cogl_<type>_unref() functions have been
|
|
deprecated, and superceded by cogl_handle_ref() and cogl_handle_unref()
|
|
respectively.
|
|
|
|
* The cogl_check_extension() function has been deprecated. This function
|
|
was never meant to be public, since it depends on calling glGetString()
|
|
before its invocation. Users of this function can be replaced by the
|
|
equivalent code:
|
|
|
|
gl_ext = glGetString (GL_EXTENSIONS);
|
|
- has_ext = cogl_check_extension (ext_name, gl_ext);
|
|
+ has_ext = strstr (gl_ext, ext_name) != NULL ? TRUE : FALSE;
|
|
|
|
Release Notes for Clutter 1.0
|
|
-------------------------------------------------------------------------------
|
|
|
|
* The clutter_actor_set_shader_param() function now takes a
|
|
GValue, which can be set using the clutter_value_set_shader()
|
|
family of functions. The floating point wrapper has been
|
|
rename clutter_actor_set_shader_param_float() to match the newly
|
|
added clutter_actor_set_shader_param_int().
|
|
|
|
* The Pango renderer API has been exposed as public API, after
|
|
a full rename from PangoClutter to CoglPango, to avoid namespace
|
|
collisions with upstream Pango. The Pango font map, renderer and
|
|
glyph cache can be used by third party code and depend only on
|
|
COGL.
|
|
|
|
* Both Clutter and COGL only allow including <clutter/clutter.h>
|
|
and <cogl/cogl.h> directly, respectively. This allows avoiding
|
|
breaking API every time a type definition is moved across
|
|
headers, and improves the reliability of third party code against
|
|
internal refactorings.
|
|
|
|
* COGL has an internal Color type, used to store a color definition
|
|
that can be efficiently used with the least amount of conversions
|
|
by both the GL and GLES implementations. The COGL API has been
|
|
changed to drop the usage of ClutterColor in favour of CoglColor.
|
|
|
|
* The fixed point API implementation Clutter uses internally has been
|
|
moved from the Clutter namespace to the COGL one.
|
|
|
|
* ClutterLabel and ClutterEntry have been removed from the API, as
|
|
both have been superceded by the ClutterText actor.
|
|
|
|
* ClutterCloneTexture has been removed from the API; in its place,
|
|
there is a generic ClutterClone actor which allows to "clone"
|
|
any existing actors -- even composite ones -- without using
|
|
frame buffer objects (FBOs).
|
|
|
|
* The ClutterEffectTemplate and clutter_effect_* functions have been
|
|
superceded by ClutterAnimation and thus removed from the public API.
|
|
|
|
* The ClutterBehaviourBspline has been superceded by the usage of
|
|
ClutterPath inside ClutterBehaviourPath, and thus removed from the
|
|
public API.
|
|
|
|
* ClutterColor API has received a much needed review to increase its
|
|
consistency. This has led to the following changes:
|
|
|
|
- clutter_color_parse() has been renamed to clutter_color_from_string()
|
|
and the order of the arguments has been changed
|
|
|
|
- the factor argument of clutter_color_shade() has been swapped with
|
|
the return location for the new color
|
|
|
|
- the fixed point entry points have been removed
|
|
|
|
- clutter_color_from_hls() and clutter_color_to_hls() do not
|
|
normalize the values in the [ 0, 255 ] interval but use the
|
|
correct HLS intervals:
|
|
|
|
Hue: [ 0, 360 )
|
|
Luminance: [ 0, 1 ]
|
|
Saturation: [ 0, 1 ]
|
|
|
|
* The ClutterFixed symbols have been completely removed: fixed-point
|
|
public entry points now take a CoglFixed.
|
|
|
|
* The -x and -u API have been removed. All the pixel-based API now
|
|
takes a float to allow sub-pixel precision; this is true also for
|
|
properties. WARNING: functions with variadic arguments (like
|
|
g_object_set(), g_object_get() and clutter_actor_animate()) do not
|
|
behave very well when dealing with integers instead of expected
|
|
floating point values, and vice versa. On 32bit machines it will
|
|
most likely lead to a crash. So:
|
|
|
|
g_object_set (actor, "width", 100, NULL);
|
|
|
|
is incorrect, and should be changed in:
|
|
|
|
g_object_set (actor, "width", 100.0, NULL);
|
|
|
|
* Composite actors that do not implement the Container interface
|
|
should implement the following virtual functions:
|
|
|
|
- void map (ClutterActor*)
|
|
- void unmap (ClutterActor*)
|
|
|
|
and chain up to the parent's implementation after calling
|
|
clutter_actor_map() or clutter_actor_unmap() on their children.
|
|
|
|
* Actors implementing the Container interface that have private
|
|
children that are not meant to be added/removed through the
|
|
Container API should implement the:
|
|
|
|
- void foreach_with_internals (ClutterContainer*,
|
|
ClutterCallback,
|
|
gpointer);
|
|
|
|
virtual function.
|
|
|
|
* Actors that perform direct transformations using the COGL API inside
|
|
their paint() implementation should override the apply_transform()
|
|
virtual function instead. Implementations of the apply_transform()
|
|
vfunc must chain up to the implementation of the parent class.
|
|
|
|
* The ClutterUnit type and the CLUTTER_UNITS_* conversion macros have
|
|
been removed: all Actors are now using sub-pixel precision directly
|
|
throughout the API. The new ClutterUnits type has been added as a
|
|
generic opaque storage for logical distance values.
|
|
|
|
* Timelines are now fully time-based: all the frame-related properties
|
|
and methods have been removed. ClutterTimeline::new-frame will provide
|
|
the elapsed milliseconds since the beginning of the Timeline, instead
|
|
of the current frame number. The clutter_timeline_new() constructor
|
|
takes the duration of the timeline in milliseconds, and thus it replaces
|
|
the clutter_timeline_new_for_duration() variant.
|
|
|
|
Cogl API changes for Clutter 1.0
|
|
-------------------------------------------------------------------------------
|
|
|
|
* All drawing functions now use a source material to determine how geometry is
|
|
filled. The source material is set via cogl_set_source. Or the convenience
|
|
functions cogl_set_source_color and cogl_set_source_texture.
|
|
|
|
"drawing functions" include: cogl_rectangle, cogl_texture_rectangle,
|
|
cogl_texture_multiple_rectangles, cogl_texture_polygon (though the
|
|
cogl_texture_* funcs have been renamed; see below for details),
|
|
cogl_path_fill/stroke and cogl_vertex_buffer_draw*.
|
|
|
|
cogl_texture_rectangle, cogl_texture_multiple_rectangles and
|
|
cogl_texture_polygon no longer take a texture handle; instead the current
|
|
source material is referenced. The functions have also been renamed to:
|
|
cogl_rectangle_with_texture_coords, cogl_rectangles_with_texture_coords
|
|
and cogl_polygon respectively.
|
|
|
|
Most code that previously did:
|
|
cogl_texture_rectangle (tex_handle, x, y,...);
|
|
needs to be changed to now do:
|
|
cogl_set_source_texture (tex_handle);
|
|
cogl_rectangle_with_texture_coords (x, y,....);
|
|
|
|
In the less likely case where you were blending your source texture with a
|
|
color like:
|
|
cogl_set_source_color4ub (r,g,b,a); /* (where r,g,b,a isn't just white) */
|
|
cogl_texture_rectangle (tex_handle, x, y,...);
|
|
you will need your own material to do that:
|
|
material = cogl_material_new ();
|
|
cogl_material_set_color4ub (r,g,b,a);
|
|
cogl_material_set_layer (material, 0, tex_handle));
|
|
cogl_set_source_material (material);
|
|
|
|
Code that uses the texture coordinates, 0, 0, 1, 1 don't need to use
|
|
cogl_rectangle_with_texture_coords since these are the coordinates that
|
|
cogl_rectangle will use.
|
|
|
|
For cogl_texture_polygon; as well as dropping the texture handle, the
|
|
n_vertices and vertices arguments were transposed for consistency. So
|
|
code previously written as:
|
|
cogl_texture_polygon (tex_handle, 3, verts, TRUE);
|
|
need to be written as:
|
|
cogl_set_source_texture (tex_handle);
|
|
cogl_polygon (verts, 3, TRUE);
|
|
|
|
* The arguments to cogl_rectangle, cogl_path_rectangle and
|
|
cogl_path_round_rectangle have been changed - for consistency - from
|
|
x, y, width, height, to x1, y1, x2, y2.
|
|
|
|
* A CoglMatrix type and utility API has been added; this is currently used to
|
|
support describing texture matrices.
|
|
|
|
* cogl_alpha_func has been removed, since this is now controlled using the
|
|
material API via cogl_material_set_alpha_test_function ()
|
|
|
|
* A Cogl Vertex Buffer API has been added that allows you to efficiently
|
|
manage arrays of vertex attributes in buffers that may be stored on
|
|
the GPU. These allow you to avoid the costs of repeatedy validating
|
|
vertex data and mapping it into the GPU.
|
|
|
|
* cogl_scale now supports scaling on the z axis
|
|
|
|
* cogl_clip_set* and cogl_clip_unset have been renamed to cogl_clip_push and
|
|
cogl_clip_pop respectively so they self document their stacking semantics.
|
|
|
|
* cogl_paint_init was renamed to cogl_clear and no longer disables lighting and
|
|
fogging. cogl_clear also now takes a mask of the auxiliary buffers you want
|
|
to clear so you can avoid redundant clears of buffers you aren't using.
|
|
|
|
* cogl_fog_set was renamed to cogl_set_fog and it now takes a mode argument
|
|
giving control over the fogging blend factor equation, so that the
|
|
density argument isn't just ignored. A cogl_disable_fog function was
|
|
also added.
|
|
|
|
* cogl_get_*_matrix were changed to use the CoglMatrix type instead of
|
|
GLfloat m[16] arrays.
|
|
|
|
* cogl_offscreen_blit_region, cogl_offscreen_blit were removed since they were
|
|
only implemnted for GL, not GLES, and it was assumed no one was using them.
|
|
|
|
* cogl_offscreen_new_multisample was removed since it only ever returned
|
|
COGL_INVALID_HANDLE so it wasn't usefull.
|
|
|
|
* The COGL_MASK_BUFFER type was removed, since there should be nicer ways of
|
|
exposing color mask if anyone wants it later. It was assumed that no one was
|
|
using this currently.
|
|
|
|
* COGLenum, COGLint and COGLuint which were simply typedefs for
|
|
GL{enum,int,uint} have been removed from the API and replaced with
|
|
specialised enum typedefs, int and unsigned int. These were causing
|
|
problems for generating bindings and also considered poor style.
|
|
|
|
* The cogl texture filter defines CGL_NEAREST and CGL_LINEAR etc are now
|
|
replaced by a namespaced typedef 'CoglTextureFilter' so they should be
|
|
replaced with COGL_TEXTURE_FILTER_NEAREST and COGL_TEXTURE_FILTER_LINEAR etc.
|
|
|
|
* The shader type defines CGL_VERTEX_SHADER and CGL_FRAGMENT_SHADER are handled
|
|
by a CoglShaderType typedef and should be replaced with
|
|
COGL_SHADER_TYPE_VERTEX and COGL_SHADER_TYPE_FRAGMENT.
|
|
|
|
* cogl_shader_get_parameteriv has been replaced by cogl_shader_get_type and
|
|
cogl_shader_is_compiled. More getters can be added later if desired.
|
|
|
|
* cogl_enable_depth_test has been renamed to cogl_set_depth_test_enabled and
|
|
a corresponding cogl_get_depth_test_enabled function has been added.
|
|
|
|
Release Notes for Clutter 0.8
|
|
-------------------------------------------------------------------------------
|
|
|
|
* The COGL GL wrapper API has been completely overhauled and now
|
|
contains many new features including new greatly improved texture
|
|
abstractions (slicing, mipmapping, deformations etc, greatly
|
|
simplifying ClutterTexture), image loading and abstraction, path
|
|
based primitive drawing, clipping, and improved FBO and shader
|
|
support. It is now also fully documented.
|
|
|
|
* GL Texture Rectangle ext is no longer used, the regular 2D NPOTS
|
|
extension is preffered instead but not required.
|
|
|
|
* Clutter now has basic suppport for multiple input devices assuming
|
|
the backend supports it (currently X11 based via XInput and Fruity
|
|
backends). New API supporting this includes
|
|
clutter_event_get_device_id, clutter_get_input_device_for_id,
|
|
clutter_grab_pointer_for_device & clutter_ungrab_pointer_for_device.
|
|
|
|
XInput support needs to be explicitly enabled at runtime by calling
|
|
clutter_x11_enable_xinput () before clutter_init. clutter_x11_has_xinput ()
|
|
can then be called after to check if XInput extension present and use-able.
|
|
|
|
* The functions that return the transformed position of an actor have
|
|
been renamed to be more explicit about it:
|
|
|
|
clutter_actor_get_abs_position - clutter_actor_get_transformed_position
|
|
clutter_actor_get_abs_size - clutter_actor_get_transformed_size
|
|
|
|
Their behaviour has not been changed.
|
|
|
|
* To increase portability, Clutter does not strictly depend on
|
|
GdkPixbuf anymore; this means that you will have to include
|
|
<gdk-pixbuf/gdk-pixbuf.h> yourself if you are operating with
|
|
GdkPixbuf objects and not including that header. The GdkPixbuf-based
|
|
API has been removed from Clutter core:
|
|
|
|
clutter_texture_new_from_pixbuf
|
|
clutter_texture_set_pixbuf
|
|
clutter_texture_get_pixbuf
|
|
|
|
are all deprecated functions. It is still possible to load a GdkPixbuf
|
|
into a ClutterTexture with this sample code:
|
|
|
|
clutter_texture_set_from_rgb_data (texture,
|
|
gdk_pixbuf_get_pixels (pixbuf),
|
|
gdk_pixbuf_get_has_alpha (pixbuf),
|
|
gdk_pixbuf_get_width (pixbuf),
|
|
gdk_pixbuf_get_height (pixbuf),
|
|
gdk_pixbuf_get_rowstride (pixbuf),
|
|
gdk_pixbuf_get_has_alpha (pixbuf) ? 4
|
|
: 3,
|
|
0,
|
|
&error);
|
|
|
|
ClutterTexture also now has a new filename property and
|
|
clutter_texture_new_from_file which is intended as an alternate to
|
|
common previous GdkPixbuf primary usage (i.e loading images from
|
|
disk).
|
|
|
|
To read texture data back into a pixbuf or system memory use a combination
|
|
of clutter_texture_get_cogl_texture & cogl_texture_get_data.
|
|
|
|
The clutter-gtk integration library has API for using GdkPixbuf with
|
|
ClutterTextures (among others).
|
|
|
|
ClutterTexture now supports a keep-aspect property which is set to FALSE
|
|
by default.
|
|
|
|
* clutter_texture_from_actor will now reparent source actors if they
|
|
are not parented. This behaviour may change in future releases.
|
|
There are known not yet fixed issues with source actors that set
|
|
depth or use clipping.
|
|
|
|
* The size negotiation API has been completely changed in order to allow
|
|
the creation of non-fixed layout managers. These functions have been
|
|
removed:
|
|
|
|
clutter_actor_request_coords()
|
|
clutter_actor_query_coords()
|
|
|
|
from the ClutterActor API, as well as their virtual functions inside
|
|
the ClutterActorClass. The size of an actor is now split into two
|
|
different concepts: the preferred size (width and height
|
|
separatedly) and the size that has been allocated by the container
|
|
to which that actor belongs. Clutter still defaults to the fixed
|
|
layout management (i.e ClutterGroup) of the actors, but supports
|
|
fluid layout managers written using the new API.
|
|
|
|
Composite actors (actors with 'private' children not implementing the
|
|
container interface) now need to implement an allocate method here pass
|
|
an allocation to any composite children.
|
|
|
|
* Clutter now depends on PangoCairo for the font rendering. The PangoClutter
|
|
API is still considered semi-private and no guarantees are made on its
|
|
stability.
|
|
|
|
* ClutterShader API has been slightly changed: the ClutterStage:bound
|
|
property, clutter_shader_bind() and clutter_shader_is_bound() have
|
|
been renamed to :compiled, clutter_shader_compile() and
|
|
clutter_shader_is_compiled(), respectively. The previously semi-private
|
|
clutter_shader_release_all() function is now not exported anymore.
|
|
|
|
* ClutterStage is not an abstract type anymore: it can be instantiated
|
|
using clutter_stage_new() and it can be properly subclassed. If the
|
|
backend supports multiple stages, every stage will be a new window,
|
|
whose lifetime will have to be managed by the developer. Clutter will
|
|
still create the default stage, and guarantees that every call to
|
|
clutter_stage_get_default() will return exactly the same pointer.
|
|
|
|
* Actors now have a new 'show-on-set-parent' property set to TRUE by
|
|
default. With this property set to TRUE, actors will automatically
|
|
have clutter_actor_show() called on them when a parent is set (i.e
|
|
added to a container).
|
|
|
|
* Clutter now features support for multiple stages assuming supported
|
|
by the backend. See test-multistage.c for example of usage. This
|
|
does not change the automatic creation of the default stage.
|
|
A single GL context is used across all stages meaning GL resources
|
|
are shared.
|
|
|
|
* There is now an experimental native iPod Touch/iPhone UIKit backend
|
|
named 'fruity'.
|
|
|
|
* There is now an experimental native Win32 WGL backend.
|
|
|
|
* COGL (and therefor Clutter) now optionally features initial support for
|
|
OpenGL ES 2.0. It features support for shaders.
|
|
|
|
* Some more focused timeline unit tests have been added and some tweaks to
|
|
timeline semantics were made; E.g. For a 10 frame timeline here are some
|
|
points about the semantics:
|
|
- When you create a timeline it starts with current_frame_num == 0
|
|
- After starting a timeline, the first timeout is for current_frame_num == 1
|
|
(Notably it isn't 0 since there is a delay before the first timeout signals
|
|
so re-asserting the starting frame (0) wouldn't make sense.)
|
|
- For a non looping timeline the last timeout would be for
|
|
current_frame_num == 10
|
|
- For a looping timeline the timeout for current_frame_num == 10 would be
|
|
followed by a timeout for current_frame_num == 1 and frame 0 is considered
|
|
== frame 10.
|
|
- Asking for a timeline of N frames might better be described as asking for
|
|
a timeline of _length_ N.
|
|
|
|
* The behaviour of clutter_actor_get_opacity() has been slightly changed;
|
|
instead of returning the composited opacity of the entire parents chain
|
|
of an actor, clutter_actor_get_opacity() does what you mean, and returns
|
|
the opacity set with clutter_actor_set_opacity(). The composited
|
|
opacity value is now returned by clutter_actor_get_paint_opacity().
|
|
|
|
* Until 0.6, clutter_label_get_color() would have returned a ClutterColor
|
|
with the alpha component equal to the composited opacity of the label.
|
|
Now, clutter_label_get_color() returns a copy of the exact color set
|
|
with clutter_label_set_color().
|
|
|
|
* The ClutterEntry actor will automatically handle key events inside
|
|
a key-press-event handler. This deprecates the usage of
|
|
clutter_entry_handle_key_event() to update the contents of the
|
|
entry using the ClutterKeyEvent.
|
|
|
|
* The Clutter X11 and GLX backends feature support for wrapping external
|
|
X Drawables (such as windows as pixmaps) via the 'texture_from_pixmap' GLX
|
|
extension if available and fallback to slower XGetImage copies if not.
|
|
|
|
* ClutterContainer can have per child custom properties via ClutterChildMeta.
|
|
|
|
Release Notes for Clutter 0.6
|
|
-------------------------------------------------------------------------------
|
|
|
|
* Now that every actor has events, the class signal handlers have been
|
|
removed from ClutterStageClass and moved into ClutterActorClass.
|
|
|
|
* The CLUTTER_2BUTTON_PRESS and CLUTTER_3BUTTON_PRESS event types have been
|
|
removed in favour of the ClutterButtonEvent:click_count counter
|
|
|
|
* X11 related called for glx and eglx backends are now shared and moved into
|
|
a clutter_x11 prefix.
|
|
|
|
* Scaling with gravity functionality was replaced by more generic and
|
|
powerful anchor point.
|
|
|
|
* The ClutterLayout interface, the ClutterBox and its implementations have
|
|
been moved outside Clutter core.
|
|
|
|
* The Effects API has been simplified, and it only requires the final value
|
|
of the effect instead of both the start and end value.
|
|
|
|
* The per-axis rotation API has been deprecated in favour of a single
|
|
pair of accessors, clutter_actor_set_rotation() and
|
|
clutter_actor_get_rotation().
|
|
|
|
* Every actor sub-class that is overriding the ClutterActor::request_coords()
|
|
virtual function *must* chain up to the parent's implementation in order
|
|
to store the bounding box inside the ClutterActor private data.
|
|
|
|
* It is now impossible to call clutter_actor_destroy() on the stage. Backends
|
|
will have to unset the CLUTTER_ACTOR_IS_TOPLEVEL private flag to actually
|
|
destroy the stage.
|
|
|
|
* The default value of the ClutterLabel:wrap property has been changed from
|
|
TRUE to FALSE.
|
|
|
|
* All the behaviours properties have been renamed to match the $PROPERTY-start
|
|
and $PROPERTY-end convention.
|
|
|
|
* The clutter_group_add() function has been "undeprecated" and reimplemented
|
|
as a commodity macro; a clutter_stage_add() commodity macro has also been
|
|
added. Both macros just safely wrap clutter_container_add_actor().
|
|
|
|
* The ClutterContainer::find_child_by_id() virtual function has been removed;
|
|
Clutter keeps track of every actor, so there's no need to recurse into
|
|
containers anymore.
|
|
|
|
* The unused ClutterActor::set_depth() and ClutterActor::get_depth() virtual
|
|
functions have been removed.
|
|
|
|
* It is now possible to roundtrip the string created by
|
|
clutter_color_to_string() to clutter_color_parse().
|
|
|
|
* The amount of motion events is now being throttled using the default frame
|
|
rate setting as the base value to compute the default and maximum frequency
|
|
of motion events to be delivered to every actor.
|
|
|
|
* ClutterAngle usage has been removed from the public API: it is an internal
|
|
optimization, which can be used for faster angle computations; users of
|
|
ClutterAngle now take a fixed point number in form of a ClutterFixed.
|
|
|
|
* ClutterGravity usage when scaling has been superceded by the anchor point.
|
|
|
|
* The precision of the clutter_sqrti() algorithm has been improved for small
|
|
values.
|
|
|
|
* ClutterBehaviourScale constructor, scale properties and accessors have
|
|
been changed to accomodate the scaling factors on both the X and Y axis,
|
|
matching the clutter_actor_set_scale() function. This also changed the
|
|
clutter_effect_scale() function, which now accepts the final scale
|
|
factor on both the X and Y axis. The gravity property has also been
|
|
removed, as it behaved incorrectly with regards to the anchor point. When
|
|
scaling an actor using a BehaviourScale, the anchor point should be set
|
|
before applying the behaviour (remember to adjust the positioning as
|
|
well by factoring in the anchor point).
|
|
|
|
* The clutter_do_event() is now public; it can be used to feed an event to
|
|
Clutter and let it generate the capture-bubble signal emissions; it should
|
|
not be used by applications.
|
|
|
|
* In the X11-based backends, the DestroyNotify event is not propagated to
|
|
Clutter core if the stage is using a foreign window.
|
|
|
|
* To avoid method name collisions between ClutterActor and ClutterEntry
|
|
in high-level languages, the clutter_entry_set_position() and
|
|
clutter_entry_get_position() functions have been renamed to
|
|
clutter_entry_set_cursor_position() and clutter_entry_get_cursor_position()
|
|
respectively.
|
|
|
|
Release Notes for Clutter 0.4.0
|
|
-------------------------------------------------------------------------------
|
|
|
|
* clutter_actor_show_all does not recurse for groups at least (this is to
|
|
match the original group_show_all behaviour). This is like 0.3 but was
|
|
never noted.
|
|
|
|
* ClutterBox API has changed: clutter_box_pack_start() and
|
|
clutter_box_pack_end() have been removed in favour of the clutter_box_pack()
|
|
API.
|
|
|
|
* Both clutter_threads_enter() and clutter_threads_leave() have been
|
|
removed from the API, as they just created confusion and the wrong
|
|
idea that Clutter is either thread-safe or thread-aware. Full
|
|
thread-awareness is arriving in the next revision (see bug #429).
|
|
|
|
* The ClutterBehaviourRotate and ClutterBehaviourEllsipse APIs have been
|
|
overhauled.
|
|
|
|
Release Notes for Clutter 0.3.1
|
|
-------------------------------------------------------------------------------
|
|
|
|
* clutter_actor_apply_transform_to_point() parameters changed to use
|
|
ClutterVertices.
|
|
|
|
* New 'Native API' backend expects EGL implementation to provide a
|
|
CreateNativeWindow() API call.
|
|
|
|
* Exisiting X11 based egl backend public API calls now prefixed eglx.
|
|
|
|
Release Notes for Clutter 0.3
|
|
-------------------------------------------------------------------------------
|
|
|
|
* ClutterTexture changes:
|
|
+ clutter_texture_set_pixbuf() now takes a GError paremeter.
|
|
+ clutter_texture_upload_data has been split into two new and
|
|
more functional versions; clutter_texture_set_from_rgb_data(),
|
|
clutter_texture_set_from_yuv_data().
|
|
|
|
* The GLX specific API has been moved to the GLX backend code and
|
|
it's now under the ClutterGlx namespace.
|
|
|
|
* The priority of the various users of the GLib main loop has been
|
|
reviewed and changed were necessary. Every paint is queued with a
|
|
priority of G_PRIORITY_DEFAULT + 10; timelines are allocated with
|
|
a G_PRIORITY_DEFAULT + 30 priority; events are processed with a
|
|
G_PRIORITY_DEFAULT priority. This ensures that events are processed
|
|
before the paints take place.
|
|
|
|
* The ClutterActor::allocate_coords() has been renamed to
|
|
ClutterActor::query_coords(), in order to clarify its usage.
|
|
|
|
* Actors overriding ClutterActor::request_coords() and
|
|
ClutterActor::query_coords() must convert sizes obtained from the
|
|
public API from pixels to ClutterUnits, using the conversion
|
|
macros found in clutter-units.h. The conversion will be necessary
|
|
until the public API will switch over to returning the generic
|
|
units too.
|
|
|
|
* Users of Intel video cards should find that disabling sync-to-vblank
|
|
is no longer necessary. In case Clutter applications take really
|
|
long times for redrawing and appear stuck and unresponsive, the
|
|
sync-to-vblank feature might still be the culprit; in that case, use
|
|
"export CLUTTER_VBLANK=none" to disable it and file a bug reporting the
|
|
video card model, the driver version and the X server version.
|
|
|
|
* ClutterTimeline objects now share the same timeout pool (see the
|
|
ClutterTimeoutPool API). This might cause problems with heavily
|
|
threaded libraries without integration with the GLib main loop.
|
|
If an application experiences bad behaviours during animations
|
|
use "export CLUTTER_TIMELINE=no-pool" to disable the timeout pool.
|
|
|
|
* clutter_color_parse() now handles color definitions with alpha. Alpha
|
|
will default to fully Opaque rather than fully transparent if not specified.
|
|
|
|
* The Clutter examples/ directory has been removed and replaced with a
|
|
tests/ directory.
|
|
|
|
* The ClutterEvent API has been changed, and specific functions have been
|
|
removed in favour of event-agnostic ones.
|
|
|
|
* The ClutterStage::input-event signal has been removed. All the events now
|
|
emit the ClutterStage::event and ClutterStage::event-after signals, for
|
|
generic event handling.
|
|
|
|
* Runtime options now dependant on backend.
|
|
|
|
* ClutterGroup API to add, remove and list children has been deprecated in
|
|
favour of ClutterContainer API. The ClutterGroup::add and
|
|
ClutterGroup::remove signals have been deprecated:
|
|
ClutterContainer::actor-added and ClutterContainer::actor-removed should
|
|
be used instead.
|