# `Bmp.opx` — Sprites and bitmaps

## Contents

- Overview

- Compatibility

- `BITMAPLOAD&:`
- `BITMAPUNLOAD:`
- `BITMAPDISPLAYMODE&:`
- `SPRITECREATE&:`
- `SPRITEAPPEND:`
- `SPRITECHANGE:`
- `SPRITEDRAW:`
- `SPRITEPOS:`
- `SPRITEDELETE:`
- `SPRITEUSE:`

## Overview

To use this OPX, you must include the header file `Bmp.oxh`, which contains the following declaration:

        DECLARE OPX BMP,&10000258,$100
              BITMAPLOAD&:(name$,index&) : 1
              BITMAPUNLOAD:(id&) : 2
              BITMAPDISPLAYMODE&:(id&) : 3
              SPRITECREATE&:(winId%,x&,y&,flags&) : 4
              SPRITEAPPEND:(time&,bitmap&,maskBitmap&,invertMask&,dx&,dy&) : 5
              SPRITECHANGE:(index&,time&,bitmap&,maskBitmap&,invertMask&,dx&,dy&) : 6
              SPRITEDRAW:() : 7
              SPRITEPOS:(x&,y&) : 8
              SPRITEDELETE:(id&) : 9
              SPRITEUSE:(id&) : 10
        END DECLARE

### Compatibility

ER5 WINS OPXs are not useable on the ER3 EPOC Emulator, and ER3 WINS OPXs will not work on the ER5 Emulator. However, ER5 MARM OPXs will work on ER3 EPOC devices, and ER3 MARM OPXs will work under ER5.

## `BITMAPLOAD&:`

Usage: `id&=BITMAPLOAD&:(name$,index&)`

Loads a bitmap from the file `name$` (in the current directory if no other is specified). If the file contains more than one bitmap, then `index&` specifies which bitmap to load. The first (or only) bitmap is specified by `index&` having the value 0. The value returned is the ID of the open bitmap, which may be used to refer to it when calling sprite procedures or when using gBUTTON, for example.

See BITMAPUNLOAD:.

## `BITMAPUNLOAD:`

Usage: `BITMAPUNLOAD:(id&)`

Unloads the bitmap whose ID is `id&`. You can call BITMAPUNLOAD: immediately after passing the bitmap ID to gBUTTON or, if used with the Sprite OPX procedures, after drawing the sprite, as the access count on a bitmap is incremented to ensure it is not unloaded prematurely.

See BITMAPLOAD&:.

## `BITMAPDISPLAYMODE&:`

Usage: `mode&=BITMAPDISPLAYMODE&:(id&)`

Returns the graphics mode of the bitmap with ID `id&`. The graphics mode is that specified at its creation (see gCREATEBIT), i.e. 0 for 2-colour mode, 1 for 4-colour mode and 2 for 16-colour mode.

## `SPRITECREATE&:`

Usage: `id&=SPRITECREATE&:(winId%,x&,y&,flags&)`

Initialises a sprite in the window given by `winId%` with its top left-hand corner at `x&,y&`. The value of `flags&` determines whether or not the sprite’s members are flashing. If `(flags& AND 1)=1` then they are flashing and if the value is 0 then they are not. The value returned is the ID of the sprite which should be used when referring to it in other sprite procedures.

See SPRITEAPPEND:, SPRITECHANGE:, SPRITEDRAW:, SPRITEPOS:, SPRITEDELETE:, SPRITEUSE:.

## `SPRITEAPPEND:`

Usage: `SPRITEAPPEND:(time&,bitmap&,maskBitmap&,invertMask&,dx&,dy&)`

Appends members or frames to the current sprite, which must have been created using CREATESPRITE&: before attempting to append to it. `bitmap&` is the ID of the bitmap to be used for this member of the sprite, and `maskBitmap&` is the ID of the bitmap to be used as a mask. The bitmap and mask must be of identical sizes. `invertMask&` takes the value of 1 or 0 to determine whether the mask is to be inverted or not respectively. For example, if you are using identical bitmap and mask and `invertMask&=1` then the member will appear as the bitmap, whereas if `invertMask&=0`, the member will be blank. `time&` is the period of time in microseconds for which the member appears in the sprite and `dx&,dy&` is the offset position of the top left-hand of the bitmap from the top left-hand corner of the sprite.

See SPRITECHANGE:.

## `SPRITECHANGE:`

Usage: `SPRITECHANGE:(id&,time&,bitmap&,maskBitmap&,invertMask&,dx&,dy&)`

Changes a member of a sprite originally set up with SPRITEAPPEND.

`id&` specifies the number of the sprite member which is to be changed. This number is determined by the order in which the members were originally appended, the first member to be appended being labelled 0. `bitmap&` is the ID of the bitmap to be used for this member of the sprite, and `maskBitmap&` is the ID of the bitmap to be used as a mask. The bitmap and mask must be of identical sizes. `invertMask&` takes the value of 1 or 0 to determine whether the mask is to be inverted or not respectively. For example, if you are using identical bitmap and mask and `invertMask&=1` then the member will appear as the bitmap, whereas if `invertMask&=0`, the member will be blank. `time&` is the period of time in microseconds for which the member appears in the sprite and `dx&,dy&` is the offset position of the top left-hand of the bitmap from the top left-hand corner of the sprite.

A sprite may not be changed unless it has already been drawn.

See SPRITEAPPEND:, SPRITEDRAW:.

## `SPRITEDRAW:`

Usage: `SPRITEDRAW:`

Draws the sprite once it has been set up. It need only be called once, and any changes made to the sprite are made as soon as the procedure making the change is called. The sprite will be drawn in the window and at the position specified by the arguments passed to SPRITECREATE.

See `SPRITECREATE&:`, `SPRITEAPPEND:`, `SPRITECHANGE:`, `SPRITEPOS:`.

## `SPRITEPOS:`

Usage: `SPRITEPOS:(x&,y&)`

Repositions the whole of the current sprite to the point `x&,y&`.

See `SPRITECREATE&`:,`SPRITEDRAW:`.

## `SPRITEDELETE:`

Usage: `SPRITEDELETE:(id&)`

Deletes the sprite with ID `id&`.

## `SPRITEUSE:`

Usage: `SPRITEUSE:(id&)`

Sets the current sprite to be that with ID `id&` in order that it may be changed.

See `SPRITECHANGE:`, `SPRITEPOS:`.

Note that using many sprites at one time may cause undesirable effects. Firstly, sprites maybe animated at a slower speed than requested, and secondly the response time to any key or pointer event can be lengthened considerably. The number of sprites which can be drawn at one time without these effects occurring depends mainly on the animation speed: the faster it is the less sprites may be used successfully at one time. As a general rule, it is advisable not to use more than around 20 sprites at any one time when the animation speed is 0.2 sec, but you should experiment to find out what is suitable for your particular program.