AMCAF Extension V1.40 Manual  Index

Additional Information


Bank Information

AMOS banks are a linear block of memory (there are two Exceptions). In these chunks various kinds of data is stored.
AMOS uses them mostly for packed graphics, sounds, music, AMAL programs, menus, resources and other data.

Generally, there are four main types of banks:

Icons and Sprites Banks

These banks do NOT consist of an linear block of memory. Therefore you neither can move, copy, encode, pack them nor make a checksum from them.
In addition, icon and sprites banks must always be in Chip ram.

Permanent Banks

These banks are called permanent, because they survive calls to Default, Erase Temp and the start of a program.
Moreover, they are saved along with the program. Normally, permanent banks have the name 'Datas'.

Temporary Banks

Temporary banks only exist during the execution of the program. They are erased on every start, testing or saving process or using the commands Default or Erase Temp.
Normally, temporary banks have the name 'Work'.

Chip Ram

On Amiga computers, chip ram is the area in memory, which is accessed by both custom chips and the CPU.
At the moment, the size of chip ram is limited to 2 MB (even on A1200 and A4000), and old A500 do only have 512 KB chip ram by default.
For that reason your program should not use more than this 512 KB of chip memory. However, this does NOT mean, that your program needs to run on 512 KB total memory!

As custom chips access the memory at the same time with the processor, the CPU is slowed down, if the program is held in chip ram.
This effect is even more severe if the screen uses more than 16 colours in lowres or more than 8 colours in hires (not A1200/A4000).

Chip ram is mainly required for screens, bobs and sprites, music and sound effects, floppy disk drives and copperlists.

Fast Ram

Fast ram is the memory area which the custom chips don't have access to. So the processor is not slowed down, if the program runs in fast ram.

BUT: You must not store any data for bitplanes, bobs and sprites, music or sound effects and then try to access it by the custom chips.
This has very unpleasant if not lethal results in most cases.

All Amigas excluding the A3000/A4000 do not have fast ram mounted by default.

Ranger Ram

Ranger ram is a special type of ram: it is neither chip nor fast ram and only exist on an Amiga A500 that has a trap door slot memory expansion.
The custom chips cannot access this ram, although the memory is not faster at all

There's a way to make ranger ram to chip ram. Just resolder jumper 2 on the main board and switch off the memory expansion. I am not responsible for any possible damage that may occur by doing this.

Byte

A bytes has got 8 bits, therefore you can display values from 0 up to 255. A byte normally has got the suffix '.b' (in assembler).
Two bytes together create a Word, four a Longword.

Word

A word consists of two Bytes so that is 16 bits. With these 16 bits you can store addresses or data up to 64KB (65536).
A word must be on a even memory address or machines with MC68000 CPU will crash with Guru number $80000003.
Since MC68020 this is not important, but you never should assume that there is no MC68000 in the computer and use odd addresses!

If you insist on using uneven addresses, check out the installed cpu using the Cpu function, if a 68020 or higher is fitted.

Longword

Four bytes result in a unit of 64 bits. These units are called longwords and are used to address up to four gigabyte of data.
For that reason they are used for every absolute address in memory. As with Words, they must lie on a even address boundary.

Cyclic

If a number reaches the upper boundary, the number is set to the lower boundary value and vice versa.

Example:

UB=31 (upper boundary)
LB=1  (lower boundary)
N=3   (number)
Do
  Inc N
  If N>UB Then N=LB
  If N<LB Then N=UB
  Print N
Loop

AGA Amiga

The new Amigas A1200, A4000 and CD≥≤ have the AGA-Chipset.
This new chipset makes is possible not only to display 6 Bitplanes but even 8 Bitplanes in nearly every resolution.

These Amigas have 12 additional colour bits to the normal 12 bits ($0RGB) and therefore can use a 24 bit value ($00RRGGBB).
Even if AMOS Pro V2.0 does not currently support AGA, nevertheless AMCAF contains some commands for the future implementation.

The most important advantages of AGA-Amigas:

My advice: If you still have an old Amiga you should think about buying a new Amiga, it's worth it!

Amiga HAM Mode

As the Amiga can only display 6 or 8 bitplanes and you need much more colours than 64 or 256 colours to achieve photo quality. The Amiga developers invented a new tricky display mode: The HAM Mode (abbreviation for "Hold And Modify").

