-
Notifications
You must be signed in to change notification settings - Fork 6
/
README.in
1169 lines (866 loc) · 49.6 KB
/
README.in
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
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
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
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
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
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
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
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
README for Clutter @CLUTTER_VERSION@
===============================================================================
Clutter is an open source software library for creating fast, compelling,
portable, and dynamic graphical user interfaces.
REQUIREMENTS
-------------------------------------------------------------------------------
Clutter currently requires:
• GLib ≥ @GLIB_REQ_VERSION@
• Cogl ≥ @COGL_REQ_VERSION@
• JSON-GLib ≥ @JSON_GLIB_REQ_VERSION@
• Atk ≥ @ATK_REQ_VERSION@
• Cairo ≥ @CAIRO_REQ_VERSION@
• PangoCairo ≥ @PANGO_REQ_VERSION@
When building the X11 backend, Clutter depends on the following extensions:
• XComposite ≥ @XCOMPOSITE_REQ_VERSION@
• XDamage
• XExt
• XFixes ≥ @XFIXES_REQ_VERSION@
• XInput (1.x or 2.x)
• XKB
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
If you are building the API reference you will also need:
• GTK-Doc ≥ @GTK_DOC_REQ_VERSION@
If you are building the additional documentation you will also need:
• xsltproc
• jw (optional, for generating PDFs)
If you are building the Introspection data you will also need:
• GObject-Introspection ≥ @GI_REQ_VERSION@
GObject-Introspection is available from:
git://git.gnome.org/gobject-introspection
If you want support for profiling Clutter you will also need:
• UProf ≥ @UPROF_REQ_VERSION@
UProf is available from:
git://github.com/rib/UProf.git
RESOURCES
-------------------------------------------------------------------------------
The official Clutter website is:
http://www.clutter-project.org/
The API references for the latest stable release are available at:
http://docs.clutter-project.org/docs/clutter/stable/
http://docs.clutter-project.org/docs/cogl/stable/
http://docs.clutter-project.org/docs/cally/stable/
The Clutter Cookbook is available at:
http://docs.clutter-project.org/docs/clutter-cookbook/@CLUTTER_API_VERSION@/
New releases of Clutter are available at:
http://source.clutter-project.org/sources/clutter/
http://download.gnome.org/sources/clutter/
The Clutter blog is available at:
http://www.clutter-project.org/blog/
To subscribe to the Clutter mailing lists and read the archives, use the
Mailman web interface available at:
http://lists.clutter-project.org/
New bug page on Bugzilla:
http://bugzilla.gnome.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
-------------------------------------------------------------------------------
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
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-maintainer-flags=[no/yes/error]
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).
--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.
--enable-deprecated=[yes/no]
Whether deprecated symbols should be available when compiling Clutter.
--disable-Bsymbolic
Disable linking with -Bsymbolic.
--enable-x11-backend=[yes/no/check]
Enable the X11 backend. (default=check)
--enable-win32-backend=[yes/no/check]
Enable the native Microsoft Windows backend. (default=check)
--enable-quartz-backend=[yes/no/check]
Enable the native Quartz backend. (default=check)
--enable-gdk-backend=[yes/no/check]
Enable the GDK backend. (default=check)
--enable-wayland-backend=[yes/no]
Enable the Wayland client backend. (default=no) [EXPERIMENTAL]
--enable-cex100-backend=[yes/no]
Enable the CEx100 platform backend. (default=no) [EXPERIMENTAL]
--enable-egl-backend=[yes/no]
Enable the EGL framebuffer backend. (default=no)
--enable-tslib-input=[yes/no]
Enable the TSLib input backend. (default=no) [EXPERIMENTAL]
--enable-evdev-input=[yes/no]
Enable the evdev input backend. (default=no) [EXPERIMENTAL]
See also the INSTALL file generated by autotools for further information.
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 HACKING file for
general implementation guidelines, and the HACKING.backends for
backend-specific implementation issues.
The CODING_STYLE file contains the rules for writing code conformant to the
style guidelines used throughout Clutter. Remember: the coding style is
mandatory; patches not conforming to it will be rejected by default.
BUGS
-------------------------------------------------------------------------------
Bugs should be reported to the Clutter Bugzilla at:
http://bugzilla.gnome.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.
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/
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.10
-------------------------------------------------------------------------------
• ClutterBox and ClutterGroup have been deprecated. ClutterActor should be
used directly, instead. Since ClutterStage inherits from ClutterGroup, the
instance and class structures are still available, but subclassing Group
is strongly disencouraged.
• ClutterContainer provides default implementations for add(), remove(),
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.
• ClutterActor is not an abstract type any more, and can be instantiated
either through clutter_actor_new() or through g_object_new().
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
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.
• 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.
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.
• 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().
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.
Release Notes for Clutter 1.4
-------------------------------------------------------------------------------
• ClutterLayoutManager sub-classes overriding the set_container() virtual
function should chain up to the parent class's implementation.
• 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.
• 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.
• 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.
• 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.
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.