Blitz:Graphics

Blitz Basic / AmiBlitz has strong support for the use of graphics in programs. There are extensive internal commands for using the Amiga's chipset directly, as well as standard OS calls for using graphics via the Amiga API. AmiBlitz also comes with various Include files which add many functions for handling graphics in a modern and system-friendly way.

General Graphics Concepts

Graphics on the Amiga are handled in a nice, pseudo-object-orientated fashion. In general, the objects that can be manipulated are as follows:

Bitmaps

Bitmap objects are areas of memory allocated for storing graphics data. Graphics can be drawn directly to a bitmap in memory for displaying later, or a bitmap may be attached directly to a rastport, in which case any drawing carried out can be seen immediately. Bitmaps can be created in any size and number of colours, memory, hardware and OS permitting. Bitmaps are natively planar on the Amiga and use indexed colour, meaning the colours aren't defined in each pixel. Instead, a colour index is stored in the pixel, which is translated by the display hardware into an actual colour by looking the index up in a palette object. Chunky bitmaps store the actual colour information for each pixel in the pixel, but can't be used natively by the Amiga chipsets and therefore aren't supported by the built-in Blitz commands. They can be used with the AmiBlitz includes however, and if you have a graphics card they are used natively which is normally very fast.

In general, bitmaps should be of the same depth as the screen they are to be displayed on, otherwise problems can occur. Planar bitmaps range in depth from 1-bit (2 colours) to 8-bit (256 colours).

Rastports

A rastport is an area of memory allocated for displaying on screen. It is similar to a bitmap, but whatever information is present in that memory block is immediately available to be displayed on screen. A window's content is normally a rastport, likewise for a screen. Normally a bitmap is copied to a rastport in order to display the bitmap contents on a screen or within a window, but a rastport can also point directly at a bitmap, in which case no copying is required and therefore can be used to speed up programs. The disadvantage of this technique is that any modifications to the bitmap are shown immediately in the rastport, so graphics may flicker or not appear smoothly, especially for slower drawing routines or when many items need to be drawn.

Shapes

Shapes are areas of memory used to store individual graphical objects and are not normally displayed on their own. Typically they are used to hold items that are later drawn (or blitted) to a bitmap, for example symbols on a map or a player's on-screen character. Normally they are created by copying a section of a previously drawn bitmap or loading directly from disc rather than being drawn directly, but it is also possible to point a bitmap at a shape and draw directly into it.

Sprites

Sprites are similar to shapes, except that they are displayed on-screen independently of the rastport. This means they can be moved and manipulated without affecting the on-screen graphics. The mouse pointer is an example of a sprite - windows underneath the pointer don't have to worry about redrawing themselves after the pointer has moved over them. The native Amiga chipset provides sprite hardware that allows them to be drawn and redrawn with practically no CPU usage, so they can be used to great effect in fast-moving games. The hardware also provides functions such as collision detection between sprites and other sprites, or the underlying rastport information. Sprites are however hardware-dependent, and that means the number of sprites available for use, as well as their size and depth are physically limited by hardware. Different Amiga chipsets have differing sprite capabilities as well.

Palettes

Palette objects describe the colours assigned to each bit in a planar or indexed bitmap, and take the form of a look-up table in memory. Bitmaps themselves don't contain any palette information, though graphics files on disc normally include a palette object too. The palette object is normally applied to a screen, and from there affects every rastport on that screen and the bitmaps they display. A palette object can be modified, and if applied to a currently displayed screen, will cause the modified colours to change immediately.

It is important to ensure that all graphics to be shown on the same screen are created using the same palette, otherwise their colours might not be correct when displayed, since only the colour index is taken into account and looked up against the screen's palette. Special consideration should be given to sprites or dual playfields if their usage is planned, as they use fixed colour index offsets from the screen's palette, regardless of the screen's depth. See Sprite colours for more details.

Other General Techniques

Double-buffering is a concept that sometimes appears confusing, but is actually relatively straightforward. The basic idea is that two bitmaps are used for the screen or window's display, with alternate bitmaps being displayed each frame or update. Any graphics changes are made to the bitmap which isn't displayed while the other bitmap is being shown. When ready, the updated bitmap is displayed, replacing the original bitmap which is now free to be edited and updated. This cycle runs constantly, providing smooth, flicker-free graphics. Usually the swapping of bitmaps is synchronized to the vertical refresh of the display as this ensures the change is flicker-free.

Built-in Commands

The built-in graphics commands are very easy to use, and are fast to execute too. They support the standard Blitz concept of objects which simplifies code, so you can reference objects like Bitmap 1 or Shape 17. Many of them access the Amiga custom chips directly however in order to achieve this speed and simplicity. This means that many of them can cause problems working on systems with a graphics card, and generally they won't work at all on non-classic systems such as AmigaOne and MorphOS machines. AmiBlitz will highlight such commands in red to alert you to potential problems, however Blitz Basic does not so if you're using Blitz 2.1, please be aware that your programs might have this limitation.

Details on some of the specific commands and their usage are available in the Built-in Graphics Commands page.

Amiga API

Using the Amiga API is the "correct", system-friendly way of displaying and manipulating graphics, and means that your code should work with any versions of AmigaOS or compatible. As with any API, care must be taken however to check for compatibility with the target version of the OS, as some calls were only added for certain versions and above. For example, some API calls were only introduced in OS 2.x and so software using these calls won't work on 1.x. Generally the OS releases are backwards compatible however, so if your software only uses 1.x API calls, it should still work on all versions since then.

The downsides of using the API are that it's a little bit slower than accessing the hardware directly on computers with the required custom chips, and that they generally refer to objects using pointers instead of simple object ID numbers. This means that you should be familiar with the techniques for programming the Amiga API to take this approach. Fortunately, using the API in Blitz is very similar to using it in C so there are many general examples around, and the official SDK graphics section contains lots of relevant information too.

Most graphics tasks are handled by the graphics.library API. Information on this API, including detailed descriptions of the functions and information regarding compatibility can be found in the graphics.library Autodocs.

AmiBlitz Includes

The Amiblitz Includes for handling graphics use the Amiga API calls and their own custom code to provide easy to use functions not dissimilar to the built-in Blitz commands, but in a system-friendly way. They also support full 24-bit colour, 32-bit colour with alpha and many useful manipulation functions. However, this does mean they can be quite slow on classic hardware, and care must be taken to avoid the many functions that assume the use of a graphics card.

The main Include file for handling graphics is image.include.ab3. This includes all the functions needed for loading and manipulating shapes and blitting them to bitmaps, as well as functions for saving graphics files. These functions use chunky graphics formats and as a result, there is no need to worry about the palette usage. However, most functions won't work properly without a graphics card. The graphics are stored in memory as an Image-type object, similar to a native Blitz Shape but incompatible.

Additionally, the dbl_display.include.ab3 Include file contains many functions for creating a double-buffered display, allowing images to be drawn and bitmaps to be displayed quickly and flicker-free.