README.in 55.2 KB
Newer Older
Emmanuele Bassi's avatar
Emmanuele Bassi committed
1
README for Clutter @CLUTTER_VERSION@
2
===============================================================================
3

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

7 8 9
REQUIREMENTS
-------------------------------------------------------------------------------

Emmanuele Bassi's avatar
Emmanuele Bassi committed
10 11
Clutter currently requires:

Emmanuele Bassi's avatar
Emmanuele Bassi committed
12
  • GLib ≥ @GLIB_REQ_VERSION@
13
  • Cogl ≥ @COGL_REQ_VERSION@
Emmanuele Bassi's avatar
Emmanuele Bassi committed
14 15 16 17
  • JSON-GLib ≥ @JSON_GLIB_REQ_VERSION@
  • Atk ≥ @ATK_REQ_VERSION@
  • Cairo ≥ @CAIRO_REQ_VERSION@
  • PangoCairo ≥ @PANGO_REQ_VERSION@
18

19
When building the X11 backend, Clutter depends on the following extensions:
20

21
  • XComposite ≥ @XCOMPOSITE_REQ_VERSION@
22 23
  • XDamage
  • XExt
Emmanuele Bassi's avatar
Emmanuele Bassi committed
24
  • XInput (1.x or 2.x)
25
  • XKB
26

27 28 29 30 31 32 33 34 35 36 37 38 39
When building the Wayland backend, Clutter also depends on:

  • wayland-client
  • xkbcommon

When building the GDK backend, Clutter also depends on:

  • gdk-3.0 > @GDK_REQ_VERSION@

When building the CEx100 backend, Clutter also depends on:

  • libgdl

40 41 42
When building the evdev input backend, Clutter also depends on:

  • xkbcommon
43 44
  • libudev ≥ @LIBUDEV_REQ_VERSION@
  • libinput ≥ @LIBINPUT_REQ_VERSION@
45

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

Emmanuele Bassi's avatar
Emmanuele Bassi committed
48
  • GTK-Doc ≥ @GTK_DOC_REQ_VERSION@
49

50 51 52 53 54
If you are building the additional documentation you will also need:

  • xsltproc
  • jw (optional, for generating PDFs)

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

Emmanuele Bassi's avatar
Emmanuele Bassi committed
57
  • GObject-Introspection ≥ @GI_REQ_VERSION@
58

59 60 61 62
GObject-Introspection is available from:

  git://git.gnome.org/gobject-introspection

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

Emmanuele Bassi's avatar
Emmanuele Bassi committed
65
  • UProf ≥ @UPROF_REQ_VERSION@
66 67 68

UProf is available from:

69
  git://github.com/rib/UProf.git
70

71
RESOURCES
72 73 74 75 76 77
-------------------------------------------------------------------------------

The official Clutter website is:

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

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

80
   http://docs.clutter-project.org/docs/clutter/stable/
81 82
   http://docs.clutter-project.org/docs/cogl/stable/
   http://docs.clutter-project.org/docs/cally/stable/
83

84 85 86 87
The Clutter Cookbook is available at:

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

88
New releases of Clutter are available at:
89

90
   http://source.clutter-project.org/sources/clutter/
91
   http://download.gnome.org/sources/clutter/
92

93
The Clutter blog is available at:
94 95 96

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

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

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

102
New bug page on Bugzilla:
103

104
   http://bugzilla.gnome.org/enter_bug.cgi?product=clutter
105

106 107
Clutter is licensed under the terms of the GNU Lesser General Public
License, version 2.1 or (at your option) later.
108

109
BUILDING AND INSTALLATION
110
-------------------------------------------------------------------------------
111

112 113 114 115 116 117 118 119 120 121 122 123 124 125 126
To build Clutter from a release tarball, the usual autotool triad should
be followed:

  $ ./configure
  $ make
  # 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 wiki page:

  http://wiki.clutter-project.org/wiki/BuildingClutter
127 128

Clutter has additional command line options for the configure script:
129

130
 --enable-debug=[no/minimum/yes]
131 132 133 134 135
	Controls Clutter debugging level:

	yes:
                All GLib asserts, checks and support for runtime Clutter
                debugging notes through CLUTTER_DEBUG. This is the default
136
                value for developers snapshots.
137 138 139 140 141 142 143 144 145

        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
