Blitz:Blitz Mode

The Amiga OS is a great operating system, but with the limited power available when the Amiga was released first it made sense to bypass the OS and use the hardware directly. This disabled multitasking and took over the machine, but allowed games to run faster and with more colours without worrying about other tasks needing access to resources.

Blitz Basic / AmiBlitz can use a special mode called "Blitz Mode" which suspends the OS like this and allows full, unrestricted access to the Amiga's features by using a special set of commands. Your program can swap in and out of Blitz mode at will, but bear in mind that any OS features that rely on other tasks, e.g. intuition, file access etc. will be unavailable in Blitz mode.

Generally, freezing the OS like this is considered antisocial on a multitasking OS, so please be sure you really need to use it. Also, bear in mind that it will only work on "real" Amigas with the custom chipsets since it uses the chips directly, so using Blitz mode automatically rules your program out of working on a next-gen Amiga system.

Switching Modes

To switch to Blitz mode, the keyword Blitz is simply used. When your program reaches this command, the OS is instantly suspended and the screen will go blank. Everything the system does from this point on must be done by accessing the chips directly.

To switch back to normal mode, use the keyword Amiga. This will restore the OS to normal running mode, and Intuition will redraw the screen as it was before Blitz mode was entered. Please remember however, that even though operation is resumed, if some task was unexpectedly interrupted when Blitz mode was activated, some unexpected behavior could result. For example, writing to a file on disk could result in a corrupted file, or even a corrupted partition. For this reason, always ensure nothing else is happening when using Blitz mode. There isn't a 100% safe way of doing this, so generally it's just an idea to not use Blitz mode at all if you want your software to be used in a multitasking environment, and if you must use Blitz mode, add a small delay before entering Blitz mode to allow any disk caches to be flushed:

VWait 250
BLITZ

This will pause for 5 seconds (on a PAL machine; 4 seconds on an NTSC Amiga) before entering Blitz mode.

QAmiga Mode

This is a special mode that is useful when your program mostly runs in Blitz mode. It switches the Amiga back to a limited Amiga mode, keeping the Blitz display and custom chip registers intact. This allows your program to use OS functions for accessing files without reverting to the standard OS display. The Blitz display can't be updated in this mode however, instead will appear frozen until your program returns to Blitz mode.

As with other mode switch commands, simply executing the command QAmiga will enter the QAmiga mode, and executing the Blitz command will return your program to Blitz mode where it left off.

Creating a Blitz Mode Display

Blitz Basic supports two separate systems for creating displays in Blitz mode: the Slice library and the Display library. The Slice library is inherited from older versions of Blitz Basic, and supports the capabilities of the OCS/ECS chipsets only. The Display Library was introduced in Blitz Basic 2 as a replacement for the Slice library that also includes more flexibility and support for the AGA chipset. If you only need to support OCS/ECS graphics then either library can be used, however to use AGA graphics you'll have to use the Display library. Note that you can only use one library or the other - commands from the Slice library won't work with a display built using the Display library for example.

The Slice Library

Slices are Blitz mode's rough equivalent to screens in Amiga mode. Setting them up is easy with the Slice command:

Slice 0, 44, 5

This simple form of the command takes just three parameters: The 0 is the Slice object ID to create. 44 is the vertical position of the slice from the start of the actual display drawing process, and 44 is a typical value to have the slice located at the top of the visible area. Finally, 5 is the number of bitplanes to use, which can be anything from 1 to 6. This example will give us a 320x256 display on a PAL Amiga, or 320x200 on an NTSC Amiga, with 32 colours available. You can add 8 to the depth to open a high res screen instead, in which case the horizontal resolution will be increased to 640.

A more comprehensive version of this command is also available, with the following template:

Slice Slice#, Y, Width, Height, Flags, BitPlanes, Sprites, Colours, w1, w2

These parameters allow you to set up more specific slice parameters. Slice # and Y are the same as before - the new Slice ID and the vertical position (typically 44). Width and Height are the dimensions of the slice to create in pixels. Flags sets the properties of the slice, including screenmode and other special flags. More information is available in the Blitz manual, however these are probably the most useful flag values:

Value	Slice Properties
$FFF8	Standard, low resolution
$FFF9	Standard, high resolution
$FFFA	Dual playfield, low resolution
$FFFB	Dual playfield, high resolution

