DeleteCel

Deletes a cel created by any Library call implemented in lib3do.lib.

Synopsis

CCB * DeleteCel (CCB *cel)

Description

Deletes any type of cel created by Lib3DO library functions. A NULL pointer is valid as input, and is quietly treated as a no-op. If extra resources, such as a data buffer or PLUT, were allocated by the creating function they are also released.

This function correctly handles anti-aliased cels, cels loaded as a group from a single cel file, and other such constructs where several related cels were created and treated as if they were a single cel. If a Lib3DO function returns a single CCB* return value even when it creates several linked cels at once, then you need pass only that single CCB* to DeleteCel() to release all resources allocated when the group of cels was created.

This function works correctly with cels loaded from a file via LoadCel(), and is equivalent to UnloadCel(). It also works on TextCels created by the TextLib functions; DeleteCel() on the tc_CCB value of a TextCel is equivalent to DeleteTextCel().

If you have custom functions for creating cels and those functions do not use the standard library CreateCel() function as their basis, you can provide DeleteCel() support for your custom cels. Doing so is a somewhat complex procedure which is fully documented in the Implementation Notes section of the source code file DeleteCelMagic.c in the Lib3DO source code.

Arguments

cel: Pointer to a cel created by any Lib3DO function; may be NULL.

Return Value

NULL, always.

Implementation

Library call implemented in lib3do.lib.

Associated Files

lib3do.lib, celutils.h