Main Page | Modules | Alphabetical List | Class List | Directories | Class Members

Frame Sets


Typedefs

typedef _cpl_frameset_ cpl_frameset
 The frame set data type.

Functions

cpl_framesetcpl_frameset_new (void)
 Create a new, empty frame set.
cpl_framesetcpl_frameset_duplicate (const cpl_frameset *other)
 Create a copy of the given frame set.
void cpl_frameset_delete (cpl_frameset *self)
 Destroy a frame set.
int cpl_frameset_get_size (const cpl_frameset *self)
 Get the current size of a frame set.
int cpl_frameset_is_empty (const cpl_frameset *self)
 Check whether a frame set is empty.
int cpl_frameset_count_tags (const cpl_frameset *self, const char *tag)
 Counts the frames stored in a frame set having the given tag.
cpl_framecpl_frameset_find (const cpl_frameset *self, const char *tag)
 Find a frame with the given tag in a frame set.
cpl_framecpl_frameset_get_first (const cpl_frameset *self)
 Get the first frame in the given set.
cpl_framecpl_frameset_get_next (const cpl_frameset *self)
 Get the next frame in the given set.
cpl_error_code cpl_frameset_insert (cpl_frameset *self, cpl_frame *frame)
 Insert a frame into the given frame set.
int cpl_frameset_erase (cpl_frameset *self, const char *tag)
 Erase all frames with the given tag from a frame set.
cpl_error_code cpl_frameset_erase_frame (cpl_frameset *self, cpl_frame *frame)
 Erase the given frame from a frame set.
int * cpl_frameset_labelise (cpl_frameset *set, int(*compare)(cpl_frame *, cpl_frame *), int *nb_labels)
 Separate a list of frames into groups, using a comparison function.
cpl_framecpl_frameset_get_frame (const cpl_frameset *set, int index)
 Get a frame from a set of frames.
cpl_framesetcpl_frameset_extract (cpl_frameset *set, int *labels, int desired_label)
 Extract a subset of frames from a set of frames.

Detailed Description

