### Method

# Cogl Onscreen add_frame_callback

#### Declaration [src]

    CoglFrameClosure*
    cogl_onscreen_add_frame_callback (
      CoglOnscreen* onscreen,
      CoglFrameCallback callback,
      void* user_data,
      CoglUserDataDestroyCallback destroy
    )

#### Description [src]

Installs a `callback` function that will be called for significant events relating to the given `onscreen` framebuffer.

The `callback` will be used to notify when the system compositor is ready for this application to render a new frame. In this case `COGL_FRAME_EVENT_SYNC` will be passed as the event argument to the given `callback` in addition to the `CoglFrameInfo` corresponding to the frame being acknowledged by the compositor.

The `callback` will also be called to notify when the frame has ended. In this case `COGL_FRAME_EVENT_COMPLETE` will be passed as the event argument to the given `callback` in addition to the `CoglFrameInfo` corresponding to the newly presented frame. The meaning of “ended” here simply means that no more timing information will be collected within the corresponding `CoglFrameInfo` and so this is a good opportunity to analyse the given info. It does not necessarily mean that the GPU has finished rendering the corresponding frame.

We highly recommend throttling your application according to `COGL_FRAME_EVENT_SYNC` events so that your application can avoid wasting resources, drawing more frames than your system compositor can display.

#### Parameters

`callback`

  Type: `CoglFrameCallback`

  A callback function to call for frame events.

`user_data`

  Type: `void*`

  A private pointer to be passed to `callback`.

  The argument can be `NULL`.
  The data is owned by the caller of the function.

`destroy`

  Type: `CoglUserDataDestroyCallback`

  An optional callback to destroy `user_data` when the `callback` is removed or `onscreen` is freed.

  The argument can be `NULL`.

#### Return value

Type: `CoglFrameClosure`

A `CoglFrameClosure` pointer that can be used to remove the callback and associated `user_data` later.

The caller of the method takes ownership of the data, and is responsible for freeing it.