The bitplanes parameter sets how many bitplanes you wish to use for the bitmaps you will be displaying with this slice, and can be 1 to 6. Sprites is the number of sprite channels you want to use with this slice, and should normally be set to 8 to prevent flickering caused by unused sprite channels. Colours is the total number of pens to have available in the palette for this slice, up to 32. Finally, w1 and w2 are the widths of the bitmaps you wish to display on this slice, w1 being the foreground bitmap width and w2 being the background bitmap width. If you're not using a dual-playfield display, you should set both of these values to the same number. Bitmaps larger than the screen can be displayed and scrolled around easily by setting this value to the width of the bitmap or bitmaps.

More than one slice can be created on the same display by using multiple Slice commands with unique IDs and different Y values. However, unlike screens, they can't overlap, and depending on the situation (number of colours, chipset etc.), 2 or more blank lines may be required between slices.

Like many other Blitz objects, the current slice can be set by using the command:

Use Slice 0

After which slice 0 will be the currently used slice. Slices can also be freed similarly to other Blitz objects:

Free Slice 0

This disposes of the slice and frees the memory taken up by it. No more operations should be carried out on a freed slice!

Displaying Bitmaps

Bitmaps can be displayed on the currently used slice by using the Show, ShowB or ShowF commands. Show is used for a standard slice:

Show 0

Displays bitmap 0 on the current slice. The top left of the bitmap will be positioned at the top left of the slice. ShowB works the same way except it displays the bitmap as the background of a dual playfield slice. ShowF is again similar, except it displays the bitmap as the foreground of a dual playfield slice.

Optionally, X and Y coordinates can be provided to any of the Show commands above. If they're given, the bitmap will be shown with these coordinates at the top left of the slice instead of with 0, 0 at the top left:

ShowB 2, 25, 50

Displays bitmap 2 as the background, with the point at 25x50 on the bitmap placed at the top left of the slice.

Sprites

To show a sprite on the display, use the ShowSprite command:

ShowSprite 1, 100, 50, 5

This takes Sprite object ID 1 and displays it through sprite channel 5 (meaning pens 1-3 of the shape are shown as pens 25-27 of the display). The sprite is displayed at the coordinates 100x50, and these coordinates are always given as low-resolution coordinates, regardless of the actual display mode given. Note that this command is only applicable when using Slice library commands - the newer Display library uses the DisplaySprite instead which allows the use of higher resolutions on AGA machines.

See the Internal Graphics Commands page for information on creating sprite objects.

Palette

To apply a Blitz Palette object to the current slice, use the ShowPalette command:

ShowPalette 3

This copies the colours from Palette object ID 3 to the currently used slice.

To read more about Blitz Palette objects, see the Blitz Graphics section.

The Display Library

The display library is similar in concept to the slice library described above, however it uses a more flexible approach, and also supports the extended capabilities of the AGA chipset. It translates more closely to how the Amiga display hardware actually works, which gives the programmer more control over its behaviour. Unfortunately this can also make it appear slightly more complicated to use.

Defining the display

To create a display, first you need to set up the Coplist. A Coplist is a set of low-level instructions used by the "Copper", a special circuit that controls how the on-screen display is built from information in Chip memory, line-by-line. Programming the copper allows for some interesting tricks and effects (such as changing colours of pens part of the way down the screen, reusing sprites further down the screen, etc.) The program itself is built internally by Blitz, but you need to tell it what type of display you require first. This is achieved using the InitCopList command. As with the Slice command, there are two versions of this, a short version which sets up the Coplist with typical values based on the flags you provide, and a long version that lets you control more aspects. The short version looks like this:

InitCopList 0, $10000+$20+$6

The 0 is the ID of the Coplist object to create, and the second parameter is the flags value. Flag parameters should be added together, and the number of bitplanes required should be added to the flags as well. The flags are listed in the Blitz manual, but the important ones are as follows:

Value	Coplist Properties
$10	Enable smooth scrolling
$20	Dual playfield display
$40	Extra-halfbrite (EHB) display mode
$100	Make high resolution (640 pixels wide)
$400	Use low resolution sprites
$800	Use high resolution sprites
$1000	Enable fetch mode 1
$2000	Enable fetch mode 2
$3000	Enable fetch mode 3
$10000	Use AGA palette

