# Using a Cel to Reveal Bitmap Contents

You can extract part of an existing bitmap as cel source data and project it as a cel into another bitmap. The Graphics folio offers a second way to put part of one bitmap into another using the cel engine. You can use the shape of a cel to reveal parts of one bitmap within another bitmap.

The pixel processor in the cel engine accepts primary and secondary sources of input pixels. Either source can be set to `CFBD` (current frame buffer data), which means that the cel engine reads pixels from a bitmap called the read buffer. This is usually the same bitmap into which the projector projects the cel, which allows effects such as a spotlight or a shadow. In both of these effects, the cel's source data determines a projected cel shape into the bitmap. The pixel processor reads the frame buffer pixels within the cel shape, and then either lightens or darkens the pixels there to create a spotlight or a shadow within the write bitmap.

In standard effects such as shadows and spotlights, the read buffer is the same as the write buffer. This need not always be the case. The read buffer can be set to a different bitmap than the write buffer. If so, the cel's projected shape traverses parallel locations in both bitmaps. The pixel processor, following the cel shape, reads pixels from the read bitmap and writes them into the write bitmap.

For example, the write bitmap (which appears on the screen) is the image of a patient lying on an operating table; the read bitmap is an image of a skeleton inside the patient. A square cel representing an X-ray machine moves from left to right in the write bitmap; it simultaneously moves from left to right in the read bitmap. All the pixels within the X-ray square come from the read bitmap (showing details of the skeleton), and are written into the same position on the write bitmap. The effect is an X-ray machine that moves over the patient. Wherever X-ray lies, it reveals the patient's skeleton.

The chief differences between projecting bitmap contents as source data and revealing them as a `CFBD` input source are that source data pixels are projected and `CFBD` pixels are simply copied from one bitmap to another. Source data pixels can be stretched or shrunk to fit a projection quadrilateral; `CFBD` pixels are read and written on a one-to-one basis between the read and write bitmaps. The set of source data pixels remains the same as the cel moves from place to place within a bitmap; the set of `CFBD` pixels changes as the cel moves.

## Setting Read and Write Buffers

To reveal bitmap pixels instead of projecting them, you must first create a cel that projects the shape in which you want to reveal the pixels. Then, you must set the cel's CCB (using its PIXC word) so that one of the pixel processor's sources is a `CFBD`. You can then set the pixel processor to further process the incoming `CFBD` pixels or pass them straight on to the write bitmap.

When you project such a cel, specify the bitmap or screen onto which you want to project (in other words, the write bitmap). The bitmap data structure of the write bitmap contains a read address, which points to a read bitmap. When a bitmap is created, its read address is set to the bitmap's own address; any cel projected there reads and writes CFBD pixels within the same bitmap. If you want to change a bitmap's read address to point to another bitmap, use this call:

  `int32 SetReadAddress( Item bitmapItem, ubyte *buffer, int32 width )`

`SetReadAddress()` accepts the item number of the bitmap whose read address you want to change. It also accepts a pointer to the read buffer (read bitmap) you want to read for `CFBD` pixels, and an integer giving the width in pixels of the read bitmap.

When `SetReadAddress()` executes, it changes the read buffer pointer within the bitmap's data structure. Whenever a cel with `CFBD` input is projected into the original bitmap, the cel engine reads pixels from the read bitmap. The cel engine uses the given width to determine the dimensions of the read bitmap. The cel engine's output is projected into the original bitmap. The call returns 0 if successful, or a negative number (an error code) if unsuccessful.

All cels projected into a bitmap use the same read and write bitmaps for `CFBD` effects because the bitmap addresses are defined within the bitmap and not within the cel.

If you want to return a bitmap to its original read and write buffer settings, use this call:

  `int32 ResetReadAddress( Item bitmapItem )`

The call accepts the item number of the bitmap you want to reset. When `ResetReadAddress()` executes, it resets the bitmap's read buffer pointer to point at the bitmap itself. The call returns a 0 if successful, or a negative number (an error code) if unsuccessful.