Commit Graph

371 Commits

Author SHA1 Message Date
Robert Bragg
f322da3794 [material] Reduce the material API in preperation for releasing Clutter 1.0
There were a number of functions intended to support creating of new
primitives using materials, but at this point they aren't used outside of
Cogl so until someone has a usecase and we can get feedback on this
API, it's being removed before we release Clutter 1.0.
2009-05-28 02:43:34 +01:00
Robert Bragg
f28d5e481b [cogl-material] Removes all the API made redundant by the blend strings API
This removes the following API:
  cogl_material_set_blend_factors
  cogl_material_set_layer_combine_function
  cogl_material_set_layer_combine_arg_src
  cogl_material_set_layer_combine_arg_op

These were rather awkward to use, so since it's expected very few people are
using them at this point and it should be straight forward to switch over
to blend strings, the API is being removed before we release Clutter 1.0.
2009-05-28 02:43:34 +01:00
Robert Bragg
33994caa71 [cogl-material] Support string based blending and layer combine descriptions
Setting up layer combine functions and blend modes is very awkward to do
programatically.  This adds a parser for string based descriptions which are
more consise and readable.

E.g. a material layer combine function could now be given as:
  "RGBA = ADD (TEXTURE[A], PREVIOUS[RGB])"
or
  "RGB = REPLACE (PREVIOUS)"
  "A = MODULATE (PREVIOUS, TEXTURE)"

The simple syntax and grammar are only designed to expose standard fixed
function hardware, more advanced combining must be done with shaders.

This includes standalone documentation of blend strings covering the aspects
that are common to blending and texture combining, and adds documentation
with examples specific to the new cogl_material_set_blend() and
cogl_material_layer_set_combine() functions.

Note: The hope is to remove the now redundant bits of the material API
before 1.0
2009-05-28 02:43:28 +01:00
Emmanuele Bassi
f8f54989be Merge commit 'origin/master' into 1.0-integration
Conflicts:
	clutter/clutter-texture.c
	clutter/cogl/gl/cogl-fbo.c
2009-05-20 16:49:22 +01:00
Emmanuele Bassi
407ac5075f [texture] Add missing accessors
ClutterTexture has many properties that can only be accessed using
the GObject API. This is fairly inefficient and makes binding the
class overly complicated.

The Texture class should have accessor methods for all its properties,
properly documented.
2009-05-19 13:24:56 +01:00
Emmanuele Bassi
21e3901d62 [text] Expose position_to_coords()
The clutter_text_position_to_coords() is useful for ClutterText
subclasses.

See bug:

  http://bugzilla.openedhand.com/show_bug.cgi?id=1521

Based on a patch by: Raymond Liu <raymond.liu@intel.com>
2009-05-14 16:19:15 +01:00
Emmanuele Bassi
ca23838752 [text] Add ClutterText::delete_selection()
Add a method for deleting the current selection inside a Text actor.

This is useful for subclasses.

See bug:

  http://bugzilla.openedhand.com/show_bug.cgi?id=1521

Based on a patch by: Raymond Liu <raymond.liu@intel.com>
2009-05-14 16:16:06 +01:00
Emmanuele Bassi
0f7a3b9739 [docs] Add Animation get_type() function
We need to reference clutter_animation_get_type() if we want the
properties, signals and object hierarchy to show up in the API
reference
2009-05-14 16:11:47 +01:00
Robert Bragg
36cfb60307 [cogl] Remove the COGL{enum,int,uint} typedefs
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.
2009-05-12 14:53:44 +01:00
Emmanuele Bassi
4cb3fa8728 [docs] Update documentation
Remove the units-based API and add the missing symbols.

Also, do not let gtk-doc check the master clock header, since
it's private.
2009-05-06 17:57:34 +01:00
Emmanuele Bassi
d0ad5a8abb [text] Expose position_to_coords()
The clutter_text_position_to_coords() is useful for ClutterText
subclasses.

See bug:

  http://bugzilla.openedhand.com/show_bug.cgi?id=1521

Based on a patch by: Raymond Liu <raymond.liu@intel.com>
2009-05-06 17:18:12 +01:00
Emmanuele Bassi
a28b9f31eb [text] Add ClutterText::delete_selection()
Add a method for deleting the current selection inside a Text actor.