146
                optimization cases, though it is strongly discouraged.
147

148
 --enable-maintainer-flags=[no/yes/error]
149 150 151
        Use strict compiler flags. This defaults to 'yes' for building from
        Git to 'no' for tarball releases. If 'error' is used, then -Werror
        will be enabled (if available).
152

153 154
 --enable-gtk-doc
	use gtk-doc to build API documentation (default=no). Requires gtk-doc
155
	present on the target system.
156

157
 --enable-docs=[no/yes]
158
        Build additional documentation. Requires xsltproc for DocBook
159
        conversion, and optionally jw for PDF generation.
160

161 162 163 164 165 166 167 168
 --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.

169 170 171 172 173
 --disable-tests
        Disable building the Clutter tests suite.

 --disable-examples
        Disable building the Clutter API reference examples.
174

175 176 177
 --enable-deprecated=[yes/no]
        Whether deprecated symbols should be available when compiling Clutter.

178 179 180
 --disable-Bsymbolic
        Disable linking with -Bsymbolic.

181 182
 --enable-x11-backend=[yes/no/check]
        Enable the X11 backend. (default=check)
183

184 185
 --enable-win32-backend=[yes/no/check]
        Enable the native Microsoft Windows backend. (default=check)
186

187 188
 --enable-quartz-backend=[yes/no/check]
        Enable the native Quartz backend. (default=check)
189

190 191
 --enable-gdk-backend=[yes/no/check]
        Enable the GDK backend. (default=check)
192

193
 --enable-wayland-backend=[yes/no]
194 195 196 197
        Enable the Wayland client backend. (default=no) [EXPERIMENTAL]

 --enable-cex100-backend=[yes/no]
        Enable the CEx100 platform backend. (default=no) [EXPERIMENTAL]
198

199 200
 --enable-egl-backend=[yes/no]
        Enable the EGL framebuffer backend. (default=no)
201

202 203
 --enable-tslib-input=[yes/no]
        Enable the TSLib input backend. (default=no) [EXPERIMENTAL]
204

205 206
 --enable-evdev-input=[yes/no]
        Enable the evdev input backend. (default=no) [EXPERIMENTAL]
207

208 209
See also the INSTALL file generated by autotools for further information.

210
VERSIONING
211
-------------------------------------------------------------------------------
212 213 214 215 216

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

Emmanuele Bassi's avatar
Emmanuele Bassi committed
217 218 219 220 221
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.
222

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

HACKING
228
-------------------------------------------------------------------------------
229

230 231 232
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.
233 234 235

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

BUGS
239
-------------------------------------------------------------------------------
240

241
Bugs should be reported to the Clutter Bugzilla at:
242

243
  http://bugzilla.gnome.org/enter_bug.cgi?product=clutter
244

245
You will need a Bugzilla account.
246 247

In the report you should include:
248

Emmanuele Bassi's avatar
Emmanuele Bassi committed
249 250
  • what system you're running Clutter on;
  • which version of Clutter you are using;
251
  • which version of GLib, Cogl, and OpenGL (or OpenGL ES) you are using;
Emmanuele Bassi's avatar
Emmanuele Bassi committed
252
  • which video card and which drivers you are using, including output of
253
    glxinfo and xdpyinfo (if applicable);
Emmanuele Bassi's avatar
Emmanuele Bassi committed
254
  • how to reproduce the bug.
255 256 257 258 259 260 261 262

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.

263
CONTRIBUTING
264
-------------------------------------------------------------------------------
265

266 267
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
268 269 270
yet reported should be attached to a newly opened bug.

Patches should always be in the unified diff format, using:
271 272 273

  diff -Nuarp clutter.source clutter.patched > clutter-patch.diff

274
If diffing against the Git repository, you should use:
275

Emmanuele Bassi's avatar
Emmanuele Bassi committed
276
  git diff > clutter-patch.diff
277

278
Or, better: commit locally and use `git format-patch` to generate a patch
279 280 281
containing authorship details, so that members of the Clutter development
team can credit your contribution properly.

282 283 284 285 286 287 288 289
Another useful tool for interacting with Git and Bugzilla is git-bz(1):

  http://git.fishsoup.net/man/git-bz.html

Which is available here:

  http://git.fishsoup.net/cgit/git-bz/