Fetch mode refers to the access the Copper has to the Chip memory at the start of each display line, where it fetches the bitplane information it needs for the upcoming line of graphics to be drawn. The default is fetch mode 0, which is the OCS/ECS chipset mode. Higher fetch modes are AGA only and allow more bitplane data to be read on every line, increasing the the number of bitplanes available in every resolution to 8 (256 colours), including VGA-style 31kHz modes. However, they also reduce the bandwidth available for the rest of the display, so to have many large sprites displayed at the same time, you'll need to reduce the horizontal width of your screen, otherwise sprites might go missing or other issues might crop up. Most other flags are self-explanatory.

AGA palette means that the RGB values possible range from 0-255 in each of the red, green and blue components (8 bits per channel for a 24-bit palette) instead of the OCS/ECS range of 0-15 (4 bits per channel for a 12-bit palette). Obviously using any of the AGA-specific values (high resolution sprites, 8 bitplanes, fetch modes, AGA palette) means that your software will only work on AGA machines.

The longer form of the InitCopList command has the following template:

InitCopList CopList#, ypos, height, flags, sprites, colors, customs

CopList# is the ID of the Coplist to create, ypos is the vertical position on the screen, with 44 being a typical value as with slices. The height of the display is defined in pixels, and the flags parameter is described above. Sprites is the number of sprite channels to use, and should normally be 8, even if you don't use them. Colours is the number of pens you want available, up to 256 on AGA machines or 32 on OCS/ECS machines. Note that this refers to the number of palette registers allocated for the CopList, not the number of bitplanes as defined in the flags field. For using sprites for example, you will want to allocate 32 pens, even if you're only using an eight-colour, three-bitplane display, because the sprites use pens 17-31. Finally, customs is the amount of memory to allocate for custom copper commands. This can normally be set to 0 unless you intend to use a custom Coplist you write yourself, or one of the custom copper commands listed in the Blitz manual.

Once the Coplist is defined, the display can be opened using the CreateDisplay command:

CreateDisplay 0

This creates a display based on Coplist object ID 0. As for slices, more than one Coplist can be displayed, provided they are defined in vertical order and do not overlap. Multiple Coplists can be displayed by adding the required Coplists to the CreateDisplay command:

CreateDisplay 0, 1, 2

Displaying Bitmaps

Bitmaps can be shown on any Coplist using the DisplayBitmap command:

DisplayBitmap 0, 1

Shows Bitmap object ID 1 on Coplist display ID 0. The top left of the bitmap will be placed at the top left of the display. Similarly to the Slice methods, coordinates can be given to show a different area of the bitmap:

DisplayBitmap 0, 1, 50, 25

In this case, bitmap 1 will have coordinates 50x20 placed in the upper left corner of the display.

Dual playfield displays also use the DisplayBitmap command for showing the second bitmap:

DisplayBitmap 0, 1, 2

This will display bitmap 1 as the rear playfield with bitmap 2 in front, both on Coplist 0. Coordinates can also be added independently for both bitmaps to show another section of each bitmap:

DisplayBitmap 0, 1, 50, 25, 2, 30, 60

Coordinates 50x25 on the rear bitmap are positioned in the top left of the display, with coordinates 30x60 on the front bitmap positioned at the top left.

Note: On AGA machines, fractional arguments are allowed for the x coordinates, in which case bitmaps will be positioned using fractions of a pixel. This allows for super-smooth horizontal scrolling. To enable this however, the Coplist must have the smooth scroll flag set. Note that this flag will disable sprite channel 7 due to the DMA timing required for sub-pixel scrolling.

Sprites

Sprites have a separate set of commands for use with the Display Library. They can be created in the same way as covered in the Internal Graphics Commands page, but to display them, you need to use the DisplaySprite command:

DisplaySprite 0, 1, 150, 75, 5

This will display the Sprite object 1 on Coplist 0 at the coordinates 150x75, using sprite channel 5. Again, on AGA machines, fractions of pixels are possible for the x position in order to synchronise with a smooth scrolling display.

To use sprites wider than 16 pixels, you need to have the fetch mode for the sprites set appropriately; change the sprite mode using the SpriteMode command:

SpriteMode 2

This should be run before creating the CopList or any sprite objects. Sprite mode 0 is the same as OCS/ECS, and allows sprites 16 pixels wide. Sprite mode 1 allows up to 32 pixels wide, and sprite mode 2 allows up to 64 pixels wide.

Palette

To apply a Blitz Palette object to the coplist, use the DisplayPalette command:

DisplayPalette 0, 3

This copies the colours from Palette object ID 3 to Coplist 0.

To read more about Blitz Palette objects, see the Blitz Graphics section.