HAM6 (without AGA chipset):
The first 16 colours can be set as normal, these are displayed on the screen as usual.

The colours 16 to 31 modify the blue part of the last colour to the left.
Same with the colours from 32 to 47, which alter the green value and the colours from 48-63 change the red value accordingly. So you can display all the 4096 colours using only 6 bitplanes.

HAM8 (AGA chipset required):
Like the HAM6 mode the first colours are displayed correctly, but in HAM8 the base palette has got 64 colours.
The rest of the colours from 64 to 255 are responsible for the modification of the previous colour like shown above.
Using this technique and a intelligent base palette you can display every colour in the 16777216 colours big palette.

Disk Object

A disk object can be:

The Blitter Chip

The Blitter is a co-processor inside the Amiga which is mainly used to copy and combine data (therefore BLockImageTransferER). Additionally, it can fill polygons and draw lines.
The Blitter is rather fast at this and works with an unbelievable speed of up to 16 million pixels per second. All data that is accessed by the Blitter chip must be in Chip ram.

AMOS uses the blitter for Bobs, Icons, Screen Copy and many other commands. The MC68020 and higher is much faster if only need to copy data.

The Blitter works at word boundaries and this results in cutting down the X coordinates to the nearest multiple of 16.

To fill a polygon using the Blitter, the lines must be only one pixel thick. This is the reason why there are two different ways to draw lines.

Blitter Minterms

The Blitter chip knows 256 different copying and combining modes. These are determined in two steps:

  1. Eight different boolean terms are used upon the three databits. Each of the terms returns true on a specific combination of A, B and C.
  2. These eight results of the terms are combined together using a logical OR. This result is the target bit D.
Bit    Minterm     Input-Bit
       ___
 0     ABC         000
       __
 1     ABC         001
       _ _
 2     ABC         010
       _
 3     ABC         011
        __
 4     ABC         100
        _
 5     ABC         101
         _
 6     ABC         110

 7     ABC         111

Procedure:

  1. At which of the eight combinations of ABC should D be true?
  2. Now set the bits of the bitmask.
  3. If not all of the three source data streams are required, every combination with the unused bits and the desired bits must be chosen.

Protection Flags

These flags contain information about the type of a certain Disk object.

The protection value consists of following bits:

Bit 0=0: File can be erased
Bit 1=0: File is executable
Bit 2=0: File can be overwritten
Bit 3=0: File can be read
Bit 4=1: File has not been changed after copying
Bit 5=1: Executable can be made resident.
Bit 6=1: File is an Amiga-DOS script
Bit 7=1: File is hidden (does not actually work)

As you see, this is rather chaotic. So you're advised to use the function Object Protection$ to convert this bitmap into a String in the format "hsparwed".

The TOME Extension

TOME is an extension for AMOS Creator and recently for AMOS Professional too, which is dedicated to tile and map programming. These tiles are used in many games e.g Jump'n'Runs or strategy games.

As the whole game map would be far to memory hungry when kept as standard bitmap, the main graphics are cut into small pieces, so that they can be used repeatedly.
The map therefore only consists of one byte per position which points to the corresponding tile.

The current version of TOME is TOME V4.30.

AMCAF Database Structure

Version: V1.15
Length : 1964 Bytes
Note   : Contrary to most other extensions, the database is not
         kept in the AMCAF.Lib file. Therefore AMCAF is very compact
         (*only* 40 KB!?).

                rsreset         ;Stars
St_X            rs.w    1       ;0
St_Y            rs.w    1       ;2
St_DbX          rs.w    1       ;4
St_DbY          rs.w    1       ;6
St_Sx           rs.w    1       ;8
St_Sy           rs.w    1       ;10
St_SizeOf       rs.b    0       ;12

                rsreset         ;Splinters
Sp_X            rs.w    1       ;0
Sp_Y            rs.w    1       ;2
Sp_Pos          rs.l    1       ;4
Sp_DbPos        rs.l    1       ;8
Sp_Sx           rs.w    1       ;12
Sp_Sy           rs.w    1       ;14
Sp_Col          rs.b    1       ;16
Sp_BkCol        rs.b    1       ;17
Sp_DbBkCol      rs.b    1       ;18
Sp_First        rs.b    1       ;19
Sp_Fuel         rs.w    1       ;20
Sp_SizeOf       rs.b    0       ;22

                rsreset         ;Blitterqueue