290 291 292 293 294
Patches submitted against Clutter have to pass the conformance test suite, or,
if possible, add new unit tests for the conformance test suite in case of new
features. Ensure you run the conformance test suite every for every patch you
wish to submit, by using:

295
  make -C tests/conform check
296

297
and verifying that the whole test suite passes.
298

299
RELEASE NOTES
300
-------------------------------------------------------------------------------
301

302
Relevant information for developers with existing Clutter applications
303 304
wanting to port to newer releases (see NEWS for general information on new
features).
305

Emmanuele Bassi's avatar
Emmanuele Bassi committed
306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324
Release Notes for Clutter 1.18
-------------------------------------------------------------------------------

• Until 1.18, ClutterStage removed its children during its dispose()
  implementation, before the default ClutterActor::destroy() implementation
  would run. ClutterStage will now destroy the children when it is destroyed
  to ensure that the children are destroyed, and that custom code can remove
  references through the ClutterActor::destroy signal.

• Clutter does not depend on the XFIXES extension API on X11 any more. Before
  1.18 Clutter used the XFIXES API to hide the cursor; the API is less than
  useful for toolkits and applications, so Clutter unconditionally uses the
  fall back code that was in place in case XFIXES was not available.

• ClutterText emits the ::insert-text and ::delete-text signals before the
  contents of the ClutterTextBuffer are changed, as documented. The signal
  emission cannot be guaranteed if the ClutterTextBuffer API is used instead
  of the ClutterText API.

325 326 327 328
• Starting from 1.18, the Clutter evdev input device backend no longer uses
  libevdev and libgudev directly, but relies on libinput for discovering,
  reading and processing input devices.

329 330 331 332 333 334
• The Clutter evdev input device backend was already considered
  experimental and not subject to Clutter's API and ABI stabitility
  guarantees. Starting from 1.18, users have to explicitly acknowldge
  this by having to #define CLUTTER_ENABLE_COMPOSITOR_API to use its
  public API.

335 336 337 338 339 340 341 342 343 344
Release Notes for Clutter 1.16
-------------------------------------------------------------------------------

• Implicit transitions will not be created on actors that are not mapped,
  unless they are in a cloned branch of the scene graph. This was never an
  approved case, as ClutterActor would implicitly skip layout and paint on
  unmapped actors, but now it's being enforced through the animation machinery
  as well. Using explicit transitions still works, as explicit transitions
  completely place the developer in charge.

345 346 347 348 349 350
Release Notes for Clutter 1.14
-------------------------------------------------------------------------------

• The X11 backend (both core X events and XInput 2 backends) now mask out
  scroll lock and num lock modifiers from the event state.

351 352 353
Release Notes for Clutter 1.12
-------------------------------------------------------------------------------

354
• ClutterBinLayout no longer requests or allocates size for children that are
355 356
  not visible, which is how the other layout managers work.

357 358 359 360 361 362 363 364 365 366
• The expansion and alignment layout properties in all the layout managers
  that provide them have been deprecated in favour of the equivalent ones
  on ClutterActor; the ClutterLayoutManager implementations provided by
  Clutter have been updated to honour the ClutterActor:x-expand,
  ClutterActor:y-expand, ClutterActor:x-align, and ClutterActor:y-align
  properties, if set.

• Setting the ClutterActor:fixed-position-set to FALSE will reset any
  currently set fixed position to (0, 0).

Emmanuele Bassi's avatar
Emmanuele Bassi committed
367 368 369 370 371 372
• ClutterActor's margin properties are now animatable.

• ClutterBindingActionFunc typedef now has a user_data parameter; the user
  data was passed by every caller, and ClutterBindingActionFunc was not used
  anywhere in the API except for documentation purposes.

Emmanuele Bassi's avatar
Emmanuele Bassi committed
373 374 375 376 377 378 379
• The clutter_threads_enter() and clutter_threads_leave() functions have been
  deprecated; the lead to non portable code, and encourage broken behaviour
  with regards to threaded applications. The only supported, portable way of
  writing Clutter application employing threads is to defer long running
  operations to a worker thread, and schedule UI updates to the main loop at
  well defined synchronization points.

380 381 382
Release Notes for Clutter 1.10
-------------------------------------------------------------------------------

