libcucul canvas frame handling


Functions

unsigned int cucul_get_canvas_frame_count (cucul_canvas_t *)
 Get the number of frames in a canvas.
int cucul_set_canvas_frame (cucul_canvas_t *, unsigned int)
 Activate a given canvas frame.
int cucul_create_canvas_frame (cucul_canvas_t *, unsigned int)
 Add a frame to a canvas.
int cucul_free_canvas_frame (cucul_canvas_t *, unsigned int)
 Remove a frame from a canvas.

Detailed Description

These functions provide high level routines for canvas frame insertion, removal, copying etc.

Function Documentation

unsigned int cucul_get_canvas_frame_count cucul_canvas_t cv  ) 
 

This function returns the current canvas frame count.

This function never fails.

Parameters:
cv A libcucul canvas
Returns:
The frame count

int cucul_set_canvas_frame cucul_canvas_t cv,
unsigned int  frame
 

This function sets the active canvas frame. All subsequent drawing operations will be performed on that frame. The current painting context set by cucul_set_color() or cucul_set_truecolor() is inherited.

If the frame index is outside the canvas' frame range, nothing happens.

If an error occurs, -1 is returned and errno is set accordingly:

  • EINVAL Requested frame is out of range.

Parameters:
cv A libcucul canvas
frame The canvas frame to activate
Returns:
0 in case of success, -1 if an error occurred.

int cucul_create_canvas_frame cucul_canvas_t cv,
unsigned int  frame
 

This function creates a new frame within the given canvas. Its contents are copied from the currently active frame.

The frame index indicates where the frame should be inserted. Valid values range from 0 to the current canvas frame count. If the frame index is greater the or equals the current canvas frame count, the new frame is appended at the end of the canvas.

The active frame does not change, but its index may be renumbered due to the insertion.

If an error occurs, -1 is returned and errno is set accordingly:

  • ENOMEM Not enough memory to allocate new frame.

Parameters:
cv A libcucul canvas
frame The index where to insert the new frame
Returns:
0 in case of success, -1 if an error occurred.

int cucul_free_canvas_frame cucul_canvas_t cv,
unsigned int  frame
 

This function deletes a frame from a given canvas.

It is not legal to remove the last frame from a canvas. Such a request will be ignored by cucul_free_canvas_frame().

The frame index indicates the frame to delete. Valid values range from 0 to the current canvas frame count minus 1. If the frame index is greater the or equals the current canvas frame count, the last frame is deleted.

If the active frame is deleted, frame 0 becomes the new active frame. Otherwise, the active frame does not change, but its index may be renumbered due to the deletion.

If an error occurs, -1 is returned and errno is set accordingly:

  • EINVAL Requested frame is out of range, or attempt to delete the last frame of the canvas.

Parameters:
cv A libcucul canvas
frame The index of the frame to delete
Returns:
0 in case of success, -1 if an error occurred.