Re: Clutter API - Documentation

[Emmanuele Bassi <ebassi gmail com>]

Hi;

On 4 March 2015 at 15:35, Richard <tuxbox guru gmail com> wrote:

> As a newbie trying to get in to Clutter I am having great difficulty
> in understanding what API functions to use.
>
> An example would be the function
>
> [QUOTE]
> clutter_texture_set_from_rgb_data has been deprecated since version
> 1.12 and should not be used in newly-written code.
> [/QUOTE]
>
> There doesnt seem to be a suggestion on what to actually use.

That's absolutely true, it should point to ClutterImage.

> another example is

> [/QUOTE]
> clutter_texture_set_from_yuv_data has been deprecated since version
> 1.10 and should not be used in newly-written code.
>
> Use clutter_texture_get_cogl_material() and the Cogl API to install a
> fragment shader for decoding YUV formats on the GPU
> [/QUOTE]
>
> and when you look at clutter_texture_get_cogl_material() it is also
> listed as Deprecated...

Well, the whole of ClutterTexture is deprecated for ClutterImage, and
the YUV support never really worked in the first place except on
limited platforms and old versions of OpenGL.

These days, the most efficient way to have texture data painted inside
an actor is to either use ClutterImage, or, in case you need to use
the GPU for pre-processing, create a new ClutterContent implementation
and use a custom ClutterPipelineNode and the Cogl API. There are
various implementations inside Clutter, as well as one in the
ClutterGst library. I'd be happy to include an example for that inside
Clutter itself, if you submit one.

> I can seem to find pages and pages of Deprecated functions on the
> https://developer.gnome.org/clutter website but no data on what the
> functions or current examples are.

The current examples are hosted with Clutter itself, under the
`/examples` directory in the source code, but the API reference does
not have "full" examples.

> I have code written using the deprecated code but I want to do the job
> properly using functions that will still be there next week.

The ClutterTexture API was mass deprecated for the 1.12 cycle, which
was released in September 2012; in the previous cycle (1.10, released
in March 2012), ClutterImage was introduced to replace most of the use
cases left for displaying image data inside a ClutterActor. So it's
been three years, not really two weeks. :-)

You are right, though: the API reference could be much better. If you
find issues, I'd be happy if you opened actionable bugs on
https://bugzilla.gnome.org/enter_bug.cgi?product=clutter&component=Documentation
— that would help figuring out what to change and which change would
be more helpful from a perspective of a newcomer.

Ciao,
 Emmanuele.

-- 
https://www.bassi.io
[ ] ebassi [ gmail com]