Emmanuele Bassi's avatar
Emmanuele Bassi committed
383 384 385 386 387 388
• The ClutterActor::paint, ClutterActor::queue-redraw, and
  ClutterActor::queue-relayout signals are now annotated as not allowing
  signal emission hooks; this enables some optimization inside GLib, and
  given the amount of emissions these three signals have, we want to get
  through all the fast paths we can.

389 390 391 392 393 394 395
• The ClutterActorBox parameter of the ClutterActor::allocation-changed
  signal is now marked as G_SIGNAL_TYPE_STATIC_SCOPE.

• The clutter-stage-window.h header is not installed any more; this header
  was never meant to be public in the first place, and nothing could have
  been implementing the ClutterStageWindow interface and use it with Clutter.

396 397 398 399 400 401 402 403 404 405 406
• ClutterActor will call its unmap() implementation when it is removed from
  its parent. This may happen after the ClutterActor::destroy signal has been
  emitted, i.e. during its dispose(). Prior to 1.10, calling the
  clutter_actor_destroy() function would unmap the actor first, and then
  emit the destroy signal. This means that extra care should be used when
  overriding the map() and unmap() virtual functions, to avoid dereferencing
  NULL pointers. It is also worthy of note that since Clutter 1.8, overriding
  map() or unmap() is not required any more for subclasses of ClutterActor
  that have children, as ClutterActor will automatically do the right thing
  inside its own implementation, and map or unmap its children when needed.

407
• ClutterBox and ClutterGroup have been deprecated. ClutterActor should be
408 409 410
  used directly, instead. Since ClutterStage inherits from ClutterGroup, the
  instance and class structures are still available, but subclassing Group
  is strongly disencouraged.
411 412

• ClutterContainer provides default implementations for add(), remove(),
413 414 415 416
  foreach(), raise(), lower(), and sort_depth_order(); this means that
  overriding these virtual functions is now deprecated, and developers
  should only implement ClutterContainer for classes providing child
  properties.
417 418 419 420

• ClutterActor is not an abstract type any more, and can be instantiated
  either through clutter_actor_new() or through g_object_new().

421 422 423 424 425 426 427 428 429
• ClutterActor now implements ClutterContainer, and takes over the entire API
  for modifying the scene graph; this means that every actor can have children
  and it's not necessary any more to implement the ClutterContainer interface.
  ClutterActor provides new API to replace clutter_actor_set_parent() and
  clutter_actor_unparent(), as well as a default implementation of every
  Container virtual function. Existing actors overriding ClutterContainer and
  providing an alternate implementation will continue to work, even though it
  is strongly encouraged to port to the new API.

430 431 432 433 434 435
• The ClutterActor::destroy signal is going to be emitted at the beginning
  of the dispose sequence of a ClutterActor, instead of the end. This allows
  to access the state of the actor being destroyed, instead of just being
  able to use its pointer. This may expose bugs in code that does not check
  for NULL actor pointers.

436 437 438 439 440 441 442
• The long since broken depth cueing support in ClutterStage has been
  deprecated; the fixed pipeline fog API has been pretty much useless
  since the switch to colors and textures with premultiplied alpha
  channels. Setting ClutterStage:use-fog to TRUE has no visible results,
  and querying the :use-fog and :fog properties will always yield the
  default values.

443 444 445 446 447 448 449 450 451 452
• ClutterDeformEffect switched from using CoglVertexBuffer to using the
  CoglPrimitive API internally, to improve performance and use non-deprecated
  Cogl API. CoglPrimitive converts COGL_WRAP_MODE_AUTOMATIC to
  COGL_WRAP_MODE_CLAMP_TO_EDGE, unlike CoglVertexBuffer which converts it to
  COGL_WRAP_MODE_REPEAT. This prevents artifacts when sampling texture
  coordinates outside the [ 0, 1 ] range. This change may cause the back
  texture to not be painted if its coordinates go outside the allowed range,
  for instance when using a custom transformation matrix on the back material
  used by the ClutterDeformEffect.

453 454 455 456 457 458
• The "default stage" has been deprecated; since the 1.0 release, the default
  stage creation was deferred to the call to clutter_stage_get_default(), and
  the preferred way for getting a ClutterStage was calling clutter_stage_new()
  instead. On platforms that do not support multiple stages, attempting to
  create more than one stage will lead to an error, and Clutter will abort.