Bn_Next         rs.l    1
Bn_Function     rs.l    1
Bn_Stat         rs.w    1
Bn_Dummy        rs.w    1
Bn_BeamPos      rs.w    1
Bn_CleanUp      rs.l    1
Bn_B40l         rs.l    1       ;BLTCON0&BLTCON1
Bn_B44l         rs.l    1       ;Masks
Bn_B48l         rs.l    1       ;Source Address C
Bn_B50l         rs.w    1
Bn_B52w         rs.w    1       ;Source Address A.w
Bn_B54l         rs.l    1       ;Target Address D
Bn_B58w         rs.w    1       ;BLTSIZE
Bn_B60w         rs.w    1       ;Modulo C
Bn_B62l         rs.w    1       ;Modulo B&A
Bn_B64w         rs.w    1       ;Modulo A
Bn_B66w         rs.w    1       ;Modulo D
Bn_B72w         rs.w    1       ;BLTBDAT
Bn_B74w         rs.w    1       ;BLTADAT
Bn_XPos         rs.w    1
Bn_SizeOf       rs.b    0

                rsreset         ;AMCAF Main Datazone
O_TempBuffer    rs.b    80
O_FileInfo      rs.b    260
O_Blit          rs.b    Bn_SizeOf
O_BobAdr        rs.l    1
O_BobMask       rs.l    1
O_BobWidth      rs.w    1
O_BobHeight     rs.w    1
O_BobX          rs.w    1
O_BobY          rs.w    1
O_StarBank      rs.l    1
O_StarLimits    rs.w    4
O_StarOrigin    rs.w    2
O_StarGravity   rs.w    2
O_StarAccel     rs.w    1
O_StarPlanes    rs.w    2
O_NumStars      rs.w    1
O_CoordsBank    rs.l    1
O_SpliBank      rs.l    1
O_SpliLimits    rs.w    4
O_SpliGravity   rs.w    2
O_SpliBkCol     rs.w    1
O_SpliPlanes    rs.w    1
O_SpliFuel      rs.w    1
O_NumSpli       rs.w    1
O_MaxSpli       rs.w    1
O_SBobMask      rs.w    1
O_SBobPlanes    rs.w    1
O_SBobWidth     rs.w    1
O_SBobImageMod  rs.w    1
O_SBobLsr       rs.w    1
O_SBobLsl       rs.w    1
O_SBobFirst     rs.b    1
O_SBobLast      rs.b    1
O_QRndSeed      rs.w    1
O_QRndLast      rs.w    1
O_PTCiaVbl      rs.w    1
O_PTCiaResource rs.l    1
O_PTCiaBase     rs.l    1
O_PTCiaTimer    rs.w    1
O_PTCiaOn       rs.w    1
O_PTInterrupt   rs.b    22
O_PTVblOn       rs.w    1
O_PTAddress     rs.l    1
O_PTBank        rs.l    1
O_PTSamBank     rs.l    1
O_PTTimerSpeed  rs.l    1
O_PTDataBase    rs.l    1
O_PTSamVolume   rs.w    1
O_AgaColor      rs.w    1
O_HamRed        rs.b    1
O_HamGreen      rs.b    1
O_HamBlue       rs.b    1
                rs.b    1       ;Pad
O_VecRotPosX    rs.w    1
O_VecRotPosY    rs.w    1
O_VecRotPosZ    rs.w    1
O_VecRotAngX    rs.w    1
O_VecRotAngY    rs.w    1
O_VecRotAngZ    rs.w    1
O_VecRotResX    rs.w    1
O_VecRotResY    rs.w    1
O_VecRotResZ    rs.w    1
O_VecCosSines   rs.w    6
O_VecConstants  rs.w    9
O_BlitTargetPln rs.l    1
O_BlitSourcePln rs.l    1
O_BlitTargetMod rs.w    1
O_BlitSourceMod rs.w    1
O_BlitX         rs.w    1
O_BlitY         rs.w    1
O_BlitWidth     rs.w    1
O_BlitHeight    rs.w    1
O_BlitMinTerm   rs.w    1
O_BlitSourceA   rs.l    1
O_BlitSourceB   rs.l    1
O_BlitSourceC   rs.l    1
O_BlitSourceAMd rs.w    1
O_BlitSourceBMd rs.w    1
O_BlitSourceCMd rs.w    1
O_BlitAX        rs.w    1
O_BlitAY        rs.w    1
O_BlitAWidth    rs.w    1
O_BlitAHeight   rs.w    1
O_PTileBank     rs.l    1
O_BufferAddress rs.l    1
O_BufferLength  rs.l    1
O_PowerPacker   rs.l    1
O_PPCrunchInfo  rs.l    1
O_DiskFontLib   rs.l    1
O_DirectoryLock rs.l    1
O_DateStamp     rs.l    3
O_OwnAreaInfo   rs.b    1
O_OwnTmpRas     rs.b    1
                rs.w    1       ;Pad
