The Object Interface

The Object Interface

Synopsis

                    CoglObject;
void *              cogl_object_ref                     (void *object);
void                cogl_object_unref                   (void *object);
                    CoglUserDataKey;
void                (*CoglUserDataDestroyCallback)      (void *user_data);
void *              cogl_object_get_user_data           (CoglObject *object,
                                                         CoglUserDataKey *key);
void                cogl_object_set_user_data           (CoglObject *object,
                                                         CoglUserDataKey *key,
                                                         void *user_data,
                                                         CoglUserDataDestroyCallback destroy);

Description

Details

CoglObject

typedef struct _CoglObject CoglObject;

cogl_object_ref ()

void *              cogl_object_ref                     (void *object);

Increases the reference count of object by 1

object :

a CoglObject

Returns :

the object, with its reference count increased

cogl_object_unref ()

void                cogl_object_unref                   (void *object);

Drecreases the reference count of object by 1; if the reference count reaches 0, the resources allocated by object will be freed

object :

a CoglObject

CoglUserDataKey

typedef struct {
  int unused;
} CoglUserDataKey;

A CoglUserDataKey is used to declare a key for attaching data to a CoglObject using cogl_object_set_user_data. The typedef only exists as a formality to make code self documenting since only the unique address of a CoglUserDataKey is used.

Typically you would declare a static CoglUserDataKey and set private data on an object something like this:

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










static CoglUserDataKey path_private_key;

static void
destroy_path_private_cb (void *data)
{
  g_free (data);
}

static void
my_path_set_data (CoglPath *path, void *data)
{
  cogl_object_set_user_data (COGL_OBJECT (path),
                             &private_key,
                             data,
                             destroy_path_private_cb);
}

int unused;

ignored.

Since 1.4


CoglUserDataDestroyCallback ()

void                (*CoglUserDataDestroyCallback)      (void *user_data);

When associating private data with a CoglObject a callback can be given which will be called either if the object is destroyed or if cogl_object_set_user_data() is called with NULL user_data for the same key.

user_data :

The data whos association with a CoglObject has been destoyed.

Since 1.4


cogl_object_get_user_data ()

void *              cogl_object_get_user_data           (CoglObject *object,
                                                         CoglUserDataKey *key);

Finds the user data previously associated with object using the given key. If no user data has been associated with object for the given key this function returns NULL.

object :

The object with associated private data to query

key :

The address of a CoglUserDataKey which provides a unique value with which to index the private data.

Returns :

The user data previously associated with object using the given key; or NULL if no associated data is found. [transfer none]

Since 1.4


cogl_object_set_user_data ()

void                cogl_object_set_user_data           (CoglObject *object,
                                                         CoglUserDataKey *key,
                                                         void *user_data,
                                                         CoglUserDataDestroyCallback destroy);

Associates some private user_data with a given CoglObject. To later remove the association call cogl_object_set_user_data() with the same key but NULL for the user_data.

object :

The object to associate private data with

key :

The address of a CoglUserDataKey which provides a unique value with which to index the private data.

user_data :

The data to associate with the given object, or NULL to remove a previous association.

destroy :

A CoglUserDataDestroyCallback to call if the object is destroyed or if the association is removed by later setting NULL data for the same key.

Since 1.4