This is useful for subclasses.

See bug:

  http://bugzilla.openedhand.com/show_bug.cgi?id=1521

Based on a patch by: Raymond Liu <raymond.liu@intel.com>
2009-05-06 17:13:33 +01:00
Emmanuele Bassi
c2abdd5e82 [docs] Add Animation get_type() function
We need to reference clutter_animation_get_type() if we want the
properties, signals and object hierarchy to show up in the API
reference
2009-05-06 16:43:52 +01:00
Robert Bragg
a5cdfdfd87 [cogl-offscreen] Cleans up the cogl offscreen API and adds documentation
There were several functions I believe no one is currently using that were
only implemented in the GL backend (cogl_offscreen_blit_region and
cogl_offscreen_blit) that have simply been removed so we have a chance to
think about design later with a real use case.

There was one nonsense function (cogl_offscreen_new_multisample) that
sounded exciting but in all cases it just returned COGL_INVALID_HANDLE
(though at least for GL it checked for multisampling support first!?)
it has also been removed.

The MASK draw buffer type has been removed. If we want to expose color
masking later then I think it at least would be nicer to have the mask be a
property that can be set on any draw buffer.

The cogl_draw_buffer and cogl_{push,pop}_draw_buffer function prototypes
have been moved up into cogl.h since they are for managing global Cogl state
and not for modifying or creating the actual offscreen buffers.

This also documents the API so for example desiphering the semantics of
cogl_offscreen_new_to_texture() should be a bit easier now.
2009-05-02 04:12:26 +01:00
Robert Bragg
d5fc61102f [cogl] Only expose CoglBitmap as a CoglHandle
It was inconsistent that we exposed the CoglBitmap struct instead of an
opaque CoglHandle.
2009-05-02 04:12:26 +01:00
Emmanuele Bassi
d2cd636fb6 [docs] Add ClutterModel::get_filter_set() 2009-04-29 15:40:13 +01:00
Havoc Pennington
125bded814 Enforce invariants on mapped, realized, visibility states
Bug 1138 - No trackable "mapped" state

* Add a VISIBLE flag tracking application programmer's
  expected showing-state for the actor, allowing us to
  always ensure we keep what the app wants while tracking
  internal implementation state separately.

* Make MAPPED reflect whether the actor will be painted;
  add notification on a ClutterActor::mapped property.
  Keep MAPPED state updated as the actor is shown,
  ancestors are shown, actor is reparented, etc.

* Require a stage and realized parents to realize; this means
  at realization time the correct window system and GL resources
  are known. But unparented actors can no longer be realized.

* Allow children to be unrealized even if parent is realized.
  Otherwise in effect either all actors or no actors are realized,
  i.e. it becomes a stage-global flag.

* Allow clutter_actor_realize() to "fail" if not inside a toplevel

* Rework clutter_actor_unrealize() so internally we have
  a flavor that does not mess with visibility flag

* Add _clutter_actor_rerealize() to encapsulate a somewhat
  tricky operation we were doing in a couple of places

* Do not realize/unrealize children in ClutterGroup,
  ClutterActor already does it

* Do not realize impl by hand in clutter_stage_show(),
  since showing impl already does that

* Do not unrealize in various dispose() methods, since
  ClutterActor dispose implementation already does it
  and chaining up is mandatory

* ClutterTexture uses COGL while unrealizable (before it's
  added to a stage). Previously this breakage was affecting
  ClutterActor because we had to allow realize outside
  a stage. Move the breakage to ClutterTexture, by making
  ClutterTexture just use COGL while not realized.

* Unrealize before we set parent to NULL in clutter_actor_unparent().
  This means unrealize() implementations can get to the stage.
  Because actors need the stage in order to detach from stage.

* Update clutter-actor-invariants.txt to reflect latest changes

* Remove explicit hide/unrealize from ClutterActor::dispose since
  unparent already forces those
  Instead just assert that unparent() occurred and did the right thing.

* Check whether parent implements unrealize before chaining up
  Needed because ClutterGroup no longer has to implement unrealize.

* Perform unrealize in the default handler for the signal.
  This allows non-containers that have children to work properly,
  and allows containers to override how it's done.