459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501
• Clutter can support multiple backends in the same shared library. Only one
  windowing or input backend can be used at run time. As a result of this
  change, the shared library name used by Clutter has changed from:

        libclutter-<flavour>-<API version>.so

  to:

        libclutter-<API version>.so

  The pkg-config file has been updated accordingly. Until the next major API
  break, Clutter will ship compatibility links for all the previous "flavours"
  that were available in versions < 1.10; this allows applications dynamically
  linking against Clutter, or using dlopen(), to keep working. For libraries
  and applications dynamically linking against Clutter, though, it is still
  recommended to recompile to make sure that the most recent version is being
  used. Language bindings using GObject Introspection will automatically use
  the new shared library without requiring any change.

• The windowing system backend for the CE3100 and CE4100 platforms using the
  libgdl library is now implemented as a separate backend instance, instead
  of being a sub-flavour of the EGL native framebuffer backend. This change
  introduces a new header file, under $includedir/clutter-1.0/clutter/cex100,
  which should be included to access the CEx100-specific API. The API and
  ABI of the platform API has not been changed, though it should still be
  considered experimental.

• As of 1.10 it is not necessary any more to call clutter_threads_init() to
  initialize threading support in Clutter; after the changes in GLib 2.32,
  threading support in Clutter is always enabled. The rules on how to use
  Clutter from multiple threads haven't changed.

• Deprecated API is now marked using the CLUTTER_DEPRECATED and the
  CLUTTER_DEPRECATED_FOR annotations; these two annotations will result in
  compiler warnings when attempting to use the deprecated API. It is possible
  to disable deprecation warnings for Clutter by defining the
  CLUTTER_DISABLE_DEPRECATION_WARNINGS symbol when compiling. The previous
  deprecation symbol, CLUTTER_DISABLE_DEPRECATED, is only used for macros.

• Deprecated functionality has been moved to separate header files, installed
  under the $includedir/clutter-1.0/clutter/deprecated directory. These files
  are still included by default by clutter/clutter.h.

502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528
Release Notes for Clutter 1.8
-------------------------------------------------------------------------------

• Cogl has been split out of tree. Clutter depends on Cogl, so users should
  not notice anything. Developers using pkg-config will gain an extra Cogl
  dependency.

• The clutter_actor_get_gid() and clutter_get_actor_by_gid() functions have
  been deprecated. They should not have been public in the first place.

• ClutterShader and its relative API have been deprecated. ClutterShaderEffect
  and the effect API is the proper way to use GLSL shaders with ClutterActors.
  It is possible to instantiate a ClutterShaderEffect directly.

• ClutterText's paint volume has been implemented using the ink rectangle of
  the PangoLayout used to paint, to allow culling to work properly even in
  the case of glyphs spilling outside the logical rectangle.

• Non fully opaque children of a non fully opaque actor will be composited
  in an offscreen framebuffer object to preserve the correct overall opacity.
  This changes the way non fully opaque actors are drawn, and might cause
  some code relying on the old, unspecified behaviour to produce different
  results.

• ClutterBoxLayout layout algorithm has been changed to map the more mature
  and more stable GtkBox one.

529 530 531 532 533 534 535 536 537 538 539 540 541
• The ClutterText:editable property was incorrectly defined in the GParamSpec
  as being TRUE by default, but it was initialized to FALSE. To avoid breaking
  existing code, the default value inside the GParamSpec (and inside the
  documentation) has been changed to FALSE as well.

• The preferred way to draw inside a ClutterCairoTexture is connecting to
  its ::draw signal, and calling the invalidate() method. The old pattern
  of creating the Cairo context using the create() method is deprecated but
  still working as intended.

• ClutterScore has been deprecated; the preferred way to chain up multiple
  animations is to use the ClutterAnimator or ClutterState classes.

542 543 544 545 546 547 548 549 550 551 552 553 554 555 556
Release Notes for Clutter 1.6
-------------------------------------------------------------------------------

• The internal copy of JSON-GLib has been removed: Clutter now strictly
  depends on the installed copy of this library. The --with-json configure
  switch has been removed.

• The ClutterBehaviour class and its sub-classes have been deprecated; the
  Clutter API reference contains a migration guide to port code based on
  behaviours to the implicit animations framework.

