# LoadCel

Loads one or more cels from a file.

### Synopsis

`CCB * LoadCel (char *filename, uint32 memTypeBits)`

### Description

Loads a cel or related group of cels from a file. Memory for the file is allocated according to memTypeBits, then the entire file is loaded into the buffer using fast block I/O. After the file is loaded, the cel(s) in the buffer are parsed by the `ParseCel()` function.

If the file contains more than one cel, the CCBs are strung together via their ccb_NextPtr fields in the same order as they are encountered in the buffer. This allows you to store a group of related cels in one file, and treat them as a single logical entity using the other CelUtils library functions that work with lists of cels.

This function also contains special handling for anti-aliased cels. AACels are two cels stored together in the same file, but the CCBs are stored in reverse order of the way they must be drawn. AACels are recognized by a characteristic signature (exactly two cels, one is 4-bit coded the other 16-bit uncoded, same size and coordinates, etc.), and when detected the CCB links are automatically reversed so the return value is a list of two cels linked in the proper order for drawing. One drawback to the signature-detection logic is that it prevents the storage of multiple related anti-aliased cels in the same file.

Use `DeleteCel()` or `UnloadCel()` to release the resources acquired when the cel file is loaded. When the file contains several cels, or an anti-aliased cel, use `DeleteCel()` or `UnloadCel()` only on the first cel in the file. That is, pass the pointer returned by this function. `DeleteCel()` will delete all the cels at once.

`DeleteCelList()` contains special logic to treat a group of cels loaded from the same file as if they were one cel. If more cels were linked in the list following a group loaded from the same file, `DeleteCelList()` calls `DeleteCel()` for the first cel in the group, then skips to the end of the group and resumes walking the ccb_NextPtr links as normal for the rest of the cels. This implies that you cannot load a group of cels from a file and then break apart the links built by `LoadCel()` and relink the cels into different lists. Doing so would confuse the logic in `DeleteCelList()`.

### Arguments

filename
  Name of file to load.

memTypeBits
  Memory to be allocated.

### Return Value

Pointer to the cel or list of cels loaded from the file.

### Implementation

Library call implemented in lib3do.lib.

### Associated Files

lib3do.lib, celutils.h

### See Also

`ParseCel`, DeleteCel, DeleteCelList, UnloadCel