* Add map/unmap virtual methods and set MAPPED flag on self and
  children in there. This allows subclasses to hook map/unmap.
  These are not signals, because notify::mapped is better for
  anything it's legitimate for a non-subclass to do.

Signed-off-by: Emmanuele Bassi <ebassi@linux.intel.com>
2009-04-24 15:27:19 +01:00
Emmanuele Bassi
08ba42a5ab Allow passing the pick mode to get_actor_at_pos()
Bug 1513 - Allow passing in ClutterPickMode to
           clutter_stage_get_actor_at_pos()

At the moment, clutter_stage_get_actor_at_pos() uses CLUTTER_PICK_ALL
internally to find an actor. It would be useful to allow passing in
ClutterPickMode to clutter_stage_get_actor_at_pos(), so that the caller
can specify CLUTTER_PICK_REACTIVE as a criteria.
2009-04-24 15:25:58 +01:00
Neil Roberts
1edc19d1d3 [clutter-text] Add a separate property for the selection color
Adds a new property so that the selection color can be different from
the cursor color. If no selection color is specified it will use the
cursor color as before. If no cursor color is specified either it will
use the text color.
2009-04-06 15:22:31 +01:00
Emmanuele Bassi
bd8d3f6bd8 [group] Remove long deprecated API
ClutterGroup still ships with API deprecated since 0.4. We did
promise to keep it around for a minor release cycle -- not for 3.

Since we plan on shipping 1.0 without the extra baggage of the
deprecated entry points, here's the chance to remove the accumulated
cruft.

All the removed methods and signals have a ClutterContainer
counterpart.
2009-04-03 12:47:21 +01:00
Emmanuele Bassi
9d0ce68c2f [shader] Remove deprecated set_uniform_1f()
Since we're planning to release 1.0 without any of the deprecated
API baggage, we can simply remove the set_uniform_1f() method from
ClutterShader public API and add it to the deprecated header.
2009-04-03 12:47:21 +01:00
Emmanuele Bassi
6114c6c1db [docs] Pick up backend-specific API
The various backend API outside from clutter-x11.h and clutter-win32.h
is documented but not picked up by gtk-doc.
2009-03-18 17:06:56 +00:00
Emmanuele Bassi
e7c5b15e60 [docs] Ignore the TimeoutInterval internal API
The TimeoutInterval API is internal, and thus should not be part
of the API reference.
2009-03-16 16:56:51 +00:00
Robert Bragg
71d65b629b [cogl-vertex-buffer] fix cogl_vertex_buffer_draw_elements prototype
This function was renamed a while ago in the .c file from
cogl_vertex_buffer_draw_range_elements  but the corresponding .h and
doc/reference/cogl changes weren't made.
2009-03-16 16:19:39 +00:00
Robert Bragg
14e6323554 [cogl-vertex-buffer] Allow querying back the number of vertices a buffer represents
This may be convenient e.g. at draw time if you are simply drawing all vertices
2009-03-16 16:17:02 +00:00
Emmanuele Bassi
9229fb6114 [docs] Bring down the undocumented symbols to 2%
The usual pre-release documentation blitzing. Most of the remaining
symbols are either COGL or X11 specific, or dummy interface typedefs.
2009-03-16 15:00:55 +00:00
Emmanuele Bassi
216373047b [animation] Enhance consistency of the Animation API
The Animation API should follow this pattern:

  - functions with an Interval as part of the arguments should have
    "interval" inside their name, e.g.:

      clutter_animation_bind_interval
      clutter_animation_update_interval

  - functions dealing with property names should have "property"
    inside their name, e.g.:

      clutter_animation_has_property
      clutter_animation_unbind_property

    - unless -

  - functions dealing with a property and its value should not
    have any modifier, e.g.:

      clutter_animation_bind

The change from update_property() to update_interval() frees up
clutter_animation_update(), to be added at a later date.
2009-03-16 14:16:18 +00:00
Emmanuele Bassi
bb795dec56 [docs] Update after Animation API changes
Rename the bind/unbind_property functions, and add the bind_interval,
completed method.

Also, add clutter_actor_get_animation().
2009-03-16 14:02:09 +00:00
Emmanuele Bassi
89e3e3a4cc [animation] Add vector variants for ::animate()
Bug 1438 - Implicit Animation API could use animatev variants