• The ClutterTimeoutPool and clutter_frame_source_* API have been deprecated;
  both API are not integrated in the Clutter main loop, and are not used
  internally any longer, so they are of relative use.

557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591
• It it not necessary any more to provide implementations for the
  ClutterActor::map() and ClutterActor::unmap() virtual functions, even
  for composite actors not implementing the ClutterContainer interface.

• ClutterTimeline now guarantees that the ::new-frame signal will be
  emitted at the beginning of the timeline, as well as guaranteeing that
  the ::completed signal will be emitted at the end of the timeline.

• ClutterActor will check for the enabled property of ClutterActorMeta
  instances (actions, constraints and effects), and will not invoke
  ClutterActorMeta functions on disabled instances. This removes the
  requirement for checking the property inside the ClutterActorMeta
  sub-classes.

• ClutterActorBox, ClutterGeometry and ClutterVertex install a progress
  function for ClutterInterval, allowing the interpolation of properties
  using them as storage types.

• ClutterColor's clutter_color_from_string() function accepts CSS3 color
  specifications.

• The previously unused "axes" field in the ClutterButtonEvent,
  ClutterScrollEvent and ClutterMotionEvent structures is now used on
  the X11-based backends with XInput support.

• ClutterListModel will honour the filter function when calling
  clutter_model_get_iter_at_row().

• ClutterClickAction does not use a pointer grab any longer, and uses
  a capture on the stage instead.

• On all platforms which allow it, ClutterStage will ask the windowing
  system for an explicit key focus when showing the stage window. This
  can be disabled using clutter_stage_set_accept_focus().

592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614
Release Notes for Cogl 1.6
-------------------------------------------------------------------------------

• Cogl may internally optimise cogl_read_pixels when only a single
  pixel is drawn and the entire scene is comprised of solid colour
  rectangles. Instead of actually rendering the rectangles it will
  compute the single pixel value in software. This effectively means
  that Clutter can do software picking without any API changes.

• Internally Cogl now has a GLSL backend as well as the ARBfp and
  fixed function backends. By default, this backend has the lowest
  priority but it can be explicitly enabled by setting the
  COGL_DEBUG environment variable, e.g.:

    export COGL_DEBUG=disable-fixed,disable-arbfp

  for builds of Clutter with debug support enabled.

• Cogl will internally now cache generated ARBfp programs so that it
  should be able to reuse a previous program even if it was generated
  for an unrelated CoglMaterial. This makes using one-shot materials
  less expensive than before although it is still not recommended.

615 616 617
Release Notes for Clutter 1.4
-------------------------------------------------------------------------------

618
• ClutterLayoutManager sub-classes overriding the set_container() virtual
619
  function should chain up to the parent class's implementation.
620

621 622 623 624 625
• The ClutterTexture:filename property is now readable, as well as writable;
  this allows querying the Texture for the filename storing the image data.
  The value will be unset when using the set_from_*_data() family of
  functions.

626 627 628 629 630 631 632 633
• If both the :sync-size and the :keep-aspect-ratio properties of a
  ClutterTexture are set to TRUE, then the texture actor will update its
  ClutterActor:request-mode property depending on the orientation of the
  image data - height-for-width for landscape, and width-for-height for
  portrait. Square image data will default to height-for-width, like all
  actors. You can still explicitly override the :request-mode value, or
  you can unset the :sync-size property to control the size yourself.

634 635 636 637 638
• All the key symbol macros have been renamed from CLUTTER_* to
  CLUTTER_KEY_*. The old names are still available inside the
  clutter-keysyms-compat.h header, which is included by clutter-keysyms.h
  unless CLUTTER_DISABLE_DEPRECATED is defined.

639 640 641 642
• The internal copy of json-glib is now deprecated. Building Clutter will
  default to the system copy and requires an explicit --with-json=internal
  to override the check.

643
Release Notes for Clutter 1.2
644
-------------------------------------------------------------------------------
645 646 647 648 649 650

* 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.

651 652 653 654 655 656
* 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.

657 658 659 660 661 662 663 664 665
* 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.

666
Cogl API changes for Clutter 1.2
667
-------------------------------------------------------------------------------
668 669 670 671

* cogl_viewport is now deprecated in favour of cogl_set_viewport which
  accepts a viewport offset.

672 673 674 675 676 677 678 679 680 681 682 683 684
* 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.

