Amos Professional Unity - SpecialFX extension - Commands Set


Amos Professional Unity "SpecialFX" extension commands list


This list will evoluate with the development of the AmosProUnity_SpecialFX.lib
There are currently 24 new commands added by the "Personal" extension.


___________________________________________________________________

Standard Commands set :
____________________________________________________________________

Command Name : Get File Size

Syntax :
  SIZE_IN_BYTES = Get File Size( FILENAME$ )

Details :
This method will return the size of a file in Bytes.

Additional informations :
-

Command Name : Set Ntsc

Syntax :
  Set Ntsc

Details :
Switch the amiga in 60hz mode.

Additional informations :
-

Command Name : Set Pal

Syntax :
  Set Pal

Details :
Switch the amiga in 50hz mode.

Additional informations :
-

Command Name : Right Click

Syntax :
  STATE = Right Click()

Details :
This method will return the state of the right mouse button
STATE = 


Additional informations :
-

Command Name : Fire()

Syntax :
  STATE = Fire(1,BUTTONID)

Details :
This method can be used to return the state of buttons 2 or 3 of the game controller connected to the default Amiga joystick port
BUTTONID = The ID of the button to test. Values can be 2 or 3 (as button 1 is already tested by native Amos Professional Banks.

Additional informations :
-

Command Name : Ehb

Syntax :
  = Ehb

Details :
This method will return the value 64 used to create Extra Half Brite screens

Additional informations :
Example to open a lowres Extra Half Brite screen : Screen Open 0, 320, 192, Ehb, Lowres

Command Name : Ham6

Syntax :
  = Ham6

Details :
This method will return the value 4096 used to create a HAM 6 screen

Additional informations :
 Example to open a lowres Ham 6 screen : Screen Open 0, 320, 192, Ham6, Lowres


___________________________________________________________________

Memblocks Commands set :
____________________________________________________________________

Command Name : Create Memblock

Syntax :
  Create Memblock MEMBLOCKID, SIZE_IN_BYTES

Details :
This method will create a memblock with the size SIZE_IN_BYTES
MEMBLOCKID = The Number ID of the memblock to read
SIZE_IN_BYTES = The exact size in bytes of the memblock. Read/Write range is 0 to SIZE_IN_BYTES-1

Additional informations :
 You cannot read nor write outside the memblock. These method are fully "memory safe" methods.  Memblocks uses the Amos Professional banks system. This mean they can be loaded using the default Load FILE$,BANKID or Load FILE$ methods, and saved using the default SAVE FILE$, BANKID. These banks are also saved with .AMOS files if they exists in memory when you save/backup your Amos Professional source code.

Command Name : Memblock Exist

Syntax :
  VALUE = Memblock Exist( MEMBLOCKID )

Details :
This method will return 1 if the memblock MEMBLOCKID exist otherwise 0
MEMBLOCKID = The Number ID of the memblock to read
VALUE = 1 if the MEMBLOCKID exists, otherwise 0

Additional informations :
 You cannot read nor write outside the memblock. These method are fully "memory safe" methods.

Command Name : Get Memblock Size

Syntax :
  SIZE_IN_BYTES = Get Memblock Size( MEMBLOCKID )

Details :
This method will return the exact size in bytes of the memblock MEMBLOCKID
MEMBLOCKID = The Number ID of the memblock to read
SIZE_IN_BYTES = The exact size in bytes of the memblock. Read/Write range is 0 to SIZE_IN_BYTES-1

Additional informations :
 You cannot read nor write outside the memblock. These method are fully "memory safe" methods.

Command Name : Write Memblock Long

Syntax :
  Write Memblock Long MEMBLOCKID, POSITION, LONG_VALUE

Details :
This method will write the long/int value (32 bits) at POSITION inside the memblock MEMBLOCKID
MEMBLOCKID = The Number ID of the memblock to read
POSITION = The position to read in the memblock, in the range : 0 <= POSITION < Get Memblock Size( MEMBLOCKID )-1.
LONG_VALUE = The long value (32 bits) to write in the memblock.

Additional informations :
 You cannot read nor write outside the memblock. These method are fully "memory safe" methods.

Command Name : Write Memblock Word

Syntax :
  Write Memblock Word MEMBLOCKID, POSITION, WORD_VALUE

Details :
This method will write the word value (16 bits) at POSITION inside the memblock MEMBLOCKID
MEMBLOCKID = The Number ID of the memblock to read
POSITION = The position to read in the memblock, in the range : 0 <= POSITION < Get Memblock Size( MEMBLOCKID )-1.
WORD_VALUE = The word value (16 bits) to write in the memblock.

Additional informations :
 You cannot read nor write outside the memblock. These method are fully "memory safe" methods.

Command Name : Write Memblock Byte

Syntax :
  Write Memblock Byte MEMBLOCKID, POSITION, BYTE_VALUE

Details :
This method will write the byte value (8 bits) at POSITION inside the memblock MEMBLOCKID
MEMBLOCKID = The Number ID of the memblock to read
POSITION = The position to read in the memblock, in the range : 0 <= POSITION < Get Memblock Size( MEMBLOCKID ).
BYTE_VALUE = The byte value (8 bits) to write in the memblock.

Additional informations :
 You cannot read nor write outside the memblock. These method are fully "memory safe" methods.

Command Name : Memblock Long

Syntax :
  VALUE = Memblock Long( MEMBLOCKID, POSITION )

Details :
This method will return the long/int value (32 bits) at POSITION inside the memblock MEMBLOCKID
MEMBLOCKID = The Number ID of the memblock to read
POSITION = The position to read in the memblock, in the range : 0 <= POSITION < Get Memblock Size( MEMBLOCKID )-1. This value must be multiple of 2.

Additional informations :
 You cannot read nor write outside the memblock. These method are fully "memory safe" methods.

Command Name : Memblock Word

Syntax :
  VALUE = Memblock Word( MEMBLOCKID, POSITION )

Details :
This method will return the word value (16 bits) at POSITION inside the memblock MEMBLOCKID
MEMBLOCKID = The Number ID of the memblock to read
POSITION = The position to read in the memblock, in the range : 0 <= POSITION < Get Memblock Size( MEMBLOCKID )-1. This value must be multiple of 2.

Additional informations :
 You cannot read nor write outside the memblock. These method are fully "memory safe" methods.

Command Name : Memblock Byte

Syntax :
  VALUE = Memblock Byte( MEMBLOCKID, POSITION )

Details :
This method will return the byte value (8 bits) at POSITION inside the memblock MEMBLOCKID
MEMBLOCKID = The Number ID of the memblock to read
POSITION = The position to read in the memblock, in the range : 0 <= POSITION < Get Memblock Size( MEMBLOCKID )

Additional informations :
 You cannot read nor write outside the memblock. These method are fully "memory safe" methods.


___________________________________________________________________

Fast CPU Paste Icon commands set :
____________________________________________________________________

Command Name : Reserve F Icon

Syntax :
  Reserve F Icon ICON_BANK_ID, AMOUNT_OF_ICONS
  
Details :
This method will create a new Fast Icon banks in Fast Ram. You can have more than one Fast Icon bank at the same time. This is useful if you want to create specific icons sets each separated in one different Fast Icon Bank.
ICON_BANK_ID = The number ID of the AMOS bank that will contain the Fast Icons.
AMOUNT_OF_ICONS = The maximum amount of Fast Icon the bank can contains.

Additional informations :
Fast Icon banks use the Amos Professional banks system. This mean they can be loaded using the default Load FILE$,BANKID or Load FILE$ methods, and saved using the default SAVE FILE$, BANKID. These banks are also saved with .AMOS files if they exists in memory when you save/backup your Amos Professional source code. There is an easy way to know the amount of Fast Icon a screen contains. You simply have to use :
   AMOUNT_OF_ICONS = ( Screen Width( ScreenID ) / 16 ) * ( Screen Height( ScreenID ) / 16 )

Command Name : Set Current F Icon Bank

Syntax :
  Set Current F Icon Bank ICON_BANK_ID

Details :
This method will set the Current F Icon Bank to be ICON_BANK_ID

Additional informations :
This method is useful if you use multiple F Icon banks containing each, differents icons. 

Command Name : Get Current F Icon Bank

Syntax :
  ICON_BANK_ID = Get Current F Icon Bank

Details :
This method return the Amos Bank ID of the current F Icon bank used to "Get F Icon" and "Paste F Icon".

Additional informations :
-

Command Name : Get F Icon

Syntax :
  Get F Icon ICONID, XPOS, YPOS

Details :
This method will grab an fast icon from the current screen
ICONID = The ID number of the F Icon to paste into the current screen
XPos = The position on the X axis in the screen, where the F Icon will be pasted
YPos = The position on the Y axis in the screen, where the F Icon will be pasted

Additional informations :
This system is optimized for tile systems, due to this and to get CPU optimizations, the XPOS and YPOS coordinates are always put as multiple of 16 pixels. This mean that if you put XPOS=24 or XPOS=31, the F Icon will be grab from XPOS=16. Size of F Icons is always 16x16 pixels. Same principle is applied to YPOS.

Command Name : Paste F Icon

Syntax :
  Paste F Icon ICONID,XPOS,YPOS,(optional)MASK

Details :
This method will paste a fast icon on the current screen
ICONID = The ID number of the F Icon to paste into the current screen
XPos = The position on the X axis in the screen, where the F Icon will be pasted
YPos = The position on the Y axis in the screen, where the F Icon will be pasted
Mask = Optional parameter to define if mask will be enabled (=1) or disabled (=0)

Additional informations :
This system is optimized for tile systems, due to this and to get CPU optimizations, the XPOS and YPOS coordinates are always put as multiple of 16 pixels. This mean that if you put XPOS=24 or XPOS=31, the F Icon will be drawn at XPOS=16. Same principle is applied to YPOS.


___________________________________________________________________

Sprites FX Commands set :
____________________________________________________________________

Command Name : Create Playfield From Sprite

Syntax :
  Create Playfield From Sprite YSTART, HEIGHT

Details :
This method will use the Amos Professional Unity sprite 0 to create a playfield from it.
YSTART = The 1st hardware line where the effect will start. It cannot be smaller than the current screen YSTART +2 position
HEIGHT = The amount of lines on which the effect will be visible. It cannot be higher than the sprite image's height and the last hardware screen Y line.

Additional informations :
This method is sensitive to Amos Professional Unity, Unity Support library method "Set Sprite Width" and will use the current parameters to create a playfield from Sprite. The native Amos Professional sprite system is adaptative to the width and depth (2 or 4 bitplanes) of the image used to create sprite. It can create composition of sprite to display the maximum portion of the image using sprites. The "Set Sprite As Playfield" takes these parameters and expand the sprite combination to be repeated from the left position to the right of the screen. If the original images requires 4 hardware sprites to be displayed, this method will repeat the 4 hardware sprites to create the playfield.
The playfield will be attached to the current screen. This mean that if you want to have playfield inside 2 screens, you will have to call the method twice. One time for the 1st screen to apply, and a second time for the 2nd screen to apply.

The details concerning compatibles sprites combinations is available in a dedicaced article on this subject : 
Aga 64 pixels width sprites playfields completed & details

Command Name : Remove Sprite Playfield

Syntax :
  Remove Sprite Playfield

Details :
This method will remove from the copper list, a sprite playfield that was previously inserted using the command "Create Playfield From Sprite SPRITEID".

Additional informations :
This method takes effect on the current screen. This mean that if you have a Sprite Playfield attached to another screen, only the current one will see its Sprite Playfield removed. The other one will continue to have its sprite playfield active.

Command Name : Set Playfield Priorities

Syntax :
  Set Playfield Priorities PF2OverPF1, SpritesVsDPF1, SpritesVsDPF2

Details :
This method will allow developer to set display priorities between sprites and playfields (especially when using dual playfield).
PF2OverPF1 : If set to 1, then 2nd dual playfield screen will be in front, otherwiser 1st dual playfield will be
SpritesVsDPF1 (range 0-4) : Define Sprites to Playfield 1 priority according to internal registers.
SpritesVsDPF2 (range 0-1) : Define Sprites to Playfield 2 priority according to internal registers.

Additional informations :
To understand how sprites Vs Playfields priorities works, see : amigadev.elowar.com/ADCD_2.1/BplCon2

Last update on 2021.04.10 11:49

Go back to Amos Professional Unity - Personal extension page