The clutter_actor_animate* family of functions use va_lists to
handle the property/value pairs for the final state of the
animation.

Language bindings have problems with variadic arguments functions,
and usually prefer vector-based API which allow a greater level
of control and conversion from native data types.

For each variadic arguments function in the clutter_actor_animate*
family there should be a vector-based version that takes:

  - the number of property/value pairs
  - a constant array of constant strings
  - an array of GValues

Most of the internal implementation can be refactored from the
current one, thus both the var_args and the vector entry points
share a common implementation of the code; then, both versions
of the API are just loops over a list of arguments.

Based on a patch by: Robert Carr <carrr@rpi.edu>
2009-03-10 12:38:04 +00:00
Emmanuele Bassi
c46106f6dd [docs] Update API reference
The API reference was still listing some symbols that have been
removed.
2009-03-10 12:38:04 +00:00
Emmanuele Bassi
f1b237b2ec [docs] Remove ClutterFixed from the documentation
Now that ClutterFixed has finally gone the way of the Dodo, we
can safely remove it from the API reference as well.
2009-03-10 12:38:04 +00:00
Emmanuele Bassi
7d674db9d2 Clean up of the ClutterColor API
The ClutterColor API has some inconsistencies:

  - the string deserialization function does not match the rest of
    the conversion function naming policy; the naming should be:

        clutter_color_parse()   ->      clutter_color_from_string()

    and the first parameter should be the ClutterColor that will
    be set from the string, not the string itself (a GDK-ism).

  - the fixed point API should not be exposed, especially in the
    form of ClutterFixed values

  - the non-fixed point HLS conversion functions do not make any
    sense. The values returned should be:

      hue        := range [ 0, 360 ]
      luminance  := range [ 0,   1 ]
      saturation := range [ 0,   1 ]

    like the current fixed point API does. Returning a value in
    the [ 0, 255 ] range is completely useless

  - the clutter_color_equal() should be converted for its use inside
    a GHashTable; a clutter_color_hash() should be added as well

  - the second parameter of the clutter_color_shade() function should
    be the shading factor, not the result (another GDK-ism). this way
    the function call can be translated from this:

      color.shade(out result, factor)

    to the more natural:

      color.shade(factor, out result)

This somewhat large commit fixes all these issues and updates the
internal users of the API.
2009-03-10 12:38:02 +00:00
Robert Bragg
af0726480c [cogl-matrix] Documents that CoglMatrix members should be considered read only
In the future if we want to annotate matrices with internal flags, and add
caching of the inverse matrix then we need to ensure that all matrix
modifications are done by cogl_matrix API so we'd know when to dirty the
cache or update the flags.

This just adds documentation to that effect, and assuming the most likley
case where someone would try and directly write to matrix members would
probably be to load a constant matrix other than the identity matrix; I
renamed cogl_matrix_init_from_gl_matrix to cogl_matrix_init_from_array to
make it seem more general purpose.
2009-02-26 16:42:32 +00:00
Emmanuele Bassi
0bc1f36ead [docs] Document envvars and command line switches
Clutter uses checks on various environment variables and installs
various command line switches. The API reference should list them
and document them both.
2009-02-23 13:44:03 +00:00
Emmanuele Bassi
1d68dcab1f [docs] Rename cogl-docs from sgml to xml
The cogl-docs.sgml file has always been XML, so it's only fitting that
we actually call it cogl-docs.xml.
2009-02-20 12:02:31 +00:00
Emmanuele Bassi
255faf602f [docs] Add the 1.0 symbols index
Add the index of symbols available since 1.0 to the Clutter
API reference.
2009-02-20 12:00:41 +00:00
Emmanuele Bassi
6b2c8f68e0 [docs] Use the --name-space option
Now that we depend on gtk-doc 1.11 we can use the --name-space
command line option for the mkdb utility.
2009-02-20 11:58:04 +00:00
Emmanuele Bassi
d0ae6b421c [docs] Update build for COGL API reference
We need to initialize the type system for gtk-doc-scan, now that
COGL exposes GTypes.
2009-02-19 17:22:21 +00:00
Emmanuele Bassi
ef7df4b736 [docs] Update the sections file
The newly added symbols should also be added to the section file.