685 686 687 688 689
* 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.

690 691 692 693 694 695 696 697 698 699 700 701
* 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 ();

702 703 704 705 706 707 708 709 710 711 712 713
* 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;
714

715
Release Notes for Clutter 1.0
716
-------------------------------------------------------------------------------
717

718 719 720 721 722 723
* 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().

724 725 726 727 728 729
* 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.

730 731 732 733 734 735
* 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.

736 737 738 739 740
* 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.

741
* The fixed point API implementation Clutter uses internally has been
Emmanuele Bassi's avatar
Emmanuele Bassi committed
742
  moved from the Clutter namespace to the COGL one.
743

744 745 746 747 748 749 750 751
* 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).

752 753 754 755 756 757 758
* 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.

Emmanuele Bassi's avatar
Emmanuele Bassi committed
759 760 761 762 763 764 765 766 767 768 769 770 771
* 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
772 773 774
      correct HLS intervals:

         Hue: [ 0, 360 )
775
         Luminance: [ 0, 1 ]
776
         Saturation: [ 0, 1 ]
Emmanuele Bassi's avatar
Emmanuele Bassi committed
777 778 779 780

* The ClutterFixed symbols have been completely removed: fixed-point
  public entry points now take a CoglFixed.

781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800
* 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*)

801 802
  and chain up to the parent's implementation after calling
  clutter_actor_map() or clutter_actor_unmap() on their children.
803 804 805 806 807 808 809 810 811 812 813

* 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.

814 815 816 817 818
* 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.

819 820 821 822 823 824 825 826 827 828 829 830
* 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.

831 832
Cogl API changes for Clutter 1.0
-------------------------------------------------------------------------------
833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865

* 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
Neil Roberts's avatar
Neil Roberts committed
866
  cogl_rectangle_with_texture_coords since these are the coordinates that
867 868 869 870 871 872 873 874 875 876
  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);

877 878 879
* 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.
880 881

* A CoglMatrix type and utility API has been added; this is currently used to
882 883
  support describing texture matrices.

884 885 886
* cogl_alpha_func has been removed, since this is now controlled using the
  material API via cogl_material_set_alpha_test_function ()

887 888 889 890 891
* 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.

892 893
* cogl_scale now supports scaling on the z axis

894 895 896
* 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.

897 898 899
* 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.
900 901 902 903 904

* 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.
905

906 907 908
* cogl_get_*_matrix were changed to use the CoglMatrix type instead of
  GLfloat m[16] arrays.

909 910 911 912 913 914 915 916 917 918
* 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.

919 920 921 922
* 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.
923 924 925 926 927 928 929 930 931 932 933 934

* 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.

935 936 937
* 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.

938
Release Notes for Clutter 0.8
939
-------------------------------------------------------------------------------
940

941 942 943 944 945 946 947
* 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.

Emmanuele Bassi's avatar
Emmanuele Bassi committed
948
* GL Texture Rectangle ext is no longer used, the regular 2D NPOTS
949
  extension is preffered instead but not required.
950

951 952 953 954 955 956
* 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.

957
  XInput support needs to be explicitly enabled at runtime by calling
958
  clutter_x11_enable_xinput () before clutter_init. clutter_x11_has_xinput ()
959 960
  can then be called after to check if XInput extension present and use-able.

961 962 963 964 965 966 967 968
* 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.

969 970 971 972 973
* 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:
974 975 976 977 978 979 980 981 982 983 984 985 986 987

    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),
988 989 990
                                       gdk_pixbuf_get_has_alpha (pixbuf) ? 4
                                                                         : 3,
                                       0,
991 992
                                       &error);

993 994 995 996 997 998 999 1000
  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.

1001 1002 1003
  The clutter-gtk integration library has API for using GdkPixbuf with
  ClutterTextures (among others).

1004 1005 1006 1007 1008 1009 1010
  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.
1011

1012 1013 1014 1015 1016 1017 1018 1019 1020
* 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
1021 1022 1023 1024 1025 1026 1027 1028 1029
  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.
1030

1031 1032 1033 1034
* 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.

1035 1036 1037 1038 1039 1040
* 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.

1041 1042 1043 1044 1045 1046 1047
* 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.

1048 1049
* Actors now have a new 'show-on-set-parent' property set to TRUE by
  default. With this property set to TRUE, actors will automatically