O_AreaInfo      rs.b    24
O_Coordsbuffer  rs.b    20*5
O_TmpRas        rs.b    8
O_FontTextAttr  rs.b    8
O_AudioPort     rs.b    32
O_AudioIO       rs.b    68
O_ChanMap       rs.w    1
O_AudioOpen     rs.w    1
O_AudioPortOpen rs.w    1
                rs.w    1       ;Pad
O_PaletteBufs   rs.w    32*8
O_ParseBuffer   rs.b    512
O_SizeOf        rs.l    0

Bitplanes

Let's go for a small tutorial, in which bitplanes and how they work is explained.

1. What is a bitplane?
On an Amiga computer the video picture is created by so called bitplanes. These are linear blocks in chip memory, of which every single bit represents one dot on the screen.

Using only one bitplane, you can only see two different colours (either bit set or bit clear). If more than one bitplane is placed on top of others, you will get 2^n colours for n bitplanes.

   Example:
   We have an 16 colours screen. So it has got 4 bitplanes. Normally, the
   bitplanes are counted from 0 to n-1...

   Binary 0 1 0 1 = Decimal 5
          | | | |    .---v---v---v---v--------------------
          | | | `----+ 1 |   |   |   | Bitplane 0
          | | |      |--v^--v^--v^--v^--v-------------------
          | | `------+--+ 0 |   |   |   | Bitplane 1
          | |        |  |--v^--v^--v^--v^--v------------------
          | `--------+--+--+ 1 |   |   |   | Bitplane 2
          |          |  |  |--v^--v^--v^--v^--v-----------------
          `----------+--+--+--+ 0 |   |   |   | Bitplane 3
                     |  |  |  |---^---^---^---'
                     |  |  |  |
                     |  |  |
                     |  |
                     |

You must imagine the bitplanes to be 'overlapped over each other'. The colour index 5 is displayed in the bitplanes like that.
Which colour the dot on the screen finally has, is determined by the palette settings.

2. Overlapping and Transparency.
Imagine, you draw a figure A in bitplane 0 and a figure B in bitplane 1 only. This produces the following:

The area, on which none of the figures are displayed, has got the colour zero (both bitplanes are cleared: %00).
whereas on regions, where only figure A is appearing, the colour 2^0=1 is used (bit 0 is set, bit 1 is clear: %01).
Figure B alone sets the bit in bitplane 1 and therefore is displayed in colour 2^1=2 (=%10).
If both figures are overlapping, the bits in both bitplanes are set and this results in colour 2^0+2^1=3 (=%11).

Now we can define the palette. For instance:
Palette 0,$F00,$F0,$FF0

The background is black ($000), figure A is red ($F00) and figure B is green ($0F0), when overlapping yellow is generated ($FF0).

By just thinking about this correlation you can achieve nice effects.

Try to find out, how the two figures will look like, when using these palettes:

1. Palette 0,$FFF,$888,$FFF
2. Palette 0,0,0,$FFF

You find the solution below.

3. Glenz and Fade
When e.g a cube appears 'transparent', out of glass or electric, the effect is called 'Glenz'.
This is mostly used for vector effects. There are two major types of Glenz vectors:

a) Wire frame objects:
With Glenz wire frame objects the lines are drawn in a different bitplane per vertical plane keeping the two or three previous frames intact.
These old and new frames then overlap, and by choosing the right palette (additive colour values per bitplane) the points where the lines are overlapping look lighter and somehow glitter.

   Example for an additive colour palette (eight coloured screen):

   DARK=$333 : LIGHTER=$666 : BRIGHT=$FFF

   '    %000 %001 %010   %011  %100   %101    %110   %111
   Palette 0,DARK,DARK,LIGHTER,DARK,LIGHTER,LIGHTER,BRIGHT