The CairoTexture section was referenced twice.
2009-02-19 15:01:33 +00:00
Emmanuele Bassi
63ae25972e [cogl] Add cogl_is_material to cogl-material.h
The COGL_DEFINE_HANDLE macro generates a cogl_is_<type> function
as well, to check whether a CoglHandle opaque pointer is of type
<type>.

The handle for CoglMaterial does not export cogl_is_material() in
its installed header.
2009-02-19 11:55:54 +00:00
Robert Bragg
03018f0c2a [Cogl] Renames cogl_paint_init to cogl_clear and adds a cogl_disable_fog function
cogl_paint_init was a bit too miscellaneous; it mainly cleared the color, depth
and stencil buffers but arbitrarily it also disabled fogging and lighting.

It no longer disables lighting, since we know Cogl never enables lighting and
disabling of fog is now handled with a seperate function.

Since I noticed cogl_set_fog was taking a density argument documented as
"Ignored" I've also added a mode argument to cogl_set_fog which exposes the
exponential fog modes which can make use of the density.
2009-02-18 16:00:52 +00:00
Robert Bragg
2b5a72dde5 [Cogl] cogl_clip_{set*,unset} renamed to cogl_clip_{push*,pop}
This is so they self document the stacking semantics of the cogl clip API
2009-02-18 16:00:51 +00:00
Robert Bragg
b4f9c8204d [docs] Various gtk-doc updates for Cogl
This hides a number of internal structs and enums from the docs, and moves
some functions to more appropriate sections as well as misc description
updates (mostly for the vertex buffer api)
2009-02-09 14:33:14 +00:00
Emmanuele Bassi
9cf02bfdb9 [text] Rename :alignment to :line-alignment
The :alignment property is prone to generate confusion: developers
will set it thinking that the contents of a ClutterText will
automagically align themselves.

Instead of using the generic term :alignment, and following the
GTK+ convention, we should use a more specific term, conveying the
actual effect of the property: alignment of the lines with respect
to each other, and not to the overall allocated area.

See bug 1428:

  http://bugzilla.openedhand.com/show_bug.cgi?id=1428
2009-02-05 19:54:48 +00:00
Emmanuele Bassi
b053d51321 [docs] Add clutter_text_set_markup()
The clutter_text_set_markup() has been added to the public API, and
should be listed in the ClutterText section of the API reference.
2009-02-02 12:07:29 +00:00
Emmanuele Bassi
801e535e94 Add Actor::create_pango_layout()
Final bit of integration between ClutterActor and Pango: a simple
method for creating a PangoLayout, pre-filled with text and ready
to be rendered using cogl_pango_render_layout().

This should make writing new Actors rendering custom text in their
paint() implementation easy and reliable.
2009-02-02 12:07:28 +00:00
Emmanuele Bassi
0530405899 [clutter-docs] Update the animation tutorial
The Alpha API and usage has been changed by the recent overhaul
of the ClutterAlpha class; hence, we need to update the relative
documentation in the animation tutorial.
2009-01-28 16:47:41 +00:00
Emmanuele Bassi
b09ee495a5 [cogl-docs] Add the Materials section
The COGL Materials API was not linked from the COGL reference
index.
2009-01-28 16:47:29 +00:00
Neil Roberts
3e68b23ea8 Merge branch 'scale-center'
Bug 1349 - Using the anchor point to set the scale center is messy

The branch adds an extra center point for scaling which can be used
for example to set a scale about the center without affecting the
position of the actor.

The scale center can be specified as a unit offset from the origin or
as a gravity. If specified as a gravity it will be stored as a
fraction of the actor's size so that the position will track when the
actor changes size.

The anchor point and rotation centers have been modified so they can
be set with a gravity in the same way. However, only the Z rotation
exposes a property to set using a gravity because the other two
require a Z coordinate which doesn't make sense to interpret as a
fraction of the actor's width or height.

Conflicts:

	clutter/clutter-actor.c
2009-01-28 15:39:51 +00:00
Emmanuele Bassi
1b578fb9c7 [docs] Documentation fixes
Update the COGL API reference to avoid a lot of warnings coming
from gtk-doc.
2009-01-27 16:53:01 +00:00