1050 1051
  have clutter_actor_show() called on them when a parent is set (i.e
  added to a container).
1052 1053 1054

* Clutter now features support for multiple stages assuming supported
  by the backend. See test-multistage.c for example of usage. This
1055
  does not change the automatic creation of the default stage.
1056 1057
  A single GL context is used across all stages meaning GL resources
  are shared.
1058

1059 1060
* There is now an experimental native iPod Touch/iPhone UIKit backend
  named 'fruity'.
1061

1062 1063
* There is now an experimental native Win32 WGL backend.

1064 1065
* COGL (and therefor Clutter) now optionally features initial support for
  OpenGL ES 2.0. It features support for shaders.
1066

1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080
* 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.
1081 1082 1083 1084 1085

* 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
1086
  opacity value is now returned by clutter_actor_get_paint_opacity().
1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097

* 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.

1098 1099
* The Clutter X11 and GLX backends feature support for wrapping external
  X Drawables (such as windows as pixmaps) via the 'texture_from_pixmap' GLX
Emmanuele Bassi's avatar
Emmanuele Bassi committed
1100
  extension if available and fallback to slower XGetImage copies if not.
1101

1102
* ClutterContainer can have per child custom properties via ClutterChildMeta.
1103

1104
Release Notes for Clutter 0.6
1105
-------------------------------------------------------------------------------
1106

1107 1108 1109 1110 1111 1112
* 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

1113 1114 1115
* X11 related called for glx and eglx backends are now shared and moved into
  a clutter_x11 prefix.

Emmanuele Bassi's avatar
Emmanuele Bassi committed
1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132
* 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.

1133 1134 1135
* 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.
Emmanuele Bassi's avatar
Emmanuele Bassi committed
1136 1137 1138 1139 1140 1141 1142

* 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.

1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169
* 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.

Emmanuele Bassi's avatar
Emmanuele Bassi committed
1170 1171 1172 1173
* 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
1174 1175 1176 1177 1178
  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).
Emmanuele Bassi's avatar
Emmanuele Bassi committed
1179

1180 1181 1182 1183 1184 1185 1186
* 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.

Emmanuele Bassi's avatar
Emmanuele Bassi committed
1187 1188 1189 1190 1191 1192
* 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.

1193
Release Notes for Clutter 0.4.0
1194
-------------------------------------------------------------------------------
1195

1196
* clutter_actor_show_all does not recurse for groups at least (this is to
1197 1198
  match the original group_show_all behaviour). This is like 0.3 but was
  never noted.
1199

1200 1201 1202 1203 1204 1205 1206 1207
* 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).
1208

1209 1210 1211
* The ClutterBehaviourRotate and ClutterBehaviourEllsipse APIs have been
  overhauled.

1212
Release Notes for Clutter 0.3.1
1213
-------------------------------------------------------------------------------
1214

1215
* clutter_actor_apply_transform_to_point() parameters changed to use
1216 1217
  ClutterVertices.

1218 1219
* New 'Native API' backend expects EGL implementation to provide a
  CreateNativeWindow() API call.
1220 1221 1222

* Exisiting X11 based egl backend public API calls now prefixed eglx.

1223
Release Notes for Clutter 0.3
1224
-------------------------------------------------------------------------------
1225

1226 1227 1228 1229 1230 1231
* 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().

1232
* The GLX specific API has been moved to the GLX backend code and
1233
  it's now under the ClutterGlx namespace.
1234 1235 1236 1237 1238

* 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
1239
  G_PRIORITY_DEFAULT priority. This ensures that events are processed
1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255
  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
Emmanuele Bassi's avatar
Emmanuele Bassi committed
1256 1257 1258 1259 1260 1261 1262 1263
  "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.
1264

1265 1266 1267
* clutter_color_parse() now handles color definitions with alpha. Alpha
  will default to fully Opaque rather than fully transparent if not specified.

1268
* The Clutter examples/ directory has been removed and replaced with a
1269 1270
  tests/ directory.

Emmanuele Bassi's avatar
Emmanuele Bassi committed
1271 1272 1273 1274 1275 1276
* 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.
1277 1278 1279

* Runtime options now dependant on backend.

Emmanuele Bassi's avatar
Emmanuele Bassi committed
1280 1281 1282 1283 1284
* 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.