The module implements a container type for frames. Frames can be stored in a frame set and retrieved, either by searching for a particular frame tag or by sequential access. Frame sets can be created, filled and saved to a so called `set of frames' file or loaded from such a file.

Synopsis:
   #include <cpl_frameset.h>

Typedef Documentation

typedef struct _cpl_frameset_ cpl_frameset
 

The frame set data type.

This data type is opaque.


Function Documentation

int cpl_frameset_count_tags const cpl_frameset self,
const char *  tag
 

Counts the frames stored in a frame set having the given tag.

Parameters:
self A frame set.
tag The frame tag.
Returns:
The number of frames with tag tag. The function returns 0 if an error occurs and sets an appropriate error code.
Errors:
CPL_ERROR_NULL_INPUT The parameter self or tag is a NULL pointer.

The function scans the frame set self for frames with the tag tag and returns the number of frames found.

void cpl_frameset_delete cpl_frameset self  ) 
 

Destroy a frame set.

Parameters:
self The frame set to destroy.
Returns:
Nothing.
The function destroys the frame set self and its whole contents.

cpl_frameset* cpl_frameset_duplicate const cpl_frameset other  ) 
 

Create a copy of the given frame set.

Parameters:
other The frame set to be copied.
Returns:
A handle for the created clone. The function returns NULL if an error occurs and sets an appropriate error code.
Errors:
CPL_ERROR_NULL_INPUT The parameter other is a NULL pointer.

The function creates a deep copy, i.e. the frame set object and its contents, of the frame set other. The created copy and the original set do not share any resources.

int cpl_frameset_erase cpl_frameset self,
const char *  tag
 

Erase all frames with the given tag from a frame set.

Parameters:
self A frame set.
tag The tag used to locate the frames to remove.
Returns:
The function returns the number of frames removed. If an error occurs 0 is returned and an appropriate error code is set.
Errors:
CPL_ERROR_NULL_INPUT The parameter self or tag is a NULL pointer.

The function searches the frame set self for frames having the tag tag and removes them from the set. The removed frames are destroyed. If no frame with the tag tag is found the function has no effect.

cpl_error_code cpl_frameset_erase_frame cpl_frameset self,
cpl_frame frame
 

Erase the given frame from a frame set.

Parameters:
self A frame set.
frame The frame to remove.
Returns:
The function returns CPL_ERROR_NONE on success or a CPL error code otherwise.
Errors:
CPL_ERROR_NULL_INPUT The parameter self or frame is a NULL pointer.

The function searches the frame set self for the first occurrance of frame. If it is present, the frame is removed from the set and destroyed. If frame is not present in self the function has no effect.

cpl_frameset* cpl_frameset_extract cpl_frameset set,
int *  labels,
int  desired_label
 

Extract a subset of frames from a set of frames.

Parameters:
set Input frame set
labels The list of labels associated to each input frame
desired_label The label identifying the requested frames
Returns:
a pointer to a newly allocated frame set or NULL in error case
Errors:
CPL_ERROR_NULL_INPUT The parameter self or labels is a NULL pointer.

The returned object has to be deallocated with cpl_frameset_delete()

cpl_frame* cpl_frameset_find const cpl_frameset self,
const char *  tag
 

Find a frame with the given tag in a frame set.

Parameters:
self A frame set.
tag The frame tag to search for.
Returns:
The handle for a frame with tag tag, or NULL if no such frame was found. The function returns NULL if an error occurs and sets an appropriate error code.
Errors:
CPL_ERROR_NULL_INPUT The parameter self or tag is a NULL pointer.

The function searches the frame set self for the frames with the tag tag. If such a frame is present, a handle for it is returned. If the set contains several frames with the tag tag the first one is returned. The remaining frames with this tag can be accessed sequentially by using NULL as tag when calling this function repeatedly, since the most recent frame accessed is cached. This cache is reset whenever the provided tag is not NULL. If no frame with the tag tag is present in self or no more frames with this tag are found the function returns NULL.

cpl_frame* cpl_frameset_get_first const cpl_frameset self  ) 
 

Get the first frame in the given set.

Parameters:
self A frame set.
Returns:
A handle for the first frame in the set, or NULL if the set is empty. The function returns NULL if an error occurs and sets an appropriate error code.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.

The function returns the first frame in the frame set self if it exists. If a first frame does not exist, i.e. the frame set is empty, NULL is returned. The function also updates the internal cache.

See also:
cpl_frameset_get_next()

cpl_frame* cpl_frameset_get_frame const cpl_frameset set,
int  index
 

Get a frame from a set of frames.

Parameters:
set Input frame set
index The requested frame (from 0 to nbframes - 1)
Returns:
a pointer to the requested frame or NULL in error case.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.

cpl_frame* cpl_frameset_get_next const cpl_frameset self  ) 
 

Get the next frame in the given set.

Parameters:
self A frame set.
Returns:
A handle for the next frame in a set. If there are no more frames in the set the function returns NULL. The function returns NULL if an error occurs and sets an appropriate error code.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.

The function returns the next frame in the frame set self if it exists and otherwise NULL. The function uses the internal cache to determine the most recently accessed frame. This means that the function only works as expected if self has been initialised by a call to cpl_frameset_get_first(), and if no function updating the internal cache was called between two subsequent calls to this function.

See also:
cpl_frameset_get_first()

int cpl_frameset_get_size const cpl_frameset self  ) 
 

Get the current size of a frame set.

Parameters:
self A frame set.
Returns:
The frame set's current size, or 0 if it is empty. The function returns 0 if an error occurs and sets an appropriate error code.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.

The reports the current number of frames stored in the frame set self.

cpl_error_code cpl_frameset_insert cpl_frameset self,
cpl_frame frame
 

Insert a frame into the given frame set.

Parameters:
self A frame set.
frame The frame to insert.
Returns:
The function returns CPL_ERROR_NONE on success or a CPL error code otherwise.
Errors:
CPL_ERROR_NULL_INPUT The parameter self or frame is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT The parameter frame has an invalid tag.

The function adds the frame frame to the frame set self using the frame's tag as key.

int cpl_frameset_is_empty const cpl_frameset self  ) 
 

Check whether a frame set is empty.

Parameters:
self A frame set.
Returns:
The function returns 1 if the set is empty, and 0 otherwise. If an error occurs 0 is returned and an appropriate error code is set.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.

The function checks if self contains any frames.

int* cpl_frameset_labelise cpl_frameset set,
int(*)(cpl_frame *, cpl_frame *)  compare,
int *  nb_labels
 

Separate a list of frames into groups, using a comparison function.

Parameters:
set Input frame set
compare Pointer to comparison function to use.
nb_labels Number of different sets
Returns:
array of labels defining the selection or NULL in error case
Errors:
CPL_ERROR_NULL_INPUT The parameter self, compare or nb_labels is a NULL pointer.

This function takes a set of frames and groups the frames that are 'identical' together. The user provided comparison function defines what being identical means for two frames. A label (int) is associated to each group of identical frames, these labels are returned in an array.

This compare function takes two frames and returns 1 if they are identical, 0 if they are different, and -1 in error case.

The returned object has to be deallocated with cpl_free()

cpl_frameset* cpl_frameset_new void   ) 
 

Create a new, empty frame set.

Returns:
The handle for the newly created frame set.
The function allocates the memory for the new frame set, initialises the set to be empty and returns a handle for it.


Generated on Mon Sep 26 14:38:18 2005 for Common Pipeline Library Reference Manual by  doxygen 1.4.1