Just look at the bit values and count the number of set bits to get the right colour value.

By changing the palette permanently you can also create a Motion Blur or Fade effect.
To achieve this, you must set every colour with the bit for the current bitplane, in which you are drawing at the moment, to the brightest, colour all colours with the bit of the previous bitplane and not with the bit of the current one to a middle colour and so on...

b) Solid objects:
Glenz on solid object is done like this: the polygons, that are facing away from the viewer (and therefore cannot actually be seen) are drawn on an other bitplane than the polygons that face the viewer.
By setting the colours according to the bitplanes, the object will seem to be transparent. The only thing to do is to mix the colours of the bitplanes, in which the different polygons are drawn.

4. Bitplane modes and their specialities.
The old ECS-Amigas can only display up to 6 bitplanes simultaneously. So 2^6=64 colours is the maximum (excluding the HAM mode ).
Though there are some special modes:

a) ExtraHalfBright (EHB).
As the OCS and ECS chipset has only 32 colour registers, the other 32 colours are displayed at half the value. When using EHB you can produce some neat shadow effects by writing into the 6th bitplane.
Note: EHB pictures cannot be faded out perfectly.

b) Hold And Modify (HAM).
HAM is a method, to decompress six bitplanes to twelve bitplanes by hardware. Therefore the colours from 16 to 63 are used reach the wanted colour by changing the red, green or blue value of the previous colour.
Very good for static pictures and pre calculated animation but useless for games and realtime graphics. The only sensible way to display moving objects on a HAM screen is to use sprites.

c) Dual Playfield.
The Amiga chipset can display all even bitplanes (0,2,4) separated from the odd ones (1,3,5).
It's better to say, he puts the one playfield on top of the other by using colour 0 as 'window' to the other playfield.
In this mode each playfield can have 2^3=8 colours.

The chipset has got separate control registers for even and odd bitplanes each, as each Playfield must be independent for Dual Playfield mode.

BitPLane CONtrol (BPLCON0) $100.
Here you determine the number of bitplanes and the resolution and can toggle the special modes.
Bit table:

        15      HIRES           Toggle hires mode
        14-12   BPUx            Number of bitplanes
        11      HOMOD           Toggle HoldAndModify
        10      DBPLF           Toggle Dual Playfield
         9      COLOR           Toggle colour burst output
         8      GAUD            Use audio input from a genlock
         7      8BPL            8 bitplanes (AGA)
         6      SHIRES          Superhires (ECS/AGA)
         3      LPEN            Activate lightpen
         2      LACE            Enable interlace mode
         1      ERSY            Switch to external synchronization

The scroll register (BPLCON1) $102.
By using this register, the screen can be scrolled to the left by up to 15 pixels. The bits 0-3 are used for the even bitplanes, the bits 4-7 for the odd ones.

Modulo registers (BPL1MOD/BPL2MOD) $108/$10A.
These registers set the amount of bytes to be added to the memory of the bitplanes after each rasterline. This is utilized by playfields that are bigger than the visible area.
When writing a negative value you can achieve vertical zoomers or mirror effects.

If you want to alter a register using Set Rain Colour, you can calculate the new 'colour' with the following formula: (REGADR-$180)/2

Note: Enabling 5 to 6 bitplanes in low resolution or 3 to 4 bitplanes in high resolution will cost free processor time, even if you only display the screen.
This is true when the running program is placed in chip ram or must access chip ram.

5. How can I access all these effects?
Simple: Define a rainbow, call Set Rain Colour and enter the new values for the registers using Rain() instead of supporting the colours.
The only limitation: Due to the AMOS rainbow restrictions you can only manipulate ONE (!) register per rasterline.

Look carefully at the example programs. These demonstrate every single effect mentioned here.
By the way: You can get the pointer to the single bitplanes using Logbase(planenr) and Phybase(planenr).
Enjoy!

Solution to the questions in 2:

1. Palette 0,$FFF,$888,$FFF
Figure A is white and is moving 'over' figure B, which is grey, because if they overlap the colour white is created.

2. Palette 0,0,0,$FFF
Figure A and Figure B are invisible as long as they down overlap. Only if both are placed over each other colour 3 is created which was set to $FFF (white).