AmigaOS Documentation Wiki - User contributions [en]

Amiga Hardware Manufacturer ID Registry

2026-03-06T07:29:18Z

Costel Mincea: /* How to Obtain a Manufacturer Number */

__TOC__

= How to Obtain a Manufacturer Number =

Manufacturer's numbers are assigned by the AmigaOS development team. To obtain your unique manufacturer number send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com].

Be sure and include your name and the type of expansion product you are developing.

= Your Manufacturer Number =

Attention hardware manufacturers. If you are developing a hardware expansion product for the Classic Amiga (e.g. 500, 2000, 3000) then you will need to obtain a special manufacturer ID number from the AmigaOS development team to identify your product. This manufacturer number is used by the Amiga to link your hardware with its driver software at boot time.

Your manufacturer number is part of the special protocol that the Amiga uses to automatically configure all expansion devices on the bus without the user having to cut jumpers or adjust dip switches. This is called auto-config.

At start-up time, the system first polls each board in the system and assigns the board its own address space. If it is a memory board, its RAM is linked into the memory free pool. Later in the boot sequence, after DOS is initialized, the binddrivers program is run. Binddrivers will search the directory SYS:Expansion for the drivers that go with the boards.

To do this binddrivers looks in the Tool Type field of all icon files in SYS:Expansion. If the first seven bytes of the Tool Type field are "PRODUCT", then this is an icon file for a driver.

Binddrivers will then attempt to match the drivers it has found with the boards that were found earlier. This is where your manufacturer number comes in.

Your manufacturer number goes in two places. First, it is burned in hex form into the PAL which is part of ALL auto-config expansion products. Second, it appears in ASCII in the Tool Type field of the icon file for your product's driver. By matching these two numbers, the Amiga can automatically configure your board and bind it's software driver into the system as well.

The manufacturer's number is a 16-bit ID which appears in PAL offsets $10-$17. There is also an 8-bit product number which you assign. The product number is for uniquely identifying different products from the same vendor. The product number will appear in PAL offsets $04-$07. This gives you a total of 24 bits to identify each of your products.

These 24 bits of information in the PAL which identify your product are matched against the information in the Tool Type field of all icon files in the SYS:Expansion drawer. For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:

; PRODUCT=1208/11
: is the Tool Type for a driver for product 11 from manufacturer number 1208.

; PRODUCT=1017
: is the Tool Type for a driver for any product from manufacturer number 1017.

For an informal explanation of the auto-configuration process, see the chapter on Software Expansion Architecture from the 2nd Annual Amiga Developer's Conference Notes (available on ADCD 2.1). For the details of timing, power, the PAL equations and PAL address specifications and the expansion library documentation, see sections 3.1 to 3.3 of the A500/A2000 Technical Reference Manual. The original auto-config spec appears in the A1000 Schematics and Expansion Specification.

The auto-config process makes the addition of expansion products to the system very easy. All the user has to do is put the board in any slot and copy the driver from the release disk to his own SYS:Expansion drawer. Everything else is automatic. There are no jumpers or dip switches to set. Best of all, you will get a lot less support calls asking how to make your product work with the XYZ-Corp-battery-backed-clock.

= Notes =

Some notes on hardware manufacturer ID assignment.

* Manufacturer ID numbers are assigned free of charge.
* Please provide the following information when requesting an ID:
*# Name of the company or person
*# Postal address/contact address
*# Name of the contact person, with a corresponding e-mail address
*# A brief description of the kind of products you want to produce
* All ID numbers smaller than 5000 must be considered unsafe because no information exists on which numbers exactly were taken during the time Commodore, Inc. disintegrated.
* ID numbers in the range 8192 to 18841 must be considered unsafe because some hardware developers mistook the numbers assigned to them to be given in hexadecimal format. Hence 0x2000 = 8192 and 0x4999 = 18841.

= Example code =

<syntaxhighlight lang="C" line>
/*-----------------------------------------------*/
/* Here is a short program which will tell you */
/* about the expansion boards configured in your */
/* system without you opening up the machine. */
/* Code by Bill Koester of CATS */
/*-----------------------------------------------*/
#include <libraries/configvars.h>
#include <libraries/expansion.h>

struct ExpansionBase *ExpansionBase;

void cleanup();
void printdev();

int main()
{
struct ConfigDev *MyConfigDev;

/*----------------------------------*/
/* Open the expansion library, */
/* if there is a problem then exit */
/*----------------------------------*/

ExpansionBase =(struct ExpansionBase *) OpenLibrary(EXPANSIONNAME,0);
if(ExpansionBase==NULL)
{
printf("Error opening expansion library!!\n");
cleanup();
exit(0);
}

/*--------------------------------------------*/
/* Use FindConfigDev to get info on the first */
/* expansion board on the list maintained by */
/* Exec. If there are no expansion boards in */
/* the system then exit. */
/*--------------------------------------------*/

MyConfigDev = NULL;

/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/

MyConfigDev = FindConfigDev(NULL,-1,-1);

if(MyConfigDev==NULL)
{
printf("No Configured Devices found!!\n");
cleanup();
exit(0);
}

printdev(MyConfigDev);

/*-----------------------------------*/
/* OK, there is at least one board, */
/* so loop and get the entire list */
/* printing as we go with printdev() */
/*-----------------------------------*/

while(MyConfigDev = FindConfigDev(MyConfigDev,-1,-1))
{
printdev(MyConfigDev);
}
cleanup();
return 0;
}

/*-------------------*/
/* Close up shop... */
/*-------------------*/
void cleanup()
{
if(ExpansionBase)
CloseLibrary(ExpansionBase);
}

/*----------------------------------*/
/* Print out the contents of the */
/* dev structure for this expansion */
/* product. */
/*----------------------------------*/

void printdev(dev)
struct ConfigDev *dev;
{
char buff[200];

printf("Flags = ");
if(dev->cd_Flags==NULL)
printf("NULL ");
if(dev->cd_Flags&CDF_SHUTUP)
printf("CDF_SHUTUP ");
if(dev->cd_Flags&CDF_CONFIGME)
printf("CDF_CONFIGME ");
printf("\n");
printf("Board Address = %x\n",dev->cd_BoardAddr);
printf("Board Size = %d bytes\n",dev->cd_BoardSize);
printf("Slot Address = %d\n",dev->cd_SlotAddr);
printf("Slot Size = %d\n",dev->cd_SlotSize);
printf("Driver code at %x\n",dev->cd_Driver);

printf("er_Type = %x\n",dev->cd_Rom.er_Type);
printf("er_Product = %x\n",dev->cd_Rom.er_Product);
printf("er_Flags = %x\n",dev->cd_Rom.er_Flags);
printf("er_Reserved03 = %x\n",dev->cd_Rom.er_Reserved03);
printf("er_Manufacturer = %x\n",dev->cd_Rom.er_Manufacturer);
printf("er_SerialNumber = %x\n",dev->cd_Rom.er_SerialNumber);
printf("er_InitDiagVec = %x\n",dev->cd_Rom.er_InitDiagVec);
printf("er_Reserved0c = %x\n",dev->cd_Rom.er_Reserved0c);
printf("er_Reserved0d = %x\n",dev->cd_Rom.er_Reserved0d);
printf("er_Reserved0e = %x\n",dev->cd_Rom.er_Reserved0e);
printf("er_Reserved0f = %x\n",dev->cd_Rom.er_Reserved0f);

printf("Hit Return to continue:\n");
gets(buff);
}
</syntaxhighlight>

= Registry =

{| class="wikitable"
! ID (decimal)
! ID (hexadecimal)
! Manufacturer
! Notes
|-
| 1
| 0001
| Micronik
|-
| 211
| 00D3
| Pacific Peripherals/Profex
|-
| 221
| 00DD
| Kupke Computertechnik GmbH
|-
| 256
| 0100
| Memphis
| Originally registered to MacroSystems US
|-
| 512
| 0200
| 3-State Computertechnik
|-
| 513
| 0201
| Commodore (Braunschweig)
|-
| 514
| 0202
| Commodore (West Chester)
|-
| 515
| 0203
| Commodore (West Chester)
| Originally registered to Combitech/Macrosystem
|-
| 756
| 02F4
| Progressive Peripherals & Software
|-
| 767
| 02FF
| Kolff Computer Supplies
|-
| 1001
| 03E9
| Tecmar
|-
| 1002
| 03EA
| Telesys
|-
| 1003
| 03EB
| The Micro-Forge
|-
| 1004
| 03EC
| Kronos/C Ltd.
| Originally registered to Card Co. (Supra)
|-
| 1005
| 03ED
| A-Squared
|-
| 1006
| 03EE
| Comspec Communications
|-
| 1007
| 03EF
| HT Electronics
|-
| 1008
| 03F0
| RDS Software
|-
| 1009
| 03F1
| Anakin Research
|-
| 1010
| 03F2
| MicroBotics
|-
| 1011
| 03F3
| Bob Krauth
|-
| 1012
| 03F4
| Access Associates (Alegra)
|-
| 1013
| 03F5
| Mini Comp Systems Ltd.
|-
| 1014
| 03F6
| Cypress Technology
|-
| 1015
| 03F7
| Fuller Computers
|-
| 1016
| 03F8
| Galaxy Computers
|-
| 1017
| 03F9
| ADA Research
|-
| 1018
| 03FA
| Computer Service Italia
|-
| 1019
| 03FB
| Amigo
|-
| 1020
| 03FC
| Micro-Solutions Inc.
|-
| 1021
| 03FD
| Stacar International
|-
| 1022
| 03FE
| Video Precisions
|-
| 1023
| 03FF
| ASDG, Inc.
|-
| 1025
| 0401
| Ing. Buero Kalawsky
|-
| 1026
| 0402
| Computer Tuning
|-
| 1027
| 0403
| Interplan Unternehmensberatung
|-
| 1028
| 0404
| Imtronics/Memphis
| Originally registered to Peter Ohlich
|-
| 1030
| 0406
| Commodore (Lowell University)
| Originally registered to Productivity Center
|-
| 1041
| 0411
| Design Labs
|-
| 1042
| 0412
| MCS
|-
| 1043
| 0413
| B. J. Freeman
|-
| 1044
| 0414
| Side Effects Inc.
|-
| 1045
| 0415
| Oklahoma Personal Comp.
|-
| 1046
| 0416
| Advanced Micro Innovations
|-
| 1047
| 0417
| Industrial Support Services
|-
| 1048
| 0418
| Technisoft
|-
| 1049
| 0419
| Prolific, Inc.
|-
| 1050
| 041A
| Softeam, Inc.
|-
| 1051
| 041B
| GRC Electronics
|-
| 1052
| 041C
| David Lai
|-
| 1053
| 041D
| Ameristar Technologies
|-
| 1054
| 041E
| Cline Refrigeration
|-
| 1055
| 041F
| Cardiac Pacemakers, Inc.
|-
| 1056
| 0420
| Supra Corp. (Creative Microsystems)
|-
| 1057
| 0421
| Wayne Diener
|-
| 1058
| 0422
| Computer Systems Associates (CSA)
|-
| 1059
| 0423
| Trionix, Inc.
|-
| 1060
| 0424
| David Lucas
|-
| 1061
| 0425
| Analog Precision
| Also assigned to D & L Distributing
|-
| 1267
| 04F3
| RBM Digitaltechnik
|-
| 1282
| 0502
| M-TEC Hardware Design
|-
| 1337
| 0539
| Thomas Stenzel (DaFR34K)
|-
| 1576
| 0628
| Boris Križma
|-
| 1761
| 06E1
| Great Valley Products
|-
| 1803
| 070B
| UAE Amiga Emulator
|-
| 2002
| 07D2
| Mimetics Corp.
|-
| 2003
| 07D3
| ACDA
|-
| 2004
| 07D4
| Finn R. Jacobsen
|-
| 2005
| 07D5
| Elthen Electronics
|-
| 2006
| 07D6
| Nine Tiles Computer Systems Ltd.
|-
| 2007
| 07D7
| Analog Electronics
|-
| 2008
| 07D8
| Bell & Howell
|-
| 2009
| 07D9
| Roland Kochler
|-
| 2010
| 07DA
| Byte Corp.
|-
| 2011
| 07DB
| Reserved
|-
| 2012
| 07DC
| DKB, Inc.
| Previously named Michigan Software
|-
| 2013
| 07DD
| Pacific Peripherals
|-
| 2014
| 07DE
| Sysaphus Software
|-
| 2015
| 07DF
| Digitronics
|-
| 2016
| 07E0
| Akron Systems
|-
| 2017
| 07E1
| Great Valley Products
|-
| 2018
| 07E2
| Calmos
|-
| 2019
| 07E3
| Dover Research
|-
| 2020
| 07E4
| David Krehbiel
|-
| 2021
| 07E5
| Synergy Peripheral Systems
| Also known as California Access
|-
| 2022
| 07E6
| Xetec
|-
| 2023
| 07E7
| Micron Technology
|-
| 2024
| 07E8
| CH Electronics
|-
| 2025
| 07E9
| American Liquid Light
|-
| 2026
| 07EA
| Progressive Peripherals & Software
| Also used by Ateo
|-
| 2027
| 07EB
| Wicat Systems
|-
| 2028
| 07EC
| Applied Systems & Peripherals
|-
| 2029
| 07ED
| Delaware Valley Software
|-
| 2030
| 07EE
| Palomax
|-
| 2031
| 07EF
| Incognito Software
|-
| 2032
| 07F0
| Jadesign
|-
| 2033
| 07F1
| BVR
|-
| 2034
| 07F2
| Spirit Technology
|-
| 2035
| 07F3
| Spirit Technology
|-
| 2036
| 07F4
| Atronic
|-
| 2037
| 07F5
| Scott Karlin
|-
| 2038
| 07F6
| Howitch
|-
| 2039
| 07F7
| Sullivan Brothers Visual Engineers
|-
| 2040
| 07F8
| G I T
|-
| 2041
| 07F9
| Amigo Business Computers
|-
| 2042
| 07FA
| Micro E Ab
|-
| 2043
| 07FB
| Ralph Kruse
|-
| 2044
| 07FC
| Clearpoint Research
|-
| 2045
| 07FD
| Kodiak
|-
| 2046
| 07FE
| BSC
| Originally registered to Phoenix Electronics
|-
| 2047
| 07FF
| No Name Shown
|-
| 2048
| 0800
| Commodore Braunschweig
|-
| 2049
| 0801
| BSC
| Originally registered to Elaborate Bytes
|-
| 2050
| 0802
| Kronos/C Ltd.
|-
| 2051
| 0803
| Spartanics
|-
| 2052
| 0804
| Jochheim Computer Tuning
|-
| 2053
| 0805
| Trans Data Systems
|-
| 2054
| 0806
| Applied Systems & Peripherals Ltd.
|-
| 2055
| 0807
| Checkpoint Technologies
| Originally registered to Amiga Solutions
|-
| 2056
| 0808
| Adept Development
|-
| 2057
| 0809
| Advanced Computer Design
|-
| 2058
| 080A
| Sir Netics
|-
| 2059
| 080B
| Expert Services
|-
| 2060
| 080C
| Digital Art Systems
|-
| 2061
| 080D
| Adept Development
|-
| 2062
| 080E
| Expansion Technologies (Expansion Systems)
|-
| 2063
| 080F
| Alphatech
|-
| 2064
| 0810
| Edotronik GmbH
|-
| 2065
| 0811
| California Access/Synergy
| Originally registered to Logical Design Works
|-
| 2066
| 0812
| Bowden, Williams, Full & Assoc.
|-
| 2067
| 0813
| NES, Inc.
|-
| 2068
| 0814
| Amdev
|-
| 2069
| 0815
| Big Brother Security Systems
|-
| 2070
| 0816
| Active Circuits Inc.
|-
| 2071
| 0817
| ICD, Inc.
|-
| 2072
| 0818
| Multi-Meg Electronique
|-
| 2073
| 0819
| Kupke Computertechnik GmbH
|-
| 2074
| 081A
| The Checkered Ball
|-
| 2075
| 081B
| Hi Tension Computer Services Ltd. (UK)
|-
| 2076
| 081C
| Alfa Data
| Originally assigned to Elmtech Research, Ltd. (UK)
|-
| 2077
| 081D
| Great Valley Products
| Originally registered to Clartscreen, Ltd. (UK)
|-
| 2078
| 081E
| Interworks
|-
| 2079
| 081F
| Galysh Enterprises
|-
| 2080
| 0820
| Hardital Synthesis
| Originally registered to Realtime Games Software Ltd.
|-
| 2081
| 0821
| GBS
|-
| 2082
| 0822
| Circum Design Inc.
|-
| 2083
| 0823
| Alberta Micro Electronic Center
|-
| 2084
| 0824
| Bestech
|-
| 2085
| 0825
| Lasar Fantasy
|-
| 2086
| 0826
| Pulsar
|-
| 2087
| 0827
| Ivis
|-
| 2088
| 0828
| Applied Engineering
|-
| 2089
| 0829
| Solid-State Design & Development
|-
| 2090
| 082A
| Vison Quest
|-
| 2091
| 082B
| Seaview Software
|-
| 2092
| 082C
| BSC
| Mistakenly used by ADS (Advanced Development Software)
|-
| 2093
| 082D
| Bernd Culenfeld
|-
| 2094
| 082E
| American Liquid Light
|-
| 2095
| 082F
| CEGITES
|-
| 2096
| 0830
| Quadlite Computers Ltd.
| Originally registered to EV Industries
|-
| 2097
| 0831
| Silicon Peace
|-
| 2098
| 0832
| Black Belt Systems
|-
| 2099
| 0833
| Village Tronic
| Originally registerd to Steve Yaeger
|-
| 2100
| 0834
| ReadySoft
|-
| 2101
| 0835
| Phoenix Micro Technologies
|-
| 2102
| 0836
| Advanced Systems & Software
| Orignally assigned to Preferred Technology
|-
| 2103
| 0837
| Rombo Productions
|-
| 2104
| 0838
| Impulse Inc.
|-
| 2105
| 0839
| Beta Unlimited
|-
| 2106
| 083A
| Memory Expansion System, Ltd.
|-
| 2107
| 083B
| Vortex Computer Systems GmbH
|-
| 2108
| 083C
| Platypus Systems
|-
| 2109
| 083D
| Gigatron OHG
|-
| 2110
| 083E
| PG Electronics
|-
| 2111
| 083F
| New Technologies Group
|-
| 2112
| 0840
| Interactive Video Systems (IVS)
| Pacific Peripherals
|-
| 2113
| 0841
| Vector
| Originally registered to H. K. Computer
|-
| 2114
| 0842
| Pacific Digital
| Originally registered to C. H. Helfrich Elektronik
|-
| 2115
| 0843
| Xanadu
|-
| 2116
| 0844
| Pacific Digital
| Originally registered to AMS
|-
| 2117
| 0845
| X-Pert
|-
| 2118
| 0846
| The Amiga Centre
|-
| 2119
| 0847
| Digital Pacific
|-
| 2120
| 0848
| Solid State Leisure
|-
| 2121
| 0849
| Hydra Systems
| Originally registered to Analog Electronics
|-
| 2122
| 084A
| Cumana
|-
| 2123
| 084B
| KAPS 2C Conception
|-
| 2124
| 084C
| Mike Mason
|-
| 2125
| 084D
| For Your Eyes
|-
| 2126
| 084E
| Volkmar Breitfeld Computersysteme
|-
| 2127
| 084F
| Sunrize Industries
|-
| 2128
| 0850
| Scott Advanced Micro Designs
|-
| 2129
| 0851
| Digital Micronics
|-
| 2130
| 0852
| Alfa-Laval
|-
| 2131
| 0853
| Multigros A/S
|-
| 2132
| 0854
| Archos
|-
| 2133
| 0855
| Icom Simulations
|-
| 2134
| 0856
| Commodore Test Engineering Group
|-
| 2135
| 0857
| Microcreations
|-
| 2136
| 0858
| Shoestring Productions
|-
| 2137
| 0859
| Faberushi
|-
| 2138
| 085A
| Evesham Micro Ltd.
|-
| 2139
| 085B
| Panagolin Laser Software
|-
| 2140
| 085C
| Thomas Rudloff
|-
| 2141
| 085D
| Daniel Hohabir
|-
| 2142
| 085E
| GfxBase, Inc.
|-
| 2143
| 085F
| Axellabs
|-
| 2144
| 0860
| Roctec Electronics Inc.
|-
| 2145
| 0861
| Omega Datentechnik
|-
| 2146
| 0862
| Atlantis
|-
| 2147
| 0863
| Skytec Computers
|-
| 2148
| 0864
| Protar Electronics
|-
| 2149
| 0865
| ACS
|-
| 2150
| 0866
| Software Results Enterprises
| Originally registered to University of Illinois
|-
| 2151
| 0867
| Infinity Systems Design Group
|-
| 2152
| 0868
| Trade It
|-
| 2153
| 0869
| Suntec, Inc.
|-
| 2154
| 086A
| DJW Micro Systems
| Originally registered to Tritec Marketing
|-
| 2155
| 086B
| Power Computing Ltd.
|-
| 2156
| 086C
| MacroSystems
|-
| 2157
| 086D
| Masoboshi GmbH (DCE)
|-
| 2158
| 086E
| HAL Software Hardware Handel
|-
| 2159
| 086F
| Mainhattan Data
| Originally registered to Michael Lamm Computersysteme
|-
| 2160
| 0870
| Digital Processing System
| Originally registered to bbdp Electronics
|-
| 2161
| 0871
| Blue Ribbon Soundworks
| Originally registered to Design Computer Systems
|-
| 2162
| 0872
| XPert
| Originally registered to The Station
|-
| 2163
| 0873
| DelaComp
| Originally registered to Bryan Williams
|-
| 2164
| 0874
| Superformance Computer Engineering GmbH
|-
| 2165
| 0875
| Overland Engineering
|-
| 2166
| 0876
| Thomas Hamren
|-
| 2167
| 0877
| Village Tronic
|-
| 2168
| 0878
| Toolbox Design
|-
| 2169
| 0879
| Digital Processing System
|-
| 2170
| 087A
| Superformance
|-
| 2171
| 087B
| Utilities Unlimited
|-
| 2172
| 087C
| phase 5
|-
| 2173
| 087D
| Juergen Kommos
|-
| 2174
| 087E
| Electronic Design
|-
| 2175
| 087F
| James Cook University of North Queensland
|-
| 2176
| 0880
| AmiTrix Development
|-
| 2177
| 0881
| Ferranti
|-
| 2178
| 0882
| Leviathan Development
|-
| 2179
| 0883
| United Video Inc.
|-
| 2180
| 0884
| GPSoft Pty. Ltd.
| Originally registered to Juergen Kommos
|-
| 2181
| 0885
| ArMAX
| Oliver Bausch
|-
| 2182
| 0886
| CP Computer
|-
| 2183
| 0887
| AMOK - Amiga Module & Oberon Klub
|-
| 2184
| 0888
| ITEK Neser & Sieber GbR
|-
| 2185
| 0889
| Phillip C. Lello
|-
| 2186
| 088A
| Cyborg Design Services
|-
| 2187
| 088B
| G2 Systems
|-
| 2188
| 088C
| Pro System Computersysteme
|-
| 2189
| 088D
| ZEUS Electronic
| Originally registered to MSPI (Markt & Technik)
|-
| 2190
| 088E
| Altatech
|-
| 2191
| 088F
| NewTek
|-
| 2192
| 0890
| M-TEC Hardware Design
| Originally registered to Hardware Design Udo Neuroth
|-
| 2193
| 0891
| Great Valley Products
| Originally registered to Viona Development
|-
| 2194
| 0892
| Amitek
| Originally assigned to Marpet Developments
|-
| 2195
| 0893
| Ingenieurbuero Helfrich
|-
| 2196
| 0894
| The Neo Group
|-
| 2197
| 0895
| Cyon
|-
| 2198
| 0896
| Bob Research Group
|-
| 2199
| 0897
| Richmond Sound Design Ltd.
|-
| 2200
| 0898
| US Cybernetics
|-
| 2201
| 0899
| Fulvio Ieva
|-
| 2202
| 089A
| Silicon Studio
|-
| 2203
| 089B
| MacroSystems (USA)
| Was named Micro System Devices
|-
| 2204
| 089C
| Conspector Entertainment
|-
| 2205
| 089D
| Laserforum
|-
| 2206
| 089E
| Elbox Computer
| Mistakenly used by Index Information Ltd.
|-
| 2207
| 089F
| Applied Magic Inc.
|-
| 2208
| 08A0
| SDL Ltd.
|-
| 2560
| 0A00
| Harms
|-
| 2588
| 0A1C
| A1K.org Community
|-
| 2640
| 0A50
| Micronik
|-
| 3084
| 0C0C
| Team 4
|-
| 3643
| 0E3B
| E3B
| Michael Boehmer
|-
| 3855
| 0F0F
| Micronik
|-
| 4096
| 1000
| MegaMicro
|-
| 4110
| 100E
| DigiFeX
|-
| 4136
| 1028
| Imtronics/Memphis
|-
| 4149
| 1035
| PROTAR
|-
| 4369
| 1111
| Frank Strauß Elektronik
| Also used by Kupke
|-
| 4626
| 1212
| Individual Computers
|-
| 4648
| 1228
| Flesch Hornemann Computer Elec.
|-
| 4680
| 1248
| Kupke Computertechnik GmbH
|-
| 4711
| 1267
| RBM digitaltechnik
|-
| 4754
| 1292
| MacroSystems
|-
| 5000
| 1388
| ITH
|-
| 5001
| 1389
| VMC
|-
| 5010
| 1392
| Ambience Creation Technology
|-
| 5011
| 1393
| Creative Development
|-
| 5012
| 1394
| Georg Braun
|-
| 5013
| 1395
| Swedish User Group of Amiga
|-
| 5014
| 1396
| Jakub Bednarski
|-
| 5015
| 1397
| KryoFlux, Ltd.
|-
| 5016
| 1398
| Igor Majstorovic
|-
| 5017
| 1399
| Alastair M. Robinson
|-
| 5018
| 139A
| Austex Software
|-
| 5019
| 139B
| Sören Gust
|-
| 5020
| 139C
| Rok Krajnc
|-
| 5030
| 13A6
| Tim Tashpulatov
|-
| 5040
| 13B0
| 7-bit
|-
| 5050
| 13BA
| Sakura IT
|-
| 5060
| 13C4
| FPGAArcade
|-
| 5070
| 13CE
| CancerSoft Inc.
|-
| 5080
| 13D8
| Stephen Leary
|-
| 5090
| 13E2
| DMA Softlab LLC
|-
| 5100
| 13EC
| Brookhouse Engineering
|-
| 5110
| 13F6
| Eduardo Arana
|-
| 5120
| 1400
| CS-LAB
|-
| 5130
| 140A
| Robert Miranda
|-
| 5140
| 1414
| RastPort
|-
| 5132
| 140C
| UAS Interface Ltd6
|-
| 5150
| 141E
| Amiga Kit
|-
| 5160
| 1428
| Central Texas Commodore User Group
|-
| 5170
| 1432
| Confusion Research Center
|-
| 5180
| 143C
| Solar Soyuz Zaibatsu
|-
| 5500
| 157C
| Inhouse Information
|-
| 5768
| 1688
| Bio Con
|-
| 6148
| 1804
| HK-Computer
|-
| 6502
| 1966
| Cloanto
|-
| 6520
| 1978
| Oliver Gantert
|-
| 7777
| 1E61
| Rafal Gabriel Chyla
|-
| 8215
| 2017
| Vortex
|-
| 8244
| 2034
| Spirit Technology
|-
| 8290
| 2062
| Expansion Systems
|-
| 8448
| 2100
| ReadySoft
|-
| 8512
| 2140
| Phase 5 Digital Products
|-
| 8553
| 2169
| Digital Processing Systems Inc.
|-
| 8704
| 2200
| ACT Elektronik
|-
| 8738
| 2222
| ACT Elektronik
|-
| 9512
| 2528
| Tower Technologies
|-
| 10676
| 29B4
| Electronic Design
|-
| 14195
| 3773
| Media-net-Point
|-
| 14501
| 38A5
| Petsoff, Finland
|-
| 16375
| 3FF7
| Uwe Gerlach
|-
| 16707
| 4143
| Ateo Concepts
|-
| 16708
| 4144
| ALiENDESiGN
|-
| 16945
| 4231
| A.C.T.
|-
| 17740
| 454C
| HK-Computer (ELSAT)
|-
| 18260
| 4754
| MacroSystems (Germany)
|-
| 19796
| 4D54
| Markt & Technik
|-
| 22359
| 5757
| Markt & Technik
|-
| 26464
| 6760
| Combitec
|-
| 26470
| 6766
| Combitec
|-
| 28014
| 6D6E
| MNT Media and Technology UG
|-
| 32768
| 8000
| M.A.S.T.
|-
| 42240
| A500
| Aethreum Digital
|-
| 43437
| A9AD
| Reis-Ware
|-
| 43521
| AA01
| Cameron
|-
| 43537
| AA11
| Reis-Ware
|-
| 44359
| AD47
| Matay
|-
| 46504
| B5A8
| Phoenix
|-
| 49160
| C008
| Combitec
|-
| 61453
| F00D
| Forefront Technologies Inc.
|}

For any changes/additions to this registry please use the [http://www.amigaos.net/contact AmigaOS web site contact form].

AmigaOS Manual: AmigaDOS Using the Editors

2026-02-12T07:21:56Z

Costel Mincea: /* EDIT */ Set the defaults of PREVIOUS and WIDTH to new 4.1 Final Edition Update 3 values

A text editor or word processing program is necessary for creating or editing text files and script files. Amiga Workbench software comes with three text editors. This chapter describes them in the following order:

* ED
* MEmacs
* EDIT

Each of the Amiga editors can be used separately for editing AmigaDOS scripts and programs; ED and MEmacs can be used for creating these files. If you are comfortable with the UNIX Emacs editor, you may prefer using the MEmacs editor. If you need to edit files containing binary code or you need to edit files too large to fit into memory, use EDIT. If you are not familiar with any of the editors, we recommend that you use the ED editor.

Each editor has the basic functionality of a word processor, however, none of these editors support style formatting options, such as italics, page numbering, or different fonts. If you need these features, you can purchase third party word processing software containing such features for your Amiga.

= ED =

ED is a full screen ASCII text editor that uses menus and function keys to access its features. It is easy to use and is suitable for editing scripts, startup files, MountLists, and other simple files. Use either a mouse or the keyboard to perform operations with ED. Although ED's menus are preprogrammed, when you are familiar with the program, you can reconfigure them as needed.

{{Note|ED does not accept files containing binary code. To edit this type of file, use EDIT or MEmacs.}}

The bottom line of the ED window is the status line used for displaying messages, prompts, and commands. Error messages displayed on the status line remain until you enter another ED command. Figure 4-1 illustrates the ED window showing the status line.

[[File:DosFig4-1.png|none|frame|ED Window with Status Line]]

== Starting ED ==

Start ED from a Shell or with the Workbench Execute Command menu item. Open ED at the prompt by entering ED and a new or existing file name, as follows:

1> ED <filename>

where <filename> is the name of an existing file or a new file to be used for saving your work. If the file name specified cannot be found in the current directory, ED opens a blank window and displays the message Creating new file.

The format for ED is the following:

<nowiki>ED [FROM] <filename> [SIZE <n>] [WITH <filename>]
[WINDOW <window specification>] [TABS <n>] [WIDTH | COLS <n>]
[HEIGHT | ROWS <n>]</nowiki>

The FROM argument specifies the source file to be edited. This argument is required, but the FROM keyword is optional.

The SIZE argument changes the ED buffer size. ED has a default text buffer size of 40,000 bytes. For example:

1> ED Script SIZE 55000

increase the size of the buffer to 55,000 bytes.

The WITH argument specifies an ED command file that can contain any sequence of ED extended mode commands. When WITH is specified, ED executes the commands contained in the command file. The WITH argument's keywords is required if you use WITH.

The WINDOW argument specifies the console type, such as RAX:0/0/640/256/EdWindow or CONSOLE:. The WINDOW argument's keyword is required if you use WINDOW.

TABS sets the tab stop interval, which is the number of spaces to the right that the cursor moves when you press the Tab key. The default value for TABS is 3.

The WIDTH and HEIGHT arguments adjust the size of the ED window by specifying the number of characters to display horizontally and vertically. By default the ED window is 640 x 200 picels or approximately 88 characters wide by 21 lines high.

== Using ED ==

All ED commands have key sequences and many are available through menus. You can enter ED commands in either of the following ways:

* By choosing the command's menu item.
* By typing in the command's key sequence and pressing Return.

In addition, you can use the mouse to perform some commands, such as those that control cursor movement.

You can work on files in ED with the following two command modes:

; Immediate
: Commands are executed as soon as typed. EP opens in immediate mode.

; Extended
: Commands are not executed until you press Return or Esc.

=== Immediate Commands ===

In immediate mode, ED executes commands right away. Specify an immediate command by pressing a single key or Ctrl+key combination or by using the mouse. All immediate commands have corresponding extended versions.

Immediate commands control the following:

* Cursor movement
* Text scrolling
* Text insertion
* Text deletion
* Repetition of commands

=== Moving the Cursor in Immediate Mode ===

The cursor can be positioned anywhere in text by moving the pointer to the desired spot and clicking the selection button. To move the cursor with the keyboard, use the arrow keys, Tab, and Ctrl+key combinations.

{{Note|In ED, the Tab key only moves the cursor. It does not insert Tab characters or spaces in a line.}}

Move the cursor one position in any direction by pressing the appropriate arrow key. If the cursor is on the right edge of the screen, ED scrolls the text to the left do display the rest of the line. ED scrolls the text vertically one line at a time and horizontally ten characters at a time. You cannot move the cursor beyond the left edge of the line. If you try to move the cursor beyond the top or bottom of the file, ED displays a Top of File or Bottom of File message.

Additional key combinations that control cursor movement are:

{| class="wikitable"
| Shift+up arrow || Top of the file.
|-
| Shift+down arrow || Bottom of the file.
|-
| Shift+left arrow || Left edge of the ED window (regardless of the margin setting).
|-
| Sift+right arrow || End of the current line.
|-
| Ctrl+] || Right edge of current line (if cursor is already there, it is moved to the left edge).
|-
| Ctrl+E || Start of the first line on the screen (if cursor is already there, it is moved to the end of the last line on the screen).
|-
| Ctrl+T || Start of the next word.
|-
| Ctrl+R || Space following the previous word.
|-
| Tab || The next tab position (multiple of the TABS value; 3 by default).
|}

If your file has more lines than can fit in the ED window, you can scroll through the file vertically. Scroll one line at a time by pressing the up or down cursor key to move in the corresponding direction. Move the text in jumps by pressing:

{| class="wikitable"
| Ctrl+D || Moves 12 lines down through the file.
|-
| Ctrl+U || Moves 12 lines up through the file.
|}

These commands do not move the cursor position in the window; they redraw the text in the window with the new line at the cursor position.

If something disturbs your screen, such as an alert from another program appearing in the ED window or message remarks in the status line, press:

{| class="wikitable"
| Ctrl+V || Refreshes the window display.
|}

=== Inserting Text in Immediate Mode ===

Any characters typed in immediate mode are inserted at the current cursor position and the cursor is shifted to the right. Any characters to the right of the cursor are shifted to make room for new text. If the line is wider than the width of the window, the window scrolls to the right to show what you are typing. If you move the cursor beyond the end of the line, ED inserts spaces between the end of the line and any new characters inserted.

There is maximum limit of 255 characters in a line. If you add more characters, ED displays a Line Too Long message.

To split the current line at the cursor, press Return. Any text to the left of the cursor remains on the original line. All text under and to the right of the cursor moves down onto a new line. Pressing Return at the end of the line creates a new blank line.

=== Deleting Text in Immediate Mode ===

ED has no type over mode. To replace a word or line, you must delete the existing words and insert new information with the following keys and key combinations:

{| class="wikitable"
| Backspace || Deletes the character to the left of the cursor.
|-
| Del || Deletes the character highlighted by the cursor.
|-
| Ctrl+O || If the cursor is over a space, all spaces up to the next character are deleted. If the cursor is over a character, all characters up to the next space are deleted.
|-
| Ctrl+Y || Deletes all characters from the cursor to the end of the line.
|}

When text is deleted, any characters remaining on the line shift to the left and any text beyond the right edge of the screen becomes visible.

=== Changing Case in Immediate Mode ===

You can change the case of text by positioning the cursor and pressing Ctrl+F. If the letter is lower case, it becomes upper case and vice versa. Ctrl+F does not change non-alphabetic characters or symbols.

After you press Ctrl+F, the cursor moves to the right. You can hold down Ctrl+F to repeat the command until you change all the letters on the line.

=== Extended Commands ===

In extended mode, commands are displayed on the command line - or status line - at the bottom of the window. ED does not execute these commands until you press Return or Esc. If you use Esc to execute extended commands, ED remains in extended mode. If you use Return to execute extended commands, ED returns to immediate mode.

Extended commands manage the following:

* Program control
* Cursor movement
* Text modification
* Block control
* Searching and exchanging text

To enter extended mode, press Esc. An asterisk appears as a prompt in the status line. Extended commands consist of one or two characters. Multiple extended commands can be typed on a single command line by separating them with a semicolon. Commands can be grouped together for ED to repeat automatically. Use Backspace to correct mistakes.

You can also execute commands through the programmable menu and function keys. Reconfigure the menus and functions keys by assigning a command to the key or menu item of your choice as described on page 4-21.

=== Using String Delimiters ===

In some cases, commands require arguments, such as a number or a text strig. A string argument for an ED command must be enclosed in a pair of identical delimiter characters. In unambiguous situations you may omit the trailing delimiter. Valid delimiters include ", /, \, !, :, +, -, and %. You cannot use the same delimiter character inside your string. Invalid delimiter characters include letters, numbers, spaces, semicolons, question marks, brackets, and control characters.

=== Using a File Requester ===

You can also ask ED to use a file requester, allowing you to view the contents of the drives and directories in your system.

To invoke a file requester for a load or save command, you must place a question mark (?) before the required string argument. Be sure to include a space before the question mark (for example, sa ?/Text/). Normally, when a command is followed by a string. ED treats the string as the file to be loaded or saved and attempts the operation immediately. However, the question mark indicates that you want to specify the file through a file requester. You must still specify a string after the question mark, but the string becomes the text that appears in the file requester title bar.

== ED Menus ==

ED has two sets of command menu assignments: default and expanded. The default menu assignments, as illustrated in Figure 4-2, are set up by the S:Ed-startup file, which is automatically executed each time you run ED. The S:Ed-startup file is a command file of ED extended mode commands, without the Escape characters. You can edit this file to set up custom menus, as described on page 4-21, or define preprogrammed function key assignments with the Set FN Key menu item.

[[File:DosFig4-2.png|none|frame|Default Menu Assignments]]

=== Enabling Expanded Menus ===

The expanded command menu assignments, as illustrated in Figure 4-3, can be enabled by renaming or deleting the default S:Ed-startup file. If ED cannot find a file named S:Ed-startup, it opens with the expanded set of menus, providing more options.

[[File:DosFig4-3.png|none|frame|Expanded Menu Assignments]]

Rather then deleting your S-Ed-startup file, we recommend that you rename it as follows:

# In the Workbench window, go to the Window menu and select Show All Files.
# Double-click on the S drawer icon.
# Click on the Ed-startup icon.
# Go to the Icons menu and choose Rename.
# Delete the name in the Rename requester's New Name text gadget and enter a new name for Ed-startup.
# Select OK.

You can also create your own customized file of startup options. Avoid including Quit commands in the S:Ed-startup file since they can cause ED to quit immediately after opening.

The menu items in both the default and expanded menus have the same function regardless of which set you use. All of the ED commands are available through the keyboard using extended mode commands even if they do not appear in any menu.

The following sections describe the menu items found in the expanded menus and their corresponding extended and immediate mode commands. An ellipsis (...) indicates that an argument is required or that a menu item opens a requester or prompt.

=== Project Menu ===

The following are the expanded Project menu items:

{| class="wikitable"
| New || Esc,N,W || Creates a new file, replacing the existing file. The message Edits will be lost-type Y to confirm: is displayed. Press any key (except Y) to abort the command.
|-
| Open... || Esc,O,P... || Opens a file. Specify the file by entering the path to the file as a properly delimited string. (If slashes appear in the path to a file, do not use the slash as a delimiter.) The message Edits will be lost-type Y to confirm: reminds you that you are replacing the current file.
|-
| Insert File... || Esc,I,F... || Inserts a file into the current file. ED reads into memory the specified file at the point immediately following the current line.
|-
| Write Block... || Esc,W,B... || Writes the currently marked block to a specified file. ED overwrites any other files with that name and copies the block to the file.
|-
| Save || Esc,S,A || Saves the text to the current file, overwriting the existing text in the file. Use Save As to save to different file. SA followed by Q is equivalent to the X command.
|-
| Save As... || Esc,S,A... || Saves the text to the specified file name.
|-
| Save & Exit || Esc,X || Exits ED, saving the current file to the designated file name. ED writes the text it is holding in memory to the file that was specified when ED was opened and then terminates.
|-
| About || Esc,S,H || Shows the current state of the editor. The screen display information, such as the value of tab stops, current margins, block marks, and the name of the file being edited.
|-
| Quit || Esc,Q || Exits ED without saving changes. If you made any changes to the file, ED asks if you want to quit. If you press Y, ED terminates immediately without saving the changes to the file.
|}

=== Edit Menu ===

The following are commands used for editing:

{| class="wikitable"
| Undo Line || Esc,U || Reverses changes made to the current line. However, ED cannot undo a line deletion. Once you have moved from the current line, the U command cannot undo a change.
|-
| Star Block || Esc,B,S || Identify the beginning and end of a block of text. To specify a block of text to be moved, inserted, or deleted, place the cursor on the first line that you want in the block and enter the BS command. Move the cursor to the last line that you want in the block and enter the BE command. You cannot start or finish a block in the middle of a line.
|-
| Show Block || Esc,S,B || Redraws the display so the block is at the top of the screen.
|-
| Insert Block || Esc,I,B || Inserts a copy of the block after the current line. The block remains defined until you change the text. Use IB to insert copies of the block throughout the document.
|-
| Delete Block || Esc,D,B || Deletes a block.
|-
| Delete Line || Esc,D Ctrl+B || Deletes the entire line.
|}

=== Movement Menu ===

The following commands move the cursor around the screen:

{| class="wikitable"
| Top || Esc,T || Top of the file; first line of the file is brought to the top of the window.
|-
| Bottom || Esc,B || Bottom of the file; last line of the file is brought to the bottom of the window.
|-
| Go To Line... || Esc,M... || Move the cursor to the specified line. Enter the line number on the status line and press Return. The line specified is brought to the top of the window. If no number is given, the cursor goes to the top of the window.
|-
| Next Page || Esc,P,D Ctrl+D || Go to next page.
|-
| Previous Page || Esc,P,U Ctrl+U || Go to previous page.
|}

=== Search Menu ===

The following commands let you search through the file for specific instances of text. You can substitute one pattern of text with another (search and replace) and have ED request confirmation of (query) each replace. If the specified text is not found or there are no more instances of the text, the message Search failed is displayed. When using the Find and Replace menu commands, ED prompts for the text strings. Enter the text without delimiters. When using extended mode, include delimited strings with the command.

{| class="wikitable"
| Find... Find Next || Esc,s... || Finds the next occurrence of the specified string of text. The search starts one character beyond the current cursor position and continues forward through the file. If the string is found, the cursor moves to the start of the located string. The search is case-sensitive, unless the Ignore Case command is used. Find Next repeats the command.
|-
| Reverse Find... Reverse Find Next || Esc,B,F... || Searches backwards through the file for the specified string. This command finds the last occurrence of the string before the current cursor position. The search continues through to the beginning of the file. Reverse Find Next repeats the command.
|-
| Replace... || Esc,E... || Exchanges one occurrence of text with another. In extended mode, enter the strings enclosed by three delimiters. For example, to replace the word to with too, enter "to"too". Specify empty strings by typing two delimiters with nothing between them. If the first string is empty, ED inserts the second string at the current cursor position. If the second string is empty, ED searches for the next occurrence of the first string and then deletes it. Note that ED ignores margin settings when exchanging text.
|-
| Global Replace || Esc,R,P,E... || Exchanges all occurrences of text.
|-
| Query-Replace... || Esc,E,Q... || Searches for the text to be exchanged and requests verification by displaying Exchange?. Enter Y to exchange or another other key to abort.
|-
| Global Query-Replace... || Esc,R,P,E,Q... || Searches for all occurrences of the text to be exchanged and requests verification for each. Enter Y to exchange or any other key to abort.
|}

=== Settings Menu ===

The following commands are used for setting up your ED environment:

{| class="wikitable"
| Set FN Key... || Esc,S,F... || Defines the function keys and other programmable keys. Defining function key and Ctrl+key commands is similar to defining menu items. See page 4-15 for instructions for defining function keys and an example of the Set FN Key command.
|-
| Show FN Key... || Esc,D,F <nowiki><key></nowiki> || Displays the setting for the function key specified by <nowiki><key></nowiki>. Enter a space and a key slot number for <nowiki><key></nowiki>.
|-
| Reset Keys || Esc,R,K || Resets the key definitions to the default. See page 4-16 for a table of special key mappings.
|-
| Right Margin... || Esc,S,R... || Sets the right margin. Use the SR command followed by a number indicating the column position.
|-
| Left Margin... || Esc,S,L... || Sets the left margin. Use the SL command followed by a number indicating the column position. The left margin should not be set beyond the right edge of the screen.
|-
| Ignore Case || Esc,U,C || Specifies a case-insensitive search. UC instructs all subsequent searches not to make any distinction between upper and lower case next. To make searches case-sensitive again, use the LC command.
|-
| Case Sensitive || Esc,L,C || Specifies a case-sensitive search.
|}

=== Set FN Key ===

Set FN Key is used to define function keys and other programmable keys. There are 57 immediate command key slots ranging from 1 to 57. Any slot number can be redefined and any numbers within the range that do not appear in the special key mappings on page 4-16 are not defined.

The following is the syntax for the Set FN Key command:

SF <slot number> /command string/

Define Ctrl+key combinations by substituting a caret (^) and the other character for the slot number.

==== Example Script ====

This example script assigns function keys to cursor control commands. You can also enter these as a series of extended mode commands. The Top of File, Bottom of File, End of Page, Next Page, Next Line, and Previous Line commands are assigned to the F1 through F6 keys, respectively. Quotation marks are used as delimiters.

SF 1 "t"
SF 2 "b"
SF 3 "ep"
SF 4 "pd"
SF 5 "n"
SF 6 "p"

=== Special Key Mappings ===

The following table shows the default key definitions used in the Reset Keys command:

{| class="wikitable"
! Slot# !! Key/Key Sequence !! Function
|-
| 1-10 || F1 through F10 || Not defined
|-
| 11-20 || Shift+F1 to Shift+F10 || Not defined
|-
| 21 || Shift+left arrow || Move to beginning of line
|-
| 22 || Shift+right arrow || Move to end of line
|-
| 23 || Shift+up arrow || Move to top of document
|-
| 24 || Shift+down arrow || Move to bottom of document
|-
| 25 || Del || Delete character at cursor
|-
| 26 || Not defined || Not defined
|-
| 27 || Ctrl+A || Insert line
|-
| 28 || Ctrl+B || Delete line
|-
| 29 || Ctrl+C || Not defined
|-
| 30 || Ctrl+D || Move down 12 lines
|-
| 31 || Ctrl+E || Move to top or bottom of screen
|-
| 32 || Ctrl+F || Change case
|-
| 33 || Ctrl+G || Repeat last extended command line
|-
| 34 || Ctrl+H || Delete character left of cursor
|-
| 35 || Ctrl+I || Move cursor to next tab position
|-
| 36 || Ctrl+J || Not defined
|-
| 37 || Ctrl+K || Not defined
|-
| 38 || Ctrl+L || Not defined
|-
| 39 || Ctrl+M || Return
|-
| 40 || Ctrl+N || Not defined
|-
| 41 || Ctrl+O || Delete word or spaces
|-
| 42 || Ctrl+P || Not defined
|-
| 43 || Ctrl+Q || Not defined
|-
| 44 || Ctrl+R || Move to end of previous word
|-
| 45 || Ctrl+S || Not defined
|-
| 46 || Ctrl+T || Move start of next word
|-
| 47 || Ctrl+U || Move up 12 lines
|-
| 48 || Ctrl+V || Redisplay window
|-
| 49 || Ctrl+W || Not defined
|-
| 50 || Ctrl+X || Not defined
|-
| 51 || Ctrl+Y || Delete to end of line
|-
| 52 || Ctrl+Z || Not defined
|-
| 53 || Ctrl+[ || Esc (enter extended command mode)
|-
| 54 || Not defined || Not defined
|-
| 55 || Ctrl+] || Move to end or start of line, depending on cursor position
|-
| 56 || Not defined || Not defined
|-
| 57 || Not defined || Not defined
|}

=== Command Menu ===

The following commands are for manipulating files:

{| class="wikitable"
| Extended Command... || Esc,C,M... || Enters extended command mode; equivalent to pressing Ctrl+[ or Esc.
|-
| Repeat Last || Esc,R,E || Attempts to repeat the last command.
|-
| Run File... || Esc,R,F... || Loads and executes a command file of extended mode commands.
|-
| ARexx Command... || Esc,R,X... || Runs the specified ARexx program.
|-
| Redisplay || Esc,V,W || Redraws the ED window and clears the status line; equivalent to pressing Ctrl+V.
|}

=== Other ED Commands ===

There are also ED commands that do not appear in menus. These commands are listed here in functional groups. Use them in extended mode by entering the following key sequences.

==== Program Control ====

The following are program control commands:

{| class="wikitable"
| Extend Margins || Esc,E,X || Extends the margins for the current line. Once you enter the EX command, ED ignores the right margin on the current line.
|-
| Status Line Message || Esc,S,M... || Prints a given string on the status line.
|-
| Exit with Query || Esc,X,Q || Exits ED unless changes were made to the file. If changes have been made, the message File has been changed-type Y to save and exit: is displayed. Press any key (except Y) to abort the exit. XQ is equivalent to clicking the close gadget on the ED window.
|}

==== Cursor Control ====

The following commands are used for controlling the cursor:

{| class="wikitable"
| End Page || Esc,E,P || End of a page.
|-
| Previous || Esc,P || Start of the previous line.
|-
| Character Left || Esc,C,L || One place to the left.
|-
| Character Right || Esc,C,R || One place to the right.
|-
| Current End || Esc,C,E || End of the current line.
|-
| Current Start || Esc,C,S || Start of the current line.
|-
| Tab || Esc,T,B || Next tab position.
|-
| Word Next || Esc,W,N || Start of the next word.
|-
| Word Previous || Esc,W,P || Space after previous word.
|}

==== Modifying Text ====

The following commands edit text on the screen:

{| class="wikitable"
| Insert Before || Esc,I || Inserts the specified string on the line before the cursor. Specify a new line's string after the I command to insert text before the current line containing the cursor.
|-
| Insert After || Esc,A || Inserts the specified string on the line after the cursor. This command works in the same way as I, except that the string is inserted on a new line beneath the current cursor position.
|-
| Split || Esc,S || Splits the current line at the cursor position.
|-
| Join || Esc,J || Joins the next line to the end of the current line.
|-
| Delete || Esc,D || Deletes the current line.
|-
| Delete Character || Esc,D,C || Deletes the character under the cursor.
|-
| Delete Left || Esc,D,L || Deletes the character to the left of the cursor.
|-
| Delete Word || Esc,D,W || Deletes to the end of the current word.
|-
| End Line || Esc,E,L || Deletes to the end of the current line.
|-
| Flip Case || Esc,F,C || Switches the case of the selected letters, one at a time.
|-
| Set Tab || Esc,S,T || Sets the tab stop. To change the current setting of tabs, use the ST command followed by a number.
|-
| Next || Esc,N || Start of the next line.
|}

== Repeating Commands in Extended Mode ==

Pressing Ctrl+G repeats a command line. You can set up execute complex sets of editing commands many times.

You can repeat a command a specified number of times by entering the number before the command. For example:

4 E/rename/copy/

exchanges the next four occurrences of "rename" to "copy".

Use the RP (Repeat) extended command to repeat a command until ED returns an error, such as reaching the end of the file. For example:

T;RP E/rename/copy/

moves the cursor to the top of the file, then exchanges all occurrences of "rename" with "copy". The T command (Top of File) changes all occurrences of Rename in the whole file. Otherwise, only the occurrences after the current cursor position are changed.

To execute command groups repeatedly, you can group the commands together in parentheses. You can also nest command groups. For example:

RP (F/Workbench/;3A//)

inserts three blank lines (the null string//) after every line containing Workbench.

To interrupt any sequence of extended commands, press any key during execution. If an error occurs, ED abandons the command sequence.

== Customizing ED ==

You can customize ED with commands that change the menus and function key setup. These commands can be entered individually within ED. They can also be saved as a script, such as S:Ed-startup, or as a file specified using the WITH argument. To execute the file from within ED, use the Run File (Esc,R,F) extended command. For information about changing the function keys, see page 4-15.

{| class="wikitable"
\ Set Menu Item || Esc,S,I || Defines the menu headings and items. There are 120 menu item slots ranging from 0 to 119. The slot type identifies the contents of the slot and is a number from 0 to 4. The 0 slot type must be the last defined slot. Do not create a menu without items; if you specify a menu heading, include menu items after it. See below for the syntax of the Set Menu Item command and a table of the slot types.
|-
| Enable Menu || Esc,E,M || Enables menus. You must follow the Set Menu Item commands with EM to enable the menu commands. See page 4-22 for an example script using the Enable Menu command.
|}

=== Set Menu Item ===

The following is the syntax for the Set Menu Item command:

SI <slot number> <slot type> /string1/string2/

The following table shows the slot types and functions used with the Set Menu Item command:

{| class="wikitable"
! Type !! Function !! String Input
|-
| 0 || End of Menus || No arguments
|-
| 1 || Menu Heading || String1 = heading name
|-
| 2 || Menu Item || String1 = item name String2 = command string
|-
| 3 || Submenu Heading || String1 = heading name String2 = command string
|-
| 4 || Separator bar || No arguments
|}

=== Example Script ===

The following is an example script using the Set Menu Item and Enable Menu commands. Quotation marks are used as the delimiters.

SI 0 1 "Project"
SI 1 2 "Open . . . " "op ? /Open file:/"
SI 2 2 "Save ... " "sa"
SI 3 4
SI 4 2 "Quit!" "q"
SI 5 1 "Move"
SI 6 2 "Top" "t"
SI 7 2 "Bottom" "b"
SI 8 0
EM

This script produces the menus illustrated in Figure 4-4:

[[File:DosFig4-4.png|none|frame|ED Custom Menu Example]]

== Printing From ED ==

Use the following steps to print a file that is open in the current ED window:

# Choose the Save As menu item to display a file requester.
# Enter prt: in the Drawer field.
# Select OK.

This prints the file, but does not save it to disk. If you wish to save the file you must select the Save menu item or Save As and a file name.

== Quitting ED ==

You can exit ED in one of the following three ways:

* Esc,X. This method exits ED and saves the current file to a designated file name that was specified when ED was opened.
* Esc,X,Q or click on the ED window's close gadget. This method exits ED if no changes were made to the file. If changes were made to the file, ED lets you save the changes or exit without saving.
* Esc,Q or select the Quit item in the Project menu. This method exits ED without saving any changes if you confirm the status line warning that changes will be lost.

== ARexx Support ==

You can also control ED from ARexx by sending and receiving commands through ED's ARexx port. Each copy of ED running concurrently has an individual ARexx port name that must be specified to handle information for the correct session. The ARexx port names are assigned as follows:

* The first session's port name is ED
* The second session's is ED_1
* The third session's is Ed_2 and so on

Many of ED's extended commands can be used from ARexx. By using ED's RV command in ARexx programs, you can send information from ED to ARexx. This gives information about the status of ED, such as the current line number of the name of the file being edited.

The RV command accepts the name of the ARexx stem variable to store its argument information. For example, in ARexx:

address 'Ed' 'RV /stem/'

assigns values to the following variables:

{| class="wikitable"
| stem.LEFT || Current left margin
|-
| stem.RIGHT || Current right margin
|-
| stem.TABSTOP || Current tab stop setting
|-
| stem.LMAX || Maximum number of lines visible on screen
|-
| stem.WIDTH || Width of the screen in characters
|-
| stem.X || Cursor X position in the ED window (1 is the left edge)
|-
| stem.Y || Cursor Y position in the ED window (1 is the top line)
|-
| stem.BASE || Window base (normally 0, but non-zero when the screen is shifted to the right)
|-
| stem.EXTEND || Extended margin value (Extend Margins command)
|-
| stem.FORCECASE || Case sensitivity flag (Ignore Case = 1, Case Sensitive = 0)
|-
| stem.LINE || Current line number in the file (1 is the first line)
|-
| stem.FILENAME || Name of the file being edited
|-
| stem.CURRENT || Text of the current line
|-
| stem.LASTCMD || Last extended command issued
|-
| stem.SEARCH || Lst string searched for
|}

Any valid ARexx symbol can be substituted for "stem". Enclose the name in proper delimiters. These variables can be treated as ordinary ARexx stem variables.

== ED/ARexx Example Program ==

The example program, Transpose.ed, illustrates the use of several extended commands from ARexx. This program transposes two characters when launched from ED. For example, if a line contains the string 123 and the cursor is highlighted the 3, Transpose.ed changes the string to 213.

Enter this program and save it as REXX:Transpose.ed. Then, open ED and edit an existing file or create a new one. Place the cursor one character to the right of the ones to be transposed, press Esc, and enter:

RX /transpose.ed/

The program executes and the characters are transposed if ARexx is running and everything is entered correctly. The entire file name, including the extension, must be specified to run the program.

<syntaxhighlight lang="C" line>
/*Transpose.ed: An example program to transpose two characters. */
/*Given string '123', if cursor is on 3, this macro converts */
/*string into '213'. */
HOST = address () /*find out which ED session invoked this program*/
address VALUE HOST /*...and talk to that session */
'rv''/CURR/' /*Ask ED to store info in stem variable CURR */
/*Obtain two pieces of information: */
currpos = CURR.X /*1.position of cursor on line */
currling = CURR.CURRENT /*2. Contents of current line */
if /currpos >2) then /*Work only on the current line */
currpos = currpos - 1
else do /*Otheriwse, report error and exit */
'sm/Cusor must be at position 2 or further to the right/'
exit 10
end

/*Next the code needs to reverse the CURRPOSth and CURRPOSth-1 */
/*characters and then replace the current line with the new one. */
/*drop CURR. CURR is no longer needed; dropping it saves some */
/*memory. */
'd' /*Tell ED to delete current line */
currlin = swapch (currpos,currlin) /*Swap the two characters */
'i/'||currlin||'/' /*Insert modified line */
do i = 1 to currpos /*Place cursor back where it started */
'cr' /*ED's `cursor right' command */
end
exit /*Program has finished */

/*Function to swap two characters */
Swapch: procedure */
parse arg cpos,clin
ch1 = substr(clin,cpos1) /*Get character */
clin = delstr(clin,cpos1) /*Delete it from string */
clin = insert(ch1,clin,cpos-2,1) /*Insert to create transposition */
return clin /*Return modified string */
</syntaxhighlight>

= MEmacs =

MEmacs (MicroEmacs), which is similar to the UNIX-based Emacs editor, is a screen-oriented editor in which you can edit multiple files at the same time. MEmacs performs all operations on memory-resident text, requiring that entire text files be able to fit into memory at once.

Line length, generally 80 characters long, is limited to the right edge of the screen. You can enter characters beyond the limit, however, they are not displayed. To see these characters, break the line or delete some of the displayed characters. A dollar sign ($) at the right edge of the screen indicates that there are characters beyond what is displayed.

The format for the MEmacs command is the following:

MEMACS [<filename>] [GOTO <n>] [OPT W]

The <filename> argument is optional.

The GOTO <n> option specifies the line on which the cursor is to appear when the file is opened.

Specifying OPT W opens MEmacs in a Workbench window rather than on its own screen, which saves memory.

== Starting MEmacs ==

MEmacs can be run from either the Workbench or the Shell. From the Workbench, double-click on the MEmacs icon in the Tools window of the Extras disk. If you have a hard disk, the Tools drawer is in your Workbench window.

From the Shell, enter:

MEmacs <filename>

where <filename> specifies the file to read into MEmacs. If a file with that name does not previously exist, a new file is created when you save your work.

== MEmacs Commands ==

The line at the bottom of the MEmacs screen identifies either the current file name or the name of the current buffer if no file name is specified. Figure 4-5 illustrates the MEmacs opening screen .

[[File:DosFig4-5.png|none|frame|MEmacs Opening Screen]]

Several buffers can be in use at the same time and one or more can be displayed on the screen simultaneously. Menu options switch between them. At all times, the screen displays what is actually in the buffer.

MEMacs has two conditions of operation:

; Normal
: When you enter and manipulate text directly in the file without special functions.

; Command
: When you enter a command through a menu selection or the keyboard shortcut for it. In the command condition, the cursor jumps to the bottom line of the display and waits for you to supply additional information following the prompt. You cannot return to the normal condition until you satisfy or cancel the command by pressing Return.

In the MEmacs normal condition, you can:

* Move the cursor using the arrow keys.
* Move the cursor to the edge of the window by holding down Shift and pressing the appropriate arrow key.
* Move the cursor by clicking the left mouse button at the desired place on the screen.
* Insert characters at the current cursor position by typing them.
* Delete the character at the current cursor position by pressing Del.
* Delete the character to the left of the cursor by pressing Backspace.
* Perform other special menu and command functions.

When using MEmacs, you should be familiar with the following special terms:

; Buffer
: A memory area that MEmacs controls. There is always at least one buffer used by MEmacs containing zero or more text characters.

; Dot
: The current cursor position.

; Mark
: A specified cursor position. (Each buffer has its own dot and mark.) The Set-mark menu item marks the current cursor position (described on page 4-33). You can move forward or backward in the file, adding or deleting text. To return to the marked place, select the Swap-dot&mark menu item (described on page 4-36).

: You can also set a mark to indicate the beginning of a block of text that you want to duplicate, move, or delete. The block encompasses all the characters starting with the mark and continuing to the current cursor position.

; Kill
: Kill commands remove text from the screen to save in a kill buffer. This text can be retrieved and inserted into your document by using the Yank command. Issuing successive Kill commands (without selecting Yank in between) adds each block of the text to the existing text in the kill buffer. If you select Yank, the next block of killed text otherwise the current block.

; Window
: MEmacs screens can be split into multiple layers for editing and displaying more than one buffer or two or more portions of the same buffer. Each layer is a MEmacs window.

; Modified Buffers
: Buffers are marked as modified when any changes are made. The modified status is removed when the buffer is saved.

: To see modified buffers, use the List-buffers command (described on page 4-33); modified buffers are identified with an asterisk (*). If you exit MEmacs without saving any changes, a prompt tells you that modified buffers exist and asks if you really want to quit.

== Menu Commands ==

MEmacs has the following menus:

{| class="wikitable"
| Project || Contains system and file-oriented items.
|-
| Edit || Contains buffer editing commands.
|-
| Window || Controls the characteristics of the MEmacs windows.
|-
| Move || Controls the placement of the cursor.
|-
| Line || Controls line-oriented operations.
|-
| Word || Controls word-oriented operations.
|-
| Search || Controls search and search/replace options.
|-
| Extras || Controls the numerical value of arguments and lets you execute a series of operations as though it were a single special command.
|}

Figure 4-6 illustrates the MEmacs expanded menu bar.

[[File:DosFig4-6.png|none|frame|Expanded Menus]]

=== Project Menu ===

The commands in the Project menu, except for Visit-file, affect the buffer associated with the current cursor position.

{| class="wikitable"
| Rename || Ctrl+X,F || Changes the name of the file associated with the current buffer. Pressing Return without specifying a file name disassociates the buffer from any file name.
|-
| Read-file || Ctrl+X, Ctrl+R || Replaces the contents of the current buffer with the contents of a file. Enter a complete file path. Press Return without specifying a file name to ignore the request and return to normal mode.
|-
| Visit-file || Ctrl+X, Ctrl+V || Allows you to work with additional files other than the one you are currently editing. Enter the complete file path.
|-
| Insert-file || Ctrl+X, Ctrl+I || Insert the contents of a file into the current buffer at a point one line above the current cursor position. Enter the complete file path.
|-
| Save-file || Ctrl+X, Ctrl+S || Writes the contents of the current buffer to the file name associated with that buffer. Issues the file's line count following a successful save. MEmacs does not save the file if no name is provided; it displays this error message: No file name.
|-
| Save-as-file || Ctrl+X, Ctrl+W || Allows you to specify the name and path of a file associated with a buffer.
|-
| Save-mod || Ctrl+X, Ctrl+M || Writes the contents of all modified buffers to the disk. Do not accidentally modify a buffer that you did not intend to change.
|-
| Save-exit || Ctrl+X, Ctrl+F || Saves all modified buffers and exits MEmacs.
|-
| New-Cli || Ctrl+- || Opens a new Shell window known as a Spawn Window. Enter AmigaDOS commands in the Spawn Window without interfering with MEmacs. Close the window with ENDSHELL.
|-
| Cli-Command || Ctrl+X,! || Lets you execute an AmigaDOS command while in MEmacs. Enter a command following the ! prompt at the bottom of the screen. Command output is placed in the spawn.output buffer.
|-
| Quit || Ctrl+C || Exits MEmacs. You are given an opportunity to save modified buffers or quit without saving. Alternative keyboard shortcuts: Ctrl+X,Ctrl+C Esc,Ctrl+C.
|-
| About... || || Gives program copyright information
|}

=== Edit Menu ===

The commands in the Edit menu affect the editing of your buffers and their associated files.

{| class="wikitable"
| Kill-region || Ctrl+W || Deletes block of text from the current buffer and saves them in a kill buffer. Text can be retrieved with the Yank command. Make copies of a block by immediately selecting Yank without changing the cursor position after killing the block. This restores the block to its position and leaves a copy in the kill buffer.
|-
| Yank || Ctrl+Y || Copies the contents of the kill buffer to the current cursor location on the current line. Reverses the action of Kill-region without changing the contents of the kill buffer. Used with Kill-region for moving text or for repeatedly copying a single block of text.
|-
| Set-mark || Ctrl+@ || Marks the cursor position in a buffer. The subsequent cursor position is referred to as a dot. Move between the mark and the dot using the Swap-dot&mark command in the Move menu. Used for marking blocks of text. Alternative keyboard shortcut: Esc,-.
|-
| Copy-region || Esc,W || Copies the contents of the marked region to the kill buffer without deleting it, replacing any previous contents.
|-
| Upper-region || Ctrl+X, Ctrl+U || Changes the text of the entire marked region to upper case.
|-
| Lower-region || Ctrl+X, Ctrl+L || Changes the text of the entire marked region to lower case.
|-
| List-buffers || Ctrl+X, Ctrl+B || Splits the current buffer's window and displays a list of the buffers MEmacs is maintaining. To redisplay the current buffer, select the One-window command or press Ctrl+X,1. The List-Buffer fields are: 
{| class="wikitable"
| C || Displays an asterisk if the buffer has been modified since it was last saved to a file. (Stands for changed.)
|-
| Size || Shows how many characters are in the buffer.
|-
| Buffer || Shows the name given to the buffer. If you read in a file, this is the name of the file without the full path.
|-
| File || Shows the full path to the file. This is the file to which MEmacs writes the buffer if you Save-file or Save-exit while the cursor is in that buffer.
|}
|-
| Select-buffer || Ctrl+X,B || Allows you to select the buffer to edit in the current window. Replaces the contents of the window with the selected buffer or new buffer.
|-
| Insert-buffer || Esc, Ctrl+Y || Insert the contents of a named buffer into the current buffer at the line above the current cursor position.
|-
| Kill-buffer || Ctrl+X,K || Deletes the contents of one or more chosen buffers, returning the memory to the memory manager to reuse. You must specify the buffer to be deleted; a buffer cannot be killed if its contents are currently displayed.
|-
| Justify-buffer || Ctrl+X,J || Removes all blank spaces and tabs from the left edge of all the lines in the current buffer. The text realigns with the current margins.
|-
| Redisplay || Ctrl+L || Redraws the screen.
|-
| Quote-char || Ctrl+Q || Allows insertion of any literal character in the text file, except the Tab key. Alternative keyboard shortcut: Ctrl+X,Q.
|-
| Indent || Ctrl+J || Moves the cursor to the next line, automatically indenting the same amount of spaces as the previous line. Alternative keyboard shortcuts: Help or Enter on the numeric keypad.
|-
| Transpose || Ctrl+T || Swaps the positions of two adjacent characters. Place the cursor on the right-most of the two characters and execute the command.
|-
| Cancel || Ctrl+G || Ends an ongoing menu command, such as query search and replace.
|}

=== Window Menu ===

The Window menu controls how to view your buffers on the screen.

{| class="wikitable"
| One-window || Ctrl+X,1 || Makes the current buffer a single, full-sized window on the MEmacs screen.
|-
| Split-window || Ctrl+X,2 || Splits the current window in half, positioning the current buffer identically in both windows. Any changes you make in either window affect the whole buffer.
|-
| Next-window || Ctrl+X,N || Moves the cursor to the next window and makes that window available for editing.
|-
| Prev-window || Ctrl+X,P || Moves the cursor to the previous window and makes that window available for editing.
|-
| Expand-window || Ctrl+X,Z || Adds a line to the height of the current window and simultaneously subtracts a line from the height of the adjacent window.
|-
| Shrink-window || Ctrl+X, Ctrl+Z || Substracts a line from the height of the current window and adds a line to the height of the adjacent window.
|-
| Next-w-page || Esc, Ctrl+V || Displays the next page of the adjacent window. This does not make the window available for editing.
|-
| Prev-w-page || Ctrl+X,V || Displays the previous page of the adjacent window. If only one window is displayed, it displays the previous page of that window.
|}

=== Move Menu ===

These commands move the cursor rapidly through the current buffer.

{| class="wikitable"
| Top-of-buffer || Esc,< || Moves the cursor to the top line of the current buffer.
|-
| End-of-buffer || Esc,> || Moves the cursor to the bottom line of the current buffer.
|-
| Top-of-window || Esc,, || Moves the cursor to the top of the current window.
|-
| End-of-window || Esc,. || Moves the cursor to the bottom of the current window.
|-
| Goto-line || Ctrl+X, Ctrl+G || Moves the cursor to a specified line number. Specifying a line number larger than the total number of lines in a buffer moves the cursor to the last line of the buffer.
|-
| Swap-dot&mark || Ctrl+X, Ctrl+X || Marks the current cursor position (dot) and moves the cursor to the previously marked setting.
|-
| Next-page || Ctrl+V || Moves the cursor toward the end of the buffer by one full window, less one line.
|-
| Prev-page || Esc,V || Moves the cursor towards the beginning of the buffer by one full window, less one line.
|-
| Next-word || Esc,F || Moves the cursor forward to the next non-alphabetic character, such as a space or punctuation mark, following the current word.
|-
| Previous-word || Esc,B || Moves the cursor back to the first letter of the previous word.
|-
| Scroll-up || Ctrl+Z || Moves the text up one line.
|-
| Scroll-down || Esc,Z || Moves the text down one line.
|}

=== Line Menu ===

These commands move the cursor within or between lines and perform operations involving entire lines.

{| class="wikitable"
| Open-line || Ctrl+O || Splits the line containing the cursor, forcing the character at the current cursor position to become the first character of the following line. The cursor remains on the original line. Pressing the Del key cancels an accidental Open-line.
|-
| Kill-line || Ctrl+X, Ctrl+D || Deletes the line containing the cursor and places the text in the kill buffer.
|-
| Kill-to-eol || Ctrl+K || Deletes the text between the current cursor position and the end of the line and places the text in the kill buffer.
|-
| Start-of-line || Ctrl+A || Moves the cursor to the first position on a line.
|-
| End-of-line || Ctrl+E || Moves the cursor to the last position on a line.
|-
| Next-line || Ctrl+N || Moves the cursor down one line.
|-
| Previous-line || Ctrl+P || Moves the cursor up one line.
|-
| Line-to-top || Esc,! || Moves the line containing the cursor to the top of the window.
|-
| Delete-blanks || Ctrl+X, Ctrl+O || Deletes blank lines, proceeding forward from the current cursor position until MEmacs reaches the next line on which there is text. Does not delete single blank lines.
|-
| Show-Line# || Ctrl+X,= || Displays information on the present cursor position.
|}

=== Word Menu ===

The Word menu contains word-associated operations.

{| class="wikitable"
| Delete-forw || Esc,D || Deletes the character on which the cursor is positioned and all remaining characters to the right until the next non-alphanumeric character is found, such as a blank space, tab, or punctuation.
|-
| Delete-back || Esc,H || Delets all characters to the left of the cursor until it finds the first character of a word. The character at the cursor position is not deleted. Alternative keyboard shortcut: Esc,Del.
|-
| Upper-word || Esc,U || Changes a word to upper case, starting at the cursor position and proceeding to the last character of the word.
|-
| Lower-word || Esc,L || Changes a word to lower case, starting at the cursor position and proceeding to the last character of the word.
|-
| Cap-word || Esc,C || Changes the character at the cursor position to upper case. Also changes the characters to the right of the cursor, up to the end of the word, to lower case.
|-
| Switch-case || Esc,^ || Changes the case of a word, starting at the current cursor position and proceeding to the right until it reaches the end of the word. If a word is upper case or has mixed text, it changes upper to lowr case and vice versa.
|}

=== Search Menu ===

These commands search through the current buffer for specific text strings. The case (upper or lower) of the string is not significant in the search. However, if you are using text substitution (search and replace), the text is replaced in the case of the replacement string.

{| class="wikitable"
| Search-forward || Ctrl+S || Searches through the text starting at the current cursor position and moving forward to the end of the buffer. At the prompt, enter the character string for the search. Alternative keyboard shortcut: Ctrl+X,S.
|-
| Search-backward || Ctrl+R || Searches through the text from the current cursor position backwards to the beginning to the buffer. Alternative keyboard shortcut: Ctrl+X,R.
|-
| Search-replace || Esc,R || Searches the same as Search-forward, allowing you to replace the string with different text. At the prompt, enter the replacement string of characters.
|-
| Query-s-r || Esc,Q || Operates the same as Search-replace, except it asks for confirmation to replace each time it finds the specified string. The options are Y (yes), N (no), C (change all occurrences), and Ctrl+G (abort).
|-
| Fence-match || Esc, Ctrl+F || Finds the closest occurrence of the fence character to match the one at the current cursor position. Fence characters are parenthesis, brackets, braces, and angle brackets.
|}

=== Extras Menu ===

These commands are MEmacs operational commands and macro commands. Specific numeric arguments may be required before selecting a command; an * indicate that an argument is required. Macro commands are executed by selecting the Execute-macro menu item.

{| class="wikitable"
| Set-arg || Ctrl+U || Lets you specify a numeric argument for a command.
|-
| Set || Esc,S || Lets you set the following MEmacs parameters:
{| class="wikitable"
| Screen || Places the MEmacs display in a Workbench window or back onto a custom screen.
|-
| Interlace || Turns the interlace mode on or off.
|-
| Mode || Results in a second prompt "Mode:"; you can enter Cmode (for editing C programs) or Wrap (to enable automatic word-wrap when the text reaches a set cursor position). Cmode provides automatic fence matching. Use +mode or -mode to add or subtract a mode.
|-
| Left || Determines the left margin. Prompts for a numerical argument if not provided with the entry.
|-
| Right || Determines the right margin. Prompts for a numerical argument if not provided with the entry.
|-
| Tab || Sets the increment for tab spacing. Prompts for a numerical argument if not provided with the entry.
|-
| Indent || Determines how far to indent each level of nesting (used in Cmode). Prompts for a numerical argument if not provided with the entry.
|-
| Case || Turns case-sensitive searches on of off; default is off.
|-
| Backup || Turns the MEmacs backup function on or off. Your options are: ON (renames the current file <filename>.bak and saves that bakkup file to the T: directory); SAFE (this option checks to see if a file already exists for the buffer - if so, it displays an error and does not overwrite the existing file, Ctrl+X clears the display); and OFF (this is the default option - MEmacs does not perform any backup).
|}
|-
| Start-macro || Ctrl+X,( || Tells MEmacs to start recording any subsequent keystrokes. Used with the Stop-macro and Execute-macro commands.
|-
| Stop-macro || Ctrl+X,) || Tells MEmacs to stop recording keystrokes.
|-
| Execute-macro || Ctrl+X,E || Repeats keystrokes that were entered between Start-macro and Stop-macro.
|-
| Set-key || Ctrl+X, Ctrl+K || Allows you to redefine all of the function keys, the Shifted function keys, the Help key, or any key on the numeric keypad as keyboard macros. You cannot use the menu shortcut of Ctrl+@ to insert the Set-mark command into any keyboard macro definitions.
|-
| Reset-keys || Esc,K || Returns any keys defined by Set-keys to their original default state.
|-
| Execute-file || Esc,E || Allows you to execute a program file within MEmacs.
|-
| Execute-line || Ctrl+[, Ctrl+[ || Sets MEmacs to command mode. At the prompt enter any menu command and its parameters. Alternate keyboard shortcut: Esc,Esc.
|}

The following table contains the default values of the Set-key/function keys when used in macro commands.

{| class="wikitable"
! Key !! Assignment !! Key Sequence
|-
| F1 || Clone line || Ctrl+A,Ctrl+K,Ctrl+Y,Ctrl+M,Ctrl+Y
|-
| F2 || Delete line || Ctrl+X,Ctrl+D
|-
| F3 || Execute keyboard macro || Ctrl+X,E
|-
| F4 || Next screen || Ctrl+V
|-
| F5 || Previous screen || Esc,V
|-
| F6 || Split window || Ctrl+X,2
|-
| F7 || One window || Ctrl+X,1
|-
| F8 || Scroll window up || Ctrl+Z
|-
| F9 || Scroll window down || Esc,Z
|-
| F10 || Save file and exit || Ctrl+X,Ctrl+F
|-
| Help || Insert line || Ctrl+J
|-
| Enter (keypad) || Insert line || Ctrl+J
|}

== Commands Not in Menus ==

The following commands are only accessible through the keyboard.

Keys are bound when they can be used to perform a function. For example, any key or key sequence that can be used as a shortcut for a menu item is bound to that menu item.

{| class="wikitable"
| Describe Key || Esc, Ctrl+D || Tells you if any functions are bound to a key or key sequence. At the prompt enter the specific key or key sequence.
|-
| Bind Key || Esc, Ctrl+B || Allows you to bind a key to a function. At the prompt, enter the key or key sequence.
|-
| Unbind Key || Esc, Ctrl+U || Allows you to return a bound key to an unbound state. At the prompt, enter the key or key sequence. Standard bound keys cannot be unbound.
|-
| Echo || Esc, Ctrl+E || Displays the string entered in the command line.
|-
| Move to Edge of Window || Shift+Arrow || Moves the cursor to the top, bottom, left, or right edge of the screen.
|-
| Delete the Next Character || Ctrl+D || Deletes the character at the current position. Same as pressing Del.
|-
| Delete the Previous Character || Ctrl+H || Deletes the character to the left of the current cursor position. Same as pressing Backspace.
|-
| Move to Next Line || Ctrl+M || Inserts a newline character after the current cursor position and moves the cursor to the start of the new line.
|-
| Move x number of Characters || Ctrl+F, Ctrl+B || Allows you to move the cursor forward or backward a specified number of spaces. Providing no value moves the cursor only one character.
|}

== Customizing MEmacs ==

MEmacs looks for an Emacs_pro file when it is opened to see if there are any command or local files that it should automatically execute. You can customize the Emacs_pro file by adding commands to it that you use often, command sequences, or text strings. If an Emacs_pro file does not already exist, you can create one.

To create a global file of commands, place the Emacs_pro file in the S: directory. Local files can be out in any directory. If that directory is the current directory when MEmacs is opened, the commands in that particular local file are executed.

When both local and global Emacs_pro files are present, the local file overrides the global file.

For example:

Set Case On
Set-Key F11 "Dear Sirs:"
Set-Key F12 "^S Workbench"
Set-Key F13 "^X^B"

makes the following assignments:

{| class="wikitable"
| Shift+F1 || Enter the text string "Dear Sirs:".
|-
| Shift+F2 || Search forward for the next occurrence of the word Workbench. (The Set Case On commands make any text searches case-sensitive.)
|-
| Shift+F3 || Display the list of buffers.
|}

You must use Ctrl+Q to enter a Ctrl+key sequence. For example, to enter the ^S character shown in the example, press Ctrl+Q, Ctrl+S.

== Quitting MEmacs ==

You can exit MEmacs by selecting the Quit menu item in the Project menu or by entering Ctrl+C. MEmacs lets you save any modified buffers or quit without saving.

= EDIT =

EDIT is a line editor designed for the automated editing of files, particularly binary files or files that are larger than available memory. You cannot create a new file with EDIT.

EDIT processes files line by line. As EDIT moves through the input, or source file, each line is passed after alteration to a sequential output file, the destination file.

EDIT processes the lines in files in a forward direction; however, you can move backward a limited number of lines. EDIT holds the lines in an output queue before writing them to the destination file. The size of this queue depends on the amount of memory available. You can increase the size of the queue with the OPT P and OPT W options.

The format for EDIT is the following:

EDIT [FROM] <filename> [[TO] <filename>] [WITH <filename>] [VER <filename>]
[OPT P <lines> | W <chars> | P<lines>W<chars>] [WIDTH <chars>] [PREVIOUS <lines>]

The FROM argument specifies the source file to be edited. You must specify a source file with EDIT, although the FROM keyword is optional.

The TO argument specifies the destination file to which EDIT sends its output, including editing changes. If you omit the TO argument, EDIT uses a temporary file. This temporary file is renamed with the name of the FROM file and overwrites the FROM file when editing is complete.

The WITH keyword specifies a file containing editing commands.

The VER keyword specifies the file to which EDIT sends error messages and line verifications. If the VER argument is not given, EDIT uses the screen.

Use OPT P <n> and OPT W <n> to specify the PREVIOUS and WIDTH options. However, do nit use the OPT keyword with PREVIOUS and WIDTH.

You can use the PREVIOUS and WIDTH options to increase or decrease the amount of available memory. The PREVIOUS option sets the number of previous lines available to EDIT to the integer <n>. The WIDTH option sets the maximum number of characters allowed on a line to <n>. EDIT multiples the number of previous lines by the maximum number of characters (PREVIOUS * WIDTH) to determine the available memory. The default values are PREVIOUS 100 WIDTH 1200.

== Starting EDIT ==

Start EDIT through a Shell using the following command:

1.< EDIT <filename>

Where <filename> is the name of an existing file to be edited.

== EDIT Commands ==

The following list provides background information about EDIT commands:

{| class="wikitable"
| Current line || Refers to the line that EDIT is working on at any time. Every command entered refers to the current line, all text changes are made to the current line, and new lines are inserted before the current line.
|-
| Original lines || The lines of the source file. Lines retain their original number until you renumber them with the REWIND or = commands.
|-
| Non-original lines || Any lines that are inserted into the source file or original lines that are split. These are not assigned line numbers.
|-
| Line verification || When using commands that change information in a line, EDIT displays the revised line after the command is executed.
|-
| Arguments || Strings, qualified strings, numbers, and switch values used with EDIT commands.
|}

Enter commands in one of the following three ways:

* Enter the commands, then press Return
* Enter the final command argument, then press Return
* Enter a semicolon or closing parenthesis

The text conventions used in the command description are the following:

* Command names are shown in upper case, although EDIT is not case-sensitive.
* Angle brackets indicate that information must be substituted. For example, <string> indicates that the command takes a string argument.
* An <n> represents a numeric argument.
* Square brackets indicate that the argument is optional. For example, [<n>] indicates that the command can take an optional numeric argument.
* Slashes are used as delimiters for strings; use one slash between two strings.
* Periods are used as delimiters for file names (slashes cannot be used since they are used to separate strings).

== Selecting the Current Line ==

The following commands let you move through the file and select the current line.

{| class="wikitable"
| Move to a specific line number || M <n> || Specify a new current line by entering its line number, a period, and an asterisk as M's argument. Only original lines can be accessed by line number.
|-
| Move to next line in the source file || N || Move forward one line. Entering a number and N indicates the number of lines to move forard. When used as the last line of the source file, EDIT creates an extra line at the end of the file. If you are already on this extra line, using N causes an error message to be displayed.
|-
| Move to the previous line in the source file || P || Moves back one line. Entering P repeatedly moves more than one line. Entering a number + P indicates how many lines to move back. You can only move back to previous lines that have not yet been written to the destination file. The default is 100 lines, which can be changed with the PREVIOUS option.
|-
| Find || F<string> || Lets you select a current line by specifying some of its content.
|-
| Search Backward || B,F<string> || Looks backward starting from the current line through the source file for a line containing the specified string.
|}

== Editing the Current Line ==

The following commands add new material or replace material on the current line.

{| class="wikitable"
| Insert <string2> after <string1> || A <string1> <string2> || Insert <string2> after the first occurrence of <string1>.
|-
| Insert <string2> before <string1> || B <string2> <string1> || Insert <string2> before the first occurrence of <string1>.
|-
| Exchange <string2> for <string1> || E <string2> <string1> || Replaces the first occurrence of <string1> with <string2>.
|}

== Inserting and Deleting Lines ==

The following commands insert new material (non-original lines) and delete lines from the source file. You can also insert complete files into the source file.

{| class="wikitable"
| Insert one or more lines || I [<n>] || If given alone or with a line number, inserts text before the current line. 
If given with an asterisk, the text is inserted at the end of the file. 
Indicate the end of the insertion by pressing Return, Z, and Return.
|-
| Delete one or more lines || D [<n>] || Deletes the current line if entered with no arguments. Deletes a specific line if entered with a line number. Deletes a set of lines if entered with a range of line numbers; do not use punctuation between the numbers. Deletes everything from the current line through the end of the source file of entered with a period and an asterisk as arguments.
|-
| Delete all lines until the specified string is found || D,F<string> || Deletes successive lines from the source file until the line containing the matching string is found. If no argument is specified, it deletes all lines until it finds the last string specified.
|-
| Delete existing lines and replace with new text || R [<n>] || Lets you delete line and then insert new ones. Entering a line number following R indicates a specific line to replace.
|-
| Change the terminator || Z <string> || Tells EDIT that it has reached the end of any new text that is being inserted. Entering a string after Z changes it from the default.
|-
| Show current information about EDIT || S,H,D || Displays saved information values, such as the last string searched for, the last command entered, and the input terminator.
|-
| Turn trailing spaces on/off || <nowiki>T,R,+|-</nowiki> || Preserves any blanks that fall at the end of lines.
|}

== Editing Line Windows ==

You can define subsections of the line, called line windows, on which EDIT executes all subsequent commands. In the descriptions of EDIT qualifiers, the beginning of the line always indicates the beginning of the line window.

Whenever EDIT verifies a current line, it indicates the position of the line window by displaying a > character directly beneath the line. EDIT omits the pointer if the line window begins at the start of the line.

The following commands control the position of the character pointer:

{| class="wikitable"
| > || Moves the pointer one character to the right.
|-
| < || Moves the pointer one character to the left.
|-
| PR || Resets the pointer to the start of the line.
|-
| PA <string> || Moves the pointer to the first character after the specified string.
|-
| <string> || Moves the pointer to the first character before the specified string.
|}

The following commands change the character at the current pointer, then move the pointer.

{| class="wikitable"
| $ || Makes the character at the pointer lower case, then moves the pointer one character to the right.
|-
| % || Makes the character at the pointer upper case, then moves the pointer one character to the right.
|-
| _ || The _ (underscore) command deletes the character at the pointer, turning it into a space, then moves the pointer one character to the right.
|-
| # || Deletes the character at the pointer, then moves the rest of the line one character to the left. To delete several characters, specify a number before the #. For example, 5# deletes the next five characters in the window.
|}

A combination of these commands can be used to edit a line character by character.

The following commands insert and exchange text on the current line, similar to the A, B, and E commands; however, the character pointer is moved on completion.

{| class="wikitable"
| Insert <string2> after <string1> || A,P <string1> <string2> || Inserts <string2> after the first occurrence of <string1>. The pointer is then positioned after <string2>.
|-
| Insert <string2> before <string1> || B,P <string1> <string2> || Inserts <string2> before the first occurrence of <string1>. The pointer is then positioned after <string2>.
|-
| Exchange <string1> with <string2> || E,P, <string1> <string2> || Replaces the first occurrence of <string1> with <string2>. The pointer is then positioned after <string2>.
|-
| Delete Till After || D,T,A <string> || Deletes all text from the beginning of the line or the character pointer to the end of the specified string.
|-
| Delete Till Before || D,T,B <string> || Deletes all text from the beginning of the line or the character pointer; stops before the specified string.
|-
| Delete From After || D,F,A <string> || Deletes all text starting after a specified string to the end of the line.
|-
| Delete From Before || D,F,B <string> || Deletes all text starting with the specified string to the end of the line.
|}

== Splitting and Joining Lines ==

These commands split a line into more than one line and join together two or more successive lines.

{| class="wikitable"
| Split line before <string> || S,B <string> || Splits the current line before the specified string. The first part of the line is sent to the output queue; the second part is made into a new non-original current line. Qualifiers can be used to restrict the context of the string.
|-
| Split line after <string> || S,A <string> || Splits the current line after the specified string. The first part of the line is sent to the output queue; the remainder of the line becomes the new current line. Qualifiers can be used to restrict the context of the string.
|-
| Join two lines || C,L [<string>] || Joins the current line with the next line of the source file. The string argument is optional; however, if a string is specified it is added to the end of the current line and that whole line is joined with the next line in the source file.
|}

== Renumbering Lines ==

These commands renumber the source file's lines to include non-original lines and to update a file that has been edited.

{| class="wikitable"
| Renumber source lines || = <n> || Sets the current line number to <n>. All subsequent original and non-original lines below <n> are renumbered you move to them.
|-
| Return to the beginning source file || REWIND || Moves back through the source file to make line 1 the current line. EDIT scans the rest of the source file and writes the lines to the destination file. This file is closed and reopened as a new source file. Non-original lines are now recognized as original lines. Can be entered as REWI.
|}

== Verifying Lines ==

These commands describe different ways of verifying lines.

{| class="wikitable"
| Turn Verification on/off || V + <nowiki>|</nowiki> - || Turns line verification on or off. If off, the lines are not displayed on the screen. To turn off, enter V -. To turn on, enter V +.
|-
| Verify the current line || ? || Verifies the current line by displaying the line number and the contents of the line.
|-
| Verify the current line with character indicators || ! || Produces two lines of verification. In the first line all non-graphic characters are replaced with the first character of their hexadecimal value In the second line, a minus sign is displayed under all positions corresponding to upper case letters and the second hexadecimal digit corresponds to non-graphic characters. All other positions contain spaces. In binary files, non-graphic characters are represented with question marks (??).
|}

== Inspecting the Source File ==

These commands advance through the source file, sending the lines it passes to the verification file, as well as to the normal output. They are known as Type commands because they display lines on the screen.

{| class="wikitable"
| Type <n> lines to the screen || T <n> || Types the specified number of lines to the screen. The first line typed is the current line. Omitting the <n> continues typing to the end of the source file. Interrupt the command with Ctrl+C.
|-
| Type the lines in the output queue || T,P || Displays the lines currently held in the output queue.
|-
| Type until EDIT has replaced all the lines in the output queue || T,N || Types from the current line forward until all the lines in the output queue are replaced. The previous contents are sent to the destination file.
|-
| Type with line numbers || T,L <n> || Similar to the T command. Types a specified number of lines, displaying the line numbers. EDIT displays + + + + for inserted or split lines since they do not have line numbers.
|}

== Making Global Changes ==

These commands start and stop global changes. Global changes take place automatically as EDIT scans the source file in forward direction. These commands automatically apply an A, B, or E command, as appropriate, to any occurrence of <string1> in a new current line. They also apply to the current line that is in effect when the command is given.

GA [qualifier] <string1> <string2>
GB [qualifier] <string1> <string2>
GE [qualifier] <string1> <string2>

For example, if you want to change DF0: to DF2: throughout an entire file, enter:

GE /DF0:/DF2:/

{| class="wikitable"
| Cancel a global command || CG [<id number>] || Cancels a global command. The identification number set with a GA, GB, or GE command is output to the verification file or the serene if EDIT is interactive. If no argument is specified, all global operations are cancelled. To cancel a specific operation, enter the identification number of the CG command.
|-
| Suspend a global command || SG [<id number>] || Suspends a global command. All global operations are suspended if no argument is given. Enter the identification number to suspend a specific operation.
|-
| Enable a global command || EG [<id number>] || Resumes global operation that had been suspended with the SG command. Unless a specific identification number is provided, all global commands are resumed.
|-
| Show global commands || SHG || Displays the current global commands and their identification numbers. Also provides the number of times each global string was matched.
|}

== Changing Command, Input, and Output Files ==

These commands change the files set up when you started EDIT from the Shell. These files are:

* the command file - started with the WITH option.
* the input file - the source file specified with FROM.
* the output file - the destination file specified with TO.

{| class="wikitable"
| Changing the Command File || C <filename> || Reads EDIT commands from a specified file. Delimit the file using a character other than a slash (/) since AmigaDOS uses these characters to separate file names. When all commands in the specified file are executed, the file is closed. You can then enter the commands through the keyboard.
|-
| Changing the Input File || FROM <filename> || Reads lines from another source file. EDIT does not close the original source file. Reselect the source file by entering the FROM command without an argument. For example of the FROM command, see page 4-54.
|-
| Closing a File || CF <filename> || Closes the destination file that was originally specified with the TO command. You can then open that file for input. CF can also close a new input file that is open. For examples of the CF command, see page 4-54.
|-
| Changing the Output File || TO <filename> || Specifies a different file as the destination file. The TO command writes the existing queue of output lines to the new TO file. The new TO file is used until another file is specified. Reselect the original destination file by using the TO command with no argument. The alternate output file remains open, but unused. For examples of the TO command, see page 4-54.
|-
| Stop executing the command file || Q || Stops EDIT from executing the current command file specified with the WITH keyword or with the C command. EDIT reverts to any previous command file. Using Q at the outermost level is equivalent to using the W command.
|}

The FROM, CF, and TO commands are used as follows:

{| class="wikitable"
! Command !! Action
|-
| M10 || Pass lines 1-9 in the original source file to the output queue.
|-
| FROM .XYZ. || Select the XYZ file for new input; line 10 of the original source file remains current.
|-
| M6 || Pass line 10 from the original file, then pass lines 1-5 from the XYZ file to the output queue. Line 6 of XYZ is the new current line.
|-
| FROM || Reselect the original source file.
|-
| M14 || Pass line 6 from XYZ, then lines 11-13 from the original source file to the output queue. Line 14 of the source file is the new current line.
|-
| FROM .XYZ. || Reselect file XYZ. Line 14 of the source file is still the current line.
|-
| M* || Pass line 14 of the source file and all remaining lines of file XYZ to the output queue. An extra line is added to the end of file XYZ. That line is the new current line.
|-
| FROM || Reselect the original source file. The extra line added to file XYZ is still the current line.
|-
| CF .XYZ. || Close file XYZ.
|-
| M* || Pass the remaining lines of the source file (lines 15 to the end of the file) to the output queue.
|-
| M11 || Pass lines 1-10 of the source file to the original destination file.
|-
| TO .XYZ. || Make XYZ the new output file.
|-
| M21 || Pass lines 11-20 to file XYZ.
|-
| TO M31 || Make the original destination file current, and pass lines 21 to 30 to it.
|-
| TO .XYZ. || Make XYZ the current output file.
|-
| M41 || Pass lines 31 to 40 to XYZ.
|-
| TO || Make the original destination file current.
|-
| TO .XYZ. || Send the output queue to file XYZ.
|-
| 1000N || Advance through the next 1000 lines of the source file.
|-
| TO || Select the original destination file.
|-
| CF .XYZ. || Close the XYZ file.
|-
| I2000 .XYZ. || Insert the 1000 lines from the source file that were sent to file XYZ back into the source file above line 2000.
|}

== Ending EDIT ==

These commands exit EDIT.

{| class="wikitable"
| Exit, saving changes || W || Exits EDIT, saving all changes to the destination file specified by TO. EDIT exits after reaching the end of the source, closing all the files, and relinquishing memory. If you started EDIT without specifying a destination file, it renames the temporary destination with the same name as the original source file, which is renamed. T/Edit-backup. This backup is only available until the next time you run EDIT.
|-
| Exit, without saving changes || STOP || Stops EDIT immediately without saving any changes to the source file. Prevents EDIT from overwriting to original source file, ensuring that no changes are made to the original input information.
|}

MediaWiki:Sidebar

2025-09-12T05:33:18Z

Costel Mincea:

* Navigation
** mainpage|mainpage-description
** recentchanges-url|recentchanges
* Developers
** Autodocs:Main|Autodocs
** Tutorials:Main|Tutorials
** DeveloperDoc:Registries|Registries
** DeveloperDoc:Standards|Standards
** DeveloperDoc:Main|Reference
** https://www.amigaos.net/viewforum.php?f=25|AmigaOS Support Forums
** https://os4coding.net/forum|OS4Coding Forum
** https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=30|Get the SDK
* Users
** AmigaOS_Manual:_Workbench|Workbench
** AmigaOS_Manual:_AmigaDOS|DOS
** AmigaOS_Manual:_ARexx|ARexx
** Bars_%26_Pipes_Professional|Bars & Pipes Professional
* Links
** https://www.hyperion-entertainment.com/|Hyperion Entertainment
** https://www.amigaos.net/|AmigaOS Web Site
** http://support.amigaos.net/|AmigaOS Support Forums
* SEARCH
* TOOLBOX

MediaWiki:Sidebar

2025-09-12T05:32:44Z

Costel Mincea:

* Navigation
** mainpage|mainpage-description
** recentchanges-url|recentchanges
* Developers
** Autodocs:Main|Autodocs
** Tutorials:Main|Tutorials
** DeveloperDoc:Registries|Registries
** DeveloperDoc:Standards|Standards
** DeveloperDoc:Main|Reference
** https://www.amigaos.net/viewforum.php?f=25|AmigaOS Support Forums (*)
** https://os4coding.net/forum|OS4Coding Forum (*)
** https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=30|Get the SDK (*)
* Users
** AmigaOS_Manual:_Workbench|Workbench
** AmigaOS_Manual:_AmigaDOS|DOS
** AmigaOS_Manual:_ARexx|ARexx
** Bars_%26_Pipes_Professional|Bars & Pipes Professional
* Links
** https://www.hyperion-entertainment.com/|Hyperion Entertainment (*)
** https://www.amigaos.net/|AmigaOS Web Site (*)
** http://support.amigaos.net/|AmigaOS Support Forums (*)
* (*) external
* SEARCH
* TOOLBOX

MediaWiki:Sidebar

2025-09-12T05:32:10Z

Costel Mincea:

* Navigation
** mainpage|mainpage-description
** recentchanges-url|recentchanges
* Developers
** Autodocs:Main|Autodocs
** Tutorials:Main|Tutorials
** DeveloperDoc:Registries|Registries
** DeveloperDoc:Standards|Standards
** DeveloperDoc:Main|Reference
** https://www.amigaos.net/viewforum.php?f=25|AmigaOS Support Forums (*)
** https://os4coding.net/forum|OS4Coding Forum (*)
** https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=30|Get the SDK (*)
* Users
** AmigaOS_Manual:_Workbench|Workbench
** AmigaOS_Manual:_AmigaDOS|DOS
** AmigaOS_Manual:_ARexx|ARexx
** Bars_%26_Pipes_Professional|Bars & Pipes Professional
* Links
** https://www.hyperion-entertainment.com/|Hyperion Entertainment*
** https://www.amigaos.net/|AmigaOS Web Site*
** http://support.amigaos.net/|AmigaOS Support Forums*
* SEARCH
* TOOLBOX

MediaWiki:Sidebar

2025-09-12T05:31:49Z

Costel Mincea:

* Navigation
** mainpage|mainpage-description
** recentchanges-url|recentchanges
* Developers
** Autodocs:Main|Autodocs
** Tutorials:Main|Tutorials
** DeveloperDoc:Registries|Registries
** DeveloperDoc:Standards|Standards
** DeveloperDoc:Main|Reference
** https://www.amigaos.net/viewforum.php?f=25|AmigaOS Support Forums[*]
** https://os4coding.net/forum|OS4Coding Forum[*]
** https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=30|Get the SDK[*]
* Users
** AmigaOS_Manual:_Workbench|Workbench
** AmigaOS_Manual:_AmigaDOS|DOS
** AmigaOS_Manual:_ARexx|ARexx
** Bars_%26_Pipes_Professional|Bars & Pipes Professional
* Links
** https://www.hyperion-entertainment.com/|Hyperion Entertainment*
** https://www.amigaos.net/|AmigaOS Web Site*
** http://support.amigaos.net/|AmigaOS Support Forums*
* SEARCH
* TOOLBOX

MediaWiki:Sidebar

2025-09-12T05:31:09Z

Costel Mincea:

* Navigation
** mainpage|mainpage-description
** recentchanges-url|recentchanges
* Developers
** Autodocs:Main|Autodocs
** Tutorials:Main|Tutorials
** DeveloperDoc:Registries|Registries
** DeveloperDoc:Standards|Standards
** DeveloperDoc:Main|Reference
** https://www.amigaos.net/viewforum.php?f=25|AmigaOS Support Forums*
** https://os4coding.net/forum|OS4Coding Forum*
** https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=30|Get the SDK*
* Users
** AmigaOS_Manual:_Workbench|Workbench
** AmigaOS_Manual:_AmigaDOS|DOS
** AmigaOS_Manual:_ARexx|ARexx
** Bars_%26_Pipes_Professional|Bars & Pipes Professional
* Links
** https://www.hyperion-entertainment.com/|Hyperion Entertainment*
** https://www.amigaos.net/|AmigaOS Web Site*
** http://support.amigaos.net/|AmigaOS Support Forums*
* SEARCH
* TOOLBOX

(*) external site

MediaWiki:Sidebar

2025-09-12T05:29:20Z

Costel Mincea:

* Navigation
** mainpage|mainpage-description
** recentchanges-url|recentchanges
* Developers
** Autodocs:Main|Autodocs
** Tutorials:Main|Tutorials
** DeveloperDoc:Registries|Registries
** DeveloperDoc:Standards|Standards
** DeveloperDoc:Main|Reference
** https://www.amigaos.net/viewforum.php?f=25|AmigaOS Support Forums (ext)
** https://os4coding.net/forum|OS4Coding Forum (ext)
** https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=30|Get the SDK (ext)
* Users
** AmigaOS_Manual:_Workbench|Workbench
** AmigaOS_Manual:_AmigaDOS|DOS
** AmigaOS_Manual:_ARexx|ARexx
** Bars_%26_Pipes_Professional|Bars & Pipes Professional
* Links
** https://www.hyperion-entertainment.com/|Hyperion Entertainment (ext)
** https://www.amigaos.net/|AmigaOS Web Site (ext)
** http://support.amigaos.net/|AmigaOS Support Forums (ext)
* SEARCH
* TOOLBOX

MediaWiki:Sidebar

2025-09-12T05:26:33Z

Costel Mincea:

* Navigation
** mainpage|mainpage-description
** recentchanges-url|recentchanges
* Developers
** Autodocs:Main|Autodocs
** Tutorials:Main|Tutorials
** DeveloperDoc:Registries|Registries
** DeveloperDoc:Standards|Standards
** DeveloperDoc:Main|Reference
** [https://www.amigaos.net/viewforum.php?f=25 AmigaOS Support Forums]
** [https://os4coding.net/forum OS4Coding Forum]
** [https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=30 SDK]
* Users
** AmigaOS_Manual:_Workbench|Workbench
** AmigaOS_Manual:_AmigaDOS|DOS
** AmigaOS_Manual:_ARexx|ARexx
** Bars_%26_Pipes_Professional|Bars & Pipes Professional
* Links
** [https://www.hyperion-entertainment.com/ Hyperion Entertainment]
** [https://www.amigaos.net/ AmigaOS Web Site]
** [http://support.amigaos.net/ AmigaOS Support Forums]
* SEARCH
* TOOLBOX

Writing Datatype Classes

2025-01-26T19:46:12Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= Subclassing =

For each of the DataType categories, there is a class that handles the data. Handlers for explicit data are subclasses under the appropriate class. For example, a class that handles ILBM pictures would be a subclass of the Picture class.

In order to fully understand the class concept used by DataTypes it helps to have a basic understanding of BOOPSI.

A subclass must provide an OM_NEW method that converts the source data into the data format required by the superclass. The subclass must optionally have a OM_DISPOSE method that discards any of the data constructed in the OM_NEW method. All other methods must be passed to the superclass.

Following is a listing of a example class dispatcher for a subclass of the picture class:

<syntaxhighlight lang="C" line>
uint32 Dispatch(Class *cl, Object *o, Msg msg)
{
struct ClassBase *cb = (struct ClassBase *) cl->cl_UserData;
uint32 retval;

switch (msg->MethodID)
{
case OM_NEW:
if (retval = IIntuition->IDoSuperMethodA(cl, o, msg))
{
/* Convert the source data to required data format */
if (!GetObjectData (cb, cl, (Object *)retval,
((struct opSet *) msg)->ops_AttrList))
{
/* Force disposal of the object */
IIntuition->ICoerceMethod (cl, (Object *) retval, OM_DISPOSE);
retval = NULL;
}
}
break;

/* Let the superclass handle everything else */
default:
retval = (uint32) IIntuition->IDoSuperMethodA (cl, o, msg);
break;
}

return (retval);
}
</syntaxhighlight>

== Obtaining a Handle to the Source Data ==

The first step that a class has to perform in order to convert the source data, is to get a handle on the data. This is obtained by passing the DTA_Handle tag to the superclass using the OM_GET method. For example:

<syntaxhighlight lang="C" line>
Object *o;
BPTR fh;

IDataTypes->GetDTAttrs(o, DTA_Handle, &fh, TAG_END);
</syntaxhighlight>

If the source Type is DTF_IFF, then DTA_Handle points to a struct IFFHandle that is already initialized and opened for reading, otherwise the handle points to a BPTR file handle.

== Handling Errors ==

Whenever an error occurs and the class is unable to continue converting the data, then it must set an appropriate error using the DOS SetIoErr() function and the <dos/dos.h> error codes or the error codes defined in <datatypes/datatypes.h>.

For example, if the class is unable to allocate memory:

<syntaxhighlight lang="C" line>
if (buf = IExec->AllocVecTags(size, AVT_ClearWithValue, 0, TAG_END))
{
... continue with conversion ...
}
else
{
IDOS->SetIoErr (ERROR_NO_FREE_STORE);
</syntaxhighlight>

== Data Format ==

The following sections outline the required data format for each of the main object types.

=== Picture Class ===

The picture class is the superclass for any static graphic classes. The structures and tags used by this class are defined in <datatypes/pictureclass.h>.

A picture subclass must fill out a BitMapHeader structure as well as provide a Mode ID, a BitMap and a ColorMap during the OM_NEW method of the class. There is no need to provide any other methods, as the remainder is handled by the picture class itself.

The picture subclass needs to fill in any fields of the BitMapHeader structure that the class has data for. This will ensure that the picture data can then be saved to a file or copied to the clipboard.

<syntaxhighlight lang="C" line>
struct BitMapHeader *bmh;

/* Obtain a pointer to the BitMapHeader structure from the picture class */
if (IDataTypes->GetDTAttrs (dto, PDTA_BitMapHeader, &bmh, TAG_END) && bmh)
{
/* Fill in some fields */
bmh->bmh_Width = 640;
bmh->bmh_Height = 200;
bmh->bmh_Depth = 2;
}
</syntaxhighlight>

Before manipulating any color information, the picture subclass must first tell the picture class how many colors it has, so that the information required for color remapping can be established.

<syntaxhighlight lang="C" line>
IDataTypes->SetDTAttrs (dto, PDTA_NumColors, ncolors, TAG_END);
</syntaxhighlight>

After the number of colors have been established, the palette information can be filled in for the picture. The following fragment illustrates filling in the palette information.

<syntaxhighlight lang="C" line>
struct ColorRegister *cmap;
int16 n, ncolors;
int32 *cregs;

/* Get a pointer to the color registers that need to be
* filled in */
IDataTypes->GetDTAttrs (dto,
PDTA_ColorRegisters, &cmap,
PDTA_CRegs, &cregs,
TAG_END);

/* Set the color information */
for (n = 0; n < ncolors; n++)
{
if (IDOS->Read (fh, &rgb, QSIZE) == QSIZE)
{
/* Set the master color table */
cmap->red = rgb.rgbRed;
cmap->green = rgb.rgbGreen;
cmap->blue = rgb.rgbBlue;
cmap++;

/* Set the color table used for remapping */
cregs[n * 3 + 0] = rgb.rgbRed << 24;
cregs[n * 3 + 1] = rgb.rgbGreen << 24;
cregs[n * 3 + 2] = rgb.rgbBlue << 24;
}
else
{
/* Indicate that we encountered an error. DOS Read
* will have already filled in the IoErr() value */
return FALSE;
}
}
</syntaxhighlight>

The picture class must get the actual picture information in standard Amiga bitmap format. If the bitmap is allocated using the graphics AllocBitMap() function, then the picture class can dispose of the bitmap at OM_DISPOSE time.

<syntaxhighlight lang="C" line>
struct BitMap *bm;

if (bm = IGraphics->AllocBitMap (bmh->bmh_Width, bmh->bmh_Height, bmh->bmh_Depth, BMF_CLEAR, NULL))
{
/* Tell the picture class about the picture data */
IDataTypes->SetDTAttrsA (dto, PDTA_BitMap, bm, TAG_END);
}
else
{
/* Indicate the error and that we encountered an error */
IDOS->SetIoErr (ERROR_NO_FREE_STORE);
return FALSE;
}
</syntaxhighlight>

A picture subclass needs to provide the following fields to the superclass, during the OM_NEW method:

{| class="wikitable"
| DTA_NominalHoriz || (int32) Set to the width of the picture.
|-
| DTA_NominalVert || (int32) Set to the height of the picture.
|-
| PDTA_ModeID || (uint32) A valid mode ID for the BitMap.
|-
| DTA_ObjName || (STRPTR) The name, or title, of the picture
|-
| DTA_ObjAuthor || (STRPTR) The author of the picture.
|-
| DTA_ObjAnnotation || (STRPTR) Notes on the picture.
|-
| DTA_ObjCopyright || (STRPTR) Copyright notice for the picture.
|-
| DTA_ObjVersion || (STRPTR) Version of the picture.
|}

If a picture subclass uses something other than AllocBitMap() to allocate the bitmap, then it must free the bitmap itself. This is done by implementing an OM_DISPOSE method for the subclass.

<syntaxhighlight lang="C" line>
uint32 Dispatch (Class *cl, Object *o, Msg msg)
{
struct ClassBase *cb = (struct ClassBase *) cl->cl_UserData;
struct localData *lod;
uint32 retval;

switch (msg->MethodID)
{
case OM_NEW:
/* ... */
break;

case OM_DISPOSE:
/* Get a pointer to our object data */
lod = INST_DATA (cl, o);

/* Tell the picture class that it doesn't have a
* bitmap to free any more */
IDataTypes->SetDTAttrs (o, PDTA_BitMap, NULL, TAG_END);

/* Free the bitmap ourself */
myfreebitmap (lod->lod_BitMap);

/* Let the superclass handle everything else */
default:
retval = (uint32) IIntuition->DoSuperMethodA (cl, o, msg);
break;
}

return retval;
}
</syntaxhighlight>

=== Sound Class ===

The sound class is the superclass for any sampled audio classes. The structures and tags used by this class are defined in
<datatypes/soundclass.h>.

A sound subclass needs to provide the following fields to the superclass, during the OM_NEW method:

{| class="wikitable"
| SDTA_Sample || (uint8 *) 8-bit sound data. The sound class will FreeVec() the sample data.
|-
| SDTA_SampleLength || (uint32) Number of 8-bit bytes in the sound data.
|-
| SDTA_Volume || (uint16) Number ranging from 0 being the quietest to 64 being the loudest.
|-
| SDTA_Period || (uint16) Amount of time to play the sound.
|-
| SDTA_Cycles || (uint16) Number of times to play the sound. 0 being an infinite loop.
|-
| DTA_ObjName || (STRPTR) The name, or title, of the sound
|-
| DTA_ObjAuthor || (STRPTR) The author of the sound.
|-
| DTA_ObjAnnotation || (STRPTR) Notes on the sound.
|-
| DTA_ObjCopyright || (STRPTR) Copyright notice for the sound.
|-
| DTA_ObjVersion || (STRPTR) Version of the sound.
|}

No methods other OM_NEW are need, as the remainder is handled by the sound class itself.

The sound subclass also needs to fill in any fields of the VoiceHeader structure that the class has data for. This will ensure that the sound data can then be saved to a file or copied to the clipboard.

<syntaxhighlight lang="C" line>
struct VoiceHeader *vh;

/* Obtain a pointer to the VoiceHeader structure from the sound class */
if (IDataTypes->GetDTAttrs (dto, SDTA_VoiceHeader, &vh, TAG_END) && vh)
{
/* Fill in some fields */
vh->vh_Octaves = 1;
vh->vh_Compression = 0;
vh->vh_Volume = 63;
}
</syntaxhighlight>

If a sound subclass uses something other than AllocVec() to allocate the sound data, then it must free the sample itself. This is done by implementing an OM_DISPOSE method for the subclass.

<syntaxhighlight lang="C" line>
uint32 Dispatch (Class *cl, Object *o, Msg msg)
{
struct ClassBase *cb = (struct ClassBase *) cl->cl_UserData;
struct localData *lod;
uint32 retval;

switch (msg->MethodID)
{
case OM_NEW:
/* ... */
break;

case OM_DISPOSE:
/* Get a pointer to our object data */
lod = INST_DATA (cl, o);

/* Tell the sound class that it doesn't have a
* sample to free any more */
IDataTypes->SetDTAttrs (o, SDTA_Sample, NULL, TAG_END);

/* Free the sample ourself */
IExec->FreeVec(lod->lod_Sample);

/* Let the superclass handle everything else */
default:
retval = (uint32) IIntuition->IDoSuperMethodA (cl, o, msg);
break;
}

return retval;
}
</syntaxhighlight>

=== Text Class ===

The text class is the superclass for any formatted or non-formatted text classes. The structures and tags used by this class are defined in <datatypes/textclass.h>.

The text class provides the subclass with a buffer that contains the text data. The subclass must then provide the text class with a list of Line segments during the layout method. This Line list should only be created at gpl_Initial time, unless the TDTA_WordWrap attribute is TRUE.

<syntaxhighlight lang="C" line>
struct Line
{
struct MinNode ln_Link;
STRPTR ln_Text;
ULONG ln_TextLen;
UWORD ln_XOffset;
UWORD ln_YOffset;
UWORD ln_Width;
UWORD ln_Height;
UWORD ln_Flags;
BYTE ln_FgPen;
BYTE ln_BgPen;
ULONG ln_Style;
APTR ln_Data;
};
</syntaxhighlight>

The Line structure fields are as follows:

;ln_Link
: MinNode used to link to the line list.

; ln_Text
: Pointer to the text for this line segment.

; ln_TextLen
: Number of bytes of text in this line segment.

; ln_XOffset
: Left pixel offset from the left edge of the object for this line segment.

; ln_YOffset
: Top pixel offset from the top edge of the object for this line segment.

; ln_Width
: Width of the line segment in pixels.

; ln_Height
: Height of the line segment in pixels.

; ln_Flags
: Control flags for this line segment.
:: LNF_LF -- Used to indicate that this segment is the end of a line.

; ln_FgPen
: Pen to use for the foreground (the text color) for this line segment.

; ln_BgPen
: Pen to use for the background color for this line segment.

; ln_Style
: Text attribute soft style to use for this line segment.

As each Line segment is allocated it must be added to the Line list.

<syntaxhighlight lang="C" line>
struct List *linelist;
struct Line *line;

/* Get a pointer to the line list */
if (IDataTypes->GetDTAttrs (o, TDTA_LineList, (uint32) &linelist, TAG_END) && linelist)
{
/* Create a Line segment */
if (line = AllocVecTags(sizeof (struct Line), AVT_ClearWithValue, 0, TAG_END))
{
/* Add it to the list */
IExec->AddTail (linelist, (struct Node *)&line->ln_Link);
}
}
</syntaxhighlight>

Currently, this is the hardest class to subclass, due to the number of methods that must be implemented. Following is the shell for a dispatcher and the layout method for a text subclass.

<syntaxhighlight lang="C" line>
struct localData
{
VOID *lod_Pool;
uint32 lod_Flags;
};

uint32 Dispatch (Class * cl, Object * o, Msg msg)
{
struct ClassBase *cb = (struct ClassBase *) cl->cl_UserData;
struct localData *lod;
struct List *linelist;
uint32G retval = 0;

switch (msg->MethodID)
{
case OM_NEW:
if (retval = IIntuition->IDoSuperMethodA (cl, o, msg))
{
uint32 len, estlines, poolsize;
BOOL success = FALSE;
STRPTR buffer;

/* Get a pointer to the object data */
lod = INST_DATA (cl, (Object *) retval);

/* Get the attributes that we need to determine memory pool size */
IDataTypes->GetDTAttrs ((Object *) retval,
TDTA_Buffer, &buffer,
TDTA_BufferLen, &len,
TAG_END);

/* Make sure we have a text buffer */
if (buffer && len)
{
/* Estimate the pool size that we will need */
estlines = (len / 80) + 1;
estlines = (estlines > 200) ? 200 : estlines;
poolsize = sizeof (struct Line) * estlines;

/* Create a memory pool for the line list */
lod->lod_Pool = IExec->AllocSysObjectTags(ASOT_MEMPOOL,
ASOPOOL_MFlags, MEMF_SHARED | MEMF_CLEAR,
ASOPOOL_Puddle, poolsize,
ASOPOOL_Threshold, poolsize,
TAG_END);
if (lod->lod_Pool != NULL)
success = TRUE;
else
IDOS->SetIoErr (ERROR_NO_FREE_STORE);
}
else
{
/* Indicate that something was missing that we needed */
IDOS->SetIoErr (ERROR_REQUIRED_ARG_MISSING);
}

if (!success)
{
IIntuition->ICoerceMethod (cl, (Object *) retval, OM_DISPOSE);
retval = NULL;
}
}
break;

case OM_UPDATE:
case OM_SET:
/* Pass the attributes to the text class and force a refresh if we need it */
if ((retval = IIntuition->IDoSuperMethodA (cl, o, msg)) && (OCLASS (o) == cl))
{
struct RastPort *rp;

/* Get a pointer to the rastport */
if (rp = IGraphics->ObtainGIRPort (((struct opSet *) msg)->ops_GInfo))
{
IIntuition->DoRender(o, ((struct opSet *) msg)->ops_GInfo, GREDRAW_UPDATE);

/* Release the temporary rastport */
IGraphics->ReleaseGIRPort (rp);
}
retval = 0;
}
break;

case GM_LAYOUT:
/* Tell everyone that we are busy doing things */
notifyAttrChanges (o, ((struct gpLayout *) msg)->gpl_GInfo, NULL,
GA_ID, G(o)->GadgetID,
DTA_Busy, TRUE,
TAG_END);

/* Let the superclass partake */
retval = (uint32) IIntuition->IDoSuperMethodA (cl, o, msg);

/* We need to do this one asynchronously */
retval += IDataTypes->DoAsyncLayout (o, (struct gpLayout *) msg);
break;

case DTM_PROCLAYOUT:
/* Tell everyone that we are busy doing things */
notifyAttrChanges (o, ((struct gpLayout *) msg)->gpl_GInfo, NULL,
GA_ID, G(o)->GadgetID,
DTA_Busy, TRUE,
TAG_END);

/* Let the superclass partake and then fall through to our layout method */
retval = (uint32) IDataTypes->DoSuperMethodA (cl, o, msg);

case DTM_ASYNCLAYOUT:
/* Layout the text */
retval = layoutMethod (cb, cl, o, (struct gpLayout *) msg);
break;

case OM_DISPOSE:
/* Get a pointer to our object data */
lod = INST_DATA (cl, o);

/* Don't let the super class free the line list */
if (IIntuition->GetDTAttrs (o, TDTA_LineList, &linelist, TAG_END) && linelist)
IExec->NewList (linelist);

/* Delete the line pool */
IExec->FreeSysObject(ASOT_MEMPOOL, lod->lod_Pool);

/* Let the superclass handle everything else */
default:
retval = (uint32) IIntuition->DoSuperMethodA (cl, o, msg);
break;
}

return (retval);
}

uint32 layoutMethod (struct ClassBase *cb, Class * cl, Object * o, struct gpLayout * gpl)
{
struct DTSpecialInfo *si = (struct DTSpecialInfo *) G (o)->SpecialInfo;
struct localData *lod = INST_DATA (cl, o);
uint32 visible = 0, total = 0;
struct RastPort trp;
uint32 hunit = 1;
uint32 bsig = 0;

/* Switches */
BOOL linefeed = FALSE;
BOOL newseg = FALSE;
BOOL abort = FALSE;

/* Attributes obtained from superclass */
struct TextAttr *tattr;
struct TextFont *font;
struct List *linelist;
struct IBox *domain;
uint32 wrap = FALSE;
uint32 bufferlen;
STRPTR buffer;
STRPTR title;

/* Line information */
uint32 num, offset, swidth;
uint32 anchor, newanchor;
uint32 style = FS_NORMAL;
struct Line *line;
uint32 yoffset = 0;
uint8 fgpen = 1;
uint8 bgpen = 0;
uint32 tabspace;
uint32 numtabs;
uint32 i, j;

uint32 nomwidth, nomheight;

/* Get all the attributes that we are going to need for a successful layout */
if (IDataTypes->GetDTAttrs (o,
DTA_TextAttr, &tattr,
DTA_TextFont, &font,
DTA_Domain, &domain,
DTA_ObjName, &title,
TDTA_Buffer, &buffer,
TDTA_BufferLen,&bufferlen,
TDTA_LineList, &linelist,
TDTA_WordWrap, &wrap,
TAG_END) == 8)
{
/* Lock the global object data so that nobody else can manipulate it */
IExec->ObtainSemaphore (&(si->si_Lock));

/* Make sure we have a buffer */
if (buffer)
{
/* Initialize the temporary RastPort */
IGraphics->InitRastPort (&trp);
IGraphics->SetFont (&trp, font);

/* Calculate the nominal size */
nomheight = (ULONG) (24 * font->tf_YSize);
nomwidth = (ULONG) (80 * font->tf_XSize);

/* Calculate the tab space */
tabspace = font->tf_XSize * 8;

/* We only need to perform layout if we are doing word wrap, or this
* is the initial layout call */
if (wrap || gpl->gpl_Initial)
{
/* Delete the old line list */
while (line = (struct Line *) IExec->RemHead (linelist))
IExec->FreePooled (lod->lod_Pool, line, sizeof (struct Line));

/* Step through the text buffer */
for (i = offset = num = numtabs = 0;
(i <= bufferlen) && (bsig == 0) && !abort;
i++)
{
/* Check for end of line */
if (buffer[i]==13 && buffer[i+1]==10)
{
newseg = linefeed = TRUE;
newanchor = i + 2;
i++;
}
/* Check for end of page */
else if (buffer[i] == 12)
{
newseg = linefeed = TRUE;
newanchor = i + 1;
}
/* Check for tab */
else if (buffer[i] == 9)
{
/* See if we need to terminate a line segment */
if ((numtabs == 0) && num)
newseg = TRUE;
numtabs++;
}
else
{
/* See if we have any TABs that we need to finish out */
if (numtabs)
{
offset += (((offset / tabspace) + 1) * tabspace) - offset;
num = numtabs = 0;
anchor = i;
}

/* Compute the width of the line. */
swidth = IGraphics->TextLength (&trp, &buffer[anchor], num+1);
if (offset + swidth > domain->Width)
{
/* Search for a whitespace character */
for (j = i; (j >= anchor) && !newseg; j--)
{
if (buffer[j] == ' ')
{
num -= (i - j);
newseg = TRUE;
i = j + 1;
}
}

newseg = linefeed = TRUE;
newanchor = i;
i--;
}
else
{
num++;
}
}

/* Time for a new text segment yet? */
if (newseg)
{
/* Allocate a new line segment from our memory pool */
if (line = IExec->AllocPooled (lod->lod_Pool, sizeof (struct Line)))
{
swidth = IGraphics->TextLength (&trp, &buffer[anchor], num);
line->ln_Text = &buffer[anchor];
line->ln_TextLen = num;
line->ln_XOffset = offset;
line->ln_YOffset = yoffset + font->tf_Baseline;
line->ln_Width = swidth;
line->ln_Height = font->tf_YSize;
line->ln_Flags = (linefeed) ? LNF_LF : NULL;
line->ln_FgPen = fgpen;
line->ln_BgPen = bgpen;
line->ln_Style = style;
line->ln_Data = NULL;

/* Add the line to the list */
IExec->AddTail (linelist, (struct Node *) line);

/* Increment the line count */
if (linefeed)
{
yoffset += font->tf_YSize;
offset = 0;
total++;
}
else
{
/* Increment the offset */
offset += swidth;
}
}
else
{
abort = TRUE;
}

/* Clear the variables */
newseg = linefeed = FALSE;
anchor = newanchor;
num = 0;

/* Check to see if layout has been aborted */
bsig = IDOS->CheckSignal (SIGBREAKF_CTRL_C);
}
}
}
else
{
/* No layout to perform */
total = si->si_TotVert;
}
}

/* Compute the lines and columns type information */
si->si_VertUnit = font->tf_YSize;
si->si_VisVert = visible = domain->Height / si->si_VertUnit;
si->si_TotVert = total;

si->si_HorizUnit = hunit = 1;
si->si_VisHoriz = (int32) domain->Width / hunit;
si->si_TotHoriz = domain->Width;

/* Release the global data lock */
IExec->ReleaseSemaphore (&si->si_Lock);

/* Were we aborted? */
if (bsig == 0)
{
/* Not aborted, so tell the world of our newest attributes */
notifyAttrChanges (o, gpl->gpl_GInfo, NULL,
GA_ID, G(o)->GadgetID,

DTA_VisibleVert, visible,
DTA_TotalVert, total,
DTA_NominalVert, nomheight,
DTA_VertUnit, font->tf_YSize,

DTA_VisibleHoriz, (uint32) (domain->Width / hunit),
DTA_TotalHoriz, domain->Width,
DTA_NominalHoriz, nomwidth,
DTA_HorizUnit, hunit,

DTA_Title, title,
DTA_Busy, FALSE,
DTA_Sync, TRUE,
TAG_END);
}
}

return total;
}
</syntaxhighlight>

= Writing a Superclass =

(relevant text to be provided)

= Defining a DataType Descriptor =

DataTypes uses a simple descriptor to determine what type of data a file contains and what class, if any, is used to handle that data.

The DTDesc utility is used to define a DataType descriptor. The following steps describe how to use this utility to define a descriptor.

1. Load several sample files of the type being defined. This can be done by dropping their icons into the DTDesc window or by using the "Extras/Load Samples..." menu item.

2. The view area in the bottom right side of the DTDesc window will show the first 64 characters of the files. This area is used to define the Mask. The characters that don't match will be blotted out and only the similar characters will be shown. If more characters are shown as similar than really are, then they can easily be blotted out by rubbing over them.

3. DataTypes can be broken out into several different categories. Use the Group menu to select the category that the DataType descriptor belongs in.

4. The remaining fields must be filled out. Following is a table describing the fields and the information they require.

:{| class="wikitable"
! Name !! Description
|-
| File Type || User description of the DataType.
|-
| Base Name || The base name of the DataType. The class library name is derived from this.
|-
| Name Pattern || The name of the file can be used to indicate the DataType. AmigaDOS wildcards can be used to specify the file name.
|-
| Function || A function can be used to further define a data type. This function must be a stand-alone executable that uses the DataType Descriptor Function Interface.
|-
| Case Sensitive? || The Mask can be either case sensitive or not.
|-
| Priority || Descriptors are sorted by Type, Function, Name Pattern and Mask. The priority field allows a DataType descriptor to be assigned a different priority than a similar DataType descriptor.
|-
| Type || This is a read-only field and is used to indicate what basic type a DataType is. Types include IFF, Binary and ASCII.
|}

5. Once a DataType descriptor has been defined, it must be saved. Select the "Project/Save As..." menu item for the file requester used to save a DataType descriptor. The default name for a DataType descriptor is the text entered into File Type field.

6. In order for a new DataType descriptor to be loaded, the datatypes.library must be flushed from the system. This can either be done with the [[SDK_Developer_Tools#Expunge|Expunge]] command included in the SDK. Another way that the new DataType descriptor can be loaded is by using the AddDataTypes command with the REFRESH option.

== DataType Descriptor Function Interface ==

Sometimes the fields within the DTDesc utility are not enough to define a DataType descriptor. In this case it is necessary to use a Function to
further narrow down a DataType.

A Function is a stand-alone executable that expects the following arguments.

<syntaxhighlight lang="C" line>
BOOL retval = Function(struct DTHookContext *dthc);
</syntaxhighlight>

The function must return TRUE if the data matches, FALSE if it doesn't.

The DTHookContext structure contains the fields that are necessary for narrowing down the DataType. Following is a listing of the DTHookContext
structure.

<syntaxhighlight lang="C" line>
struct DTHookContext
{
struct Library *dthc_SysBase;
struct Library *dthc_DOSBase;
struct Library *dthc_IFFParseBase;
struct Library *dthc_UtilityBase;

/* File context */
BPTR dthc_Lock; /* Lock on the file */
struct FileInfoBlock *dthc_FIB; /* Pointer to a FileInfoBlock */
BPTR dthc_FileHandle; /* Pointer to the file handle (may be NULL) */
struct IFFHandle *dthc_IFF; /* Pointer to an IFFHandle (may be NULL) */
STRPTR dthc_Buffer; /* Buffer */
ULONG dthc_BufferLength; /* Length of the buffer */

ULONG dthc_Length; /* size of this structure */
struct ExecIFace * dthc_IExec;
struct DOSIFace * dthc_IDOS;
struct IFFParseIFace * dthc_IIFFParse;
struct UtilityIFace * dthc_IUtility;
};
</syntaxhighlight>

The DTHookContext structure fields are as follows:

; dthc_SysBase
; dthc_DOSBase
; dthc_IFFParseBase
; dthc_UtilityBase
: These are library bases that your function can utilize. It will need to open any other libraries that it needs.

; dthc_Lock
: If the source data is a DOS file, then this is a lock on the file.

; dthc_FIB
: If the source data is a DOS file, then this is a filled in FileInfoBlock for the file.

; dthc_FileHandle
: If the source data is a DOS file, then this is the file handle for the file otherwise the handle will be NULL. The file is guaranteed to be at the beginning.

; dthc_IFF
: If the source data is IFF, then this is the IFFHandle for accessing the data, otherwise the handle will be NULL. The position is guaranteed to be at the beginning of the data. The DOS file fields must not be accessed if the data is IFF.

; dthc_Buffer
: This buffer contains the first dthc_BufferLength bytes of data.

; dthc_BufferLength
: Indicates the number of bytes in dthc_Buffer, up to 64.

; dthc_Length
: Size in bytes of struct DTHookContext

; dthc_IExec
; dthc_IDOS
; dthc_IIFFParse
; dthc_IUtility
: These are interface pointers that your function can utilize.

The following example shows how to write a simple DataTypes Descriptor Function.

<syntaxhighlight lang="C" line>
/* This example must not be linked with any startup code so that
* DTHook is the entry point for the executable.
*
*/
#include <exec/types.h>
#include <dos/dos.h>
#include <dos/dosextens.h>
#include <datatypes/datatypes.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/utility.h>

BOOL DTHook (struct DTHookContext * dthc)
{
BOOL retval = FALSE;
uint32 i;
uint8 ch;

/* Make sure we have a buffer */
if (dthc->dthc_Buffer)
{
for (i = 0; (i < dthc->dthc_BufferLength) && !retval; i++)
{
ch = dthc->dthc_Buffer[i];

/* Look at the data... */
}
}
return retval;
}
</syntaxhighlight>

The next example shows how to write a DataTypes Descriptor that looks into an IFF file for needed chunk information.

<syntaxhighlight lang="C" line>
/* This example must not be linked with any startup code
* so that DTHook is the entry point for the executable.
*/
#include <exec/types.h>
#include <dos/dos.h>
#include <dos/dosextens.h>
#include <datatypes/datatypes.h>
#include <datatypes/pictureclass.h>
#include <libraries/iffparse.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/iffparse.h>
#include <proto/utility.h>

#define BMH_SIZE (sizeof (struct BitMapHeader))

BOOL DTHook(struct DTHookContext * dthc)
{
struct BitMapHeader bmh;
struct ContextNode *cn;
struct IFFHandle *iff;
BOOL retval = FALSE;

/* Make sure that this is an IFF data type */
if (iff = dthc->dthc_IFF)

/* Stop on the BitMapHeader (type, id) */
if (dthc->dthc_IIFFParse->StopChunk (iff, ID_ILBM, ID_BMHD) == 0)

/* Scan through the IFF handle */
if (dthc->dthc_IIFFParse->ParseIFF (iff, IFFPARSE_SCAN) == 0L)

/* Make sure we have a current chunk */
if (cn = dthc->dthc_IIFFParse->CurrentChunk (iff))

/* Make sure the current chunk is ILBM BMHD */
if ((cn->cn_Type == ID_ILBM) && (cn->cn_ID == ID_BMHD))

/* Read the chunk data */
if (dthc->dthc_IIFFParse->ReadChunkBytes (iff, &bmh, BMH_SIZE) == BMH_SIZE)

/* See if the depth is set to 24 */
if (bmh.bmh_Depth == 24)
retval = TRUE;

return (retval);
}
</syntaxhighlight>

Exec Messages and Ports

2025-01-26T19:40:03Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

== Exec Messages and Ports ==

For inter-process communication, Exec provides a consistent, high-performance mechanism of messages and ports. This mechanism is used to pass message structures of arbitrary sizes from task to task, interrupt to task, or task to software interrupt. In addition, messages are often used to coordinate operations between cooperating tasks. This section describes many of the details of using messages and ports that the casual Amiga programmer won't need. See [[Introduction_to_Exec|Introduction to Exec]] for a general introduction to using messages and ports.

A ''message'' data structure has two parts: system linkage and message body. The system linkage is used by Exec to attach a given message to its destination. The message body contains the actual data of interest. The message body is any arbitrary data up to 64K bytes in size. The message body data can include pointers to other data blocks of any size.

Messages are always sent to a predetermined destination ''port''. At a port, incoming messages are queued in a first-in-first-out (FIFO) order. There are no system restrictions on the number of ports or the number of messages that may be queued to a port (other than the amount of available system memory).

Messages are always queued by ''reference'', i.e., by a pointer to the message. For performance reasons message copying is not performed. In essence, a message between two tasks is a temporary license for the receiving task to use a portion of the memory space of the sending task; that portion being the message itself. This means that if task A sends a message to task B, the message is still part of the task A context. Task A, however, should not access the message until it has been ''replied''; that is, until task B has sent the message back, using the ReplyMsg() function. This technique of message exchange imposes important restrictions on message access.

== Message Ports ==

Message ports are rendezvous points at which messages are collected. A port may contain any number of outstanding messages from many different originators. When a message arrives at a port, the message is appended to the end of the list of messages for that port, and a pre-specified arrival action is invoked. This action may do nothing, or it may cause a predefined task signal or software interrupt (see [[Exec_Interrupts|Exec Interrupts]]).

Like many Exec structures, ports may be given a symbolic name. Such names are particularly useful for tasks that must rendezvous with dynamically created ports. They are also useful for debugging purposes.

A message port consists of a MsgPort structure as defined in the <exec/ports.h> and <exec/ports.i> include files. The C structure for a port is as follows:

<syntaxhighlight lang="C" line>
struct MsgPort {
struct Node mp_Node;
UBYTE mp_Flags;
UBYTE mp_SigBit;
struct Task *mp_SigTask;
struct List mp_MsgList;
};
</syntaxhighlight>

; mp_Node
: is a standard Node structure. This is useful for tasks that might want to rendezvous with a particular message port by name.

; mp_FLags
: are used to indicate message arrival actions. See the explanation below.

; mp_SigBit
: is the signal bit ''number'' when a port is used with the task signal arrival action.

; mp_SigTask
: is a pointer to the task to be signaled. If a software interrupt arrival action is specified, this is a pointer to the interrupt structure.

; mp_MsgList
: is the list header for all messages queued to this port. (See [[Exec_Lists_and_Queues|Exec Lists and Queues]]).

The mp_Flags field contains a subfield indicated by the PF_ACTION mask. This sub-field specifies the message arrival action that occurs when a port receives a new message.

The possibilities are as follows:

; PA_SIGNAL
: This flag tells Exec to signal the mp_SigTask using signal number mp_SigBit on the arrival of a new message. Every time a message is put to the port another signal will occur regardless of how many messages have been queued to the port.

; PA_SOFTINT
: This flag tells Exec to Cause() a software interrupt when a message arrives at the port. In this case, the mp_SigTask field must contain a pointer to a struct Interrupt rather than a Task pointer. The software interrupt will be Caused every time a message is received.

; PA_IGNORE
: This flag tells Exec to perform no operation other than queuing the message. This action is often used to stop signaling or software interrupts without disturbing the contents of the mp_SigTask field.

It is important to realize that a port's arrival action will occur for each new message queued, and that there is not a one-to-one correspondence between messages and signals. Task signals are only single-bit flags so there is no record of how many times a particular signal occurred. There may be many messages queued and only a single task signal; sometimes however there may be a signal, but no messages. All of this has certain implications when designing code that deals with these actions. Your code should not depend on receiving a signal for every message at your port. All of this is also true for software interrupts.

=== Creating a Message Port ===

To create a new message port use AllocSysObject() with an object type of ASOT_PORT. If you want to make the port ''public'', you will need to use the ASOPORT_Name tag. Don't make a port public when it is not necessary for it to be so.

Prior to V50 of the operating system, functions such as CreatePort() and CreateMsgPort() were often used. Some older applications may even have created their own static message ports by hand. Although all of the older methods still function for backwards compatibility, they should no longer be used.

Using dynamic message ports with ASOT_PORT is the only way to ensure your applications will remain compatible and its message ports automatically freed by the system when required.

=== Deleting a Message Port ===

Before a message port is deleted, all outstanding messages from other tasks must be returned. This is done by getting and replying to all messages at the port until message queue is empty. Of course, there is no need to reply to messages owned by the current task (the task performing the port deletion). Public ports must be removed from the system properly before deallocation. If a signal was allocated for the message port, it must also be freed. FreeSysObject() handles all of this automatically.

Prior to V50 of the operating system, message ports must be freed using the correct corresponding function such as DeletePort() or DeleteMsgPort(). The FreeSysObject() function must only be used on ports which were allocated with AllocSysObject().

=== How to Rendezvous at a Message Port ===

The FindPort() function provides a means of finding the address of a public port given its symbolic name. For example, FindPort("Griffin") will return either the address of the message port named "Griffin" or NULL indicating that no such public port exists. Since FindPort() does not do any arbitration over access to public ports, the usage of FindPort() must be protected with Forbid()/Permit(). Names should be unique to prevent collisions among multiple applications. It is a good idea to use your application name as a prefix for your port name. FindPort() does not arbitrate for access to the port list. The owner of a port might remove it at any time. For these reasons a Forbid()/Permit() pair is required for the use of FindPort(). The port address can no longer be regarded as being valid after Permit() unless your application knows that the port cannot go away (for example, if your application created the port).

The following is an example of how to safely put a message to a specific port:

<syntaxhighlight lang="C" line>
#include <exec/types.h>
#include <exec/ports.h>

BOOL SafePutToPort(struct Message *message, CONST_STRPTR portname)
{
IExec->Forbid();

struct MsgPort *port = IExec->FindPort(portname);
if (port != NULL)
IExec->PutMsg(port,message);

IExec->Permit();

return(port ? TRUE : FALSE); /* If FALSE, the port was not found */

/* Once we've done a Permit(), the port might go away and leave us with
an invalid port address. So we return just a BOOL to indicate whether
the message has been sent or not. */
}
</syntaxhighlight>

== Messages ==

As mentioned earlier, a message contains both system header information and the actual message content. The system header is of the Message form defined in <exec/ports.h>. This structure is as follows:

<syntaxhighlight lang="C" line>
struct Message {
struct Node mn_Node;
struct MsgPort *mn_ReplyPort;
UWORD mn_Length;
};
</syntaxhighlight>

; mn_Node
: is a standard Node structure used for port linkage.

; mn_ReplyPort
: is used to indicate a port to which this message will be returned when a reply is necessary.

; mn_Length
: indicates the total length of the message, including the Message structure itself.

This structure is always attached to the head of all messages. For example, if you want a message structure that contains the ''x'' and ''y'' coordinates of a point on the screen, you could define it as follows:

<syntaxhighlight lang="C" line>
struct XYMessage {
struct Message xy_Msg;
UWORD xy_X;
UWORD xy_Y;
}
</syntaxhighlight>

For this structure, the mn_Length field should be set to sizeof(struct XYMessage).

=== Creating a Message ===

Messages are allocated using AllocSysObject() with an object type of ASOT_MESSAGE. The ASOMSG_ReplyPort tag is set to the reply port if desired. Some messages may be sent in one direction in which case the ASOMSG_ReplyPort tag is not used. The size of the message is indicated with ASOMSG_Length and includes the size of the payload.

<syntaxhighlight lang="C" line>
struct XYMessage xymsg = IExec->AllocSysObjectTags(ASOT_MESSAGE,
ASOMSG_Size, sizeof(struct XYMessage),
ASOMSG_ReplyPort, replyPort,
TAG_END);
</syntaxhighlight>

=== Deleting a Message ===

Messages are freed using FreeSysObject(). Programmers should be careful not to free a message which is still in use or queues in a message port.

=== Putting a Message ===

A message is delivered to a given destination port with the PutMsg() function. The message is queued to the port, and that port's arrival action is invoked. If the action specifies a task signal or a software interrupt, the originating task may temporarily lose the processor while the destination processes the message. If a reply to the message is required, the mn_ReplyPort field must be set up prior to the call to PutMsg().

Here is a code fragment for putting a message to a public port. A complete example is at the end of the article.

<syntaxhighlight lang="C" line>
#include <exec/types.h>
#include <exec/memory.h>
#include <exec/ports.h>
#include <libraries/dos.h>

BOOL SafePutToPort(struct Message *, CONST_STRPTR);

struct XYMessage {
struct Message xy_Msg;
uint16 xy_X;
uint16 xy_Y;
};

int main()
{
struct MsgPort *xyport, *xyreplyport;
struct XYMessage *msg;
BOOL foundport;

/* Allocate the message we're going to send. */
struct XYMessage *xymsg = IExec->AllocSysObjectTags(ASOT_MESSAGE,
ASOMSG_Size, sizeof(struct XYMessage),
TAG_END);

if (xymsg != NULL)
{
/* The replyport we'll use to get response */
if (xyreplyport = IExec->AllocSysObject(ASOT_PORT, NULL)) {

xymsg->xy_Msg.mn_ReplyPort = xyreplyport;
xymsg->xy_X = 10;
xymsg->xy_Y = 20;

/* Now try to send that message to a public port named "xyport".
* If foundport eq 0, the port isn't out there.
*/
if (foundport = SafePutToPort((struct Message *)xymsg, "xyport"))
{

. . . /* Now let's wait till the someone responds... */

}
else IDOS->Printf("Couldn't find 'xyport'\n");

IExec->FreeSysObject(ASOT_PORT, xyreplyport);
else IDOS->Printf("Couldn't create message port\n");

IExec->FreeSysObject(ASOT_MESSAGE, xymsg);
}
else IDOS->Printf("Couldn't get memory for xymessage\n");

return 0;
}
</syntaxhighlight>

=== Waiting for a Message ===

A task may go to sleep waiting for a message to arrive at one or more ports. This technique is widely used on the Amiga as a general form of event notification. For example, it is used extensively by tasks for I/O request completion.

The MsgPort.mp_SigTask field contains the address of the task to be signaled and mp_SigBit contains a preallocated signal number (as described in [[Exec_Tasks|Exec Tasks]]).

You can call the WaitPort() function to wait for a message to arrive at a port. This function will return the first message (it may not be the only) queued to a port. Note that your application must still call GetMsg() to remove the message from the port. If the port is empty, your task will go to sleep waiting for the first message. If the port is not empty, your task will not go to sleep. It is possible to receive a signal for a port without a message being present yet. The code processing the messages should be able to handle this. The following code illustrates WaitPort().

<syntaxhighlight lang="C" line>
struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "xyport",
TAG_END);

if (xyport == NULL)
{
IDOS->Printf("Couldn't create xyport\n");
return RETURN_FAIL;
}

struct XYMessage *xy_msg = IExec->WaitPort(xyport); /* go to sleep until message arrives */
</syntaxhighlight>

A more general form of waiting for a message involves the use of the Wait() function (see [[Exec_Signals|Exec Signals]]). This function waits for task event signals directly. If the signal assigned to the message port occurs, the task will awaken. Using the Wait() function is more general because you can wait for more than one signal. By combining the signal bits from each port into one mask for the Wait() function, a loop can be set up to process all messages at all ports.

Here's an example using Wait():

<syntaxhighlight lang="C" line>
struct XYMessage *xy_msg;
BOOL ABORT = FALSE;

struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "xyport",
TAG_END);

if (xyport != NULL)
{
uint32 portsig = 1 << xyport->mp_SigBit;
uint32 usersig = SIGBREAKF_CTRL_C; /* User can break with CTRL-C. */
for (;;)
{
uint32 signal = IExec->Wait(portsig | usersig); /* Sleep till someone signals. */

if (signal & portsig) /* Got a signal at the msgport. */
{ . . .
}
if (signal & usersig) /* Got a signal from the user. */
{
ABORT = TRUE; /* Time to clean up. */
. . .
}
if (ABORT) break;
}
IExec->FreeSysObject(ASOT_PORT, xyport);
}
else IDOS->Printf("Couldn't create xyport\n");
</syntaxhighlight>

{{Note|text=WaitPort() only returns a pointer to the first message in a port. It does not actually remove the message from the port queue.|title=WaitPort() Does Not Remove A Message}}

=== Getting a Message ===

Messages are usually removed from ports with the GetMsg() function. This function removes the next message at the head of the port queue and returns a pointer to it. If there are no messages in a port, this function returns a zero.

The example below illustrates the use of GetMsg() to print the contents of all messages in a port:

<syntaxhighlight lang="C" line>
while (xymsg = IExec->GetMsg(xyport))
IDOS->Printf("x=%ld y=%ld\n", xymsg->xy_X, xymsg->xy_Y);
</syntaxhighlight>

Certain messages may be more important than others. Because ports impose FIFO ordering, these important messages may get queued behind other messages regardless of their priority. If it is necessary to recognize more important messages, it is easiest to create another port for these special messages.

=== Replying ===

When the operations associated with receiving a new message are finished, it is usually necessary to send the message back to the originator. The receiver replies the message by returning it to the originator using the ReplyMsg() function. This is important because it notifies the originator that the message can be reused or deallocated.

The ReplyMsg() function serves this purpose. It returns the message to the port specified in the mn_ReplyPort field of the message. If this field is zero, no reply is returned.

The previous example can be enhanced to reply to each of its messages:

<syntaxhighlight lang="C" line>
while (xymsg = IExec->GetMsg(xyport)) {
IDOS->Printf("x=%ld y=%ld\n", xymsg->xy_X, xymsg->xy_Y);
IExec->ReplyMsg(xymsg);
}
</syntaxhighlight>

Notice that the reply does not occur until ''after'' the message values have been used.

Often the operations associated with receiving a message involve returning ''results'' to the originator. Typically this is done within the message itself. The receiver places the results in fields defined (or perhaps reused) within the message body before replying the message back to the originator. Receipt of the replied message at the originator reply port indicates it is once again safe for the originator to use or change the values found within the message.

The following are two short example tasks that communicate by sending, waiting for and replying to messages. Run these two programs together.

==== Port1.c ====

<syntaxhighlight lang="C" line>
// port1.c - port and message example, run at the same time as port2.c

#include <exec/types.h>
#include <exec/ports.h>
#include <dos/dos.h>
#include <proto/exec.h>
#include <proto/dos.h>

struct XYMessage {
struct Message xym_Msg;
int16 xy_X;
int16 xy_Y;
};

int main()
{
BOOL ABORT = FALSE;

struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "xyport",
TAG_END);

if (xyport != NULL)
{
uint32 portsig = 1U << xyport->mp_SigBit; /* Give user a `break' signal. */
uint32 usersig = SIGBREAKF_CTRL_C;

IDOS->Printf("Start port2 in another shell. CTRL-C here when done.\n");
do
{ /* port1 will wait forever and reply */
uint32 signal = IExec->Wait(portsig | usersig); /* to messages, until the user breaks. */
struct XYMessage *xymsg = 0;

/* Since we only have one port that might get messages we */
if (signal & portsig) /* have to reply to, it is not really necessary to test for */
{ /* the portsignal. If there is not message at the port, xymsg */

while(xymsg = (struct XYMessage *)IExec->GetMsg(xyport)) /* simply will be NULL. */
{
IDOS->Printf("port1 received: x = %d y = %d\n", xymsg->xy_X, xymsg->xy_Y);

xymsg->xy_X += 50; /* Since we have not replied yet to the owner of */
xymsg->xy_Y += 50; /* xymsg, we can change the data contents of xymsg. */

IDOS->Printf("port1 replying with: x = %d y = %d\n", xymsg->xy_X, xymsg->xy_Y);
IExec->ReplyMsg((struct Message *)xymsg);
}
}

if (signal & usersig) /* The user wants to abort. */
{
while(xymsg = (struct XYMessage *)IExec->GetMsg(xyport)) /* Make sure port is empty. */
IExec->ReplyMsg((struct Message *)xymsg);
ABORT = TRUE;
}
}
while (ABORT == FALSE);
IExec->FreeSysObject(ASOT_PORT, xyport);
}
else IDOS->Printf("Couldn't create 'xyport'\n");
return 0;
}
</syntaxhighlight>

==== Port2.c ====

<syntaxhighlight lang="C" line>
// port2.c - port and message example, run at the same time as port1.c

#include <exec/types.h>
#include <exec/ports.h>
#include <exec/memory.h>
#include <dos/dos.h>
#include <proto/exec.h>
#include <proto/dos.h>

BOOL SafePutToPort(struct Message *, CONST_STRPTR);

struct XYMessage {
struct Message xy_Msg;
int16 xy_X;
int16 xy_Y;
};

int main()
{
struct MsgPort *xyreplyport = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);

if (xyreplyport != NULL)
{
struct XYMessage *reply = NULL;

struct XYMessage *xymsg = IExec->AllocSysObjectTags(ASOT_MESSAGE,
ASOMSG_Size, sizeof(struct XYMessage),
ASOMSG_ReplyPort, xyreplyport,
TAG_END);

if (xymsg != NULL)
{
xymsg->xy_X = 10; /* our special message information. */
xymsg->xy_Y = 20;

IDOS->Printf("Sending to port1: x = %d y = %d\n", xymsg->xy_X, xymsg->xy_Y);

/* port2 will simply try to put */
if (SafePutToPort((struct Message *)xymsg, "xyport")) /* one message to port1 wait for */
{ /* the reply, and then exit */
IExec->WaitPort(xyreplyport);
if (reply = (struct XYMessage *)IExec->GetMsg(xyreplyport))
IDOS->Printf("Reply contains: x = %d y = %d\n", /* We don't ReplyMsg since */
xymsg->xy_X, xymsg->xy_Y); /* WE initiated the message. */

/* Since we only use this private port for receiving replies, and we sent */
/* only one and got one reply there is no need to cleanup. For a public port, */
/* or if you pass a pointer to the port to another process, it is a very good */
/* habit to always handle all messages at the port before you delete it. */
}
else IDOS->Printf("Can't find 'xyport'; start port1 in a separate shell\n");
IExec->FreeSysObject(ASOT_MESSAGE, xymsg);
}
else IDOS->Printf("Couldn't get memory\n");
IExec->FreeSysObject(ASOT_PORT, xyreplyport);
}
else IDOS->Printf("Couldn't create xyreplyport\n");
return 0;
}

BOOL SafePutToPort(struct Message *message, CONST_STRPTR portname)
{
IExec->Forbid();
struct MsgPort *port = IExec->FindPort(portname);
if (port != NULL) IExec->PutMsg(port, message);
IExec->Permit();
return(port ? TRUE : FALSE); /* FALSE if the port was not found */

/* Once we've done a Permit(), the port might go away and leave us with an invalid port */
} /* address. So we return just a BOOL to indicate whether the message has been sent or not. */
</syntaxhighlight>

== Function Reference ==

The following chart gives a brief description of the Exec functions that control inter-task communication with messages and ports. See the SDK for details about each call.

{| class="wikitable"
! Function
! Description
|-
| AddPort()
| Add a public message port to the system list.
|-
| AllocSysObject(ASOT_PORT)
| Allocate and initialize a new message port.
|-
| FindPort()
| Find a public message port in the system list.
|-
| FreeSysObject(ASOT_PORT)
| Free a message port.
|-
| GetMsg()
| Get next message from the message port.
|-
| PutMsg()
| Put a message to a message port.
|-
| RemPort()
| Remove a message port from the system list.
|-
| ReplyMsg()
| Reply to a message on its reply port.
|}

Audio Device

2025-01-26T19:37:57Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

[[Category:Devices|Audio]]{{CodeReview}}
== Audio Device ==

The Amiga has four hardware audio channels—two of the channels produce audio output from the left audio connector, and two from the right. These channels can be used in many ways. You can combine a right and a left channel for stereo sound, use a single channel, or play a different sound through each of the channels to create four-part harmony.

== About Amiga Audio ==

Most personal computers that produce sound have hardware designed for one ''specific'' synthesis technique. The Amiga computer uses a very general method of digital sound synthesis that is quite similar to the method used in digital hi-fi components and state-of-the-art keyboard and drum synthesizers.

For programs that can afford the memory, playing sampled sounds gives you a simple and very CPU-efficient method of sound synthesis. A sampled sound is a table of numbers which represents a sound digitally. When the sound is played back by the Amiga, the table is fed by a DMA channel into one of the four digital-to-analog converters in the custom chips. The digital-to-analog converter converts the samples into voltages that can be played through amplifiers and loudspeakers, reproducing the sound.

On the Amiga you can create sound data in many other ways. For instance, you can use trigonometric functions in your programs to create the more traditional sounds—sine waves, square waves, or triangle waves—by using tables that describe their shapes. Then you can combine these waves for richer sound effects by adding the tables together. Once the data are entered, you can modify them with techniques described below. For information about the limitations of the audio hardware and suggestions for improving system efficiency and sound quality, refer to the ''Amiga Hardware Reference Manual''.

Some commands enable your program to co-reside with other programs using the audio device at the same time. Programs can co-reside because the audio device handles allocation of audio channels and arbitrates among programs competing for the same resources. When properly used, this allows many programs to use the audio device simultaneously.

The audio device commands help isolate the programmer from the idiosyncrasies of the custom chip hardware and make it easier to use. But you can also produce sound on the Amiga by directly accessing the hardware registers if you temporarily lock out other users first. For certain types of sound synthesis, this is more CPU-efficient.

=== Definitions ===

Terms used in the following discussions may be unfamiliar. Some of the more important ones are defined below.
;Amplitude
:The height of a waveform, which corresponds to the amount of voltage or current in the electronic circuit.
;Amplitude modulation
:A means of producing special audio effects by using one channel to alter the amplitude of another.
;Channel
:One “unit” of the audio device.
;Cycle
:One repetition of a waveform.
;Frequency
:The number of times per second a cycle repeats.
;Frequency modulation
:A means of producing special audio effects by using one channel to affect the period of the waveform produced by another channel.
;Period
:The time elapsed between the output of successive sound samples, in units of system clock ticks.
;Precedence
:Priority of the user of a sound channel.
;Sample
:Unit of audio data, one of the fixed-interval points on the waveform.
;Waveform
:Graph that shows a model of how the amplitude of a sound varies over time—usually over one cycle.

== Audio Device Commands and Functions ==

{| class="wikitable"
!Command!!Command Operation
|-
|'''ADCMD_ALLOCATE'''||Allocate one or more of the four audio channels.
|-
|'''ADCMD_FINISH'''||Abort the current write request on one or more of the channels. Can be done immediately or at the end of the current cycle.
|-
|'''ADCMD_FREE'''||Free one or more audio channels.
|-
|'''ADCMD_LOCK'''||Lock one or more audio channels.
|-
|'''ADCMD_PERVOL'''||Change the period and volume for writes in progress. Can be done immediately or at the end of the cycle.
|-
|'''ADCMD_SETPREC'''||Set the allocation precedence of one or more channels.
|-
|'''ADCMD_WAITCYCLE'''||Wait for the current write cycle to complete on a single channel. Returns at the end of the cycle or immediately if no cycle is active on the channel.
|-
|'''CMD_FLUSH'''||Purge all write cycles and waitcycles (in-progress and queued) for one or more channels.
|-
|'''CMD_READ'''||Return a pointer to the I/O block currently writing on a single channel.
|-
|'''CMD_RESET'''||Reset one or more channels their initialized state. All active and queued requests will be aborted.
|-
|'''CMD_START'''||Resume writes to one or more channels that were stopped.
|-
|'''CMD_STOP'''||Stop any write cycle in progress on one or more channels.
|-
|'''CMD_WRITE'''||Start a write cycle on a single channel.
|}

== Device Interface ==

The audio device operates like the other Amiga I/O devices. To make sound, you first open the audio device, then send I/O requests to it, and then close it when finished. See [[Exec_Device_I/O|Exec Device I/O]] for general information on device usage.

Audio device commands use an extended I/O request block named IOAudio to send commands to the audio device. This is the standard IORequest block with some extra fields added at the end.

<syntaxhighlight lang="C" line>
struct IOAudio
{
struct IORequest ioa_Request; /* I/O request block. See exec/io.h. */
WORD ioa_AllocKey; /* Alloc. key filled in by audio device */
UBYTE *ioa_Data; /* Pointer to a sample or allocation mask */
ULONG ioa_Length; /* Length of sample or allocation mask. */
UWORD ioa_Period; /* Sample playback speed */
UWORD ioa_Volume; /* Volume of sound */
UWORD ioa_Cycles; /* # of times to play sample. 0=forever. */
struct Message ioa_WriteMsg; /* Filled in by device - usually not used */
};
</syntaxhighlight>

See the include file devices/audio.h for the complete structure definition.

=== Opening the Audio Device ===

Before you can use the audio device, you must first open it with a call to OpenDevice(). Four primary steps are required to open the audio device:

* Create a message port using CreatePort. Reply messages from the device must be directed to a message port.
* Allocate memory for an extended I/O request structure of type IOAudio using AllocMem().
* Fill in io_Message.mn_ReplyPort with the message port created by CreatePort().
* Open the audio device. Call OpenDevice(), passing IOAudio.

<pre>
struct MsgPort *AudioMP; /* Define storage for port pointer */
struct IOAudio *AudioIO; /* Define storage for IORequest pointer */

if (AudioMP = CreatePort(0,0) )
{
AudioIO = (struct IOAudio *)
AllocMem(sizeof(struct IOAudio), MEMF_PUBLIC | MEMF_CLEAR);
if (AudioIO)
{
AudioIO->ioa_Request.io_Message.mn_ReplyPort = AudioMP;
AudioIO->ioa_AllocKey = 0;
}

if (OpenDevice(AUDIONAME,0L,(struct IORequest *)AudioIO,0L) )
printf("%s did not open\n",AUDIONAME);
</pre>

A special feature of the OpenDevice() function with the audio device allows you to automatically allocate channels for your program to use when the device is opened. This is convenient since you ''must'' allocate one or more channels before you can produce sound.

This is done by setting the value of ioa_AllocKey to zero, setting the value of ioa_Request.io_Message.mn_Node.ln_Pri to the appropriate precedence, setting io_Data to the address of a channel combination array, and setting ioa_Request.ioa_Length to a non-zero value (the length of the channel combination array). The audio device will attempt to allocate channels just as if you had sent the ADCMD_ALLOCATE command (see below). If the allocation fails, the OpenDevice() call will return immediately.

If you want to allocate channels at some later time, set the value of the ioa_Request.ioa_Length field of the IOAudio block to zero when you call OpenDevice(). For more on channel allocation and the ADCMD_ALLOCATE command, see the section on “Allocation and Arbitration” below.

<pre>
UBYTE chans[] = {1,2,4,8}; /* get any of the four channels */

if (AudioIO)
{
AudioIO->ioa_Request.io_Message.mn_ReplyPort = AudioMP;
AudioIO->ioa_AllocKey = 0;
AudioIO->ioa_Request.io_Message.mn_Node.ln_Pri= 120;
AudioIO->ioa_Data = chans;
AudioIO->ioa_Length = sizeof(chans);
}

if (OpenDevice(AUDIONAME,0L,(struct IORequest *)AudioIO,0L) )
printf("%s did not open\n", AUDIONAME);
</pre>

=== Audio Device Command Types ===

Commands for audio use can be divided into two categories: allocation/arbitration commands and hardware control commands.

There are four allocation/arbitration commands. These do not actually produce any sound. Instead they manage and arbitrate the audio resources for the many tasks that may be using audio in the Amiga’s multitasking environment.

{|
|-
|ADCMD_ALLOCATE||Reserves an audio channel for your program to use.
|-
|ADCMD_FREE||Frees an audio channel.
|-
|ADCMD_SETPREC||Changes the precedence of a sound in progress.
|-
|ADCMD_LOCK||Tells if a channel has been stolen from you.
|}

The hardware control commands are used to set up, start, and stop sounds on the audio device:

{|
|-
|CMD_WRITE||The main command. Starts a sound playing.
|-
|ADCMD_FINISH||Aborts a sound in progress.
|-
|ADCMD_PERVOL||Changes the period (speed) and volume of a sound in progress.
|-
|CMD_FLUSH||Clears the audio channels.
|-
|CMD_RESET||Resets and initializes the audio device.
|-
|ADCMD_WAITCYCLE||Signals you when a cycle finishes.
|-
|CMD_STOP||Temporarily stops a channel from playing.
|-
|CMD_START||Restarts an audio channel that was stopped.
|-
|CMD_READ||Returns a pointer to the current IOAudio request.
|}

=== Scope of Audio Commands ===

Most audio commands can operate on multiple channels. The exceptions are ADCMD_WAITCYCLE, CMD_WRITE and CMD_READ, which can only operate on one channel at a time. You specify the channel(s) that you want to use by setting the appropriate bits in the ioa_Request.io_Unit field of the IOAudio block. If you send a command for a channel that you do not own, your command will be ignored. For more details, see the section on “Allocation and Arbitration” below.

=== Audio and System I/O Functions ===

==== BeginIO() ====

All the commands that you can give to the audio device should be sent by calling the BeginIO() function. This differs from other Amiga devices which generally use SendIO() or DoIO(). You should not use SendIO() or DoIO() with the audio device because these functions clear some special flags used by the audio device; this might cause audio to work incorrectly under certain circumstances. To be safe, you should always use BeginIO() with the audio device.

==== Wait() and WaitPort() ====

These functions can be used to put your task to sleep while a sound plays. Wait() takes a wake-up mask as its argument. The wake-up mask is usually the mp_SigBit of a MsgPort that you have set up to get replies back from the audio device.

'''WaitPort()''' will put your task to sleep while a sound plays. The argument to WaitPort() is a pointer to a MsgPort that you have set up to get replies back from the audio device.

'''Wait()''' and WaitPort() will not remove the message from the reply port. You must use GetMsg() to remove it.

You must always use Wait() or WaitPort() to wait for I/O to finish with the audio device.

==== AbortIO() ====

This function can be used to cancel requests for ADCMD_ALLOCATE, ADCMD_LOCK, CMD_WRITE, or ADCMD_WAITCYCLE. When used with the audio device, AbortIO() always succeeds.

=== Closing the Audio Device ===

An OpenDevice() must eventually be matched by a call to CloseDevice().

All I/O requests must be complete before CloseDevice(). If any requests are still pending, abort them with AbortIO():

<pre>AbortIO((struct IORequest *)AudioIO); /* Abort any pending requests */
WaitPort(AudioMP); /* Wait for abort message */
GetMsg(AudioMP); /* Get abort message */
CloseDevice((struct IORequest *)AudioIO);</pre>
'''CloseDevice()''' performs an ADCMD_FREE command on any channels selected by the ioa_Request.io_Unit field of the IOAudio request. This means that if you close the device with the same IOAudio block that you used to allocate your channels (or a copy of it), the channels will be automatically freed.

If you allocated channels with multiple allocation commands, you cannot use this function to close all of them at once. Instead, you will have to issue one ADCMD_FREE command for each allocation that you made. After issuing the ADCMD_FREE commands for each of the allocations, you can call CloseDevice().

== A Simple Audio Example ==

The Amiga’s audio software has a complex allocation and arbitration system which is described in detail in the sections below. At this point, though, it may be helpful to look at a simple audio example:

== Audio Allocation and Arbitration ==

The first command you send to the audio device should always be ADCMD_ALLOCATE. You can do this when you open the device, or at a later time. You specify the channels you want in the '''ioa_Data''' field of the '''IOAudio''' block. If the allocation succeeds, the audio device will return the channels that you now own in the lower four bits of the '''ioa_Request.io_Unit''' field of your '''IOAudio''' block. For instance, if the '''io_Unit''' field equals 5 (binary 0101) then you own channels 2 and 0. If the '''io_Unit''' field equals 15 (binary 1111) then you own all the channels.

When you send the ADCMD_ALLOCATE command, the audio device will also return a unique allocation key in the '''ioa_AllocKey''' of the '''IOAudio''' block. You must use this allocation key for all subsequent commands that you send to the audio device. The audio device uses this unique key to identify which task issued the command. If you do not use the correct allocation key assigned to you by the audio device when you send a command, your command will be ignored.

When you request a channel with ADCMD_ALLOCATE, you specify a precedence number from -128 to 127 in the '''ioa_Request.io_Message.mn_Node.ln_Pri''' field of the '''IOAudio''' block. If a channel you want is being used and you have specified a higher precedence than the current user, ADCMD_ALLOCATE will “steal” the channel from the other user. Later on, if your precedence is lower than that of another user who is performing an allocation, the channel may be stolen from you.

If you set the precedence to 127 when you open the device or raise the precedence to 127 with the ADCMD_SETPREC command, no other tasks can steal a channel from you. When you have finished with a channel, you must relinquish it with the ADCMD_FREE command to make it available for other users.

The following table shows suggested precedence values.

{| class="wikitable"
|+Suggested Precedences for Channel Allocation
!Predecence!!Type of Sound
|-
|127||''Unstoppable''. Sounds first allocated at lower precedence, then set to this highest level.
|-
|90 – 100||''Emergencies''. Alert, urgent situation that requires immediate action.
|-
|80 – 90||''Annunciators''. Attention, bell (Ctrl-G).
|-
|75||''Speech''. Synthesized or recorded speech (narrator.device).
|-
|50 – 70||''Sonic cues''. Sounds that provide information that is not provided by graphics. Only the beginning of each sound (enough to recognize it) should be at this level; the rest should be set to sound effects level.
|-
| -50 – 50||''Music program''. Musical notes in music-oriented program. The higher levels should be used for the attack portions of each note.
|-
| -70 – -50||''Sound effects''. Sounds used in conjunction with graphics. More important sounds should use higher levels.
|-
| -100 – -80||''Background''. Theme music and restartable background sounds.
|-
| -128||''Silence''. Lowest level (freeing the channel completely is preferred)
|}

If you attempt to perform a command on a channel that has been stolen from you by a higher priority task, an AUDIO_NOALLOCATION error is returned and the bit in the ioa_Request.io_Unit field corresponding to the stolen channel is cleared so you know which channel was stolen.

If you want to be warned before a channel is stolen so that you have a chance to stop your sound gracefully, then you should use the ADCMD_LOCK command after you open the device. This command is also useful for programs which write directly to the audio hardware. For more on ADCMD_LOCK, see the section below.

== Allocation and Arbitration Commands ==

These commands allow the audio channels to be shared among different tasks and programs. None of these commands can be called from interrupt code.

=== ADCMD_ALLOCATE ===

This command gives your program a channel to use and should be the first command you send to the audio device. You specify the channels you want by setting a pointer to an array in the '''ioa_Data''' field of the '''IOAudio''' structure. This array uses a value of 1 to allocate channel 0, 2 for channel 1, 4 for channel 2, and 8 for channel 3. For multiple channels, add the values together. For example, if you want to allocate all channels, use a value of 15.

If you want a pair of stereo channels and you have no preference about which of the left and right channels the system will choose for the allocation, you can pass a pointer to an array containing 3, 5, 10, and 12. Channels 1 and 2 produce sound on the left side and channels 0 and 3 on the right side. The table below shows how this array corresponds to all the possible combinations of a right and a left channel.

{| class="wikitable"
|+Possible Channel Combinations
!Channel 3
right
!Channel 2
left
!Channel 1
left
!Channel 0
right
!Decimal Value
of
Allocation Mask
|-
|0||0||1||1||3
|-
|0||1||0||1||5
|-
|1||0||1||0||10
|-
|1||1||0||0||12
|}

==== How ADCMD_ALLOCATE Operates ====

The ADCMD_ALLOCATE command tries the first combination, 3, to see if channels 0 and 1 are not being used. If they are available, the 3 is copied into the '''io_Unit''' field and you get an allocation key for these channels in the '''ioa_AllocKey''' field. You copy the key into other I/O blocks for any other commands you may want to perform on these channels.

If channels 0 and 1 are being used, ADCMD_ALLOCATE tries the other combinations in turn. If all the combinations are in use, ADCMD_ALLOCATE checks the precedence number of the users of the channels and finds the combination that requires it to steal the channel or channels of the lowest precedence. If all the combinations require stealing a channel or channels of equal or higher precedence, the ADCMD_ALLOCATE request fails. Precedence is in the '''ln_Pri''' field of the '''io_Message''' in the '''IOAudio''' block you pass to ADCMD_ALLOCATE; it has a value from -128 to 127.

==== The ADIOF_NOWAIT Flag ====

If you need to produce a sound right now and otherwise don’t want to allocate, set the ADIOF_NOWAIT flag to 1. This will cause the command to return an IOERR_ALLOCFAILED error if it cannot allocate any of the channels. If you are producing a non-urgent sound and you can wait, set the ADIOF_NOWAIT flag to 0. Then, the '''IOAudio''' block returns only when you get the allocation. If ADIOF_NOWAIT is set to 0, the audio device will continue to retry the allocation request whenever channels are freed until it is successful. If the program decides to cancel the request, '''AbortIO'''() can be used.

==== ADCMD_ALLOCATE Examples ====

The following are more examples of how to tell ADCMD_ALLOCATE your channel preferences. If you want any channel, but want a right channel first, use an array containing 1, 8, 2, and 4:

{|
|0001
|-
|1000
|-
|0010
|-
|0100
|}

If you only want a right channel, use 1 and 8 (channels 0 and 3):

{|
|0001
|-
|1000
|}
If you want only a left channel, use 2 and 4 (channels 1 and 2):

{|
|0010
|-
|0100
|}

If you want to allocate a channel and keep it for a sound that can be interrupted and restarted, allocate it at a certain precedence. If it is stolen, allocate it again with the ADIOF_NOWAIT flag set to 0. When the channel is relinquished, you will get it again.

==== The Allocation Key ====

If you want to perform multi-channel commands, all the channels must have the same key since the '''IOAudio''' block has only one allocation key field. The channels must all have that same key even when they were not allocated simultaneously. If you want to use a key you already have, you can pass that key in the '''ioa_AllocKey''' field and ADCMD_ALLOCATE can allocate other channels with that existing key. The ADCMD_ALLOCATE command returns a new and unique key only if you pass it a zero in the allocation key field.

=== ADCMD_FREE ===

ADCMD_FREE is the opposite of ADCMD_ALLOCATE. When you perform ADCMD_FREE on a channel, it does a CMD_RESET command on the hardware and “unlocks” the channel. It also checks to see if there are other pending allocation requests. You do not need to perform ADCMD_FREE on channels stolen from you. If you want channels back after they have been stolen, you must reallocate them with the same allocation key.

=== ADCMD_SETPREC ===

This command changes the precedence of an allocated channel. As an example of the use of ADCMD_SETPREC, assume that you are making the sound of a chime that takes a long time to decay. It is important that user hears the chime but not so important that he hears it decay all the way. You could lower precedence after the initial attack portion of the sound to let another program steal the channel. You can also set the precedence to maximum (127) if you do not want the channel(s) stolen from you.

=== ADCMD_LOCK ===

The ADCMD_LOCK command performs the “steal verify” function. When another application is attempting to steal a channel or channels, ADCMD_LOCK gives you a chance to clean up before the channel is stolen. You perform a ADCMD_LOCK command right after the ADCMD_ALLOCATE command. ADCMD_LOCK does not return until a higher-priority user attempts to steal the channel(s) or you perform an ADCMD_FREE command. If someone is attempting to steal, you must finish up and ADCMD_FREE the channel as quickly as possible.

You must use ADCMD_LOCK if you want to write directly to the hardware registers instead of using the device commands. If your channel is stolen, you are not notified unless the ADCMD_LOCK command is present. This could cause problems for the task that has stolen the channel and is now using it at the same time as your task. ADCMD_LOCK sets a switch that is not cleared until you perform an ADCMD_FREE command on the channel. Canceling an ADCMD_LOCK request with '''AbortIO()''' will not free the channel.

The following outline describes how ADCMD_LOCK works when a channel is stolen and when it is not stolen.

# ''User A'' allocates a channel.
# ''User A'' locks the channel.
#:If ''User B'' allocates the channel with a higher precedence:
## ''User B''’s ADCMD_ALLOCATE command is suspended (regardless of the setting of the ADIOF_NOWAIT flag).
## ''User A''’s lock command is replied to with an error (this will be ADIOERR_CHANNELSTOLEN).
## ''User A'' does whatever is needed to finish up when a channel is stolen.
## ''User A'' frees the channel with ADCMD_FREE.
## ''User B''’s ADCMD_ALLOCATE command is replied to. Now user B has the channel.
#:If the channel is not allocated by another user:
## ''User A'' finishes the sound.
## ''User A'' performs the ADCMD_FREE command.
## ''User A''’s ADCMD_LOCK command is replied to.

Never make the freeing of a channel (if the channel is stolen) dependent on allocating another channel. This may cause a deadlock. If you want channels back after they have been stolen, you must reallocate them with the same allocation key. To keep a channel and never let it be stolen, set precedence to maximum (127). Do not use a lock for this purpose.

== Hardware Control Commands ==

The following commands change hardware registers and affect the actual sound output.

=== CMD_WRITE ===

This is a single-channel command and is the main command for making sounds. You pass the following to CMD_WRITE:

* A pointer to the waveform to be played (must start on a word boundary and must be in memory accessible by the custom chips, MEMF_CHIP)
* The length of the waveform in bytes (must be an even number)
* A count of how many times you want to play the waveform

If the count is 0, CMD_WRITE will play the waveform from beginning to end, then repeat the waveform continuously until something aborts it.

If you want period and volume to be set at the start of the sound, set the WRITE command’s ADIOF_PERVOL flag. If you do not do this, the previous volume and period for that channel will be used. This is one of the flags that is cleared by '''DoIO()''' and '''SendIO()'''. The '''ioa_WriteMsg''' field in the '''IOAudio''' block is an extra message field that can be replied to at the start of the CMD_WRITE. This second message is used only to tell you when the CMD_WRITE command ''starts'' processing, and it is used only when the ADIOF_WRITEMESSAGE flag is set to 1.

If a CMD_STOP has been performed, the CMD_WRITE requests are queued up. The CMD_WRITE command does not make its own copy of the waveform, so any modification of the waveform before the CMD_WRITE command is finished may affect the sound. This is sometimes desirable for special effects. To splice together two waveforms without clicks or pops, you must send a separate, second CMD_WRITE command while the first is still in progress. This technique is used in double-buffering, which is described below.

By using two waveform buffers and two CMD_WRITE requests you can compute a waveform continuously. This is called double-buffering. The following describes how you use double-buffering.

# Compute a waveform in memory buffer A.
# Issue CMD_WRITE A with '''io_Data''' pointing to buffer A.
# Continue the waveform in memory buffer B.
# Issue CMD_WRITE B with '''io_Data''' pointing to Buffer B.
# Wait for CMD_WRITE A to finish.
# Continue the waveform in memory buffer A.
# Issue CMD_WRITE A with '''io_Data''' pointing to Buffer A.
# Wait for CMD_WRITE B to finish.
# Loop back to step 3 until the waveform is finished.
# At the end, remember to wait until both CMD_WRITE A and B are finished.

=== ADCMD_FINISH ===

The ADCMD_FINISH command aborts (calls '''AbortIO()''') the current write request on a channel or channels. This is useful if you have something playing, such as a long buffer or some repetitions of a buffer, and you want to stop it.

ADCMD_FINISH has a flag you can set (ADIOF_SYNCCYCLE) that allows the waveform to finish the current cycle before aborting it. This is useful for splicing together sounds at zero crossings or some other place in the waveform where the amplitude at the end of one waveform matches the amplitude at the beginning of the next. Zero crossings are positions within the waveform at which the amplitude is zero. Splicing at zero crossings gives you fewer clicks and pops when the audio channel is turned off or the volume is changed.

=== ADCMD_PERVOL ===

ADCMD_PERVOL lets you change the volume and period of a CMD_WRITE that is in progress. The change can take place immediately or you can set the ADIOF_SYNCCYCLE flag to have the change occur at the end of the cycle. This is useful to produce vibratos, glissandos, tremolos, and volume envelopes in music or to change the volume of a sound.

=== CMD_FLUSH ===

CMD_FLUSH aborts (calls AbortIO()) all CMD_WRITEs and all ADCMD_WAITCYCLEs that are queued up for the channel or channels. It does not abort ADCMD_LOCKs (only ADCMD_FREE clears locks).

=== CMD_RESET ===

CMD_RESET restores all the audio hardware registers. It clears the attach bits, restores the audio interrupt vectors if the programmer has changed them, and performs the CMD_FLUSH command to cancel all requests to the channels. CMD_RESET also unstops channels that have had a CMD_STOP performed on them. CMD_RESET does not unlock channels that have been locked by ADCMD_LOCK.

=== ADCMD_WAITCYCLE ===

This is a single-channel command. ADCMD_WAITCYCLE is replied to when the current cycle has completed, If there is no CMD_WRITE in progress, it returns immediately.

=== CMD_STOP ===

This command stops the current write cycle immediately. If there are no CMD_WRITEs in progress, it sets a flag so any future CMD_WRITEs are queued up and do not begin processing (playing).

=== CMD_START ===

CMD_START undoes the CMD_STOP command. Any cycles that were stopped by the CMD_STOP command are actually lost because of the impossibility of determining exactly where the DMA ceased. If the CMD_WRITE command was playing two cycles and the first one was playing when CMD_STOP was issued, the first one is lost and the second one will be played.

This command is also useful when you are playing the same wave form with the same period out of multiple channels. If the channels are stopped when the CMD_WRITE commands are issued, CMD_START exactly synchronizes them, avoiding cancellation and distortion. When channels are allocated, they are effectively started by the CMD_START command.

=== CMD_READ ===

CMD_READ is a single-channel command. Its only function is to return a pointer to the current CMD_WRITE command. It enables you to determine which request is being processed.

== Double Buffered Sound Example ==

The program listed below demonstrates double buffering with the audio device. Run the program from the CLI. It takes one parameter—the name of an IFF 8SVX sample file to play on the Amiga’s audio device. The maximum size for a sample on the Amiga is 128K. However, by using double-buffering and queueing up requests to the audio device, you can play longer samples smoothly and without breaks.

<pre>/*
* Audio_8SVX.c
*
* 8SVX example - double buffers >128K samples
*
* Compile with SAS C 5.10 lc -b1 -cfistq -v -y -L
*
* Run from CLI only
*/

#include <exec/types.h>
#include <exec/memory.h>
#include <devices/audio.h>
#include <dos/dos.h>
#include <dos/dosextens.h>
#include <graphics/gfxbase.h>
#include <iff/iff.h>
#include <iff/8svx.h>

#include <clib/exec_protos.h>
#include <clib/alib_protos.h>
#include <clib/dos_protos.h>
#include <clib/graphics_protos.h>

#include <stdlib.h>
#include <stdio.h>

#ifdef LATTICE
int CXBRK(void) { return(0); } /* Disable SAS CTRL/C handling */
int chkabort(void) { return(0); } /* really */
#endif

#define VHDR MakeID('V','H','D','R')
#define BODY MakeID('B','O','D','Y')
#define MY8S MakeID('8','S','V','X')

void kill8svx(char *);
void kill8(void);

/*--------------------*/ /* These globals are needed */
/* G L O B A L S */ /* by the clean up routines */
/*--------------------*/
struct IOAudio *AIOptr1, /* Pointers to Audio IOBs */
*AIOptr2,
*Aptr;
struct Message *msg; /* Msg, port and device for */
struct MsgPort *port, /* driving audio */
*port1,*port2;
ULONG device;
UBYTE *sbase,*fbase; /* For sample memory allocation */
ULONG fsize,ssize; /* and freeing */

struct FileHandle *v8handle;
UBYTE chan1[] = { 1 }; /* Audio channel allocation arrays */
UBYTE chan2[] = { 2 };
UBYTE chan3[] = { 4 };
UBYTE chan4[] = { 8 };
UBYTE *chans[] = {chan1,chan2,chan3,chan4};

BYTE oldpri,c; /* Stuff for bumping priority */

struct Task *mt=0L;
struct GfxBase *GfxBase = NULL;

/*-----------*/
/* M A I N */
/*-----------*/

void main(int argc,char **argv)
{

/*-------------*/
/* L O C A L S */
/*-------------*/

char *fname; /* File name and data pointer*/
UBYTE *p8data; /* for file read. */
ULONG clock; /* Clock constant */
ULONG length[2]; /* Sample lengths */
BYTE iobuffer[8], /* Buffer for 8SVX header */
*psample[2]; /* Sample pointers */
Chunk *p8Chunk; /* Pointers for 8SVX parsing */
Voice8Header *pVoice8Header;
ULONG y,rd8count,speed; /* Counters, sampling speed */
ULONG wakebit; /* A wakeup mask */

/*-------------*/
/* C O D E */
/*-------------*/

/*------------------------------*/
/* Check Arguments, Initialize */
/*------------------------------*/

fbase=0L;
sbase=0L;
AIOptr1=0L;
AIOptr2=0L;
port=0L;
port1=0L;
port2=0L;
v8handle=0L;
device=1L;

if (argc < 2)
{
kill8svx("No file name given.\n");
exit(1L);
}
fname=argv[1];

/*---------------------------*/
/* Initialize Clock Constant */
/*---------------------------*/

GfxBase=(struct GfxBase *)OpenLibrary("graphics.library",0L);
if (GfxBase==0L)
{
puts("Can't open graphics library\n");
exit(1L);
}

if (GfxBase->DisplayFlags & PAL)
clock=3546895L; /* PAL clock */
else
clock=3579545L; /* NTSC clock */

if (GfxBase)
CloseLibrary( (struct Library *) GfxBase);

/*---------------*/
/* Open the File */
/*---------------*/

v8handle= (struct FileHandle *) Open(fname,MODE_OLDFILE);
if (v8handle==0)
{
kill8svx("Can't open 8SVX file.\n");
exit(1L);
}

/*-------------------------------------------*/
/* Read the 1st 8 Bytes of the File for Size */
/*-------------------------------------------*/
rd8count=Read((BPTR)v8handle,iobuffer,8L);
if (rd8count==-1)
{
kill8svx ("Read error.\n");
exit(1L);
}

if (rd8count<8)
{
kill8svx ("Not an IFF 8SVX file, too short\n");
exit(1L);
}

/*-----------------*/
/* Evaluate Header */
/*-----------------*/
p8Chunk=(Chunk *)iobuffer;
if (p8Chunk->ckID != FORM )
{
kill8svx("Not an IFF FORM.\n");
exit(1L);
}

/*--------------------------------------------*/
/* Allocate Memory for File and Read it in. */
/*--------------------------------------------*/
fbase= (UBYTE *)AllocMem(fsize=p8Chunk->ckSize , MEMF_PUBLIC|MEMF_CLEAR);
if (fbase==0)
{
kill8svx("No memory for read.\n");
exit(1L);
}

p8data=fbase;

rd8count=Read((BPTR)v8handle,p8data,p8Chunk->ckSize);
if (rd8count==-1)
{
kill8svx ("Read error.\n");
exit(1L);
}

if (rd8count<p8Chunk->ckSize)
{
kill8svx ("Malformed IFF, too short.\n");
exit(1L);
}

/*-------------------*/
/* Evaluate IFF Type */
/*-------------------*/
if (MakeID( *p8data, *(p8data+1) , *(p8data+2) , *(p8data+3) ) != MY8S )
{
kill8svx("Not an IFF 8SVX file.\n");
exit(1L);
}

/*----------------------*/
/* Evaluate 8SVX Chunks */
/*----------------------*/
p8data=p8data+4;

while( p8data < fbase+fsize )
{
p8Chunk=(Chunk *)p8data;

switch(p8Chunk->ckID)
{
case VHDR:
/*------------------------------------------------*/
/* Get a pointer to the 8SVX header for later use */
/*------------------------------------------------*/
pVoice8Header=(Voice8Header *)(p8data+8L);
break;

case BODY:
/*-------------------------------------------------*/
/* Create pointers to 1-shot and continuous parts */
/* for the top octave and get length. Store them. */
/*-------------------------------------------------*/
psample[0] = (BYTE *)(p8data + 8L);
psample[1] = psample[0] + pVoice8Header->oneShotHiSamples;
length[0] = (ULONG)pVoice8Header->oneShotHiSamples;
length[1] = (ULONG)pVoice8Header->repeatHiSamples;
break;

default:
break;
}
/* end switch */

p8data = p8data + 8L + p8Chunk->ckSize;

if (p8Chunk->ckSize&1L == 1)
p8data++;
}

/* Play either the one-shot or continuous, not both */
if (length[0]==0)
y=1;
else
y=0;

/*---------------------------------------*/
/* Allocate chip memory for samples and */
/* copy from read buffer to chip memory. */
/*---------------------------------------*/
if (length[y]<=102400)
ssize=length[y];
else
ssize=102400;

sbase=(UBYTE *)AllocMem( ssize , MEMF_CHIP | MEMF_CLEAR);
if (sbase==0)
{
kill8svx("No chip memory.\n");
exit(1L);
}

CopyMem(psample[y],sbase,ssize);
psample[y]+=ssize;

/*----------------------------------*/
/* Calculate playback sampling rate */
/*----------------------------------*/
speed = clock / pVoice8Header->samplesPerSec;

/*-------------------*/
/* Bump our priority */
/*-------------------*/
mt=FindTask(NULL);
oldpri=SetTaskPri(mt,21);

/*--------------------------------*/
/* Allocate two audio I/O blocks */
/*--------------------------------*/
AIOptr1=(struct IOAudio *)
AllocMem( sizeof(struct IOAudio),MEMF_PUBLIC|MEMF_CLEAR);
if (AIOptr1==0)
{
kill8svx("No IO memory\n");
exit(1L);
}

AIOptr2=(struct IOAudio *)
AllocMem( sizeof(struct IOAudio),MEMF_PUBLIC|MEMF_CLEAR);
if (AIOptr2==0)
{
kill8svx("No IO memory\n");
exit(1L);
}

/*----------------------*/
/* Make two reply ports */
/*----------------------*/

port1=CreatePort(0,0);
if (port1==0)
{
kill8svx("No port\n");
exit(1L);
}

port2=CreatePort(0,0);
if (port2==0)
{
kill8svx("No port\n");
exit(1L);
}

c=0;
while(device!=0 && c<4)
{
/*---------------------------------------*/
/* Set up audio I/O block for channel */
/* allocation and Open the audio device */
/*---------------------------------------*/
AIOptr1->ioa_Request.io_Message.mn_ReplyPort = port1;
AIOptr1->ioa_Request.io_Message.mn_Node.ln_Pri = 127; /* No stealing! */
AIOptr1->ioa_AllocKey = 0;
AIOptr1->ioa_Data = chans[c];
AIOptr1->ioa_Length = 1;

device=OpenDevice(AUDIONAME,0L,(struct IORequest *)AIOptr1,0L);
c++;
}

if (device!=0)
{
kill8svx("No channel\n");
exit(1L);
}

/*-------------------------------------------*/
/* Set Up Audio IO Blocks for Sample Playing */
/*-------------------------------------------*/

AIOptr1->ioa_Request.io_Command =CMD_WRITE;
AIOptr1->ioa_Request.io_Flags =ADIOF_PERVOL;

/*--------*/
/* Volume */
/*--------*/

AIOptr1->ioa_Volume=60;

/*---------------*/
/* Period/Cycles */
/*---------------*/

AIOptr1->ioa_Period =(UWORD)speed;
AIOptr1->ioa_Cycles =1;

*AIOptr2 = *AIOptr1; /* Make sure we have the same allocation keys, */
/* same channels selected and same flags */
/* (but different ports...) */

AIOptr1->ioa_Request.io_Message.mn_ReplyPort = port1;
AIOptr2->ioa_Request.io_Message.mn_ReplyPort = port2;

/*--------*/
/* Data */
/*--------*/

AIOptr1->ioa_Data =(UBYTE *)sbase;
AIOptr2->ioa_Data =(UBYTE *)sbase + 51200;

/*-----------------*/
/* Run the sample */
/*-----------------*/

if (length[y]<=102400)
{
AIOptr1->ioa_Length=length[y]; /* No double buffering needed */
BeginIO((struct IORequest *)AIOptr1); /* Begin the sample, wait for */
wakebit=0L; /* it to finish, then quit. */
wakebit=Wait(1 << port1->mp_SigBit);
while((msg=GetMsg(port1))==0){};
}
else
{
length[y]-=102400; /* It's a real long sample so */
AIOptr1->ioa_Length=51200L; /* double buffering is needed */
AIOptr2->ioa_Length=51200L;
BeginIO((struct IORequest *)AIOptr1); /* Start up the first 2 blocks... */
BeginIO((struct IORequest *)AIOptr2);
Aptr=AIOptr1;
port=port1; /* Set the switch... */

while(length[y]>0)
{ /* We Wait() for one IO to finish, */
wakebit=Wait(1 << port->mp_SigBit); /* then reuse the IO block & queue */
while((msg=GetMsg(port))==0){}; /* it up again while the 2nd IO */
/* block plays. Switch and repeat. */
/* Set length of next IO block */
if (length[y]<=51200)
Aptr->ioa_Length=length[y];
else
Aptr->ioa_Length=51200L;

/* Copy sample fragment from read buffer to chip memory */
CopyMem(psample[y],Aptr->ioa_Data,Aptr->ioa_Length);

/* Adjust size and pointer of read buffer*/
length[y]-=Aptr->ioa_Length;
psample[y]+=51200;

BeginIO((struct IORequest *)Aptr);

if (Aptr==AIOptr1)
{
Aptr=AIOptr2; /* This logic handles switching */
port=port2; /* between the 2 IO blocks and */
} /* the 2 ports we are using. */
else
{
Aptr=AIOptr1;
port=port1;
}
}

/*-------------------------------------------------*/
/* OK we are at the end of the sample so just wait */
/* for the last two parts of the sample to finish */
/*-------------------------------------------------*/
wakebit=Wait(1 << port->mp_SigBit);
while((msg=GetMsg(port))==0){};
if (Aptr==AIOptr1)
{
Aptr=AIOptr2; /* This logic handles switching */
port=port2; /* between the 2 IO blocks and */
} /* the 2 ports we are using. */
else
{
Aptr=AIOptr1;
port=port1;
}
wakebit=Wait(1 << port->mp_SigBit);
while((msg=GetMsg(port))==0){};
}

kill8();
exit(0L);
}

/*----------------*/
/* Abort the Read */
/*----------------*/
void
kill8svx(kill8svxstring)
char *kill8svxstring;
{
puts(kill8svxstring);
kill8();
}

/*-------------------------*/
/* Return system resources */
/*-------------------------*/
void
kill8()
{
if (device ==0)
CloseDevice((struct IORequest *)AIOptr1);
if (port1 !=0)
DeletePort(port1);
if (port2 !=0)
DeletePort(port2);
if (AIOptr1!=0)
FreeMem( AIOptr1,sizeof(struct IOAudio) );
if (AIOptr2!=0)
FreeMem( AIOptr2,sizeof(struct IOAudio) );

if (mt!=0)
SetTaskPri(mt,oldpri);

if (sbase !=0)
FreeMem (sbase, ssize);
if (fbase !=0)
FreeMem(fbase,fsize);
if (v8handle!=0)
Close((BPTR)v8handle);
}</pre>
== Additional Information on the Audio Device ==

Additional programming information on the audio device can be found in the include files and the Autodocs for the audio device. Both are contained in the [[Autodocs:Main|Autodocs]]. Information can also be found in the ''Amiga Hardware Reference Manual''.

{| class="wikitable"
!colspan="2"|Audio Device Information
|-
|Includes||devices/audio.h devices/audio.i
|-
|[[Autodocs:Main|Autodocs]]||[[audio.doc]]
|}

Intuition Menu Class

2025-01-26T19:36:51Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= An overview =

Starting with version 54.6, Intuition features a built-in BOOPSI menu class ("menuclass") which aims to fully replace the traditional way of setting up and handling menus in applications.

Its object-oriented API allows to easily build complex menu trees, freeing a program from the need to use gadtools.library for that job. It also provides extensive control over menus, making it possible to define, read and change their properties thanks to simple yet flexible methods and attributes.

Moreover, menuclass extends the capabilities of the original Intuition menu system. For instance, it can handle any number of sub-menu levels, as well as any amount of items in menus and sub-menus. For nearly all operations, it transparently synchronizes itself with Intuition and performs menu relayout if needed. Automatic placement of custom images in front of menu item labels is also supported.

== BOOPSI menus vs. traditional menus ==

BOOPSI menus may look and feel identical to traditional ones from the point of view of the user, but are handled quite differently in application code.

The old-style, white-box Menu and MenuItem structures are replaced by abstract objects (instances of menuclass) accessed through an object-oriented interface, removing the need for manual poking or dedicated menu functions.

Such BOOPSI menu objects are able to perform automatically most operations for which their traditional counterparts would require special assistance from the application.

== Types of menuclass objects ==

There exist three distinct types of menuclass objects -- menu root, menu and menu item. Any instance of the class belongs to one of these types, specified at OM_NEW time through the MA_Type attribute.

The possible values for MA_Type are:

; T_ROOT
: A menu root object, also known as a menu strip as it is the parent of all menu objects. This differs from the old-style menu system, where a "menu strip" was just a linked list of Menu structures. Besides being the actual root of a menu tree, a menu root object also holds essential state information on the tree as a whole. It may be used in any place an old-style menu strip can, except for the ItemAddress() function (replaced by the MM_FINDID method). A menu root object can have any number of menu objects as children.

; T_MENU
: A menu object, equivalent to the old-style Menu structure. A menu object can have any number of menu item objects as children (and should always have at least one).

; T_ITEM
: A menu item object, equivalent to the old-style MenuItem structure. A menu item object can have any number of menu item objects as children (sub-items), even in the case it is itself a sub-item of some other menu item. Only a menu (sub-)item having no children (i.e. a leaf item) can be actually selected by the user.

== Compatibility ==

Save where explicitly allowed, menu and menu item objects instantiated from menuclass cannot be transparently used in place of the equivalent old-style Intuition elements, as not all of the traditional menu-related functions and rules apply to them.

A limited form of compatibility exists due to menuclass objects having Menu or MenuItem structures embedded in them, just like gadgetclass ones do with the (Ext)Gadget structure. However, such structures should never be directly accessed by user code unless otherwise documented.

Under most circumstances, applications should treat menuclass instances as "black boxes", the only exception to this rule currently being that it is permitted to read certain bits from the Flags field of their embedded legacy structure (see also next subsection).

== Recognizing a BOOPSI menu object ==

Although an application normally should know if it is using BOOPSI menus, it may happen that a library or a class needs to check the type of menus passed to it by a client. This is easily done with the following test:

<syntaxhighlight lang="C" line>
if ((((struct Menu *)menu_object_ptr)->Flags & BOOPSIMENU) != 0)
...
</syntaxhighlight>

If the flag BOOPSIMENU is set, the object is a menuclass instance, otherwise it is a traditional Menu or MenuItem structure.

{{Note|text=In the above test it would have been exactly the same if we had chosen to cast the object to a struct MenuItem * rather than to a struct Menu * because the Flags field is located at the same offset (and has the same size) in both structures.}}

= Adding BOOPSI menus to an application =

In this section we'll cover the basics of using the new menuclass in a typical application, and the main differences between BOOPSI and traditional menus.

The first step in adding BOOPSI menus to your application is to build a tree of menuclass objects, each with its appearance and behavior defined by attributes that can be set at NewObject() time.

== Label and ID of menus and menu items ==

For menu and menu item objects, the application should specify at least a label string and an ID number as a minimal set of attributes.

The label is assigned via MA_Label and is the text Intuition will display to represent a menu or menu item on the screen. A special value for this attribute is the constant ML_SEPARATOR, which turns a menu item into a separator line.

The ID, passed with the MA_ID tag, is a 32-bit unsigned integer that uniquely identifies a particular menu or menu item object. This number is passed back to the application through the IDCMP mechanism whenever the user picks a menu item or asks for help on a menu or menu item.

Any number may be chosen as an ID for a menuclass object, except for 0 (zero): this constant has the alias NO_MENU_ID in <intuition/menuclass.h> and is always an invalid value for an object's MA_ID attribute. Also, when an IDCMP_MENUPICK or IDCMP_MENUHELP ExtIntuiMessage reports NO_MENU_ID in its eim_LongCode field, this is to be interpreted as "no menu selection" (i.e. it has the same meaning MENUNULL has for old-style menus).

Menu root objects, as well as menu items acting as separator lines, don't need to have an ID number. Menu root objects don't need a label string either.

== Building a menu tree with menuclass ==

A menu tree is organized as a hierarchy of nested menuclass objects.

At the very top of the tree there is the menu root, having one or more menus as children. These make up the menu strip that appears on the screen when the user presses the right mouse button.

Each menu is the parent of one or more menu items. A menu item can have other menu items as children as well, thus forming a sub-menu. A menu item which is part of a sub-menu (also called a sub-item, i.e. the child of another menu item) can in turn have children (sub-items) of its own.

The leaf nodes of the tree are menu items or sub-items with no children. These are the actually selectable menu options.

There is no limit to the depth of the menu tree other than the available system memory.

You can append children to a menuclass object at OM_NEW or OM_SET time with the MA_AddChild tag, or by using the OM_ADDMEMBER method (more on this later).

An example of a very simple menu tree generation could be:

<syntaxhighlight lang="C" line>
Object *menustripobj;

menustripobj = IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ROOT,
MA_AddChild, IIntuition->NewObject(NULL,"menuclass",MA_Type,T_MENU,
MA_Label, "Project",
MA_AddChild, IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ITEM,
MA_Label, "Open...",
MA_ID, MID_PROJECT_OPEN,
TAG_END),
MA_AddChild, IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ITEM,
MA_Label, "Save",
MA_ID, MID_PROJECT_SAVE,
TAG_END),
MA_AddChild, IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ITEM,
MA_Label, "Save as...",
MA_ID, MID_PROJECT_SAVEAS,
TAG_END),
MA_AddChild, IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ITEM,
MA_Label, ML_SEPARATOR,
TAG_END),
MA_AddChild, IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ITEM,
MA_Label, "About...",
MA_ID, MID_PROJECT_ABOUT,
TAG_END),
MA_AddChild, IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ITEM,
MA_Label, ML_SEPARATOR,
TAG_END),
MA_AddChild, IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ITEM,
MA_Label, "Quit",
MA_ID, MID_PROJECT_QUIT,
TAG_END),
TAG_END),
TAG_END);
</syntaxhighlight>

If you prefer a more compact style of coding, <intuition/menuclass.h> offers a number of macros allowing to simplify the tree description a little. Using said macros, the above code could be rewritten as follows:

<syntaxhighlight lang="C" line>
Object *menustripobj;

menustripobj = MStrip,
MA_AddChild, MTitle("Project"),
MA_AddChild, MItem("Open..."),
MA_ID, MID_PROJECT_OPEN,
MEnd,
MA_AddChild, MItem("Save"),
MA_ID, MID_PROJECT_SAVE,
MEnd,
MA_AddChild, MItem("Save as..."),
MA_ID, MID_PROJECT_SAVEAS,
MEnd,
MA_AddChild, MSeparator,
MEnd,
MA_AddChild, MItem("About..."),
MA_ID, MID_PROJECT_ABOUT,
MEnd,
MA_AddChild, MSeparator,
MEnd,
MA_AddChild, MItem("Quit"),
MA_ID, MID_PROJECT_QUIT,
MEnd,
MEnd,
MEnd;
</syntaxhighlight>

{{Note|text=When using the MTitle() and MItem() macros, the label is passed as an argument to the macro itself rather than via an explicit MA_Label tag.}}

We'll use the compact style in the rest of this document, except in cases where the more verbose one provides greater clarity.

== Menu item keyboard shortcuts ==

As with traditional Intuition menus, menuclass item objects can have a keyboard shortcut which is displayed next to the item's label. Shortcuts can have one or more characters; a shortcut of more than one character is also called "command string" (for instance, "ctrl z").

A single-character shortcut is processed directly by Intuition, and appears at the right side of the menu item with an "Amiga key" symbol prepended to it. When using a command string of more than one character, however, Intuition will display it at the right side of the item (without the "Amiga key" symbol) but won't process the corresponding key combination; the application has to handle that on its own.

There are two ways to specify a keyboard shortcut for a menuclass item object.

You can pass it with the MA_Key attribute, as in the following example:

<syntaxhighlight lang="C" line>
item = MItem("Save"),
MA_ID, MID_SAVE,
MA_Key, "S",
MEnd;
</syntaxhighlight>

Alternatively, you can prepend it to the item's label string, separed by a '|' character, this way:

<syntaxhighlight lang="C" line>
item = MItem("S|Save"),
MA_ID, MID_SAVE,
MEnd;
</syntaxhighlight>

If you opt for the latter approach, you may also use a NUL ('\0') character in place of the '|'. This can prove useful when converting to BOOPSI menu usage an existing application employing such a method to embed shortcuts in its catalog strings.

{{Note|text=The NUL byte solution only works for single-letter shortcuts and requires that no item in the menu tree has a label of just one letter, as any such label would be mistaken for a shortcut followed by random bytes. When you have single-letter labels, therefore, you cannot use this feature and must disable it for the whole tree. That's done by passing { MA_EmbeddedKey, FALSE } to the menu root object; this attribute will be inherited by all objects.}}

== Inheritance of menu attributes ==

There are some attributes of menuclass objects that are automatically inherited by all their descendants, except those for which they're explicitly set to some different value. For instance, if you want your menus to use a particular font, you only need to set the MA_TextAttr attribute for the menu root, and all items (and sub-items) of all menus will be displayed with that font.

Any menuclass attribute which is automatically inherited from the parent object when not specified explicitly is clearly described as such, both in the autodoc and in the <intuition/menuclass.h> header file.

== Attaching the menu tree to a window ==

You can attach a menu tree built with menuclass to a window just like you would do with traditional non-BOOPSI menus, i.e. by calling SetMenuStrip(). Starting with Intuition V54, this function accepts a BOOPSI menu root object as the menu strip pointer.
Therefore, once you've opened your window, you can simply do the following:

<syntaxhighlight lang="C" line>
IIntuition->SetMenuStrip(window,menustripobj);
</syntaxhighlight>

and the menu tree will be ready to use, after undergoing an automatic layout to adapt itself to the window's screen.

An alternative to the above is passing the menus to the window at opening time, via the new V54 tag WA_MenuStrip. This way your window will open with the menus already attached and laid out.

When using window.class, you can achieve the same by passing the class-specific tag WINDOW_MenuStrip. (Starting with V54, window.class supports WA_MenuStrip as well, as an alias for WINDOW_MenuStrip.)

== Detaching the menu tree from a window ==

BOOPSI menus, like traditional ones, can be detached from a window at any time with ClearMenuStrip(). After having been detached, they can also be reattached by way of ResetMenuStrip(), as usual.

In many cases, however, you don't need to remove BOOPSI menus as you would with old-style menus. Changing the selection state of "checkmarkable" items, as well as disabling or enabling single items or whole menus, may be performed by just setting the appropriate attribute of the menu object in question, regardless of whether or not the menus are in use. Any needed synchronization with Intuition is handled internally by menuclass.

The above is generally true for all operations you can do on menuclass objects, such as changing their label, image, font or charset, or even their position in the menu tree. In fact, a BOOPSI menu tree even supports addition or removal of menus and items on-the-fly without any clearing and resetting of the menus.

Whenever a change requires a relayout of some part of the menu tree, menuclass will automatically take care of that.

Additionally, as of Intuition V54 it is no longer mandatory to remove the menus with ClearMenuStrip() before closing the window. CloseWindow() itself will take care of clearing the menus if needed (no matter if BOOPSI or old-style).

{{Note|text=It is still required, however, to use ClearMenuStrip() to remove the menu strip of a window before setting a different one with SetMenuStrip().}}

== Handling menu item selections by the user ==

Upon receiving a menu pick event such as IDCMP_MENUPICK (or WMHI_MENUPICK if using window.class), your application can find out which menu items the user selected by invoking repeatedly the MM_NEXTSELECT method on the root object of the menu tree (i.e. the menu strip object). This will return all selected item IDs in sequence; in many cases there will be only one, but there may be more if the user performed multiple selection.

Once all IDs have been retrieved, MM_NEXTSELECT will return NO_MENU_ID which means there are no more selections in the list.

{{Note|text=MM_NEXTSELECT might even return NO_MENU_ID immediately on the first invocation; this would mean the user initiated and terminated a menu session without picking any item. Be prepared to handle this case.}}

The MM_NEXTSELECT method uses the following mpNextSelect message structure:

<syntaxhighlight lang="C" line>
struct mpNextSelect
{
uint32 MethodID;
uint32 mpns_Reserved;
uint32 mpns_CurrentID;
};
</syntaxhighlight>

where MethodID is MM_NEXTSELECT, mpns_Reserved should be always set to zero, and mpns_CurrentID is the menu item ID the method returned on the previous invocation. To obtain the first ID in the selection list, pass NO_MENU_ID in the mpns_CurrentID field.

An example of this method's usage would be:

<syntaxhighlight lang="C" line>
uint32 id = NO_MENU_ID;

while ((id = IIntuition->IDoMethod(menustripobj,MM_NEXTSELECT,0,id)) != NO_MENU_ID)
{
switch (id)
{
/* Process menu selections */

case MID_PROJECT_OPEN:
...
}
}
</syntaxhighlight>

An alternative way to get the ID of the first (or only) selected menu item is to read it from the eim_LongCode field of the ExtIntuiMessage reporting the IDCMP_MENUPICK event (IntuiMessages generated by Intuition are always really ExtIntuiMessages, and can be cast as such). Since a menuclass object's ID is a 32-bit value, it can't fit in the 16-bit IntuiMessage.Code field, the value of which is currently undefined for IDCMP events coming from BOOPSI menus.

The above example could thus be modified as follows:

<syntaxhighlight lang="C" line>
uint32 id = ((struct ExtIntuiMessage *)intuimsg)->eim_LongCode;

while (id != NO_MENU_ID)
{
switch (id)
{
/* Process menu selections */

case MID_PROJECT_OPEN:
...
}

id = IIntuition->IDoMethod(menustripobj,MM_NEXTSELECT,0,id);
}
</syntaxhighlight>

The first approach is probably more convenient when using window.class since in that case you would need an additional IDCMP hook to access the ExtIntuiMessage in order to read its eim_LongCode field.

== Handling menu help requests by the user ==

If your window has the WA_MenuHelp attribute set to TRUE, and it's listening to IDCMP_MENUHELP events, the user can request help on a menu item or a menu title by pressing the [Help] key when that item or title is being highlighted by the mouse pointer. Upon reception of a menu help event, your application can easily find out the ID of the item or title the help request was about by querying the MA_MenuHelpID attribute of the menu root object.

An example of this might be:

<syntaxhighlight lang="C" line>
uint32 help_id;

IIntuition->GetAttr(MA_MenuHelpID,menustripobj,&help_id);
</syntaxhighlight>

{{Note|text=The menu help ID value may be NO_MENU_ID, which means the [Help] key was pressed by the user while no menu item or title was highlighted.}}

Menu help doesn't support multiple selection, so you have to deal with just one ID per event. As with menu pick, you can also retrieve the ID value by reading the ExtIntuiMessage.eim_LongCode field.

== Menu pick hooks and menu help hooks ==

Any menuclass object can have custom hooks associated to it with dedicated code to handle menu selections or help requests for that specific object. Such hooks can be invoked automatically by the main event handling loop every time a menu pick or menu help event occurs.

The hook that handles menu item selections is specified through the MA_PickHook attribute; similarly, you can use the MA_HelpHook attribute to specify the hook handling menu help requests.

These two attributes are inherited by all children of a menuclass object. This allows, if desired, to reuse the same hook for all the items of a menu (or all the sub-items of an item) simply by setting it for that menu (or item), rather than having to pass it to each child explicitly. Such a "common" hook could act as a dispatcher, calling the appropriate individual handling function according to the ID of the object it is invoked on.

A menuclass object's pick or help hook will be invoked as follows:

<syntaxhighlight lang="C" line>
HookFunction(struct Hook *hook, Object *obj, struct MenuEventMessage *msg)
</syntaxhighlight>

where 'obj' is the object itself and 'msg' is a pointer to a MenuEventMessage structure.

The MenuEventMessage structure is defined as follows:

<syntaxhighlight lang="C" line>
struct MenuEventMessage
{
uint32 StructSize; /* For future expansion */
uint32 EventType; /* ET_MENUPICK or ET_MENUHELP */
struct Window *Window; /* Event window pointer */
APTR UserData; /* Custom data pointer */
};
</syntaxhighlight>

The EventType field is useful to distinguish between the two types of event the hook could be invoked for, in case the same hook function is used for both. The Window field holds the address of the event's window (i.e. the window your menu tree is associated to) and the UserData field is used to pass to the hook any kind of context information it might require, as explained a little below.

The pick or help hook can use the supplied information (menu object, window and custom data pointer) to process the event. The return value of the hook is not currently defined; it's recommended to set it to zero for future compatibility.

To have menuclass invoke the pick hook of a menuclass object, your application needs to use the MM_HANDLEPICK method in its event loop.

Like MM_NEXTSELECT, MM_HANDLEPICK can be invoked repeatedly to browse through all items in the menu selection chain. The difference is that this method only returns the ID of selected items that don't have a pick hook; whenever it finds a selected item whose pick hook is non-NULL, it invokes that hook and proceeds to the next item without returning anything. When there are no more items left in the menu selection chain, MM_HANDLEPICK returns NO_MENU_ID.

The mechanism is exactly the same for help hooks, except in that case you have to use the MM_HANDLEHELP method, which only needs to invoked once as menu help events don't support multiple selection: if the menu object the user asked help about doesn't have a help hook, MM_HANDLEHELP will return its ID, otherwise it will invoke the hook and return NO_MENU_ID.

Both the MM_HANDLEPICK and MM_HANDLEHELP methods should be invoked on the menu root object, and use the same message structure:

<syntaxhighlight lang="C" line>
struct mpHandleEvent
{
uint32 MethodID;
uint32 mphe_Reserved;
uint32 mphe_CurrentID;
struct Window *mphe_Window;
APTR mphe_UserData;
};
</syntaxhighlight>

where MethodID is MM_HANDLEPICK or MM_HANDLEHELP, mphe_Reserved should always be set to zero, and mphe_CurrentID is the ID returned by the method's previous invocation (ignored by MM_HANDLEHELP; pass NO_MENU_ID on the first invocation of MM_HANDLEPICK). Additionally, you should store the event's window address in mphe_Window (e.g. IntuiMessage->IDCMPWindow) and any custom data to be passed to the pick or help hook in mphe_UserData; your hook will be able to read back this information from the MenuEventMessage.

A simple example of how to take advantage of the custom pick hook feature might be the following:

<syntaxhighlight lang="C" line>
uint32 id = NO_MENU_ID;

while ((id = IIntuition->IDoMethod(menustripobj,MM_HANDLEPICK,
0,
id,
imsg->IDCMPWindow,
mycustomdata)) != NO_MENU_ID)
{
/* This selected menu object doesn't have
* a pick hook, so let's handle it here.
*/
switch (id)
{
/* Process menu selections */

case MID_PROJECT_OPEN:
...
}
}
</syntaxhighlight>

It goes without saying that if none of your application's menuclass object has a pick hook or help hook, you never need to invoke MM_HANDLEPICK/MM_HANDLEHELP in your event handling code; you can just use the simpler MM_NEXTSELECT method and MA_MenuHelpID attribute instead, as covered in previous subsections.

== Retrieving a menuclass object's address from its ID number ==

Once you have found out which menu item was picked by the user by examining its ID, you may want to do some operations on the item object itself, and thus need its actual address. One way to achieve this could be to keep a look-up table in your application, initialized as the menu tree gets built, and using the IDs as indices. For instance, something like the following:

<syntaxhighlight lang="C" line>
...
MA_AddChild, mtable[MID_PROJECT_OPEN] = MItem("Open..."),
MA_ID, MID_PROJECT_OPEN,
MEnd,
MA_AddChild, mtable[MID_PROJECT_SAVE] = MItem("Save"),
MA_ID, MID_PROJECT_SAVE,
MEnd,
...
</syntaxhighlight>

The drawbacks of such an approach are increased memory consumption and reduced code readability. A simpler solution is offered by menuclass in the form of the MM_FINDID method. This uses the mpFindID structure, defined as:

<syntaxhighlight lang="C" line>
struct mpFindID
{
uint32 MethodID;
uint32 mpfi_Reserved;
uint32 mpfi_ID;
};
</syntaxhighlight>

where MethodID is MM_FINDID, mpfi_Reserved should always be set to zero, while mpfi_ID is the ID of the menu object whose address you're looking for. Here's a simple example of this method's invocation on the menu root object:

<syntaxhighlight lang="C" line>
m_obj = (Object *)IIntuition->IDoMethod(menustripobj,MM_FINDID,0,id);
</syntaxhighlight>

If a menu object with the specified ID is found within the menu tree, MM_FINDID will return its address, otherwise it will return NULL.

The MM_FINDID method doesn't actually need to be invoked on the menu root as in the above example. It just searches for an object having a given ID within the menu (sub-)tree hanging from the object it's invoked on. So if you already know the address of an object whose local sub-tree contains the one you want, it is possible to invoke MM_FINDID directly on that object and restrict the search to only a part of the menu tree.

Invoking the MM_FINDID method is the BOOPSI equivalent of calling ItemAddress() with traditional menus.

== Enabling and disabling menus and menu items ==

By default, a BOOPSI menu or item is enabled, meaning it looks clearly readable and can be selected by the user. When disabled, it is instead rendered with low contrast or a recessed appearance and is not selectable.

The MA_Disabled attribute is used to control the enable state of BOOPSI menu or item objects. It is possible to disable a menuclass object right from the start by passing { MA_Disabled, TRUE } to NewObject(), or change the object's enable state later at any time via SetAttrs(). Setting MA_Disabled to TRUE or FALSE is the BOOPSI equivalent of calling OnMenu() or OffMenu() on old-style menus.

Disabling a menu or a menu item will make all of its children show up disabled as well, down to the deepest sub-menu levels. Additionally, you can disable all your menus at once (i.e. make the entire menu tree disabled and not selectable) simply by disabling the menu strip object.

Another way to examine and modify the enable state of a menu or menu item is to invoke the MM_GETSTATE and MM_SETSTATE methods (see below for more on this).

== Selection state of toggle select and mutual exclude items ==

Whenever a toggle select or mutual exclude menu item is picked by the user, you can examine its selection state by reading the item's MA_Selected attribute. If its value is TRUE, the item is currently selected (checked) and is displayed with some small checkmark or radio button symbol drawn in front of it.

You can also programmatically change the selection state of this kind of items at any time by setting the value of MA_Selected with SetAttrs(), without having to clear and then reset the menu strip as you would with non-BOOPSI menus.

This attribute has no meaning for action items, i.e. items that don't represent the "on" or "off" state of some option.

Another way to examine and modify the selection state of a menu or menu item is to invoke the MM_GETSTATE and MM_SETSTATE methods (see below for more on this).

== Methods for controlling the enable and selection state of menu items ==

It is possible to examine and modify the enable state of a menu or menu item by invoking the MM_GETSTATE and MM_SETSTATE methods. These may prove more handy in many cases since they take an ID number to specify the target object instead of the object's actual address. This means they can be directly fed the result of MM_NEXTSELECT without having to go through MM_FINDID first.

Both these methods use the bitmask constants MS_CHECKED and MS_DISABLED to read or modify the corresponding MA_Selected and MA_Disabled attributes.

The MM_GETSTATE method uses the following message structure:

<syntaxhighlight lang="C" line>
struct mpGetState
{
uint32 MethodID;
uint32 mpgs_Reserved;
uint32 mpgs_ID;
};
</syntaxhighlight>

where MethodID is MM_GETSTATE, mpgs_Reserved should always be set to zero, and mpgs_ID is the ID number of the menuclass object whose state you want to read. The method should be invoked on the menu root object (or on the parent of the target object, if you have its address) and will return a bit mask whose value can be MS_CHECKED, MS_DISABLED, both constants ORed together, or zero. For instance, if MS_CHECKED is set in the method's return value it means that the object's MA_Selected attribute is currently TRUE.

The MM_SETSTATE method uses the following message structure:

<syntaxhighlight lang="C" line>
struct mpSetState
{
uint32 MethodID;
uint32 mpss_Reserved;
uint32 mpss_ID;
uint32 mpss_ApplyMask;
uint32 mpss_StateMask;
};
</syntaxhighlight>

where the first three fields are analogous to those of the mpGetState structure while mpss_ApplyMask is used to specify which attribute(s) should be modified, and mpss_StateMask contains the new values. For instance, if MS_DISABLED is set in mpss_ApplyMask, but not in mpss_StateMask, the object will become enabled as its MA_Disabled attribute will be set to FALSE. If MS_CHECKED is cleared in the mpss_ApplyMask field, on the other hand, the object's selection state will stay unchanged no matter what the value of mpss_StateMask is.

== Disposing of the menu tree ==

Due to its dynamic nature, usually a BOOPSI menu tree doesn't need to be freed and rebuilt by your application on environment changes or each time it has to undergo some significant modification. You may for instance reuse the same menu tree on different screens (as long as it's used on one screen at a time).

This means that all important state information stored in the menu tree such as which items are checked, disabled, etc. is never lost while the application is running, and that the menu tree can be disposed of just once on program's exit.

To free an entire menu tree, you just have to call DisposeObject() on its root object. Whatever disposable object you attached to some menu item, such as e.g. a BOOPSI image, will be freed as well unless you asked not to do so.

= Further menuclass features =

This section will outline a number of attributes and methods giving access to some more specialized functionality of menuclass.

== Specifying the menu font ==

Each menu item object can be displayed in its own font and size, although this is strongly discouraged as such an arrangement would look quite unprofessional. Still, if you for any reason need to set the font used by a menu item, you can do so with the MA_TextAttr attribute.

The font specified this way will be opened and closed by menuclass as needed.

If you set MA_TextAttr for a menuclass object, it will be inherited by all of its children. To specify a font for the entire menu tree, therefore, just set MA_TextAttr for the menu root object.

Whenever there isn't any specific reason to do otherwise, it's recommended not to use MA_TextAttr at all and just let the menus be displayed in the font that was chosen in the user's preferences for the screen they appear on.

== Adding images to menu items ==

A BOOPSI menu item can have an image displayed at the left side of (or in place of) the item's label. The image is specified through the MA_Image attribute; it may be either traditional or BOOPSI.

The item's height is adjusted if needed to make enough room for the image.

If the image is BOOPSI, it will be automatically disposed of when the menu item object is; to avoid that, you should set the item's MA_FreeImage attribute to FALSE. However, if you want to prevent automatic disposal for ALL images in the menu tree, it is more practical to set MA_FreeImage to FALSE for the menu root object since this way it will be inherited by all objects.

If the menu item has no label (i.e. it's an image-only item), you can still use MA_TextAttr to specify the font used for its keyboard shortcut character.

== Hiding menus and menu items ==

Any member of a BOOPSI menu tree can be hidden or revealed again at any time by your application. A hidden menuclass object is still physically present in the menu tree, but does not appear on the screen when menus are displayed, as if it had been actually removed.

The MA_Hidden attribute is used to control the hiding of a BOOPSI menu or item objects. It is possible to make a menu or item hidden right from the start by passing { MA_Hidden, TRUE } to NewObject(), or change the object's hiding state later via SetAttrs().

Hiding a menu or a menu item will (obviously) hide all of its children as well. Unlike disabling, however, you cannot hide the menu strip object -- if you want to make the entire menu tree disappear, just call ClearMenuStrip().

== Dynamic menu localization ==

So far, we've only examined the simple case where you pass an actual string as the value of a menuclass object's MA_Label attribute. There is however another possibility, and that is to specify a numeric index as MA_Label's value, which is later used to look up the appropriate string in the currently open catalog.

To be able to pass an integer value for MA_Label instead of a string, you need to tell menuclass what is the numeric range of string IDs. Any value outside of that range will be considered a string, and used directly as such. Values lying in the range, on the other hand, will be treated as catalog indices. The string ID range is specified with the MA_MinStringID and MA_MaxStringID attributes. (By default, the string ID range is empty and MA_Label is always interpreted as a string.)

Whenever an object's MA_Label attribute is actually a numeric index, its value is passed on each menu layout to a "localization hook" which will convert it to the correct string for the current language and charset.

The localization hook (aka string hook) is supplied by your application via the MA_StringHook attribute. You can simply set it for the root object, and it will be inherited by all objects in the menu tree.

Your hook will be invoked as follows:

<syntaxhighlight lang="C" line>
HookFunction(struct Hook *hook, Object *obj, struct MenuStringMessage *msg)
</syntaxhighlight>

where 'obj' is the menu or item the string ID to be converted belongs to, and 'msg' is a pointer to a MenuStringMessage structure (see below for definition) which carries the string ID.

You can also specify the address of an open catalog and/or a charset by setting the MA_Catalog and MA_CharSet attributes for the menu root object; if supplied, this information is also passed back to the hook in the MenuStringMessage.

The MenuStringMessage structure is defined as follows:

<syntaxhighlight lang="C" line>
struct MenuStringMessage
{
uint32 StructSize; /* For future expansion */
uint32 StringID; /* The string ID number */
struct Catalog *Catalog; /* Catalog pointer, may be NULL */
uint32 CharSet; /* Charset number, may be zero */
};
</syntaxhighlight>

Your string hook should return the correct catalog string for the passed string ID, or a default string if no catalog is available.

{{Note|text=All of the above is equally valid for the MA_Key attribute, which can be a string ID instead of an actual string just like MA_Label. Its string ID range is the same one of MA_Label (as defined by MA_MinStringID and MA_MaxStringID).}}

{{Note|title=Also Note|text=If you don't use a string hook, MA_Label and MA_Key should always be real strings and not numeric IDs, otherwise they'll get converted by menuclass to "????", which isn't very meaningful. The same will happen if the string hook returns a NULL string pointer.}}

== Adding and removing menus and menu items ==

A BOOPSI menu tree built with menuclass allows for dynamic addition and removal of menus and items at any time. As with other modifications, there's no need to detach the menu tree from the window in order to perform these operations; it's menuclass that takes care of synchronizing each change with Intuition and doing any necessary relayout afterwards.

To add a child to a menuclass object, you can simply call SetAttrs() to pass it the MA_AddChild tag with the address of the new child as data, the same way you would at OM_NEW time.

Here's an example of adding a sub-item to an item:

<syntaxhighlight lang="C" line>
/* Append a new entry to our "recent files" sub-menu */

new_item = MItem(filename), MA_ID, new_id++, MEnd;

IIntuition->SetAttrs(recentfiles_itemobj,MA_AddChild,new_item,TAG_END);
</syntaxhighlight>

A NULL pointer can safely be passed with MA_AddChild, and is simply ignored.

{{Note|text=In this example we're using a simple counter variable to generate an unique ID for each new sub-item -- we don't care about the ID value itself, we simply want to take notice if the item gets selected, and be able to retrieve its address with MM_FINDID whenever needed. This requires the new item to have a valid and unique ID number.}}

Just like they can be added, menus and menu items can also be removed from the menu tree as needed. This is achieved by passing the MA_RemoveChild tag to the parent menu object via SetAttrs(), with the address of the child as data.

For instance, we could remove an item from a menu this way:

<syntaxhighlight lang="C" line>
/* Close a window and remove its entry from our "open windows" menu */

id = (uint32)window->UserData; /* We stored the menu item's ID there */

IIntuition->CloseWindow(window);

item = (Object *)IIntuition->IDoMethod(openwindows_menuobj,MM_FINDID,0,id);

IIntuition->SetAttrs(openwindows_menuobj,MA_RemoveChild,item,TAG_END);

IIntuition->DisposeObject(item); /* Accepts a NULL argument */
</syntaxhighlight>

As with MA_AddChild, you can safely pass a NULL pointer with MA_RemoveChild.

Another way to perform addition and removal of children with menuclass objects is to use rootclass' OM_ADDMEMBER and OM_REMMEMBER methods. The above examples could thus be rewritten by replacing the SetAttrs() calls with:

<syntaxhighlight lang="C" line>
IIntuition->IDoMethod(recentfiles_itemobj,OM_ADDMEMBER,new_item);

IIntuition->IDoMethod(openwindows_menuobj,OM_REMMEMBER,item);
</syntaxhighlight>

As you would when dealing with Exec lists, you must be careful to avoid adding or removing the same child twice, or removing a child which was never added in the first place, since doing so will cause memory corruption.

== Browsing through all children of a menu object ==

You can obtain the addresses of all children of a menuclass object in sequence by invoking the MM_NEXTCHILD method in a loop. Once all the object's children have been been retrieved, MM_NEXTCHILD will return NULL to signal there are no more children.

The MM_NEXTCHILD method uses the following message structure:

<syntaxhighlight lang="C" line>
struct mpNextChild
{
uint32 MethodID;
uint32 mpnc_Reserved;
Object *mpnc_Current;
};
</syntaxhighlight>

where MethodID is MM_NEXTCHILD, mpnc_Reserved should always be set to zero, and mpnc_Current is the child object address the method did return on the previous invocation. Pass NULL in mpnc_Current to get the address of the first child.

An example of a loop retrieving all items of a menu:

<syntaxhighlight lang="C" line>
Object *obj = NULL;

while ((obj = (Object *)IIntuition->IDoMethod(menuobj,MM_NEXTCHILD,0,obj)) != NULL)
{
/* Do something with the item object */
}
</syntaxhighlight>

If you use MM_NEXTCHILD in a loop to remove an object's children one by one, be careful not to pass the method the address of an already removed object.

The correct way to do a sequential child removal is the following:

<syntaxhighlight lang="C" line>
while ((obj = (Object *)IIntuition->IDoMethod(menuobj,MM_NEXTCHILD,0,NULL)) != NULL)
{
IIntuition->IDoMethod(menuobj,OM_REMMEMBER,obj);
}
</syntaxhighlight>

This is analogous to performing a RemHead() loop on an Exec list.

== Scanning the menu tree ==

You can perform a scan of the whole menu tree, or even just a subsection of it, and have a custom function called on each object that is part of it. This makes it possible to implement any kind of operation that is not already provided by the existing menuclass methods.

To scan a menu (sub-)tree, you invoke the MM_SCAN method on its root object and specify a callback function and some parameters that will be passed back to it on each call. The MM_SCAN method uses the following message structure:

<syntaxhighlight lang="C" line>
struct mpScan
{
uint32 MethodID;
uint32 mps_Reserved;
struct Hook *mps_Hook;
uint32 mps_Args[4];
};
</syntaxhighlight>

where MethodID is MM_SCAN, mps_Reserved should always be set to zero, mps_Hook is a pointer to your custom hook, and mps_Args[0] to mps_Args[3] are (optional) arguments for the hook's function. Your hook will be invoked as follows:

<syntaxhighlight lang="C" line>
HookFunction(struct Hook *hook, Object *obj, struct MenuScanMessage *msg)
</syntaxhighlight>

where 'obj' is a menuclass object (whose exact type you can inspect by reading its MA_Type attribute) and 'msg' is a pointer to a MenuScanMessage structure.

The MenuScanMessage structure is defined as follows:

<syntaxhighlight lang="C" line>
struct MenuScanMessage
{
uint32 StructSize; /* For future expansion */
int32 Level; /* How deep we are in the menu tree */
uint32 Args[4]; /* Custom arguments */
};
</syntaxhighlight>

The Level field indicates the depth in the tree of the current object, starting from -1 for the root object. The four Args variables hold the same values which were passed upon invocation of the MM_SCAN method and can be used to feed your custom arguments back to the hook.

If your hook returns a non-zero value, the scan stops with the method returning the address of the object on which it stopped. If the hook always returns zero, all objects are scanned and the MM_SCAN method returns NULL.

An example of this method's usage could be the following:

<syntaxhighlight lang="C" line>
/* A simple function to count how many items a menu has, using MM_SCAN */

uint32 HookFunction(struct Hook *h, Object *o, struct MenuScanMessage *msg)
{
if (msg->Level == 1)
*((uint32 *)msg->Args[0]) += 1;
return (0);
}

uint32 CountMenuItems(Object *menuobj)
{
struct Hook hook;
uint32 count = 0;

memset(&hook,0,sizeof(struct Hook));

hook.h_Entry = (HOOKFUNC)HookFunction;

IIntuition->IDoMethod(menuobj,MM_SCAN,0,&hook,&count,0,0,0);

return (count);
}
</syntaxhighlight>

In this example we pass as the only custom argument the address of an variable which, once the MM_SCAN method returns, will hold the amount of children of the specified menu object. In the hook function we check that the object's level is 1, to make sure we only take it into account if it is a direct child of a menu (menus have a level of zero), rather than being a sub-item of an item, or even the menu object itself on which the method is invoked.

== Generating a whole menu (sub-)tree from a single tag list ==

So far we have only seen menu trees built by way of a series of nested calls to NewObject(). This is certainly a working approach to putting together a tree of BOOPSI objects organized in a hierarchy. Still, it presents a few drawbacks:

* It can consume a significant amount of stack with very deep trees;
* It may produce code which is hard to read unless special macros are used;
* It makes error checking not very easy.

All in all, nesting NewObject() calls is quite acceptable with relatively small menu trees, while it can become less manageable as the tree's size grows.

A different technique for building menu trees, which attempts to overcome these issues, is provided by menuclass' MM_NEWMENU method. This allows to generate an entire tree, or a sub-tree, out of a flat description of its structure given in the form of a single tag list.

The MM_NEWMENU method uses the following message structure:

<syntaxhighlight lang="C" line>
struct mpNewMenu
{
uint32 MethodID;
uint32 mpnm_Reserved;
struct TagItem *mpnm_AttrList;
};
</syntaxhighlight>

where MethodID is MM_NEWMENU, mpnm_Reserved should always be set to zero, and mpnm_AttrList is the tag list describing the menu tree to be generated.

Said tag list is made up for the most part of the usual menuclass tags that are used to specify attributes of the individual objects; however, the menu objects themselves are introduced by special tags prepended with NM_ which are actually directives for the method.

MM_NEWMENU understands three directives: NM_Menu / NM_Item, indicating to add a new menu or item object at the current level (the tag data is the object's text label), and NM_SubItems, indicating to move down or up by one level before the next item object is added. If the tag data of NM_SubItems is SI_BEGIN, the next item will become a child of the most recent one added (i.e. we move down by one level); if it is SI_END, the next item will become a sibling of the most recent one's parent (i.e. we move up by one level).

{{Note|text=NM_SubItems is not needed to add menus to a menu strip object, nor to add items to a menu object -- its only purpose is to act as a "delimiter" for a list of sub-items of an item object.}}

Any menuclass tag that is encountered in the tag list is passed as an attribute to the most recently added object.

The method should be invoked on an existing menuclass object, which in case of success will become the new tree's root. MM_NEWMENU returns FALSE to indicate failure, the exact reasons for which can be inspected through the MA_ErrorCode and MA_ErrorTagItem tags. See <intuition/menuclass.h> for a list of menuclass error codes and their explanation.

Here's a simple example to illustrate the method's usage:

<syntaxhighlight lang="C" line>
/* Service function allowing to pass varargs tag list to MM_NEWMENU
*/
static BOOL VARARGS68K DoNewMenu(Object *root, ...)
{
va_list ap;
struct TagItem *tags;
BOOL result;

va_startlinear(ap,root);
tags = (struct TagItem *)va_getlinearva(ap,struct TagItem *);
result = IIntuition->IDoMethod(root,MM_NEWMENU,0,tags);
va_end(ap);

return (result);
}

/* Build a menu tree with the MM_NEWMENU method
*/
Object *BuildMenuTree(void)
{
Object *menustripobj;
uint32 success, error;
struct TagItem *error_ti;

menustripobj = IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ROOT,TAG_END);

if (menustripobj)
{
success = DoNewMenu(menustripobj,
MA_ErrorCode, &error,
MA_ErrorTagItem, &error_ti,
NM_Menu, "Project", MA_ID, MID_PROJECT,
NM_Item, "O|Open", MA_ID, MID_OPEN,
NM_Item, "S|Save", MA_ID, MID_SAVE,
NM_Item, "A|Save as...", MA_ID, MID_SAVEAS,
NM_Item, ML_SEPARATOR,
NM_Item, "Q|Quit", MA_ID, MID_QUIT,
NM_Menu, "Options", MA_ID, MID_OPTIONS,
NM_Item, "F|Font...", MA_ID, MID_FONT,
NM_Item, "Style", MA_ID, MID_STYLE,
NM_SubItems, SI_BEGIN,
NM_Item, "B|Bold", MA_ID, MID_BOLD, MA_Toggle, TRUE,
NM_Item, "I|Italic", MA_ID, MID_ITALIC, MA_Toggle, TRUE,
NM_Item, "U|Underline", MA_ID, MID_UNDERLINE, MA_Toggle, TRUE,
NM_SubItems, SI_END,
NM_Item, "W|Word wrap", MA_ID, MID_WORDWRAP, MA_Toggle, TRUE,
TAG_END);

if (!success)
{
IDOS->Printf("Failed with error %ld, at tag %08lX\n",error,error_ti->ti_Tag);
IIntuition->IDoMethod(menustripobj,MM_DELETEMENU,0);
IIntuition->DisposeObject(menustripobj);
menustripobj = NULL;
}
}

return (menustripobj);
}
</syntaxhighlight>

In this example we make use of a small service function to pass the tag list on the stack as varargs; of course the tag list can also be allocated statically. Also, the above tree is rather small for the sake of keeping the example short, so it does not benefit much from using MM_NEWMENU instead of nested NewObject() calls, but obviously the same technique can be used to build trees of any size.

As you can see, with MM_NEWMENU you can write compact and quite readable code to describe your menu trees, without having to resort to using macros on top of nested calls. The tree's description can even be made somewhat reminiscent of traditional NewMenu arrays as used with GadTools, which may look more familiar to long-time developers.

To free a menu (sub-)tree generated with MM_NEWMENU, you invoke MM_DELETEMENU on the root object. This method uses the following message structure:

<syntaxhighlight lang="C" line>
struct mpDeleteMenu
{
uint32 MethodID;
uint32 mpdm_Reserved;
};
</syntaxhighlight>

where MethodID is MM_DELETEMENU, and mpdm_Reserved should (as usual) be set to zero. Therefore, the correct way to invoke the method is the following:

<syntaxhighlight lang="C" line>
IIntuition->IDoMethod(menustripobj,MM_DELETEMENU,0);
</syntaxhighlight>

{{Note|text=This call only disposes of all of the object's children, not of the root object itself. This way you can reuse the object in case you need to build another menu tree with MM_NEWMENU. To free the root object (and its children if you didn't already do that), simply use DisposeObject().}}

Preferences

2025-01-26T19:36:36Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

{{WIP}}
== Preferences ==

To make the Amiga operating system easily configurable by the user, the OS comes with a family of editors and associated data files known collectively as Preferences. Preferences allows the user to set system-wide configuration options such as the printer driver to use, serial port baud rate and other items. To make an application appealing to the user, the system-wide Preferences settings should be respected as much as possible by applications. This article describes how to use the Preferences system in your programs.

== Preferences Editors and Storage ==

In AmigaOS there can be any number of Preferences editors each with its own separate configuration file covering a specific area. All these Preferences editors have the same look and feel. Using separate Preferences editors and configuration files allows for adding new Preferences items (and editors) in future versions of the OS.

Preferences are store in various ".prefs" files located in the "ENV:sys" and "ENVARC:sys" directories. Preferences options currently in use are located in "ENV:sys". Permanent, saved copies of Preferences files are stored in "ENVARC:sys". These are copied to "ENV:" on an as-needed basis. Applications may also store their own preference files in "ENV:" but should use a sub-directory for that purpose.

Currently the following Preferences editors and files are available:

{| class="wikitable"
|+ Preferences Editors
! Preferences Editor
! Preferences Configuration File
|-
| IControl
| icontrol.prefs
|-
| Input
| input.prefs
|-
| Palette
| palette.ilbm
|-
| Pointer
| pointer.ilbm
|-
| Printer
| printer.prefs
|-
| PrinterGfx
| printergfx.prefs
|-
| Overscan
| overscan.prefs
|-
| ScreenMode
| screenmode.prefs
|-
| Serial
| serial.prefs
|-
| -
| wbconfig.prefs
|-
| Font
| wbfont.prefs, sysfont.prefs and screenfont.prefs
|-
| Time
| -
|-
| WBPattern
| wb.pat and win.pat
|}

Each .prefs file is managed by editor with the same name, except for wbconfig.prefs, which is written directly by Workbench and has no editor. One Preferences editor has no .prefs file, Time. That Preferences editor writes directly to the battery backed clock.

When the user makes a change to a Preferences item with one of the editors, the changes will be saved in either "ENV:sys" or ''both'' "ENV:sys" and "ENVARC:sys" depending on whether the user saves the changes with the "Use" gadget or "Save" gadget of the Preferences editor.

The "Use" gadget is for making temporary changes and the new preferences will be stored only in "ENV:sys". If the user reboots, the old preferences will be restored from the permanent copy in "ENVARC:sys".

The "Save" gadget is for making permanent changes and the new preferences will be stored in both "ENV:sys" and "ENVARC:sys". That way, if the user reboots, the new preferences will still be in effect since the system looks in "ENVARC:sys" to find out what preferences should be set to at boot time.

=== The ENV: Directory and Notification ===

One advantage of the new Preferences system is file notification. File notification is a form of inter-process communication that allows an application to be automatically notified if a change is made to a specific file or directory. This makes it easy for the application to react to changes the user makes to Preferences files. See [[Notification]] for more complete information about the notification feature.

File notification is also used by the system itself. The Preferences control program, IPrefs, sets up notification on most of the Preferences files in "ENV:sys". If the user alters a Preferences item (normally this is done with a Preferences editor), the system will notify IPrefs about the change and IPrefs will attempt to alter the user's environment to reflect the change.

For example, if the user opens the ScreenMode Preferences editor and changes the Workbench screen mode to high-resolution, the new settings are saved in "screenmode.prefs" in the "ENV:sys" directory. IPrefs sets up notification on this file at boot time, so the file system will notify IPrefs of the change. IPrefs will read in the Screenmode.prefs file and reset the Workbench screen to high resolution mode.

Here's a short example showing how to set up notification on the "serial.prefs" file in "ENV:sys". The program displays a message in a window whenever this file is changed (e.g., when the user selects the "Use" or "Save" gadget in the Serial Preferences editor).

<syntaxhighlight lang="C" line>
/*
** prefnotify.c - notified if serial prefs change
*/
#include <exec/types.h>
#include <exec/memory.h>
#include <dos/dos.h>
#include <dos/notify.h>

#include <proto/exec.h>
#include <proto/dos.h>

#define PREFSFILENAME "ENV:sys/serial.prefs"

int main(int argc, char **argv)
{
/* Allocate a NotifyRequest structure */
struct NotifyRequest *notifyrequest = IExec->AllocMem(sizeof(struct NotifyRequest), MEMF_CLEAR);

if (notifyrequest != NULL)
{
/* And allocate a signalsbit */
int8 signum;
if ((signum = IExec->AllocSignal(-1L)) != -1)
{
/* Initialize notifcation request */
CONST_STRPTR filename = PREFSFILENAME;
notifyrequest->nr_Name = filename;
notifyrequest->nr_Flags = NRF_SEND_SIGNAL;
/* Signal this task */
notifyrequest->nr_stuff.nr_Signal.nr_Task = (struct Task *) IExec->FindTask(NULL);
/* with this signals bit */
notifyrequest->nr_stuff.nr_Signal.nr_SignalNum = signum;

if ((IDOS->StartNotify(notifyrequest)) == DOSTRUE)
{
IDOS->Printf("Select Serial Prefs SAVE or USE to notify this program\n");
IDOS->Printf("CTRL-C to exit\n\n");

BOOL done = FALSE;

/* Loop until Ctrl-C to exit */
while(!done)
{
uint32 signals = IExec->Wait( (1L << signum) | SIGBREAKF_CTRL_C );
if (signals & (1L << signum))
IDOS->Printf("Notification signal received.\n");

if (signals & SIGBREAKF_CTRL_C)
{
IDOS->EndNotify(notifyrequest);
done = TRUE;
}
}
}
else IDOS->Printf("Can't start notification\n");
IExec->FreeSignal(signum);
}
else IDOS->Printf("No signals available\n");

IExec->FreeMem(notifyrequest, sizeof(struct NotifyRequest));
}
else IDOS->Printf("Not enough memory for NotifyRequest.\n");

return 0;
}
</syntaxhighlight>

=== Preference File Format ===

To understand the format of Preferences files, you must be familiar with IFF file standard (see [[IFF_Standard|IFF Standard]] for the complete specification).

In general all Preferences files are stored in the IFF format with a type of PREF (see the exceptions noted below). Each file contains at least two Chunks, a header Chunk and a data Chunk.

==== The Header Chunk ====

The PRHD header chunk, contains a PrefHeader structure:

<syntaxhighlight lang="C" line>
struct PrefHeader
{
UBYTE ph_Version;
UBYTE ph_Type;
ULONG ph_Flags;
};
</syntaxhighlight>

Currently all the fields are set to NULL. In future revisions these fields may be used to indicate a particular version and contents of a PREF chunk.

==== The Data Chunk ====

The data Chunk that follows the header Chunk depends on the kind of Preferences data the file contains. The types of Preferences data Chunks that are currently part of the system are:

{| class="wikitable"
|+ IFF Chunk Types in Preferences Data Files
! Chunk Name
! Used With
|-
| FONT
| Fonts, used for all font Preferences files. In future the PrefHeader may indicate what the font is used for.
|-
| ICTL
| IControl
|-
| INPT
| Input
|-
| OSCN
| Overscan
|-
| PGFX
| PrinterGfx
|-
| PTXT
| PrinterText
|-
| SCRM
| ScreenMode
|-
| SERL
| Serial
|}

Each chunk contains a structure applicable to the type.

=== FONT ===

<syntaxhighlight lang="C" line>
struct FontPrefs
{
LONG fp_Reserved[4];
UBYTE fp_FrontPen; /* Textcolor */
UBYTE fp_BackPen; /* Character background color */
UBYTE fp_DrawMode;
struct TextAttr fp_TextAttr;
BYTE fp_Name[FONTNAMESIZE]; /* Font name */
};
</syntaxhighlight>

=== ICTL ===

<syntaxhighlight lang="C" line>
struct IControlPrefs
{
LONG ic_Reserved[4]; /* System reserved */
UWORD ic_TimeOut; /* Verify timeout */
WORD ic_MetaDrag; /* Meta drag mouse event */
ULONG ic_Flags; /* IControl flags (see below) */
UBYTE ic_WBtoFront; /* CKey: WB to front */
UBYTE ic_FrontToBack; /* CKey: front screen to back */
UBYTE ic_ReqTrue; /* CKey: Requester TRUE */
UBYTE ic_ReqFalse; /* CKey: Requester FALSE */
};
</syntaxhighlight>

The ic_Flags field can have the following values:

; ICF_COERCE_COLORS
: This indicates that a displaymode with a matching number of colors has preference over a correct aspect ration when screen coercing takes place.

; ICF_COERCE_LACE
: This indicates that choosing an interlaced display mode is allowed when coercing screens. Otherwise a non-interlaced display mode will be selected.

; ICF_STRGAD_FILTER
: This indicates that control characters should be filtered out of string gadget user input.

; ICF_MENUSNAP
: This indicates that an auto-scroll screen should be snapped back to origin when the mouse menu-button is selected.

Note that the command key values in the last four fields of the IControlPrefs structure are ANSI codes, not RAWKEY codes.

=== INPT ===

<syntaxhighlight lang="C" line>
struct InputPrefs
{
LONG ip_Reserved[4];
UWORD ip_PointerTicks; /* Sensitivity of the pointer */
struct timeval ip_DoubleClick; /* Interval between clicks */
struct timeval ip_KeyRptDelay; /* keyboard repeat delay */
struct timeval ip_KeyRptSpeed; /* Keyboard repeat speed */
WORD ip_MouseAccel; /* Mouse acceleration */
};
</syntaxhighlight>

=== OSCN ===

<syntaxhighlight lang="C" line>
struct OverscanPrefs
{
ULONG os_Reserved[4];
ULONG os_DisplayID; /* Displaymode ID */
Point os_ViewPos; /* View X/Y Offset */
Point os_Text; /* TEXT overscan dimension */
struct Rectangle os_Standard; /* STANDARD overscan dimension */
};
</syntaxhighlight>

=== PGFX ===

<syntaxhighlight lang="C" line>
struct PrinterGfxPrefs
{
LONG pg_Reserved[4];
UWORD pg_Aspect; /* Horizontal or vertical */
UWORD pg_Shade; /* B&W, Greyscale, Color */
UWORD pg_Image; /* Positive or negative image */
WORD pg_Threshold; /* Black threshold */
UBYTE pg_ColorCorrect; /* RGB color correction */
UBYTE pg_Dimensions; /* Dimension type */
UBYTE pg_Dithering; /* Type of dithering */
UWORD pg_GraphicFlags; /* Rastport dump flags */
UBYTE pg_PrintDensity; /* Print density 1 - 7 */
UWORD pg_PrintMaxWidth; /* Maximum width */
UWORD pg_PrintMaxHeight; /* Maximum height */
UBYTE pg_PrintXOffset; /* X Offset */
UBYTE pg_PrintYOffset; /* Y Offset */
};
</syntaxhighlight>

The possible values of each field are defined in <prefs/printergfx.h>. Note that your application is responsible for checking if the supplied values are valid.

=== PTXT ===

<syntaxhighlight lang="C" line>
struct PrinterTxtPrefs
{
LONG pt_Reserved[4]; /* System reserved */
UBYTE pt_Driver[DRIVERNAMESIZE]; /* printer driver filename */
UBYTE pt_Port; /* printer port connection */

UWORD pt_PaperType; /* Fanfold or single */
UWORD pt_PaperSize; /* Standard, Legal, A4, A3 etc. */
UWORD pt_PaperLength; /* Paper length in # of lines */

UWORD pt_Pitch; /* Pica or Elite */
UWORD pt_Spacing; /* 6 or 8 LPI */
UWORD pt_LeftMargin; /* Left margin */
UWORD pt_RightMargin; /* Right margin */
UWORD pt_Quality; /* Draft or Letter */
};
</syntaxhighlight>

=== SCRM ===

<syntaxhighlight lang="C" line>
struct ScreenModePrefs
{
ULONG sm_Reserved[4];
ULONG sm_DisplayID; /* Displaymode ID */
UWORD sm_Width; /* Screen width */
UWORD sm_Height; /* Screen height */
UWORD sm_Depth; /* Screen depth */
UWORD sm_Control; /* BIT 0, Autoscroll yes/no */
};
</syntaxhighlight>

=== SERL ===

<syntaxhighlight lang="C" line>
struct SerialPrefs
{
LONG sp_Reserved[4]; /* System reserved */
ULONG sp_BaudRate; /* Baud rate */

ULONG sp_InputBuffer; /* Input buffer: 0 - 64K */
ULONG sp_OutputBuffer; /* Future: Output: 0 - 64K, def 0 */

UBYTE sp_InputHandshake; /* Input handshaking */
UBYTE sp_OutputHandshake; /* Future: Output handshaking */

UBYTE sp_Parity; /* Parity */
UBYTE sp_BitsPerChar; /* I/O bits per character */
UBYTE sp_StopBits; /* Stop bits */
};
</syntaxhighlight>

=== Other Preferences File Formats ===

Not every Preferences file is stored as an IFF file of type PREF. The palette.ilbm and pointer.ilbm files contain a regular ILBM FORM to store their imagery. The win.pat and wb.pat files use a raw format with 16 bytes reserved, followed by a WORD giving the total size of the pattern, a WORD giving the bitplane count, and byte arrays (currently 32 bytes) for each bitplane. The format of the wbconfig.prefs file is private.

=== Reading a Preferences File ===

The following example shows a way to read a Preferences file.

<syntaxhighlight lang="C" line>
/*
** showprefs.c - parse and show some info from an IFF Preferences file
**
*/

#include <exec/types.h>
#include <dos/dos.h>
#include <libraries/dos.h>
#include <libraries/iffparse.h>
#include <prefs/prefhdr.h>
#include <prefs/font.h>
#include <prefs/icontrol.h>
#include <prefs/input.h>
#include <prefs/overscan.h>
#include <prefs/printergfx.h>
#include <prefs/printertxt.h>
#include <prefs/screenmode.h>
#include <prefs/serial.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/iffparse.h>

struct IFFParseIFace *IIFF;

static uint8 *IFFErrTxt[] = {
"EOF", /* (end of file, not an error) */
"EOC", /* (end of context, not an error) */
"no lexical scope",
"insufficient memory",
"stream read error",
"stream write error",
"stream seek error",
"file corrupt",
"IFF syntax error",
"not an IFF file",
"required call-back hook missing",
NULL, /* (return to client, never shown) */
};

int main()
{
struct RDArgs *readargs;
int32 rargs[2];
struct IFFHandle *iffhandle;
struct ContextNode *cnode;
struct StoredProperty *hdrsp;
struct StoredProperty *sp;
uint8 *filename;
int32 ifferror, error = 0, rc = RETURN_OK;

struct Library *IFFParseBase = IExec->OpenLibrary ("iffparse.library", 50);
IIFF = (struct IFFParseIFace*)IExec->GetInterface(IFFParseBase, "main", 1, NULL);

if (IIFF != NULL) {
if (readargs = IDOS->ReadArgs("FILE/A", rargs, NULL)) {

/* Test later if valid */
filename = (uint8 *)rargs[0];

/* allocate an IFF handle */
if (iffhandle = IIFF->AllocIFF()) {
/* Open the file for reading */
if (iffhandle->iff_Stream = (int32)IDOS->Open(filename, MODE_OLDFILE)) {
/* initialize the iff handle */
IIFF->InitIFFasDOS (iffhandle);
if ((ifferror = IIFF->OpenIFF (iffhandle, IFFF_READ)) == 0) {
IIFF->PropChunk(iffhandle, ID_PREF, ID_PRHD);

IIFF->PropChunk(iffhandle, ID_PREF, ID_FONT);
IIFF->PropChunk(iffhandle, ID_PREF, ID_ICTL);
IIFF->PropChunk(iffhandle, ID_PREF, ID_INPT);
IIFF->PropChunk(iffhandle, ID_PREF, ID_OSCN);
IIFF->PropChunk(iffhandle, ID_PREF, ID_PGFX);
IIFF->PropChunk(iffhandle, ID_PREF, ID_PTXT);
IIFF->PropChunk(iffhandle, ID_PREF, ID_SCRM);
IIFF->PropChunk(iffhandle, ID_PREF, ID_SERL);

for (;;) {
ifferror = IIFF->ParseIFF(iffhandle, IFFPARSE_STEP);

if (ifferror == IFFERR_EOC)
continue;
else if (ifferror)
break;

/* Do nothing is this is a PrefHeader chunk,
* we'll pop it later when there is a pref
* chunk.
*/
if (cnode = IIFF->CurrentChunk(iffhandle))
if (cnode->cn_ID == ID_PRHD || cnode->cn_ID == ID_FORM)
continue;

/* Get the preferences header, stored previously */
hdrsp = IIFF->FindProp(iffhandle, ID_PREF, ID_PRHD);

if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_FONT)) {
IDOS->Printf("FrontPen: %ld\n",
((struct FontPrefs *)sp->sp_Data)->fp_FrontPen);
IDOS->Printf("BackPen: %ld\n",
((struct FontPrefs *)sp->sp_Data)->fp_BackPen);
IDOS->Printf("DrawMode: %ld\n",
((struct FontPrefs *)sp->sp_Data)->fp_DrawMode);
IDOS->Printf("Font: %s\n",
(LONG)((struct FontPrefs *)sp->sp_Data)->fp_Name);
IDOS->Printf("ta_YSize: %ld\n",
((struct FontPrefs *)sp->sp_Data)->fp_TextAttr.ta_YSize);
IDOS->Printf("ta_Style: %ld\n",
((struct FontPrefs *)sp->sp_Data)->fp_TextAttr.ta_Style);
IDOS->Printf("ta_Flags: %ld\n",
((struct FontPrefs *)sp->sp_Data)->fp_TextAttr.ta_Flags);
} else if (sp = FindProp(iffhandle, ID_PREF, ID_ICTL)) {
IDOS->Printf("TimeOut: %ld\n",
((struct IControlPrefs *)sp->sp_Data)->ic_TimeOut);
IDOS->Printf("MetaDrag: %ld\n",
((struct IControlPrefs *)sp->sp_Data)->ic_MetaDrag);
IDOS->Printf("WBtoFront: %ld\n",
((struct IControlPrefs *)sp->sp_Data)->ic_WBtoFront);
IDOS->Printf("FrontToBack: %ld\n",
((struct IControlPrefs *)sp->sp_Data)->ic_FrontToBack);
IDOS->Printf("ReqTrue: %ld\n",
((struct IControlPrefs *)sp->sp_Data)->ic_ReqTrue);
IDOS->Printf("ReqFalse: %ld\n",
((struct IControlPrefs *)sp->sp_Data)->ic_ReqFalse);
/* etc */
} else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_INPT)) {
IDOS->Printf("PointerTicks: %ld\n",
((struct InputPrefs *)sp->sp_Data)->ip_PointerTicks);
IDOS->Printf("DoubleClick/Secs: %ld\n",
((struct InputPrefs *)sp->sp_Data)->ip_DoubleClick.tv_secs);
IDOS->Printf("DoubleClick/Micro: %ld\n",
((struct InputPrefs *)sp->sp_Data)->ip_DoubleClick.tv_micro);
/* etc */
} else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_OSCN)) {
IDOS->Printf("DisplayID: 0x%lx\n",
((struct OverscanPrefs *)sp->sp_Data)->os_DisplayID);
/* etc */
} else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_PGFX)) {
IDOS->Printf("Aspect: %ld\n",
((struct PrinterGfxPrefs *)sp->sp_Data)->pg_Aspect);
/* etc */
} else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_PTXT)) {
IDOS->Printf("Driver: %s\n",
(LONG)((struct PrinterTxtPrefs *)sp->sp_Data)->pt_Driver);
/* etc */
} else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_SCRM)) {
IDOS->Printf("DisplayID: 0x%lx\n",
((struct ScreenModePrefs *)sp->sp_Data)->sm_DisplayID);
/* etc */
} else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_SERL)) {
IDOS->Printf("BaudRate: %ld\n",
((struct SerialPrefs *)sp->sp_Data)->sp_BaudRate);
/* etc */
}
}

IIFF->CloseIFF(iffhandle);
}

if (ifferror != IFFERR_EOF) {
rargs[1] = (LONG)IFFErrTxt[-ifferror - 1];
IDOS->VFPrintf(IDOS->Output(), "%s: %s\n", rargs);
rc = RETURN_FAIL;
}

IDOS->Close(iffhandle->iff_Stream);
} else
error = IoErr();

IIFF->FreeIFF(iffhandle);
} else {
IDOS->VFPrintf(Output(), "Can't allocate IFF handle\n", NULL);
rc = RETURN_FAIL;
}

IDOS->FreeArgs(readargs);
} else
error = IoErr();

IDOS->SetIoErr(error);
if (error) {
rc = RETURN_FAIL;
IDOS->PrintFault(error, filename);
}
} else {
rc = RETURN_FAIL;
}

IExec->DropInterface((struct Interface*)IIFF);
IExec->CloseLibrary(IFFParseBase);

return(rc);
}
</syntaxhighlight>

== Preferences in 1.3 and Older Versions of the OS ==

In 1.3, the Preferences program allows the user to see and change many system wide parameters, like the Workbench colors, pointer image, printer settings etc. When a Preferences item is changed, the new setting can be used temporarily (until a reset occurs) or stored permanently in the "DEVS:system-configuration" file. Under 1.3, all Preferences items are stored in this file which the system reads at boot time to find out how to set various system-wide options.

<syntaxhighlight lang="C" line>
struct Preferences *GetPrefs(struct Preferences *preferences, LONG size);
struct Preferences *GetDefPrefs(struct Preferences *preferences, LONG size);
struct Preferences *SetPrefs( struct Preferences *preferences, LONG size, BOOL inform );
</syntaxhighlight>

None of these functions should be used in any new programs. They are only present for backwards compatibility.

== Function Reference ==

The following are brief descriptions of the system functions that relate to the use of Preferences. See the SDK for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| GetPrefs()
| Old 1.3 (V34) function for making a copy of the Preferences structure
|-
| SetPrefs()
| Old 1.3 (V34) function for overwriting Preferences with new data
|-
| GetDefPrefs()
| Old 1.3 (V34) function for copying default Preferences from ROM
|-
| StartNotify()
| DOS library function for monitoring a .prefs file for changes
|-
| EndNotify()
| Ends notification started with StartNotify()
|-
| AllocIFF()
| IFFParse library function that creates an IFFHandle for parsing
|-
| InitIFFasDOS()
| Initialize the IFFHandle as a DOS stream
|-
| OpenIFF()
| Initialize an IFFHandle for reading or writing a new stream
|-
| PropChunk()
| Specify a property chunk to store
|-
| ParseIFF()
| Parse an IFF file from the IFFHandle stream
|-
| CurrentChunk()
| Returns the top level context of an IFF stream
|-
| FindProp()
| Search for a property chunk previously declared with PropChunk()
|-
| CloseIFF()
| Closes an IFF context opened with OpenIFF()
|-
| FreeIFF()
| Frees the IFFHandle created with AllocIFF()
|}

Console Device

2025-01-26T19:36:02Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

[[Category:Devices|Console]]
== Console Device ==

The console device provides the text-oriented interface for Intuition windows. It acts like an enhanced ASCII terminal obeying many of the standard ANSI sequences as well as special sequences unique to the Amiga. The console device also provides a copy-and-paste facility and an internal character map to redraw a window when it is resized.

== Console Device Commands and Functions ==

{| class="wikitable"
! Command
! Command Operation
|-
| CD_ASKDEFAULTKEYMAP || Get the current default keymap.
|-
| CD_ASKKEYMAP || Get the current key map structure for this console.
|-
| CD_ASKKEYMAP_POINTERS || Get pointers to the current key map structures for this console. (V51.19)
|-
| CD_GETATTRS || Get attributes for this console. (V53)
|-
| CD_SETATTRS || Set attributes for this console. (V53)
|-
| CD_SETDEFAULTKEYMAP || Set the current default keymap.
|-
| CD_SETKEYMAP || Set the current key map structure for this console.
|-
| CD_SETKEYMAP_POINTERS || Set the current key map structures for the console. (V51.19)
|-
| CMD_CLEAR || Remove any reports waiting to satisfy read requests from the console input buffer.
|-
| CMD_READ || Read the next input, generally from the keyboard. The form of this input is as an ANSI byte stream.
|-
| CMD_WRITE || Write a text record to the display interpreting any ANSI control characters in the record.
|}

Console Device Functions:

{| class="wikitable"
| CDInputHandler() || Handle an input event for the console device.
|-
| RawKeyConvert() || Decode raw input classes and convert input events of type IECLASS_RAWKEY to ANSI bytes based on the keymap in use.
|}

== Device Interface ==

The console device operates like the other Amiga devices. To use it, you must first open the console device, then send I/O requests to it, and then close it when finished. See [[Exec_Device_I/O|Exec Device I/O]] for general information on device usage.

The I/O request used by the console device is called IOStdReq.

<syntaxhighlight lang="C" line>
struct IOStdReq
{
struct Message io_Message;
struct Device *io_Device; /* device node pointer */
struct Unit *io_Unit; /* unit (driver private)*/
UWORD io_Command; /* device command */
UBYTE io_Flags;
BYTE io_Error; /* error or warning num */
ULONG io_Actual; /* actual number of bytes transferred */
ULONG io_Length; /* requested number bytes transferred*/
APTR io_Data; /* points to data area */
ULONG io_Offset; /* offset for block structured devices */
};
</syntaxhighlight>

See the include file exec/io.h for the complete structure definition.

=== Console Device Units ===

The console device provides four units, three that require a console window and one that does not. The unit type is specified when you open the device. See the [[#Opening the Console Device|Opening the Console Device]] section below for more details.

The CONU_STANDARD unit (0) is generally used with a SMART_REFRESH window. This unit has the least amount of overhead (e.g., memory usage and rendering time), and is highly compatible with all versions of the operating system.

There are two variations of character mapped console units. Both must be used with SIMPLE_REFRESH windows and both have the ability to automatically redraw a console window when resized or revealed.

A character mapped console can be opened which allows the user to drag-select text with the mouse and '''Copy''' the highlighted area. The copied text can then be '''Paste'''d into other console windows or other windows which support reading data from the [[Clipboard_Device|clipboard device]].

Character mapped console units have more overhead than standard consoles (e.g., rendering times and memory usage).

The CONU_LIBRARY unit (-1) does not require a console window. It is designed to be primarily used with the console device functions and also with the console device commands that do not require a console window.

The Amiga uses the [http://www.ecma-international.org/publications/standards/Ecma-094.htm ECMA-94 Latin 1 International 8-bit] character set.

=== Opening the Console Device ===

Four primary steps are required to open the console device:

# Create a message port using AllocSysObject(ASOT_PORT). Reply messages from the device must be directed to a message port.
# Create an I/O request structure of type IOStdReq. The IOStdReq structure is created by the AllocSysObject(ASOT_IOREQUEST) function. AllocSysObject() will initialize your I/O request to point to your reply port.
# Open an Intuition window and set a pointer to it in the io_Data field of the IOStdReq and the size of the window in the io_Length field. This is the window to which the console will be attached. The window must be SIMPLE_REFRESH for use with the CONU_CHARMAP and CONU_SNIPMAP units.
# Open the console device. Call OpenDevice() passing it the I/O request and the type of console unit set in the unit and flags fields. Console unit types and flag values are listed below.

Console device units:

; CONU_LIBRARY
: Return the device library vector pointer used for calling console device functions. No console is opened.

; CONU_STANDARD
: Open a standard console.

; CONU_CHARMAP
: Open a console with a character map.

; CONU_SNIPMAP
: Open a console with a character map and copy-and-paste support.

; CONU_HISTORY (V53)
: Similar to CONU_SNIPMAP with content history and tabbed windows.

See the include file devices/conunit.h for the unit definitions and the SDK for an explanation of each unit.

{{Note|title=No Changes Required|text=CONU_STANDARD has a numeric value of zero to insure compatibility with pre-V36 applications. CONU_LIBRARY has a numeric value of negative one and is also compatible with pre-V36 applications.}}

Console device flags:

; CONFLAG_DEFAULT
: The console device will redraw the window when it is resized.

; CONFLAG_NODRAW_ON_NEWSIZE
: The console device will not redraw the window when it is resized

; CONFLAG_CREATE_WINDOW and CONFLAG_TABBED_WINDOW (V53)
: These bits define the combinations of window source, tabs and sharing. These are only applicable when using CONUNIT_HISTORY or greater.

; CONFLAG_SYNC_WRITES (V53)
: Forces a task issuing a Write request to wait until the request is complete before returning to the caller.

The character map units are the only units which use the flags parameter to set how the character map is used. CONU_STANDARD units ignore the flags parameter. See the console.doc autodoc for the most up to date information.

See the include file devices/conunit.h for the flag definitions and the SDK for an explanation of the flags.

<syntaxhighlight lang="C" line>
struct NewWindow nw =
{
10, 10, /* starting position (left,top) */
620,180, /* width, height */
-1,-1, /* detailpen, blockpen */
CLOSEWINDOW, /* flags for idcmp */
WINDOWDEPTH|WINDOWSIZING|
WINDOWDRAG|WINDOWCLOSE|
SIMPLE_REFRESH|ACTIVATE, /* window flags */
NULL, /* no user gadgets */
NULL, /* no user checkmark */
"Console Test", /* title */
NULL, /* pointer to window screen */
NULL, /* pointer to super bitmap */
100,45, /* min width, height */
640,200, /* max width, height */
WBENCHSCREEN /* open on workbench screen */
};

/* Create reply port console */
struct MsgPort *ConsoleMP = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "RKM.Console",
TAG_END);
if (ConsoleMP == NULL)
cleanexit("Can't create write port\n", RETURN_FAIL);

/* Create message block for device I/O */
struct IOStdReq *ConsIO = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOStdReq),
ASOIOR_ReplyPort, ConsoleMP,
TAG_END);
if (ConsIO == NULL)
cleanexit("Can't create IORequest\n", RETURN_FAIL);

/* Open a window --- we assume intuition.library is already open */
struct Window *win = IIntuition->OpenWindow(&nw);
if (win == NULL)
cleanexit("Can't open window\n",RETURN_FAIL);

/* Set window pointer and size in I/O request */
ConsIO->io_Data = (APTR) win;
ConsIO->io_Length = sizeof(struct Window);

/* Open the console device */
if (error = IExec->OpenDevice("console.device", CONU_CHARMAP, ConsIO, CONFLAG_DEFAULT))
cleanexit("Can't open console.device\n",RETURN_FAIL);
</syntaxhighlight>

=== Closing the Console Device ===

Each OpenDevice() must eventually be matched by a call to CloseDevice().

All I/O requests must be complete before CloseDevice(). If any requests are still pending, abort them with AbortIO().

<syntaxhighlight lang="C" line>
if (!(IExec->CheckIO(ConsIO)))
IExec->AbortIO(ConsIO); /* Ask device to abort any pending requests */

IExec->WaitIO(ConsIO); /* Wait for abort, then clean up */
IExec->CloseDevice(ConsIO); /* Close console device */
</syntaxhighlight>

== About Console I/O ==

The console device may be thought of as a kind of terminal. You send character streams to the console device; you also receive them from the console device. These streams may be characters, control sequences or a combination of the two.

Console I/O is closely associated with the Amiga Intuition interface; a console must be tied to a window that is already opened. From the Window data structure, the console device determines how many characters it can display on a line and how many lines of text it can display in a window without clipping at any edge.

You can open the console device many times, if you wish. The result of each open call is a new console unit. AmigaDOS and Intuition see to it that only one window is currently active and its console, if any, is the only one (with a few exceptions) that receives notification of input events, such as keystrokes. Later in this article you will see that other Intuition events can be sensed by the console device as well.

{{Note|title=Introducing...|text=For this entire article the characters <CSI> represent the ''control sequence introducer''. For output you may use either the two-character sequence <Esc>[ (0x1B 0x5B) or the one-byte value 0x9B. For input you will receive 0x9B unless the sequence has been typed by the user.}}

=== Exec Functions and the Console Device ===

The various Exec functions such as DoIO(), SendIO(), AbortIO() and CheckIO() operate normally. The only caveats are that CMD_WRITE may cause your application to wait internally, even with SendIO(), and a task using CMD_READ to wait on a response from a console is at the user’s mercy. If the user never reselects that window, and the console response provides the only wake-up call, that task will sleep forever.

=== General Console Screen Output ===

Console character screen output (as compared to console command sequence transmission) outputs all standard printable characters (character values hex 20 through 7E and A0 through FF) normally.

Many control characters such as '''Backspace''' (0x08) and '''Return''' (0x0D) are translated into their exact ANSI equivalent actions. The '''Line feed''' character (0x0A) is a bit different in that it can be translated into a '''Return/Line feed''' action. The net effect is that the cursor moves to the first column of the next line whenever an <LF> is displayed. This option is set via the mode control sequences discussed under “Control Sequences for Window Output.”

=== Console Keyboard Input ===

If you read from the console device, the keyboard inputs are preprocessed for you and you will get ASCII characters, such as “B.” Most normal text-gathering programs will read from the console device in this manner. Some programs may also ask to receive raw events in their console stream. Keypresses are converted to ASCII characters or CSI sequences via the keymap associated with the unit.

== Writing to the Console Device ==

You write to the console device by passing an I/O request to the device with a pointer to the write buffer set in io_Data, the number of bytes in the buffer set in io_Length and CMD_WRITE set in io_Command.

<syntaxhighlight lang="C" line>
CONST_STRPTR outstring= "Make it so";

ConsIO->io_Data = outstring;
ConsIO->io_Length = IUtility->Strlen(outstring);
ConsIO->io_Command = CMD_WRITE;
IExec->DoIO(ConsIO);
</syntaxhighlight>

You may also send NULL-terminated strings to the console device in the same manner except that io_Length must be set to -1.

<syntaxhighlight lang="C" line>
ConsIO->io_Data = "\033[3mOh boy.";
ConsIO->io_Length = -1;
ConsIO->io_Command = CMD_WRITE;
IExec->DoIO(ConsIO);
</syntaxhighlight>

The fragment above will output the string “Oh boy.” in italics. Keep in mind that setting the text rendition to italics will remain in effect until you specifically instruct the console device to change it to another text style.

=== Synchronized Writes ===

Synchronized writes were the only option for Console Device before version 53.38. Returning from the Write call means that the data has been transferred from the caller's buffer and the IORequest structure contents are no longer required. The data may not yet have been written to the display and any effects caused by the data (e.g. change of cursor position) may not yet have started or been completed.

If the Console was opened in legacy mode (no TABBED or HISTORY options), then the SYNCWRITES option is forced for greater compatibility with older applications. Otherwise, the Console is opened with synchronized writes disabled. This enables the application to continue to do work while the Console works in parallel.

You can still force the Write operation to block until completed by opening the Console with the CONFLAG_SYNC_WRITES set or (for a Shell) including the option SYNCWRITES in the command line.

If you do not want to wait for all Write requests, you can set the IOF_WAIT_WRITE bit in the io_Flags byte before calling CMD_WRITE. This flag bit has the same effect as opening the console with the CONFLAG_SYNC_WRITES set, but its scope is limited to the current IORequest.

=== Control Sequences for Window Output ===

The following table lists functions that the console device supports, along with the character stream that you must send to the console to produce the effect. For more information on the control sequences, consult the console.doc in the SDK. The table uses the second form of <CSI>, that is, the hex value 0x9B, to minimize the number of characters to be transmitted to produce a function.

A couple of notes about the table. If an item is enclosed in square brackets, it is optional and may be omitted. For example, for '''Insert [N] Characters''' the value for ''N'' is shown as optional. The console device responds to such optional items by treating the value of ''N'' as 1 if it is not specified. The value of ''N'' or ''M'' is always a decimal number, having one or more ASCII digits to express its value.

{| class="wikitable"
|+ ANSI Console Control Sequences
! Console Command
! Comment
! Sequence of Characters (in Hexadecimal Form)
|-
| Bell || Flash the display—do an Intuition DisplayBeep() || 07
|-
| Backspace || Move left one column || 08
|-
| Horizontal Tab || Move right one tab stop || 09
|-
| Line Feed || Move down one text line as specified by the mode function || 0A
|-
| Vertical Tab || Move up one text line || 0B
|-
| Form Feed || Clear the console’s window || 0C
|-
| Carriage Return || Move to first column || 0D
|-
| Shift In || Undo Shift Out || OE
|-
| Shift Out || Set MSB of each character before displaying || 0F
|-
| Esc || Escape can be part of the control sequence introducer || 1B
|-
| Index || Move the active position down one line || 84
|-
| Next Line || Go to the beginning of the next line || 85
|-
| Horizontal Tabulation || Set a tab at the active cursor position || 88
|-
| Reverse Index || Move the active position up one line || 8D
|-
| CSI || Control sequence introducer || 9B
|-
| Reset to Initial State || || 1B 63
|-
| Insert [N] Characters || Insert one or more spaces, shifting the remainder of the line to the right || 9B [N] 40
|-
| Cursor Up [N] Character Positions || (default = 1) || 9B [N] 41
|-
| Cursor Down [N] Character Positions || (default = 1) || 9B [N] 42
|-
| Cursor Forward [N] Character Positions || (default = 1) || 9B [N] 43
|-
| Cursor Backward [N] Character Positions || (default = 1) || 9B [N] 44
|-
| Cursor Position || Where ''N'' is row, ''M'' is column, and semicolon (hex 3B) must be present as a separator, or if row is left out, so the console device can tell that the number after the semicolon actually represents the column number || 9B [N] [3B M] 48
|-
| Cursor Horizontal Tabulation || move cursor forward to ''N''th tab position || 9B [N] 49
|-
| Cursor Next Line [N] || (to column 1) || 9B [N] 45
|-
| Cursor Preceding Line [N] || (to column 1) || 9B [N] 46
|-
| Erase in Display || (only to end of display) || 9B 4A
|-
| Erase in Line || (only to end of line) || 9B 4B
|-
| Insert Line || Above the line containing the cursor || 9B 4C
|-
| Delete Line || Remove current line, move all lines up one position to fill gap, blank bottom line || 9B 4D
|-
| Delete Character [N] || That cursor is sitting on and to the right if [N] is specified || 9B [N] 50
|-
| Scroll up [N] Lines || Remove line(s) from top of window, move all other lines up, blanks [N] bottom lines || 9B [N] 53
|-
| Scroll down [N] Lines || Remove line(s) from bottom of window, move all other lines down, blanks [N] top lines || 9B [N] 54
|-
| Cursor Tabulation Control || where ''N''=0 set tab, ''N''=2 clear tab, ''N''=5 clear all tabs || 9B [N] 57
|-
| Cursor Backward Tabulation || move cursor backward to ''N''th tab position || 9B [N] 5A
|-
| Set Line Feed Mode || Cause '''Line Feed''' to respond as Return-Line Feed || 9B 32 30 68
|-
| Reset Newline Mode || Cause '''Line Feed''' to respond only as Line Feed || 9B 32 30 6C
|-
| Device Status Report || Cause console device to insert a '''Cursor''' Position Report into your read stream; see “Reading from the Console Device” for more information || 9B 36 6E
|-
| Select Graphic Rendition || Select text style (K), character color (L), character cell color (M), background color (N). See note below. || 9B K 3B 3L 3B 4M 3B >N 6D
|}

For '''Select Graphic Rendition''', any number of parameters, in any order, are valid. They are separated by semicolons. The parameters follow:

{| class="wikitable"
| 0 || Plain text
|-
| 1 || Boldface
|-
| 2 || faint (secondary color)
|-
| 3 || Italic
|-
| 4 || Underscore
|-
| 5 || Set slow character blink (V53.5)
|-
| 6 || Set fast character blink (V53.5)
|-
| 7 || Reversed character/cell colors
|-
| 8 || Concealed mode
|-
| 22 || Normal color, not bold (V36)
|-
| 23 || Italic off (V36)
|-
| 24 || Underscore off (V36)
|-
| 25 || Slow blink off (V53.5)
|-
| 26 || Fast blink off (V53.5)
|-
| 27 || Reversed off (V36)
|-
| 28 || Concealed off (V36)
|-
| 29 || Strike-through off (V53.5)
|}

{| class="wikitable"
| 30–37 || System colors 0–7 for character color.
|-
| 39 || Reset to default character color
|}

{| class="wikitable"
|+ Transmitted as two ASCII characters.
| 40–47 || System colors 0–7 for character cell color.
|-
| 39 || Reset to default character color
|}

{| class="wikitable"
|+ Transmitted as two ASCII characters
| >0–7 || System colors 0–7 for background color. (V36)
|}

You must specify the “>” in order for this to be recognized and it must be the last parameter.

For example, to select bold face, with color 3 as the character color, and color 0 as the character cell color and the background color, send the hex sequence:

<pre>9B 31 3B 33 33 3B 34 30 3B 3E 30 6D</pre>
representing the ASCII sequence:

<pre><CSI>1;33;40;>0m</pre>
where <CSI> is the control sequence introducer, here used as the single character value 0x9B.

{{Note|title=Go Easy On The Eyes|text=In most cases, the character cell color and the background color should be the same.}}

==== Set Graphic Rendition Implementation Notes ====

The sequences in the next table are not ANSI standard sequences, they are private Amiga sequences. In these command descriptions, length, width, and offset are comprised of one or more ASCII digits, defining a decimal value.

{| class="wikitable"
|+ Amiga Console Control Sequences
! Console Command
! Comment
! Sequence of Characters (in Hexadecimal Form)
|-
| Enable Scroll || (this is the default) || 9B 3E 31 68
|-
| Disable Scroll || || 9B 3E 31 6C
|-
| Autowrap On || (the default) || 9B 3F 37 68
|-
| Autowrap Off || || 9B 3F 37 6C
|-
| Set Page Length || In character raster lines, causes console to recalculate, using current font, how many text lines will fit on the page || 9B <length> 74
|-
| Set Line Length || In character positions, using current font, how many characters should be placed on each line
|| 9B <width> 75
|-
| Set Left Offset || In raster columns, how far from the left of the window should the text begin || 9B <offset> 78
|-
| Set Top Offset || In raster lines, how far from the top of the window’s RastPort should the topmost line of the character begin || 9B <offset> 79
|-
| Set Raw Events || Set the raw input events that will trigger an '''Input Event Report'''. see the “Selecting Raw Input Events” section below for more details. || 9B <events> 7B
|-
| Input Event Report || Returned by the console device in response to a raw event set by the '''Set Raw Event''' sequence. See the “Input Event Reports” section below for more details. || 9B <parameters> 7C
|-
| Reset Raw Events || Reset the raw events set by the '''Set Raw Event''' sequence. see the “Selecting Raw Input Events” section below. || 9B <events> 7D
|-
| Special Key Report || Returned by the console device whenever '''Help''', or one of the function keys or arrow keys is pressed. Some sequences do not end with 7E || 9B <keyvalue> 7E
|-
| Set Cursor Rendition || Make the cursor visible or invisible; turning off the cursor increases text output speed || 9B N 20 70 Invisible = 9B 30 20 70 Visible = 9B 20 70
|-
| Window Status Request || Ask the console device to tell you the current bounds of the window, in upper and lower row and column character positions. User may have resized or repositioned it. See “Window Bounds Report” below. || 9B 30 20 71
|-
| Window Bounds Report || Returned by the console device in response to a '''Window Status Request''' sequence || 9B 31 3B 31 3B <bottom margin> 3B <right margin> 72
|-
| Right ‘Amiga V’ Press || Returned by the console device when the user presses '''Right-Amiga-V'''. See the “Copy and Paste Support” section below for more details. || 9B 30 20 76
|}

{{Note|title=Give Back What You Take|text=The console device normally handles the '''Set Page Length''', '''Set Line Length''', '''Set Left Offset''', and '''Set Top Offset''' functions automatically. To allow it to do so again after setting your own values, send the functions without a parameter.}}

=== Example Console Control Sequences ===

{| class="wikitable"
| Move cursor right by 1 || <CSI>C or <CSI>1C || 9B 43 9B 31 43
|-
| Move cursor right by 20 || <CSI>20C || 9B 32 30 43
|-
| Move cursor to upper-left corner (Home Position) || <CSI>H or <CSI>1;1H or <CSI>;1H or <CSI>1;H || 9B 48 9B 31 3B 31 48 9B 3B 31 48 9B 31 3B 48
|-
| Move cursor to the fourth column of the first line of the window || <CSI>1;4H or <CSI>;4H || 9B 31 3B 34 48 9B 3B 34 48
|-
| Clear the window || <FF> or Ctrl-L (clear window) or <CSI>H<CSI>J (home and clear to end of window) || 0C 9B 48 9B 4A
|}

== Reading from the Console Device ==

Reading input from the console device returns an ANSI 3.64 standard byte stream. This stream may contain normal characters and/or raw input event information. You may also request other raw input events using the '''Set Raw Events''' and '''Reset Raw Events''' control sequences discussed below. See “Selection of Raw Input Events.”

Generally, console reads are performed asynchronously so that your program can respond to other events and other user input (such as menu selections) when the user is not typing on the keyboard. To perform asynchronous I/O, an I/O request is sent to the console using the SendIO() function (rather than a synchronous DoIO() which would wait until the read request returned with a character).

You read from the console device by passing an I/O request to the device with a pointer to the read buffer set in io_Data, the number of bytes in the buffer set in io_Length and CMD_READ set in io_Command.

<syntaxhighlight lang="C" line>
#define READ_BUFFER_SIZE 25
char ConsoleReadBuffer[READ_BUFFER_SIZE];

ConsIO->io_Data = (APTR)ConsoleReadBuffer;
ConsIO->io_Length = READ_BUFFER_SIZE;
ConsIO->io_Command = CMD_READ;
IExec->SendIO(ConsIO);
</syntaxhighlight>

{{Note|title=You May Get Less Than You Bargained For|text=A request for more than one character may be satisfied by the receipt of only one character. If you request more than one character, you will have to examine the io_Actual field of the request when it returns to determine how many characters you have actually received.}}

After sending the read request, your program can wait on a combination of signal bits including that of the reply port you created. The following fragment demonstrates waiting on both a queued console read request, and Window IDCMP messages:

<syntaxhighlight lang="C" line>
uint32 conreadsig = 1 << ConsoleMP->mp_SigBit;
uint32 windowsig = 1 << win->UserPort->mp_SigBit;

/* A character, or an IDCMP msg, or both will wake us up */
ULONG signals = IExec->Wait(conreadsig | windowsig);

if (signals & conreadsig)
{
/* Then check for a character */
};

if (signals & windowsig)
{
/* Then check window messages */
};
</syntaxhighlight>

=== Information About the Input Stream ===

For the most part, keys whose keycaps are labeled with ANSI-standard characters will ordinarily be translated into their ASCII-equivalent character by the console device through the use of its keymap. Keymap information can be found in [[Keymap_Library|Keymap Library]].

For keys other than those with normal ASCII equivalents, an escape sequence is generated and inserted into your input stream. For example, in the default state (no raw input events selected) the function, arrow and special keys (reserved for 101 key keyboards) will cause the sequences shown in the next table to be inserted in the input stream.

{| class="wikitable"
|+ Special Key Report Sequences
! Key
! Unshifted Sends
! Shifted Sends
! Comment
|-
| F1 || <CSI>0 || <CSI>10 ||
|-
| F2 || <CSI>1 || <CSI>11 ||
|-
| F3 || <CSI>2 || <CSI>12 ||
|-
| F4 || <CSI>3 || <CSI>13 ||
|-
| F5 || <CSI>4 || <CSI>14 ||
|-
| F6 || <CSI>5 || <CSI>15 ||
|-
| F7 || <CSI>6 || <CSI>16 ||
|-
| F8 || <CSI>7 || <CSI>17 ||
|-
| F9 || <CSI>8 || <CSI>18 ||
|-
| F10 || <CSI>9 || <CSI>19 ||
|-
| F11 || <CSI>20 || <CSI>30 || (101 key keyboard)
|-
| F12 || <CSI>21 || <CSI>31 || (101 key keyboard)
|-
| Help || <CSI>? || <CSI>? || (same sequence for both)
|-
| Insert || <CSI>40 || <CSI>50 || (101 key keyboard)
|-
| Page Up || <CSI>41 || <CSI>51 || (101 key keyboard)
|-
| Page Down || <CSI>42 || <CSI>52 || (101 key keyboard)
|-
| Pause/Break || <CSI>43 || <CSI>53 || (101 key keyboard)
|-
| Home || <CSI>44 || <CSI>54 || (101 key keyboard)
|-
| End || <CSI>45 || <CSI>55 || (101 key keyboard)
|-
| Cursor Up || <CSI>A || <CSI>T ||
|-
| Cursor Down || <CSI>B || <CSI>S ||
|-
| Cursor Left || <CSI>D || <CSI> A || (notice the space after <CSI>)
|-
| Cursor Right || <CSI>C || <CSI> @ || (notice the space after <CSI>)
|}

=== Cursor Position Report ===

If you have sent the '''Device Status Report''' command sequence, the console device returns a cursor position report into your input stream. It takes the form:

<pre>
<CSI><row>;<column>R
</pre>

For example, if the cursor is at column 40 and row 12, here are the ASCII values (in hex) you receive in a stream:

<pre>
9B 34 30 3B 31 32 52
</pre>

=== Window Bounds Report ===

A user may have either moved or resized the window to which your console is bound. By issuing a '''Window Status Report''' to the console, you can read the current position and size in the input stream. This window bounds report takes the following form:

<pre>
<CSI>1;1;<bottom margin>;<right margin> r
</pre>

The bottom and right margins give you the window row and column dimensions as well. For a window that holds 20 lines with 60 characters per line, you will receive the following in the input stream:

<pre>
9B 31 3B 31 3B 32 30 3B 36 30 20 72
</pre>

== Copy and Paste Support ==

As noted above, opening the console device with a unit of CONU_SNIPMAP allows the user to drag-select text with the mouse and copy the selection with '''Right-Amiga-C'''.

Internally, the snip is copied to a private buffer managed by the console device where it can be copied to other console device windows by pressing '''Right-Amiga-V'''.

However, your application should assume that the user is running the “Conclip” utility which is part of the standard Workbench 2.0 environment. Conclip copies snips from the console device to the clipboard device where they can be used by other applications which support reading from the clipboard.

When Conclip is running and the user presses '''Right-Amiga-V''', the console device puts an escape sequence in your read stream—<CSI>0 v (Hex 9B 30 20 76)—which tells you that the user wants to paste text from the clipboard.

Upon receipt of this sequence, your application should read the contents of the clipboard device, make a copy of any text found there and then release the clipboard so that it can be used by other applications. See [[Clipboard_Device|Clipboard Device]] for more information on reading data from it.

You paste what you read from the clipboard by using successive writes to the console. In order to avoid problems with excessively long data in the clipboard, you should limit the size of writes to something reasonable. (We define reasonable as no more than 1K per write with the ideal amount being 256 bytes.) You should also continue to monitor the console read stream for additional use input, paster requests and, possibly, '''Raw Input Events''' while you are doing this.

You should ''not'' open a character mapped console unit with COPY capability if you are unable to support '''Paste''' from the clipboard device. The user will reasonably expect to be able to '''Paste''' into windows from which a '''Copy''' can be done.

Keep in mind that users do make mistakes, so an '''Undo''' mechanism for aborting a '''Paste''' is highly desirable—particularly if the user has just accidentally pasted text into an application like a terminal program which is sending data at a slow rate.

{{Note|title=Use “CON:”, You’ll Be Glad You Did|text=It is highly recommended that you consider using the console-handler (CON:) if you want a console window with '''Copy''' and '''Paste''' capabilities. CON: provides you with free '''Paste''' support and is considerably easier to open and use than using the console device directly.}}

== Selecting Raw Input Events ==

If the keyboard information–including “cooked” keystrokes–does not give you enough information about input events, you can request additional information from the console driver.

The command to '''Set Raw Events''' is formatted as:

<pre>
<CSI>[event-types-separated-by-semicolons]{
</pre>

If, for example, you need to know when each key is pressed and released, you would request “Raw keyboard input.” This is done by writing <CSI>1<math>\{</math> to the console. In a single '''Set Raw Events''' request, you can ask the console to set up for multiple event types at one time. You must send multiple numeric parameters, separating them by semicolons (;). For example, to ask for gadget pressed, gadget released, and close gadget events, write:

<pre>
<CSI>7;8;11{
</pre>

You can reset, that is, delete from reporting, one or more of the raw input event types by using the '''Reset Raw Events''' command, in the same manner as the '''Set Raw Events''' was used to establish them in the first place. This command stream is formatted as:

<pre>
<CSI>[event-types-separated-by-semicolons]}
</pre>

So, for example, you could reset all of the events set in the above example by transmitting the command sequence:

<pre>
<CSI>7;8;11}
</pre>

{{Note|title=The Read Stream May Not Be Dry|text=There could still be pending '''Raw Input Events''' in your read stream after turning off one or more '''Raw Input Events'''.}}

The following table lists the valid raw input event types.

{| class="wikitable"
|+ Raw Input Event Types
! Request Number
! Request Description
|-
| 0 || No-op (used internally)
|-
| 1 || RAW keyboard input (Intuition swallows all except the select button)
|-
| 2 || RAW mouse input
|-
| 3 || Private Console Event
|-
| 4 || Pointer position
|-
| 5 || (unused)
|-
| 6 || Timer
|-
| 7 || Gadget pressed
|-
| 8 || Gadget released
|-
| 9 || Requester activity
|-
| 10 || Menu numbers
|-
| 11 || Close Gadget
|-
| 12 || Window resized
|-
| 13 || Window refreshed
|-
| 14 || Preferences changed
|-
| 15 || Disk removed
|-
| 16 || Disk inserted
|-
| 17 || Active window
|-
| 18 || Inactive window
|-
| 19 || New pointer position
|-
| 20 || Menu help
|-
| 21 || Window changed (zoom, move)
|}

The event types—requester, window refreshed, active window, inactive window, window resized and window changed—are dispatched to the console unit which owns the window from which the events are generated, even if it is not the active (selected ) window at the time the event is generated. This ensures that the proper console unit is notified of those events. All other events are dispatched to the active console unit (if it has requested those events).

== Input Event Reports ==

If you select any of these events you will start to get information about the events in the following form:

<pre>
<CSI><class>;<subclass>;<keycode>;<qualifiers>;<x>;<y>;<seconds>;<microseconds>|
</pre>

; <CSI>
: is a one-byte field. It is the “control sequence introducer,” 0x9B in hex.

; <class>
: is the raw input event type, from the above table.

; <subclass>
: is usually 0. If the mouse is moved to the right controller, this would be 1.

; <keycode>
: indicates which raw key number was pressed. This field can also be used for mouse information.

: {{Note|title=The Raw Key Might Be The Wrong Key|text=National keyboards often have different keyboard arrangements. This means that a particular raw key number may represent different characters on different national keyboards. The normal console read stream (as opposed to raw events) will contain the proper ASCII character for the keypress as translated according to the user’s keymap.}}

; <qualifiers>
: indicates the state of the keyboard and system. The qualifiers are defined as follows:

:{| class="wikitable"
|+ Input Event Qualifiers
! Bit
! Mask
! Key
! Comment
|-
| 0 || 0001 || Left shift
|-
| 1 || 0002 || Right shift
|-
| 2 || 0004 || Caps Lock || Associated keycode is special; see below
|-
| 3 || 0008 || Ctrl
|-
| 4 || 0010 || Left Alt
|-
| 5 || 0020 || Right Alt
|-
| 6 || 0040 || Left Amiga key pressed
|-
| 7 || 0080 || Right Amiga key pressed
|-
| 8 || 0100 || Numeric pad
|-
| 9 || 0200 || Repeat
|-
| 10 || 0400 || Interrupt || Not currently used.
|-
| 11 || 0800 || Multibroadcast || This window (active one) or all windows.
|-
| 12 || 1000 || Middle mouse button || (Not available on standard mouse)
|-
| 13 || 2000 || Right mouse button
|-
| 14 || 4000 || Left mouse button
|-
| 15 || 8000 || Relative mouse || Mouse coordinates are relative, not absolute.
|}

: The '''Caps Lock''' key is handled in a special manner. It generates a keycode only when it is pressed, not when it is released. However, the up/down bit (80 hex) is still used and reported. If pressing the '''Caps Lock''' key causes the LED to light, keycode 62 ('''Caps Lock''' pressed) is sent. If pressing the '''Caps Lock''' key extinguishes the LED, keycode 190 ('''Caps Lock''' released) is sent. In effect, the keyboard reports this key as held down until it is struck again.

; <x> and <y>
: filled by some classes with an Intuition address: x<<16+y.

; <seconds> and <microseconds>
: contain the system time stamp taken at the time the event occurred. These values are stored as longwords by the system.

With RAW keyboard input selected, keys will no longer return a simple one-character “A” to “Z” but will instead return raw keycode reports of the form:

<pre>
<CSI>1;0;<keycode>;<qualifiers>;<prev1>;<prev2>;<seconds>;<microseconds>|
</pre>

For example, if the user pressed and released the '''A''' key with the '''Left Shift''' and '''Right Amiga''' keys also pressed, you might receive the following data:

<pre>
<CSI>1;0;32;32769;14593;5889;421939940;316673|
<CSI>1;0;160;32769;0;0;421939991;816683|
</pre>

The <keycode> field is an ASCII decimal value representing the key pressed or released. Adding 128 to the pressed key code will result in the released keycode.

The <prev1> and <prev2> fields are relevant for the interpretation of keys which are modifiable by dead-keys (see “Dead-Class Keys” section). The <prev1> field shows the previous key pressed. The lower byte shows the qualifier, the upper byte shows the key code. The <prev2> field shows the key pressed before the previous key. The lower byte shows the qualifier, the upper byte shows the key code.

== Using the Console Device Without a Window ==

Most console device processing involves a window, but there are functions and special commands that may be used without a window. To use the console device without a window, you call OpenDevice() with the console unit CONU_LIBRARY.

The console device functions are CDInputHandler() and RawKeyConvert(); they may only be used with the CONU_LIBRARY console unit. The console device commands which do not require a window are CD_ASKDEFAULTKEYMAP and CD_SETDEFAULTKEYMAP; they be used with any console unit. The advantage of using the commands with the CONU_LIBRARY unit is the lack of overhead required for CONU_LIBRARY because it doesn’t require a window.

To use the functions requires the following steps:

* Declare the console device base address variable ConsoleDevice in the global data area.
* Declare storage for an I/O request of type IOStdReq.
* Open the console device with CONU_LIBRARY set as the console unit.
* Set the console device base address variable to point to the device library vector which is returned in io_Device.
* Call the console device function(s).
* Close the console device when you are finished.

<syntaxhighlight lang="C" line>
#include <devices/conunit.h>

int main()
{
struct IOStdReq ConsIO = {0};

/* Open the device with CONU_LIBRARY for function use */
if (0 == IExec->OpenDevice("console.device", CONU_LIBRARY, (struct IORequest *)&ConsIO, 0))
{
/* Set the base address variable to the device library vector */
struct ConsoleDevice *ConsoleDevice = (struct ConsoleDevice *)ConsIO.io_Device;
struct ConsoleIFace *IConsole = (struct ConsoleIFace*)
IExec->GetInterface((struct Library*)ConsoleDevice, "main", 1, NULL);

.
. (console device functions would be called here)
.

IExec->DropInterface((struct Interface *)IConsole);
IExec->CloseDevice(ConsIO);
}
}
</syntaxhighlight>

The code fragment shows only the steps outlined above, it is not complete in any sense of the word. For a complete example of using a console device function, see the ''rawkey.c'' code example in the [[Intuition_Keyboard|Intuition Keyboard]]. The example uses the RawKeyConvert() function.

To use the commands with the CONU_LIBRARY console unit, you follow the same steps that were outlined in [[#Opening the Console Device|Opening the Console Device]].

<syntaxhighlight lang="C" line>
struct KeyMap *keymap; /* pointer to keymap */

/* Create the message port */
struct MsgPort *ConsoleMP = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);
if (ConsoleMP != NULL)
{
/* Create the I/O request */
struct IOStdReq *ConsoleIO = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOStdReq),
ASOIOR_ReplyPort, ConsoleMP,
TAG_END);

if (ConsoleIO != NULL)
{
/* Open the Console device */
if (IExec->OpenDevice("console.device", CONU_LIBRARY, (struct IORequest *)ConsoleIO, 0))

/* Inform user that it could not be opened */
IDOS->Printf("Error: console.device did not open\n");
else
{
/* Allocate memory for the keymap */
if (keymap = (struct KeyMap *)
AllocVecTags(sizeof(struct KeyMap), AVT_ClearWithValue, 0, TAG_END))
{
/* device opened, send CD_ASKKEYMAP command to it */
ConsoleIO->io_Length = sizeof(struct KeyMap);
ConsoleIO->io_Data = (APTR)keymap; /* where to put it */
ConsoleIO->io_Command = CD_ASKKEYMAP;
IExec->DoIO((struct IORequest *)ConsoleIO))
}

IExec->CloseDevice(ConsIO);
}
</syntaxhighlight>

Again, as in the previous code fragment, this is not complete and you should only use it as a guide.

== Console Device Caveats ==

<ul>
<li>Only one console unit can be attached per window. Sharing a console window must be done at a level higher than the device.</li>
<li>Do not mix graphics.library calls with console rendering in the same areas of a window. It is permissible to send console sequences to adjust the area in which console renders, and use graphics.library calls to render outside of the area console is using.
For example, do not render text with console sequences and scroll using the graphics.library ScrollRaster() function.</li>
<li>The character map feature is private and cannot be accessed by the programmer. Implementation details and behaviors of the character map my change in the future.</li>
<li>Do not use an IDCMP with character mapped consoles. All Intuition messages should be obtained via '''Raw Input Events''' from the console device.</li></ul>

== Console Device Example Code ==

The following is a console device demonstration program with supporting routines:

<syntaxhighlight lang="C" line>
/*
* Console.c
*
* Example of opening a window and using the console device
* to send text and control sequences to it. The example can be
* easily modified to do additional control sequences.
*
* Run from CLI only.
*/

#include <exec/types.h>
#include <exec/io.h>
#include <exec/memory.h>
#include <intuition/intuition.h>
#include <libraries/dos.h>
#include <devices/console.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/utility.h>

/* Note - using two character <CSI> ESC[. Hex 9B could be used instead */
#define RESETCON "\033c"
#define CURSOFF "\033[0 p"
#define CURSON "\033[ p"
#define DELCHAR "\033[P"

/* SGR (set graphic rendition) */
#define COLOR02 "\033[32m"
#define COLOR03 "\033[33m"
#define ITALICS "\033[3m"
#define BOLD "\033[1m"
#define UNDERLINE "\033[4m"
#define NORMAL "\033[0m"

/* our functions */
void cleanexit(uint8 *,LONG);
void cleanup(void);
int8 OpenConsole(struct IOStdReq *,struct IOStdReq *, struct Window *);
void CloseConsole(struct IOStdReq *);
void QueueRead(struct IOStdReq *, uint8 *);
uint8 ConGetChar(struct MsgPort *, uint8 *);
LONG ConMayGetChar(struct MsgPort *, uint8 *);
void ConPuts(struct IOStdReq *, uint8 *);
void ConWrite(struct IOStdReq *, uint8 *, LONG);
void ConPutChar(struct IOStdReq *, uint8);

struct NewWindow nw =
{
10, 10, /* starting position (left,top) */
620,180, /* width, height */
-1,-1, /* detailpen, blockpen */
CLOSEWINDOW, /* flags for idcmp */
WINDOWDEPTH|WINDOWSIZING|
WINDOWDRAG|WINDOWCLOSE|
SMART_REFRESH|ACTIVATE, /* window flags */
NULL, /* no user gadgets */
NULL, /* no user checkmark */
"Console Test", /* title */
NULL, /* pointer to window screen */
NULL, /* pointer to super bitmap */
100,45, /* min width, height */
640,200, /* max width, height */
WBENCHSCREEN /* open on workbench screen */
};

/* Opens/allocations we'll need to clean up */
struct Library *IntuitionBase = NULL;
struct IntuitionIFace *IIntuition = NULL;
struct Window *win = NULL;
struct IOStdReq *writeReq = NULL; /* IORequest block pointer */
struct MsgPort *writePort = NULL; /* replyport for writes */
struct IOStdReq *readReq = NULL; /* IORequest block pointer */
struct MsgPort *readPort = NULL; /* replyport for reads */
BOOL OpenedConsole = FALSE;

BOOL FromWb;

int main(int argc, char **argv)
{
struct IntuiMessage *winmsg;
ULONG signals, conreadsig, windowsig;
LONG lch;
SHORT InControl = 0;
BOOL Done = FALSE;
uint8 ch, ibuf;
uint8 obuf[200];
int8 error;

FromWb = (argc==0) ? TRUE : FALSE;

IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
if(IIntuition == NULL)
cleanexit("Can't open intuition\n",RETURN_FAIL);

/* Create reply port and io block for writing to console */
writePort = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "RKM.console.write",
TAG_END);
if(writePort == NULL)
cleanexit("Can't create write port\n",RETURN_FAIL);

writeReq = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOStdReq),
ASOIOR_ReplyPort, writePort,
TAG_END);
if(writeReq == NULL)
cleanexit("Can't create write request\n",RETURN_FAIL);

/* Create reply port and io block for reading from console */
readPort = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "RKM.console.read",
TAG_END);
if(readPort == NULL)
cleanexit("Can't create read port\n",RETURN_FAIL);

readReq = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOStdReq),
ASOIOR_ReplyPort, readPort,
TAG_END);
if(readReq == NULL)
cleanexit("Can't create read request\n",RETURN_FAIL);

/* Open a window */
if(!(win = IIntuition->OpenWindow(&nw)))
cleanexit("Can't open window\n",RETURN_FAIL);

/* Now, attach a console to the window */
if(error = OpenConsole(writeReq, readReq, win))
cleanexit("Can't open console.device\n",RETURN_FAIL);
else OpenedConsole = TRUE;

/* Demonstrate some console escape sequences */
ConPuts(writeReq,"Here's some normal text\n");
IUtility->SNPrintf(obuf, sizeof(obuf), "%s%sHere's text in color 3 and italics\n", COLOR03, ITALICS);
ConPuts(writeReq,obuf);
ConPuts(writeReq,NORMAL);
IDOS->Delay(50); /* Delay for dramatic demo effect */
ConPuts(writeReq,"We will now delete this asterisk =*=");
IDOS->Delay(50);
ConPuts(writeReq,"\b\b"); /* backspace twice */
IDOS->Delay(50);
ConPuts(writeReq,DELCHAR); /* delete the character */
IDOS->Delay(50);

QueueRead(readReq,&ibuf); /* send the first console read request */

ConPuts(writeReq,"\n\nNow reading console\n");
ConPuts(writeReq,"Type some keys. Close window when done.\n\n");

conreadsig = 1 << readPort->mp_SigBit;
windowsig = 1 << win->UserPort->mp_SigBit;

while(!Done)
{
/* A character, or an IDCMP msg, or both could wake us up */
signals = IExec->Wait(conreadsig|windowsig);

/* If a console signal was received, get the character */
if (signals & conreadsig)
{
if((lch = ConMayGetChar(readPort,&ibuf)) != -1)
{
ch = lch;
/* Show hex and ascii (if printable) for char we got.
* If you want to parse received control sequences, such as
* function or Help keys, you would buffer control sequences
* as you receive them, starting to buffer whenever you
* receive 0x9B (or 0x1B[ for user-typed sequences) and
* ending when you receive a valid terminating character
* for the type of control sequence you are receiving.
* For CSI sequences, valid terminating characters
* are generally 0x40 through 0x7E.
* In our example, InControl has the following values:
* 0 = no, 1 = have 0x1B, 2 = have 0x9B OR 0x1B and [,
* 3 = now inside control sequence, -1 = normal end esc,
* -2 = non-CSI(no [) 0x1B end esc
* NOTE - a more complex parser is required to recognize
* other types of control sequences.
*/

/* 0x1B ESC not followed by '[', is not CSI seq */
if (InControl==1)
{
if(ch=='[') InControl = 2;
else InControl = -2;
}

if ((ch==0x9B)||(ch==0x1B)) /* Control seq starting */
{
InControl = (ch==0x1B) ? 1 : 2;
ConPuts(writeReq,"=== Control Seq ===\n");
}

/* We'll show value of this char we received */
if (((ch >= 0x1F)&&(ch <= 0x7E))||(ch >= 0xA0))
IUtility->SNPrintf(obuf, sizeof(obuf), "Received: hex %02x = %c\n",ch,ch);
else IUtility->SNPrintf(obuf, sizeof(obuf), "Received: hex %02x\n",ch);
ConPuts(writeReq,obuf);

/* Valid ESC sequence terminator ends an ESC seq */
if ((InControl==3)&&((ch >= 0x40) && (ch <= 0x7E)))
{
InControl = -1;
}
if (InControl==2) InControl = 3;
/* ESC sequence finished (-1 if OK, -2 if bogus) */
if (InControl < 0)
{
InControl = 0;
ConPuts(writeReq,"=== End Control ===\n");
}
}
}

/* If IDCMP messages received, handle them */
if (signals & windowsig)
{
/* We have to ReplyMsg these when done with them */
while (winmsg = (struct IntuiMessage *)IExec->GetMsg(win->UserPort))
{
switch(winmsg->Class)
{
case CLOSEWINDOW:
Done = TRUE;
break;
default:
break;
}
IExec->ReplyMsg((struct Message *)winmsg);
}
}
}

/* We always have an outstanding queued read request
* so we must abort it if it hasn't completed,
* and we must remove it.
*/
if(!(IExec->CheckIO(readReq))) IExec->AbortIO(readReq);
IExec->WaitIO(readReq); /* clear it from our replyport */

cleanup();
return RETURN_OK;
}

void cleanexit(uint8 *s,LONG n)
{
if(*s & (!FromWb)) IDOS->Printf(s);
cleanup();
exit(n);
}

void cleanup()
{
if(OpenedConsole) CloseConsole(writeReq);
IExec->FreeSysObject(ASOT_IOREQUEST, readReq);
IExec->FreeSysObject(ASOT_PORT, readPort);
IExec->FreeSysObject(ASOT_IOREQUEST, writeReq);
IExec->FreeSysObject(ASOT_PORT, writePort);
if(IIntuition != NULL && win != NULL) IIntuition->CloseWindow(win);
IExec->DropInterface((struct Interface *)IIntuition);
IExec->CloseLibrary(IntuitionBase);
}

/* Attach console device to an open Intuition window.
* This function returns a value of 0 if the console
* device opened correctly and a nonzero value (the error
* returned from OpenDevice) if there was an error.
*/
int8 OpenConsole(struct IOStdReq *writereq, struct IOStdReq *readreq, struct Window *window)
{
int8 error;

writereq->io_Data = (APTR) window;
writereq->io_Length = sizeof(struct Window);
error = IExec->OpenDevice("console.device", 0, writereq, 0);
readreq->io_Device = writereq->io_Device; /* clone required parts */
readreq->io_Unit = writereq->io_Unit;
return(error);
}

void CloseConsole(struct IOStdReq *writereq)
{
IExec->CloseDevice(writereq);
}

/* Output a single character to a specified console
*/
void ConPutChar(struct IOStdReq *writereq, uint8 character)
{
writereq->io_Command = CMD_WRITE;
writereq->io_Data = (APTR)&character;
writereq->io_Length = 1;
IExec->DoIO(writereq);
/* command works because DoIO blocks until command is done
* (otherwise ptr to the character could become invalid)
*/
}

/* Output a stream of known length to a console
*/
void ConWrite(struct IOStdReq *writereq, uint8 *string, LONG length)
{
writereq->io_Command = CMD_WRITE;
writereq->io_Data = (APTR)string;
writereq->io_Length = length;
IExec->DoIO(writereq);
/* command works because DoIO blocks until command is done
* (otherwise ptr to string could become invalid in the meantime)
*/
}

/* Output a NULL-terminated string of characters to a console
*/
void ConPuts(struct IOStdReq *writereq,uint8 *string)
{
writereq->io_Command = CMD_WRITE;
writereq->io_Data = (APTR)string;
writereq->io_Length = -1; /* means print till terminating null */
IExec->DoIO(writereq);
}

/* Queue up a read request to console, passing it pointer
* to a buffer into which it can read the character
*/
void QueueRead(struct IOStdReq *readreq, uint8 *whereto)
{
readreq->io_Command = CMD_READ;
readreq->io_Data = (APTR)whereto;
readreq->io_Length = 1;
IExec->SendIO(readreq);
}

/* Check if a character has been received.
* If none, return -1
*/
LONG ConMayGetChar(struct MsgPort *msgport, uint8 *whereto)
{
struct IOStdReq *readreq;

if (!(readreq = (struct IOStdReq *)IExec->GetMsg(msgport))) return(-1);
int temp = *whereto; /* get the character */
QueueRead(readreq,whereto); /* then re-use the request block */
return(temp);
}

/* Wait for a character
*/
uint8 ConGetChar(struct MsgPort *msgport, uint8 *whereto)
{
struct IOStdReq *readreq;

WaitPort(msgport);
readreq = (struct IOStdReq *)GetMsg(msgport);
int temp = *whereto; /* get the character */
QueueRead(readreq,whereto); /* then re-use the request block*/
return((uint8)temp);
}
</syntaxhighlight>

== Additional Information on the Console Device ==

Additional programming information on the console device can be found in the include files and the Autodocs for the console device. Both are contained in the SDK.

{| class="wikitable"
! Includes
|-
| devices/console.h
|-
| devices/conunit.h
|}

{| class="wikitable"
! AutoDocs
|-
| console.doc
|}

Programming AmigaOS 4: Utility - Little Helpers

2025-01-26T19:35:24Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

''This article was adapted from Amiga Future magazine's series on developing for AmigaOS....''

The inconspicuous AmigaOS 4 utility.library has been extended with some useful functions. So it's about time we took a closer look at it.

We have sub-divided the overall description into different sections. So, let's get started with part one, the very flexible taglists.

= Tag list improvements =

Extending function-calls and their parameters can be a complicated issue, without updating all the old sources. By using a tag list, you can include new tags very flexibly, so unknown tags will be ignored. So if you are running the program on an older system, these new options are not available. That means, tag lists will become more and more important. Many of these new functions are about creating, searching and filtering the tagslists. A complete overview about all the new functions can be found in the final section of this article.

<syntaxhighlight lang="C" line>
struct TagItem *taglist;

/* allocates memory for four pairs of tag-entries */
/* the fifth entry only includes the identification for the list-ending */
if((taglist = IUtility->AllocateTagItems(5)))
{
/* Fill the taglist */
taglist[0].ti_Tag = TAG_IGNORE;
taglist[0].ti_Data = 1;
...
taglist[4].ti_Tag = TAG_END;
taglist[4].ti_Data = 0;

/* do something wiht the taglist */
...

/*at the end the taglist memory can be deallocated*/
IUtility->FreeTagItems(taglist);
}
</syntaxhighlight>

= Check-digits =

The utility.library provides a list of interesting features for check-digits. There are a great number of different check-digits and algorithms (i.e. CR32, MD5). The Amiga allows you to calculate a 160 bit (= 20 byte) check-digit via the SHA-1 algorithm. This comes in handy, if you want to check over huge data sections, without having an identical number. In comparison to check-digits with only 2 respectively 4 bytes, this can become a real problem. In detail, there are 3 steps to be made.

First of all, you have to initialise the data structure by using the IUtility->MessageDigest_SHA_Unit() command. Second comes the actual calculation via the IUtility->MessageDigest_SHA_Update() command, whereas the data and the length must be given to create the check-digit.

Lastly we type in the IUtility->MessageDigest_SHA_Final() command. After completing all three steps, it's possible to get the calculated check-digit through mdsha_Code. The example below shows you how:

<syntaxhighlight lang="C" line>
struct MessageDigest_SHA mdsha = { 0 };
STRPTR testdata = "This is just a test";

IUtility->MessageDigest_SHA_Init(&mdsha);
IUtility->MessageDigest_SHA_Update(&mdsha, testdata, IUtility->Strlen(somedata));
IUtility->MessageDigest_SHA_Final(&mdsha);

IDOS->Printf(" Checksum is: %.20s\n",mdsha.mdsha_Code);
</syntaxhighlight>

The test value will be output bit by bit, so it's not very clever to use the IDOS->Printf() command, because control-characters can be included there as well. The value can be compared with the reference value thru the IUtility->StriCmp() command.

<syntaxhighlight lang="C" line>
/*
* CalcChecksum.c
*
* gcc CalcChecksum.c -o CalcChecksum -l auto
*/

/******************************* INCLUDES *************************************/

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/utility.h>

/******************************* DEFINES **************************************/

#define BUFFER_SIZE 65536 /* 64 kByte Block */

/************************ VARIABLEN DEKLARATIONEN *****************************/

const UBYTE *gb_ArgTemplate = "FILENAME/A";
enum { ARG_filename, ARG_MAX };
ULONG gb_Args[ARG_MAX] = { 0 };

/******************************************************************************/

BOOL CalculateChecksum(CONST_STRPTR filename, UBYTE *checksum)
{
BPTR fh;
struct MessageDigest_SHA mdsha = { 0 };

/* Preparing checksum calculation */
IUtility->MessageDigest_SHA_Init(&mdsha);

if((fh = IDOS->Open((STRPTR)filename, MODE_OLDFILE)))
{
LONG character;
UBYTE *buffer;

if((buffer = (UBYTE *) IExec->AllocVecTags(BUFFER_SIZE, TAG_END)))
{
while((character = IDOS->Read(fh, buffer, BUFFER_SIZE)) > 0)
{
IUtility->MessageDigest_SHA_Update(&mdsha, buffer, character);
}

IExec->FreeVec(buffer);
}

IDOS->Close(fh);
}

IUtility->MessageDigest_SHA_Final(&mdsha);
IUtility->Strlcpy(checksum, mdsha.mdsha_Code, 20);
checksum[20] = '\0';

return fh ? TRUE : FALSE;
}

/******************************************************************************/

int main()
{
struct RDArgs *rda;

if((rda = IDOS->ReadArgs((STRPTR)gb_ArgTemplate,(LONG*)gb_Args,NULL)))
{
UBYTE keybuffer[21]; /* 20 Bytes Checksum + \0 */

if(BerechneChecksumme((STRPTR)gb_Args[ARG_filename], keybuffer))
{
/*
** The checksum is a 160-bit data stream which should
** not strictly be output like a string. We do so here
** for convenience only.
*/
IDOS->Printf("Checksum for file '%s' is %s\n",
gb_Args[ARG_filename], keybuffer);
}

IDOS->FreeArgs(rda);
}
else IDOS->PrintFault(IDOS->IoErr(),"CalcChecksum");

return 0;
}
</syntaxhighlight>

[[File:AF111_CalcChecksum.png|frame|center]]

= Standard-C-Functions =

If you don't like to include the additonal C-libraries (newlib or clib2), it's possible to get similar functions from the utility.libary. In the case of string-functions, there are IUtility->Strlcpy() and IUtility->Strlcat() functions, which seem to have a slightly strange name, but work in a similar way as strncpy and strncat from the C-libaries. Since version 53.4 there is also a function called IUtility->Strlen() which determines the length of a string. With AmigaOS 4.1 Final Edition new functions were added for handling UTF-8 coded strings.

Like the memset function, there is a function called IUtility->SetMem(), which is able to set the memory-area. The required arguments are the starting-address in the memory, the value to be set (usually 0 deletes the memory-area) and the number of bytes that have to be amended. In general the order of the arguments are the same as in the memset function. A shortcut can be taken, if you just use the IUtility->ClearMem() function. This one only needs the starting-address and the number of bytes that should be cleared to zero. One other function, that works with memory-areas, is called IUtility->MoveMem(). As the name implies, the memory-area will be moved. Well the source material stays unchanged, so it's more like copying the areas. You can compare this function to the IExec->CopyMem() function from the exec.libary, but with the difference of allowing overlapping memory-areas. Make sure that your destination has enough free space for the data and, of course, it has to be reserved in your own program as well, because without reserving it, the OS will shutdown your program, if "aggravated" memory protection is enabled.

<syntaxhighlight lang="C" line>
/*
* MemoryFunctions.c
*
* gcc MemoryFunctions.c -o MemoryFunctions -l auto
*/

/******************************* INCLUDES *************************************/

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/utility.h>

/******************************************************************************/

int main()
{
UBYTE *mem;

/* Request memory */
if((mem = (UBYTE *) IExec->AllocVecTags(512, TAG_END)))
{
IDOS->Printf("memory allocated\n");

/* Clear memory area */
IUtility->ClearMem(mem,512);

/* Set memory area */
IUtility->SetMem(mem,'@',128);

/* Move memory area */
IUtility->MoveMem(mem,mem + 128,256);

/* Free memory area */
IExec->FreeVec(mem);
}
else IDOS->Printf("Not enough memory\n");

return( 0 );
}
</syntaxhighlight>

= Randomizing =

If you ever liked to create your own lottery numbers, the new IUtility->Random() function will allow you to do just that. All you need is a number, so you can just pick the actual time or a random value from the stack. The function will return a number ranging from 1 up to 2147483647, which can be cut down via the modulo operation. Next up we see an example of how to create your own lottery numbers.
The same number can be chosen again, so there is room for improvement.

<syntaxhighlight lang="C" line>
struct RandomState state;
ULONG i, number;
IDOS->Printf("6 out of 49:\n");
for(i=1; i<7; i++)
{
/* determines a number between 1 and 49 */
number = (IUtility->Random(&state) % 48) + 1;
IDOS->Printf("%ld. Number %2ld\n",i,number);
}

number = (IUtility->Random(&state) % 48) + 1;
IDOS->Printf("Additional number %2ld\n",number);
</syntaxhighlight>

<syntaxhighlight lang="C" line>
/* LottoGenerator.c
*
* gcc LottoGenerator.c -o LottoGenerator -l auto
*/

/******************************* INCLUDES *************************************/

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/utility.h>
#include <time.h>

/******************************************************************************/

int main()
{
struct RandomState state;
uint32 i, number;

/*
** Initialize the start values so that a different
** series of random numbers are generated each time.
*/
state.rs_High = time(NULL);
state.rs_Low = time(NULL);

IDOS->Printf("Lotto 6 out of 49:\n");
for(i=1; i<7; i++)
{
/*
** Determine a number from 1 to 49.
*/
number = (IUtility->Random(&state) % 48) + 1;
IDOS->Printf("%ld. Number is %2ld\n",i,number);
}

number = (IUtility->Random(&state) % 48) + 1;
IDOS->Printf("The bonus number is %2ld\n",number);

return 0;
}
</syntaxhighlight>

[[File:AF111_LottoGenerator.png|frame|center]]

= Miscellaneous functions =

Another helpful function is called IUtility->GetUniqueID(), which determines a unique number. This comes in handy by creating temporary files using multiple processes. As long as the system isn't shutdown, this unique number will be available. By restarting the system, the numbers will be created from scratch. Here is an easy example of how to create files with unique numbers:

<syntaxhighlight lang="C" line>
ULONG id = IUtility->GetUniqueID();
BPTR fh;
TEXT filename[30];
IUtility->SNPrintf(filename,sizeof(filename),"t:tmp.%ld",id);
if(IDOS->Open(filename,MODE_NEWFILE))
{
...
IDOS->CLose(fh);
}
</syntaxhighlight>

= New utility.library functions =

== Taglist functions ==

Allocates the memory for the number of given tags.
struct TagItem *AllocateTagItems(ULONG numtags);

Changes the tag-data-values in the changelist based on the values from the list. Unknown tags in the list will be ignored.
VOID ApplyTagChanges(struct TagItem *list, struct TagItem *changelist);

Creating a taglist copy; has to be deallocated via FreeTagItems().
struct TagItem *CloneTagItems(struct TagItem *orglist);

Deallocates the memory for the taglist.
VOID FreeTagItems(struct TagItem *taglist);

Creates a skip-tag-list; has to be deallocated via DeleteSkipList().
struct SkipList * CreateSkipList(struct Hook *hook, LONG max_levels);
VOID DeleteSkipList(struct SkipList *list);

Searches the changelist and deletes all entries, which are identical to the entries in the orglist. In the case of different values, the keyword "apply" defines if the value should be assumed from the orglist.
VOID FilterTagChanges(struct TagItem *changelist, struct TagItem *orglist, ULONG apply);

Deletes the tags from the changelist, if they occur in the filter array.
ULONG FilterTagItems(struct TagItem *changelist, Tag *filterarray ,ULONG logic);

Searches the taglist for the right entry and returns the matching items.
struct TagItem *FindTagItem(Tag tag,struct TagItem *taglist);

Determines the data value of the declared tag from the list.
ULONG GetTagData(Tag tag, ULONG default, struct TagItem *taglist);

Transfers the maplist values into the corresponding fields of the taglist. Type pin-points what happens to all entries, which only occur in the taglist.
VOID MapTags(struct TagItem *taglist, struct TagItem *maplist, ULONG type);

== Splay-Tree-Functions ==

Creating a Splay-Tree-Datastructure; has to be deallocated via DeleteSplayTree()
struct SplayTree * CreateSplayTree(struct Hook *hook);
VOID DeleteSplayTree(struct SplayTree *tree);

Searches the tree for a specific key and returns the matching node
struct SplayNode * FindSplayNode(struct SplayTree *tree, APTR key);

Creates a new SplayNode and adds it to the tree
struct SplayNode * InsertSplayNode(struct SplayTree *tree, APTR key, ULONG data_size);

Removes the SplayNode from the tree, if a matching entry for the key was found.
BOOL RemoveSplayNode(struct SplayTree *tree, APTR key);

== Skip-List-Functions ==

Searches the list for a specific key and returns the matching node.
struct SkipNode * FindSkipNode(struct SkipList *list, APTR key);

Determines the first node in the list
struct SkipNode * GetFirstSkipNode(struct SkipList *list);

Determines the next node after the previous node in the list.
struct SkipNode * GetNextSkipNode(struct SkipList *list, struct SkipNode *previousnode);

Creates a new skipnode and adds it to the list.
struct SkipNode * InsertSkipNode(struct SkipList *list, APTR key, ULONG total_size);

Removes the SkipNode from the list, if a matching entry for the key was found.
BOOL RemoveSkipNode(struct SkipList *list, APTR key);

== Miscellaneous functions ==

Calculates a 160 bit checksum
VOID MessageDigest_SHA_Init(struct MessageDigest_SHA *mdsha);
VOID MessageDigest_SHA_Update(struct MessageDigest_SHA *mdsha, APTR data, LONG num_bytes);
VOID MessageDigest_SHA_Final(struct MessageDigest_SHA *mdsha);

A hook-function for an object to send a message
ULONG CallHookPkt(struct Hook *hook, APTR object, APTR message);

Provides a unique number (as long as the computer is running)
ULONG GetUniqueID(void);

A random number between 1 ... 2147483647 will be returned
LONG Random(struct RandomState *state);

Adds a value to the memory-area
APTR SetMem(APTR destination, UBYTE value, LONG length);

Deletes a memory-area (it will be filled with 0 bytes):
VOID ClearMem(APTR destination, uint32 size);

Moves parts of the memory-area (even if they are overlapping):
VOID MoveMem(APTR source, APTR destination, uint32 size);

Adds the source string to the destination, where the max length will be considered.
LONG Strlcat(STRPTR destination, CONST_STRPTR source, LONG destination_size);

Copies the string from its source to its destination, where the max length will be considered.
LONG Strlcpy(STRPTR destination, CONST_STRPTR source, LONG destination_size);

Determines the length of a string
uint32 Strlen(CONST_STRPTR string);

Searches a node based on its name. Lower and Upper case will be ignored.
struct Node *node = FindNameNC(struct Node *start, STRPTR name);

Creates a string based on a specific format and the required args, (the returned string has to be deallocated via FreeVec)
STRPTR VASPrintf(CONST_STRPTR format, APTR args);
STRPTR ASPrintf(CONST_STRPTR format, ...);

Creates a Format-String, where the result is stored in the buffer.
LONG VSNPrintf(STRPTR buffer, LONG buffer_size, CONST_STRPTR format, APTR args);
LONG SNPrintf(STRPTR buffer, LONG buffer_size, CONST_STRPTR format, ...);

= Authors =

Written by Michael Christoph 
Translation by Florian Hanel 
Copyright (c) 2013 Michael Christoph

SANA-II Revision 7

2025-01-26T19:34:56Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

{{WIP}}
= SANA-II Network Device Driver Specification =

The "SANA-II Network Device Driver Specification" is a standard for an Amiga software interface between networking hardware and network protocol stacks (or for software tools such as network monitors). A network protocol stack is a layer of software that network applications use to address particular processes on remote machines and to send data reliably in spite of hardware errors. There are several common network protocol stacks including ''TCP/IP'', ''OSI'', ''AppleTalk'', ''DECNet'' and ''Novell''.

SANA-II device drivers are intended to allow multiple network protocol stacks running on the same machine to share one network device. For example, the TCP/IP and AppleTalk protocol stacks could both run on the same machine over one ethernet board. The device drivers are also intended to allow network protocol stacks to be written in a hardware-independent fashion so that a different version of each protocol stack doesn't have to be written for each networking hardware device.

The standard does not address the writing of network applications. Application writers must not use SANA-II Device Drivers directly. Network applications must use the API provided by the network protocol software the application supports. The Amiga standard network API for TCP/IP is provided via the bsdsocket.library which is a part of Roadshow.

To write a SANA-II device driver, you will need to be familiar with the specification documents for the hardware you are writing to and with the "SANA-II Network Device Driver Specification".

To write a network protocol stack which will use SANA-II device drivers, you should have general familiarity with common network hardware and must be very familiar with the "SANA-II Network Device Driver Specification" as well as the specification for the protocol you are developing. If you are creating a new protocol, you must obtain a protocol type number for any hardware on which your protocol will be used.

This version of the specification is final. Any new version of the standard (i.e., to add new features) is planned to be backward compatible. No SANA-II device driver or software utilizing those drivers should be written to any earlier version of the specification.

Distribution of this version of the standard is unlimited. Anyone may write Amiga software which implements a SANA-II network device driver or which calls a SANA-II network device driver without restriction and may freely distribute such software that they have written.

It is important to try to test each SANA-II device driver against all software which uses SANA-II devices. Available example programs are valuable in initial testing. The Amiga Networking Group is interested in receiving evaluation and/or beta test copies of all Amiga networking hardware, SANA-II device drivers and software which uses SANA-II devices. However, we make no assurances regarding any testing which we may or may not perform with such evaluation copies.

The SANA-II standard caters to both Motorola 68000 platforms and PowerPC platforms.

Please feel free to comment. You can contact the AmigaOS development team through the [http://www.amigaos.net/contact AmigaOS contact form].

= Driver Form =

SANA-II device drivers are Amiga Exec device drivers. They use an extended IORequest structure and a number of extended commands for tallying network statistics, sending broadcasts and multicasts, network addressing and the handling of unexpected packets. The SDK includes information on how to construct an Exec device.

= Opening a SANA-II Device =

As when opening any other Exec device, on the call to OpenDevice() a SANA-II device receives an IORequest structure which the device initializes for the opener's use. The opener must copy this structure if it desires to use multiple asynchronous requests. The SANA-II IORequest is defined as follows:

<syntaxhighlight lang="C" line>
struct IOSana2Req
{
struct IORequest ios2_Req;
ULONG ios2_WireError;
ULONG ios2_PacketType;
UBYTE ios2_SrcAddr[SANA2_MAX_ADDR_BYTES];
UBYTE ios2_DstAddr[SANA2_MAX_ADDR_BYTES];
ULONG ios2_DataLength;
APTR ios2_Data;
APTR ios2_StatData;
APTR ios2_BufferManagement;
};
</syntaxhighlight>

; ios2_Req
: A standard Exec device IORequest.
; ios2_WireError
: A more specific device code which may be set when there is an io_Error. See <devices/sana2.h> for the defined WireErrors.
; ios2_PacketType
: The type of packet requested. See the section on "Packet Types".
; ios2_SrcAddr
: The device fills in this field with the interface (network hardware) address of the source of the packet that satisfied a read command. The bytes used to hold the address will be left justified but the bit layout is dependent on the particular type of network.
; ios2_DstAddr
: Before the device user sends a packet, it fills this with the interface destination address of the packet. On receives, the device fills this with the interface destination address. Other commands may use this field differently (see the "SANA-II network device driver Autodocs" in the SDK). The bytes used to hold the address will be left justified but the bit layout is dependent on the particular type of network.
; ios2_DataLength
: The device user initializes this field with the amount of data available in the Data buffer before passing the IOSana2Req to the device. The device fills in this field with the size of the packet data as it was sent on the wire. This does not include the header and trailer information. Depending on the network type and protocol type, the driver may have to calculate this value. This is generally used only for reads and writes (including broadcast and multicast).
; ios2_Data
: A pointer to some abstract data structure containing packet data. ''Drivers may not directly manipulate or examine anything pointed to by Data!'' This is generally used only for reads and writes (including broadcast and multicast).

; ios2_StatData
: Pointer to a structure in which to place a snapshot of device statistics. The data area must be long word aligned. This is only used on calls to the statistics commands.

; ios2_BufferManagement
: The opener places a pointer to a tag list in this field before calling OpenDevice(). Functions pointed to in the tag list are called by the device when processing IORequests from the opener. When returned from OpenDevice(), this field contains a pointer to driver-private information used to access these functions. See "Buffer Management" below for more details.

: Note that the <tt>ios2_BufferManagement</tt> field provided by the driver on <tt>OpenDevice()</tt> time in conjunction with <tt>io_Device</tt> and <tt>io_Unit</tt> is the unique identifier for all requests coming from this protocol stack until <tt>CloseDevice()</tt>. The driver must not ever change the <tt>ios2_BufferManagement</tt> field for a protocol stack at run time, even if <tt>S2_SANAHOOK</tt> is called to request extended features.

The flags used with the device on OpenDevice() are (SANA2OPB_xxx):

{| class="wikitable"
! Name
! Description
|-
| SANA2OPB_MINE
| Exclusive access to the unit requested.
|-
| SANA2OPB_PROM
| Promiscuous mode requested. Hardware which supports promiscuous mode allows all packets sent over the wire to be captured whether or not they are addressed to this node.
'''''Note:''' Promiscuous mode requires exclusive opening of the device.''
|}

The flags used during I/O requests are (SANA2IOB_xxx):

{| class="wikitable"
! Name
! Description
|-
| SANA2IOB_RAW
| Raw packet read/write requested. Raw packets should include the entire data-link layer packet. Devices with the same hardware device number should have the same raw packet format.
|-
| SANA2IOB_BCAST
| Broadcast packet (received).
|-
| SANA2IOB_MCAST
| Multicast packet (received).
|-
| SANA2IOB_QUICK
| Quick IO requested.
|}

= Buffer Management =

Unlike most other Exec Device drivers, SANA-II drivers have no internal buffers. Instead, they read/write to/from an abstract data structure allocated by the driver user. The driver accesses these buffers only via functions that the driver user provides to the driver. The driver user must provide two functions: one copies data to the abstract data structure and one copies data from the abstract data structure. The driver user can therefore choose the data structure used for buffer management by both the driver and driver user in order to have efficient memory and CPU usage overall.

The IOSana2Req contains a pointer to data and the length of said data. A driver is not allowed to make assumptions about how the data is stored. The driver cannot directly manipulate or examine the buffer in any manner. The driver can only access the buffer by calling the functions provided by the driver user.

Before calling OpenDevice(), the driver user points ios2_BufferManagement to a list of tags (defined in <devices/sana2.h>) which include pointers to the buffer management functions required by the driver (defined below). The driver will fail to open if the driver user does not supply all of the required functions. If the device opens successfully, the driver sets ios2_BufferManagement to a value which this opener must use in all future calls to the driver. This "magic cookie" is used from then on to access these functions (a "magic cookie" is a value which one software entity passes to another but which is only meaningful to one of the software entities). The driver user may not use the "magic cookie" in any way--it is for the driver to do with as it wishes. The driver could in theory choose to just copy the tag list to driver-owned memory and then parse the list for every IORequest, but it is much more efficient for the driver to create some sort of table of functions and to point ios2_BufferManagement to that table.

Another recommendation for the ``magic cookie`` is to use it to maintain a separate packet read queue for each device opener. This would allow multiple protocol stacks that all wish to receive the same packet type to work together without having to "know" about each other as ''Envoy'' and ''AS225'' do right now. What does multiple protocol stack support mean? Basically this means that each opener gets all the packets necessary. If a packet comes in that fills a request for more than one opener of the device, all of them will get a copy of the packet. This feature should never be left out of a device design. If it is missing, the usefulness of the device is severely limited.

In order to help system load, a packet filter callback allows protocol stacks to reject packets that are known to not be useful. ''Envoy'''s nipc.library (for example) could be modified to reject TCP packets (as it never uses them).

The specification currently defines the following tags for the OpenDevice() ios2_BufferManagement tag list:

{| class="wikitable"
|+ Copy data from network interface to protocol stack buffer
! Tag
! Description
|-
| S2_CopyToBuff (mandatory)
| This is a pointer to a function which conforms to the CopyToBuff Autodoc.
|-
| S2_CopyToBuff16 (optional)
| Copy to a 16 bit aligned buffer using 16 bit data words.
|-
| S2_CopyToBuff32 (optional)
| Copy to a 32 bit aligned buffer using 32 bit data words.
|-
| S2_DMACopyToBuff32 (optional)
| Perform a DMA copy to a 32 bit aligned contiguous buffer using 32 bit data words.
|-
| S2_DMACopyToBuff64 (optional)
| Perform a DMA copy to a 64 bit aligned contiguous buffer using 64 bit data words.
|}

{| class="wikitable"
|+ Copy data from protocol stack buffer to network interface
! Tag
! Description
|-
| S2_CopyFromBuff (mandatory)
| This is a pointer to a function which conforms to the CopyFromBuff Autodoc.
|-
| S2_CopyFromBuff16 (optional)
| Copy from a 16 bit aligned buffer using 16 bit data words.
|-
| S2_CopyFromBuff32 (optional)
| Copy from a 32 bit aligned buffer using 32 bit data words.
|-
| S2_DMACopyFromBuff32 (optional)
| Perform a DMA copy from a 32 bit aligned contiguous buffer using 32 bit data words.
|-
| S2_DMACopyFromBuff64 (optional)
| Perform a DMA copy from a 64 bit aligned contiguous buffer using 64 bit data words.
|}

{| class="wikitable"
|+ Filter data before protocol stack buffer
! Tag
! Description
|-
| S2_PacketFilter (optional)
| This is a pointer to a standard Hook to be called before S2_CopyToBuff is done. See the PacketFilter Autodoc for more information.
|}

{| class="wikitable"
|+ Logging messages from the driver
! Tag
! Description
|-
| S2_Log (optional)
| This is a pointer to a standard Hook to be called when the driver logs events.
|}

== Better buffer management ==

The mandatory buffer management callbacks may not be very efficient for certain types of hardware. They also do not allow driver DMA access.

All the new features are completely optional and do not collide with existing features. They may be used only when the protocol stack asks for them on opening a driver.

The enhancements consist of several new tags that may be specified by a protocol stack on OpenDevice() to offer certain data transfer options. It is up to the device driver to chose which callbacks to use at what time. These tags are advisory only and may be ignored by the driver for any data buffer at any time:

{| class="wikitable"
| S2_CopyToBuff16
|-
| S2_CopyFromBuff16
|-
| S2_CopyToBuff32
|-
| S2_CopyFromBuff32
|}

These are optional callbacks presented to the device with the same calling interface as for S2_CopyToBuff or S2_CopyFromBuff, respectively. The difference to the original callbacks is the required and guaranteed transfer size and alignment for accessing the device's buffer for a single piece of a data of either 16 or 32 bits, a data word. The copy function called may only use 16/32 bit aligned read/write commands of 16/32 bits at once to transfer the data words, respectively. If the buffer data length is not a multiple of the required data word transfer size, the last data word transfer may contain garbage padding in either transfer direction.

The following tags have been added to support direct writes into hardware buffers that do not allow arbitrarily sized or aligned accesses:

{| class="wikitable"
| S2_DMACopyToBuff32
|-
| S2_DMACopyFromBuff32
|}

If the protocol stack wants to optionally enhance data transfer efficiency with DMA supporting devices, it may pass any of these optional tags to the device on OpenDevice().

If the device driver supports DMA, it may call the respective callback with the abstract magic cookie ios2_Data in register A0. The callback may return NULL in D0. In this case, the driver may not use DMA for this buffer. Alternatively, the callback may return the address of the actual data buffer in D0, if it has these characteristics:

* The buffer is in contiguous memory. Depending on the intended data direction, it shall be readable or writable.
* The buffer is aligned on a 32 bit boundary.
* The buffer size shall be a multiple of 32 bit and it is at least = ios2_DataLength.
* It is up to the driver to decide if it can use DMA for this buffer and it shall fall back to the standard CPU callbacks if necessary. The data transfer method actually used by the driver will not be known in advance by the protocol stack.

The following tags have been added to allow for 64 bit aligned PCI DMA accesses to take place:

{| class="wikitable"
| S2_DMACopyToBuff64
|-
| S2_DMACopyFromBuff64
|}

These two callbacks are identical in operation to the <tt>S2_DMACopyToBuff32</tt> and <tt>S2_DMACopyFromBuff32</tt> callbacks. The difference is in that the memory region DMA is to take place in must be aligned to a 64 bit boundary and must be large enough to hold data that is a multiple of 64 bits in size.

== Best buffer management ==

The SANA-II driver interface is intended to transform data between the hardware layer and the link layer, to be used by networking software such as TCP/IP stacks. This transformation is performed by callback functions which are supplied by the networking software at the time the device driver is opened. The device driver then invokes these functions later in order to transfer data received and data to be sent.

The function parameters used by these callbacks are passed in 68000 registers for the lowest overhead. The problem with 68000 register parameters is that on the PowerPC platform, this form of parameter passing may require the use of emulation code. This is costly and may incur a severe performance penalty. It is an even greater problem if PowerPC native networking software is calling PowerPC native networking driver software and the other way round. In both cases the runtime environment will have to enter emulation mode, return to to PowerPC native execution, dip into emulation mode and return to native PowerPC execution. It would be much better if the chain of execution would stay in PowerPC mode all the time.

Alternatively, if a hook function is used, the operating system may be able to decide whether the function to be invoked needs emulating or called directly. The <tt>Hook</tt> effectively works as an abstraction which makes the function invocation platform independent.

The following standard wraps the copying and logging functions into the standardized <tt>Hook</tt> interface.

==== The hook function ====

The hook function itself is invoked with the following parameters:

<syntaxhighlight lang="C" line>
result = hook_function(hook, sana2req, sana2hookmsg)

ULONG hook_function(struct Hook *hook,
struct IOSana2Req *sana2req,
struct SANA2HookMsg *sana2hookmsg);
</syntaxhighlight>

Note that the result is not necessarily of type <tt>ULONG</tt>. It is a 32 bit value, which can be a boolean result code (for <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt> and their like) or a pointer to a memory address (for <tt>DMACopyToBuff</tt>, <tt>DMACopyFromBuff</tt> and their like).

=== Data structures ===

The following hook messages are to be used:

<syntaxhighlight lang="C" line>
struct SANA2HookMsg
{
ULONG shm_Method;
ULONG shm_MsgSize;
};
</syntaxhighlight>

In this data structure the <tt>shm_Method</tt> field would indicate the task to be performed. This can be a request to copy data or to store a log message. The <tt>shm_MsgSize</tt> field tells you how large the data structure is for future enhancements which may cause the data structure to grow.

==== Copying operations ====

For copying operations the message is:

<syntaxhighlight lang="C" line>
struct SANA2CopyHookMsg
{
ULONG schm_Method;
ULONG schm_MsgSize;

APTR schm_To;
APTR schm_From;
ULONG schm_Size;
};
</syntaxhighlight>

The structure members are as follows:

; schm_Method
: This must be one <tt>S2_CopyToBuff</tt>, <tt>S2_CopyFromBuff</tt>, <tt>S2_CopyToBuff16</tt>, <tt>S2_CopyFromBuff16</tt>, <tt>S2_CopyToBuff32</tt>, <tt>S2_CopyFromBuff32</tt>, <tt>S2_DMACopyToBuff32</tt>, <tt>S2_DMACopyFromBuff32</tt>, <tt>S2_DMACopyToBuff64</tt> or <tt>S2_DMACopyFromBuff64</tt> to identify the function to be performed.

; schm_MsgSize
: Size of this message data structure in bytes. This must be >= 20 for this message type.
: The driver shall set <tt>schm_MsgSize</tt> always correctly to be compliant. The protocol stack shall use this field to validate the message and to reject/ignore bad messages via a <tt>FALSE</tt> hook function return value. For DMA related hooks, a <tt>FALSE</tt> return value is equivalent to a <tt>NULL</tt> pointer.

; schm_To
: Equivalent to the <tt>to</tt> parameter of the <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt> and <tt>DMACopyToBuff</tt> functions.

; schm_From
: Equivalent to the <tt>from</tt> parameter of the <tt>CopyFromBuff</tt> and <tt>CopyToBuff</tt> functions.

; schm_Size
: Equivalent to the <tt>n</tt> parameter of the <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt>, functions.

==== Logging operations ====

For logging operations the message is:

<syntaxhighlight lang="C" line>
struct SANA2LogHookMsg
{
ULONG slhm_Method;
ULONG slhm_MsgSize;

ULONG slhm_Priority;
STRPTR slhm_Name;
STRPTR slhm_Message;
};
</syntaxhighlight>

The structure members would be used as follows:

; slhm_Method
: This must be <tt>S2_Log</tt>, as defined in the SANA-IIR4 specification.

; slhm_MsgSize
: Size of this message data structure in bytes. This must be >= 20 for this message type.
: The driver shall set <tt>slhm_MsgSize</tt> always correctly to be compliant. The protocol stack shall use this field to validate the message and to reject/ignore bad messages via a <tt>FALSE</tt> hook function return value. For DMA related hooks, a <tt>FALSE</tt> return value is equivalent to a <tt>NULL</tt> pointer.

; slhm_Priority
: The smaller this value, the more important the message to be logged or displayed. The following priority levels are defined (similar to the Unix syslog() mechanism):
:{| class="wikitable"
| S2LOG_Emergency || A panic condition.
|-
| S2LOG_Alert || A condition that should be corrected immediately.
|-
| S2LOG_Critical || Critical conditions.
|-
| S2LOG_Error || A plain error.
|-
| S2LOG_Warning || A warning message.
|-
| S2LOG_Notice || Conditions that are not error conditions, but should possibly be handled specially.
|-
| S2LOG_Information || An informational message.
|-
| S2LOG_Debug || Messages that contain information normally of use only when debugging.
|}
: Only these priority values may be used by a driver. It is suggested that a driver is configurable to generate different types of messages or not, e.g., a driver may be configured to only emit <tt>S2LOG_Emergency</tt> and <tt>S2LOG_Debug</tt> messages

; slhm_Name
: Pointer to a <tt>NUL</tt>-terminated string which identifies the source of this message. This can be <tt>NULL</tt> in which case the OS device name of the driver shall be used by the protocol stack.

; slhm_Message
: Pointer to a <tt>NUL</tt>-terminated string which contains the log message. The text should not contain any formatting characters such as line feeds or carriage returns. The <tt>slhm_Message</tt> member must never be <tt>NULL</tt>.
: All message texts shall preferably be formatted in the current user's locale. If that is not possible, the english language shall be used. <tt>slhm_Name</tt> and <tt>slhm_Message</tt> shall only contain printable characters.

=== Application and driver software use of the new functions ===

Since plenty of software exists which uses the 'traditional' <tt>TagItem</tt> list provided at <tt>OpenDevice()</tt> time, drivers must always examine these parameters and not expect a <tt>S2_SANA2HOOK</tt> command to be sent later.

If the new <tt>Hook</tt>-based callback functions are used then the driver must invoke the Hooks via <tt>utility.library/CallHookPkt</tt>. It must never invoke the hook functions through local assembly language stubs or the <tt>amiga.lib/CallHook</tt> and <tt>amiga.lib/CallHookA</tt> functions.

=== Caveats ===

The functionality above suggests that one could do entirely without the <tt>TagItem</tt> list passed in at <tt>OpenDevice()</tt> time. However, at this time it is hard to tell how existing driver software will react to empty <tt>TagItem</tt> lists or even a NULL pointer in the <tt>IOSana2Req->ios2_BufferManagement</tt> field. It is therefore important to always provide for a <tt>TagItem</tt> list which includes proper (i.e. they must point to working functions and may not be <tt>NULL</tt>) function pointers for the <tt>S2_CopyToBuff</tt> and <tt>S2_CopyFromBuff</tt> tags. Once the device has been opened successfully, the next step is to try and install the copy <tt>Hook</tt> through the proposed <tt>S2_SANA2HOOK</tt> command. If the command fails, the application can still expect that the <tt>S2_CopyToBuff</tt> and <tt>S2_CopyFromBuff</tt> tags supplied at <tt>OpenDevice()</tt> time will work.

== Packet filtering ==

With the original "SANA-II Network Device Driver Specification", a protocol stack could open a device and ask for certain packet types. It got all the packets that matched this type. As it turned out, this could be mighty inefficient if there were packets that the protocol stack did not use at all. These would go into read processing of the protocol stack and waste CPU time even though they could have been easily identified on arrival.

== Driver event logging ==

A driver may want to report an important event for the user to see. Adding a log message to a file or opening a window to display a message in may not be the optimum approach as the user may be unaware of the context into which the message belongs. It may be advisable for the driver to use the message reporting and logging facilities used by the client software that uses its services, such as a TCP/IP stack. The <tt>S2_Log</tt> callback hook is intended to provide for such a link.

If present, the driver must use this callback hook rather than whatever logging methods it implements itself. Note that unlike the other SANA-II callbacks, this is a regular hook, as to be invoked using <tt>utility.library</tt>/<tt>CallHookPkt()</tt>. The hook function is invoked using the following parameters:

<syntaxhighlight lang="C" line>
log_hook_function(hook, reserved, message)

void log_hook_function(struct hook * hook,APTR reserved,
struct S2LogMessage * message);
</syntaxhighlight>

The <tt>reserved</tt> parameter '''must''' be set to <tt>NULL</tt>. The <tt>S2LogMessage</tt> structure passed as the third parameter looks like this:

<syntaxhighlight lang="C" line>
struct S2LogMessage
{
LONG s2lm_Size;
ULONG s2lm_Priority;
STRPTR s2lm_Name;
STRPTR s2lm_Message;
};
</syntaxhighlight>

The individual structure members serve the following functions:

; s2lm_Size
: Size of the <tt>S2LogMessage</tt> structure, in bytes. The idea is to extend this data structure in the future, and the size stored in here tells you how long the structure is. The size '''must''' always be >= 16.

;s2lm_Priority
: The smaller this value, the more important the message to be logged or displayed. The following priority levels are defined (similar to the Unix <tt>syslog()</tt> mechanism):
:{| class="wikitable"
| S2LOG_Emergency || A panic condition.
|-
| S2LOG_Alert || A condition that should be corrected immediately.
|-
| S2LOG_Critical || Critical conditions.
|-
| S2LOG_Error || A plain error.
|-
| S2LOG_Warning || A warning message.
|-
| S2LOG_Notice || Conditions that are not error conditions, but should possibly be handled specially.
|-
| S2LOG_Information || An informational message.
|-
| S2LOG_Debug || Messages that contain information normally of use only when debugging.
|}

; s2lm_Name</tt>
: Pointer to a <tt>NUL</tt>-terminated string which identifies the source of this message. This can be <tt>NULL</tt> in which case the name is treated as being unknown.

; s2lm_Message
: Pointer to a <tt>NUL</tt>-terminated string which contains the log message. The text should not contain any formatting characters such as line feeds or carriage returns. The <tt>s2lm_Message</tt> member '''must never''' be <tt>NULL</tt>.

All error messages issued by the device driver should use the current system locale wherever this is possible. The purpose of an error message is, after all, to assist the user in recovering from the error. Which may be difficult if the user does not even know the language in which the message is written.

The log message string is valid until the log hook function returns. If the driver needs to retain the message any longer, it must make a copy of it.

Since the client software into which the log hook calls may have to allocate memory to hold and display the log message, the log hook '''must not''' be called from interrupt code. The log hook shall not <tt>Wait()</tt> and it shall assume only a <tt>Task</tt> calling context of unknown priority. <tt>dos.library</tt> functions may not be called. Also, stack space is provided only to call <tt>exec.library</tt> and <tt>utility.library</tt> functions. The callback shall not place excessive data on the stack. Stack space should be considered limited and the callback should be designed to be fast and short.

This hook is installed at <tt>OpenDevice()</tt> time, which means that the hook is used for the unit that was opened, and not just for the I/O request it was opened with. The hook must remain installed until the I/O request that installed it is eventually used to close the device. When this happens, the device should fall back to use no log hook at all. No nesting is permitted or required.

= Packet Type =

Network frames always have a type field associated with them. These type fields vary in length, position and meaning by frame type (frame types generally correspond one-to-one with hardware types, but see "Ethernet Packet Types" below). The meanings of the type numbers are always carefully defined and every type number is registered with some official body. Do not use a type number which is not registered for any standard hardware you use or in a manner inconsistent with that registration.

The type field allows the SANA-II device driver to fulfill CMD_READs based on the type of packet the driver user wants. Multiple protocols can therefore run over the same wire using the same driver without stepping on each other's toes.

Packet types are specified as a long word. Unfortunately, the type field means different things on different wires. Driver users must allow their software to be configured with a SANA-II device name, unit number and the type number(s) used by the protocol stack with each device. This way, if new hardware becomes available, a hardware manufacturer can supply a listing of type assignments to configure pre-existing software.

== Ethernet Packet Types ==

Ethernet has a special problem with packet types. Two types of ethernet frames can be sent over the same wire: ethernet and 802.3. These frames differ in that the Type field of an ethernet frame is the Length field of an 802.3 frame. This creates a problem in that demultiplexing incoming packets can be cumbersome and inefficient, as well as requiring driver users to be aware of the frame type used.

All 802.3 frames have numbers less than 1500 in the Type field. The only frames with numbers less than 1500 in the type field are 802.3 frames. SANA-II ethernet drivers abnormally return packets contained in ethernet frames when the requested Type falls within the 802.3 range-if the Type requested is within the 802.3 range, the driver returns the next packet contained within an 802.3 frame, regardless of the type specified for the packet within the 802.3 frame. This requires that there be no more than one driver user requesting 802.3 packets and that it do its own interpretation of the frames.

== ARCNET Frames ==

ARCNET also has a special problem with framing. ARCNET frames consist of a hardware header and a software header. The software header is in the data area of the hardware packet, and includes at least the protocol ID.

There are two types of software header. Old-style ARCNET software headers consist entirely of a one or two byte protocol ID. New ARCNET software headers (defined in RFC 1201 and in the paper "ARCNET Packet Header Definition Standard", Novell, Inc., 1989) include more information. They allow more efficient use of ARCNET through data link layer fragmentation and reassembly (ARCNET has a small Maximum Transmission Unit) and allow sending any size packet up to the MTU (rather than requiring that packets of size 253, 254 and 255 be padded to at least 256 bytes).

SANA-II device drivers for ARCNET should implement the old ARCNET packet headers. Driver users which wish to interoperate with platforms using the new software headers must add the new fields to the data to be sent and must process it for incoming data. A SANA-II driver which implemented the data link layer fragmentation internally (and advertised a large MTU) could be more efficient than requiring the driver user to do it. This would make driver writing more difficult and reduce interoperability, but if there is ever a demand for that extra performance, a new hardware type may be assigned by Amiga for SANA-II ARCNET device drivers which implement the new framing.

= Addressing =

In the SANA-II standard, network hardware addresses are stored in an array of ''n'' bytes. No meaning is ascribed by the standard to the contents of the array.

In case there exists a network which does not have an address field consisting of a number of bits not divisible by eight, add pad bits at the end of the bit stream. For example, if an address is ten bits long it will be stored like this:

<pre>
98765432 10PPPPPP
BYTE 0 BYTE 1
</pre>

Where the numerals are bit numbers and "P" is a pad (ignored) bit.

Driver users which do not implement the bit shifting necessary to use a network with such addressing (if one exists) should at least check the number of significant bits in the address field (returned from the device's S2_DEVICEQUERY function) to make sure that it is evenly divisible by eight.

Driver users will map hardware addresses to protocol addresses in a protocol and hardware dependent manner, as described by the relevant standards (i.e., RFC 826 for TCP/IP over Ethernet, RFC 1201 or RFC 1051 for TCP/IP over ARCNET). Some protocols will always use the same mapping on all hardware, but other protocols will have particular address mapping schemes for some particular hardware and a reasonable default for other (unknown) hardware.

Some SANA-II devices will have "hardware addresses" which aren't really hardware addresses. As an example, consider ''PPP'' (Point-to-Point Protocol). PPP is a standard for transmitting IP packets over a serial line. It uses IP addresses negotiated during the establishment of a connection. In a SANA-II driver implementation of PPP, the driver would negotiate the address at S2_CONFIGINTERFACE. Thus, the address in SrcAddr returned by the device on an S2_CONFIGINTERFACE (or in a subsequent S2_GETSTATIONADDRESS) will be a protocol address, not a true hardware address.

'''Note:''' Some hardware always uses a ROM hardware address. Other hardware which has a ROM address or is configurable with DIP switches may be overridden by software. Some hardware always dynamically allocates a new hardware address at initialization. See "Configuration" for details on how this is handled by driver writers and by driver users.

= Hardware Type =

The HardwareType returned by the device's S2_DEVICEQUERY function is necessary for those protocols whose standards require different behavior on different hardware. It is also useful for determining appropriate packet type numbers to use with the device. The HardwareType values already issued for standard network hardware are the same as those in RFC 1060 (assigned numbers). Hardware developers implementing networks without a SANA-II hardware number must contact the AmigaOS development team to have a new hardware type number assigned. Driver users should all have reasonable defaults which can be used for hardware with which they are not familiar.

= Errors =

The SANA-II extended IORequest structure (struct IOSana2Req) includes both the ios2_Error and ios2_WireError fields. Driver users must always check IOSana2Reqs on return for an error in ios2_Error. ios2_Error will be zero if no error occurred, otherwise it will contain a value from <exec/errors.h> or <devices/sana2.h>. If there was an error, there may be more specific information in ios2_WireError. Drivers are required to fill in the WireError if there is an applicable error code.

Error codes are #define'd in the "defined errors" sections of the file <devices/sana2.h>: 

{| class="wikitable"
! IOSana2Req S2io_Error field
! Description
|-
| S2ERR_NO_RESOURCES
| Insufficient resources available.
|-
| S2ERR_BAD_ARGUMENT
| Noticeably bad argument.
|-
| S2ERR_BAD_STATE
| Command inappropriate for current state.
|-
| S2ERR_BAD_ADDRESS
| Noticeably bad address.
|-
| S2ERR_MTU_EXCEEDED
| Write data too large.
|-
| S2ERR_NOT_SUPPORTED
| Command is not supported by this driver. This is similar to IOERR_NOCMD as defined in <exec/errors.h> but S2ERR_NOT_SUPPORTED indicates that the requested command is a valid SANA-II command and that the driver does not support it because the hardware is incapable of supporting it (e.g., S2_MULTICAST). Note that IOERR_NOCMD is still valid for reasons other than a lack of hardware support (i.e., commands which are no-ops in a SANA-II driver).
|-
| S2ERR_SOFTWARE
| Software error of some kind.
|-
| S2ERR_OUTOFSERVICE
| When a hardware device is taken off-line, any pending requests are returned with this error.
|}

See also the standard errors in <exec/errors.h>.

{| class="wikitable"
! IOSana2Req S2io_WireError field
! Description
! Value
|-
| S2WERR_NOT_CONFIGURED
| Command requires unit to be configured.
|-
| S2WERR_UNIT_ONLINE
| Command requires that the unit be off-line.
|-
| S2WERR_UNIT_OFFLINE
| Command requires that the unit be on-line.
|-
| S2WERR_ALREADY_TRACKED
| Protocol is already being tracked.
|-
| S2WERR_NOT_TRACKED
| Protocol is not being tracked.
|-
| S2WERR_BUFF_ERROR
| Buffer management function returned an error.
|-
| S2WERR_SRC_ADDRESS
| Problem with the source address field.
|-
| S2WERR_DST_ADDRESS
| Problem with destination address field.
|-
| S2WERR_BAD_BROADCAST
| Problem with an attempt to broadcast.
|-
| S2WERR_BAD_MULTICAST
| Problem with an attempt to multicast.
|-
| S2WERR_MULTICAST_FULL
| Multicast address list full.
|-
| S2WERR_BAD_EVENT
| Event specified is unknown.
|-
| S2WERR_BAD_STATDATA
| The ios2_StatData pointer or the data it points to failed a sanity check.
|-
| S2WERR_IS_CONFIGURED
| Attempt to reconfigure the unit.
|-
| S2WERR_NULL_POINTER
| A NULL pointer was detected in one of the arguments. S2ERR_BAD_ARGUMENT should always be the S2ERR.
|-
| S2WERR_UNIT_DISCONNECTED
| This error code is a counterpart to <tt>S2WERR_UNIT_OFFLINE</tt>. It indicates that the associated command could not be executed because the link layer is not connected.
| 19
|-
| S2WERR_UNIT_CONNECTED
| This error code is a counterpart to <tt>S2WERR_UNIT_ONLINE</tt>. It indicates that the associated command could not be executed because the link layer is already connected.
| 20
|-
| S2WERR_INVALID_OPTION
| This error code indicates that an option, such as passed by the <tt>S2_CONNECT</tt> command, is not acceptable. The option's value may be out of range or may not match the syntax specifications. To indicate which option that may be, a different mechanism '''must''' be used; a simple indication that something was wrong is '''not sufficient'''.
| 21
|-
| S2WERR_MISSING_OPTION
| This error code indicates that a mandatory option, such as passed by the <tt>S2_CONNECT</tt> command, is not present. To indicate which option that may be, a different mechanism '''must''' be used; a simple indication that something was wrong is '''not sufficient'''.
| 22
|-
| S2WERR_AUTHENTICATION_FAILED
| Some drivers run protocols that require them to authenticate to a server. That process may fail. This wire error code is to indicate this fact.
| 23
|}

= Standard Commands =

See the "SANA-II network device driver Autodocs" for full details on each of the SANA-II device commands. Extended commands are explained in the sections below.

Many of the Exec device standard commands are no-ops in SANA-II devices, but this may not always be the case. For example, CMD_RESET might someday be used for dynamically reconfiguring hardware. This should present no compatibility problems for properly written drivers.

== Broadcast and Multicast ==

Some hardware supports broadcast and/or multicast. A broadcast is a packet sent to all other machines. A multicast is a packet sent to a set of machines. Drivers for hardware which does not allow broadcast or multicast will return ios2_Error S2ERR_NOT_SUPPORTED as appropriate.

To send a broadcast, use S2_BROADCAST instead of CMD_WRITE. Broadcasts are received just like any other packets (using a CMD_READ for the appropriate packet type).

To send a multicast, use S2_MULTICAST instead of CMD_WRITE. The device keeps a list of addresses that want to receive multicasts. You add a receiver's address to this list by using S2_ADDMULTICASTADDRESS. The receiver then posts a CMD_READ for the type of packet to be received. Some SANA-II devices which support multicast may have a limit on the number of addresses that can simultaneously wait for packets. Always check for an S2WERR_MULTICAST_FULL error return when adding a multicast address.

Note that when the device adds a multicast address, it is usually added for all users of the device, not just the driver user which called S2_ADDMULTICASTADDRESS. In other words, received multicast packets will fill a read request of the appropriate type regardless of whether the requesting driver user is the same one which added the multicast address.

In general, driver users should not care how received packets were sent (normally or broadcast/multicast), only that it was received. If a driver user really must know, however, it can check for SANA2IOB_BCAST and/or SANA2IOB_MCAST in the ios2_Flags field.

Drivers should keep a count for the number of opens on a multicast address so that they don't actually remove it until it has been S2_DELMULTICASTADDRESS'd as many times as it has been S2_ADDMULTICASTADDRESS'd.

== Stats ==

There are many statistics which may be very important to someone trying to debug, tune or optimize a protocol stack, as well as to the end user who may need to tune parameters or investigate a problem. Some of these statistics can only be kept by the SANA-II driver, thus there are several required and optional statistics and commands for this purpose.

S2_TRACKTYPE tells the device driver to gather statistics for a particular packet type. S2_UNTRACKTYPE tells it to stop (keeping statistics by type causes the driver to use additional resources). S2_GETTYPESTATS returns any statistics accumulated by the driver for a type being tracked (stats are lost when a type is S2_UNTRACKTYPE'd). Drivers are required to implement the functionality of type tracking. The stats are returned in a struct Sana2PacketTypeStats:

<syntaxhighlight lang="C" line>
struct Sana2PacketTypeStats
{
ULONG PacketsSent;
ULONG PacketsReceived;
ULONG BytesSent;
ULONG BytesReceived;
ULONG PacketsDropped;
};
</syntaxhighlight>

; PacketsSent
: Number of packets of a particular type sent.
; PacketsReceived
: Number of packets of a particular type that satisfied a read command.
; BytesSent
: Number of bytes of data sent in packets of a particular type.
; BytesReceived
: Number of bytes of data of a particular packet type that satisfied a read command.
; PacketsDropped
: Number of packets of a particular type that were received while there were no pending reads of that packet type.

returns global statistics kept by the driver. Drivers are required to keep all applicable statistics. Since all are applicable to most hardware, most drivers will maintain all statistics. The stats are returned in a struct Sana2DeviceStats:

<syntaxhighlight lang="C" line>
struct Sana2DeviceStats
{
ULONG PacketsReceived;
ULONG PacketsSent;
ULONG BadData;
ULONG Overruns;
ULONG UnknownTypesReceived;
ULONG Reconfigurations;
struct timeval LastStart;
};
</syntaxhighlight>

; PacketsReceived
: Number of packets that this unit has received.
; PacketsSent
: Number of packets that this unit has sent.
; BadData
: Number of bad packets received (i.e., hardware CRC failed).
; Overruns
: Number of packets dropped due to insufficient resources available in the network interface.
; UnknownTypeReceived
: Number of packets received that had no pending read command with the appropriate packet type.
; Reconfigurations
: Number of network reconfigurations since this unit was last configured.
; LastStart
: The time when this unit last went on-line.

returns any special statistics kept by a particular driver. Each new wire type will have a set of documented, required statistics for that wire type and a standard set of optional statistics for that wire type (optional because they might not be available from all hardware). The data returned by S2_GETSPECIALSTATS will require wire-specific interpretation. See <devices/sana2specialstats.h> on page devicessana2specialstatspage for currently defined special statistics. The statistics are returned in the following structures:

<syntaxhighlight lang="C" line>
struct Sana2SpecialStatRecord
{
ULONG Type;
ULONG Count;
char * String;
};
</syntaxhighlight>

; Type
: Statistic identifier.
; Count
: Statistic itself.
; String
: An identifying, null-terminated string for the statistic. Should be plain ASCII with no formatting characters.

<syntaxhighlight lang="C" line>
struct Sana2SpecialStatHeader
{
ULONG RecordCountMax;
ULONG RecordCountSupplied;
struct Sana2SpecialStatRecord[RecordCountMax];
};
</syntaxhighlight>

; RecordCountMax
: There is space for this many records into which statistics may be placed.
; RecordCountSupplied
: Number of statistic records supplied.

is not, strictly speaking, a statistical function. It is a request to read any packet of a type for which there is no outstanding CMD_READ. S2_READORPHAN might be used in the same manner as many statistics, though, such as to determine what packet types are causing overruns, etc.

== Configuration ==

The device driver needs to configure the hardware before using it. The driver user must know some network hardware parameters (hardware address and MTU, for example) when using it. These commands address those needs.

When a driver user is initialized, it should try to S2_CONFIGINTERFACE even though an interface can only be configured once and someone else may have done it. Before you call S2_CONFIGINTERFACE, first call S2_GETSTATIONADDRESS to determine the factory address (if any). Also provide for user-override of the factory address (that address may be optional and the user may need to override it). When S2_CONFIGINTERFACE returns, check the ios2_SrcAddr for the actual address the hardware has been configured with. This is because some hardware (or serial line standards such as PPP) always dynamically allocates an address at initialization.

Driver users will want to use S2_DEVICEQUERY to determine the MTU and other characteristics of the network. The structure returned from S2_DEVICEQUERY is defined as:

<syntaxhighlight lang="C" line>
struct Sana2DeviceQuery
{
/*
** Standard information
*/
ULONG SizeAvailable; /* bytes available */
ULONG SizeSupplied; /* bytes supplied */
LONG DevQueryFormat; /* this is type 0 */
LONG DeviceLevel; /* this document is level 0 */

/*
** Common information
*/
UWORD AddrFieldSize; /* address size in bits */
ULONG MTU; /* maximum packet data size */
LONG BPS; /* line rate (bits/sec) */
LONG HardwareType; /* what the wire is */
ULONG RawMTU; /* maximum raw packet data size */

/*
** Format specific information
*/
};
</syntaxhighlight>

; SizeAvailable
: Size, in bytes, of the space available in which to place device information. This includes both size fields.
; SizeSupplied
: Size, in bytes, of the data supplied.
; DevQueryFormat
: The format defined here is format 0.
; DeviceLevel
: This spec defines level 0.
; AddrFieldSize
: The number of bits in an interface address.
; MTU
: Maximum Transmission Unit, the size, in bytes, of the maximum packet size, not including header and trailer information.
; BPS
: Best guess at the raw line rate for this network in bits per second.

; HardwareType
: Specifies the type of network hardware the driver controls.

; RawMTU
: The <tt>RawMTU</tt> member is new as of SANA-II Revision 4. Devices which do not know and support this structure member may fill in the <tt>Sana2DeviceQuery</tt> structure only up to and including the <tt>HardwareType</tt> member.

: In this context 'raw' means the number of bytes that are available for reading and writing when using the <tt>SANA2IOB_RAW</tt> flag with a <tt>CMD_READ</tt>/<tt>CMD_WRITE</tt> request on a device that supports these access methods. Currently, software developers can only make assumptions on how many bytes might comprise the 'raw' MTU by checking the <tt>Sana2DeviceQuery.HardwareType</tt> member and hoping that the driver supports raw <tt>CMD_READ</tt>/<tt>CMD_WRITE</tt> access.

: Devices which know and support the <tt>RawMTU</tt> member must fill it with a well-defined value. For Amiga Ethernet drivers, that value would be 1514, which is the standard MTU value of 1500 bytes plus the size of the Ethernet frame header, as per RFC894 (six bytes for the destination address, six bytes for the source address and two bytes for the frame type; the eight byte preamble and the terminating four byte CRC value are typically not under the control of the driver). Drivers which do not support raw read or write access must set the <tt>RawMTU</tt> member to zero.

: If the <tt>RawMTU</tt> member is not provided, all bets are off and the application software must fall back to making estimates based upon the hardware type and the raw frame types it wishes to read and write. Ultimatively, the driver itself must decide whether it can accept raw read and write commands (or has to reject them with <tt>S2ERR_NOT_SUPPORTED</tt>) and whether the raw packet size is still covered by the underlying hardware MTU (or must be rejected with <tt>S2ERR_MTU_EXCEEDED</tt>).

: A word of warning: a little testing with various Ethernet hardware drivers has revealed that the A2065 driver <tt>a2065.device</tt> does not handle the <tt>S2_DEVICEQUERY</tt> command properly if the <tt>Sana2DeviceQuery</tt> structure provided is larger than 30 bytes. In other words, the command will fail if the proposed <tt>RawMTU</tt> member is present in the query data structure to be filled in.

== On-line ==

In order to run hardware tests on an otherwise live system, the S2_OFFLINE command allows the SANA-II device driver to be "turned off" until the tests are complete and an S2_ONLINE is sent to the driver. S2_ONLINE causes the interface to re-configure and re-initialize. Any packets destined for the hardware while the device is off-line will be lost. All pending and new requests to the driver shall be returned with S2ERR_OUTOFSERVICE when a device is off-line.

All driver users must understand that any IO request may return with S2ERR_OUTOFSERVICE because the driver is off-line (any other program may call S2_OFFLINE to make it so). In such an event, the driver will usually want to wait until the unit comes back on-line (for the program which called S2_OFFLINE to call S2_ONLINE). It may do this by calling S2_ONEVENT to wait for S2EVENT_ONLINE. S2_ONEVENT allows the driver user to wait on various events.

A driver must track events, but may not distinguish between some types of events. Drivers return S2_ONEVENT with S2ERR_NOT_SUPPORTED and S2WERR_BAD_EVENT for unsupported events. One error may cause more than one event (see below). Errors which seem to have been caused by a malformed or unusual request should not generally trigger an event. 

{| class="wikitable"
! Event type
! Description
|-
| S2EVENT_ERROR
| Return when any error occurs.
|-
| S2EVENT_TX
| Return on any transmit error (always an error).
|-
| S2EVENT_RX
| Return on any receive error (always an error).
|-
| S2EVENT_ONLINE
| Return when unit goes on-line or return immediately if unit is already on-line (not an error).
|-
| S2EVENT_OFFLINE
| Return when unit goes off-line or return immediately if unit is already off-line (not an error.)
|-
| S2EVENT_BUFF
| Return on any buffer management function error (always an error).
|-
| S2EVENT_HARDWARE
| Return when any hardware error occurs (always an error, may be a S2EVENT_TX or S2EVENT_RX, too).
|-
| S2EVENT_SOFTWARE
| Return when any software error occurs (always an error, may be a S2EVENT_TX or S2EVENT_RX, too).
|-
| S2EVENT_CONFIGCHANGED
| Return when client-visible configuration information changes (not an error).
|-
| S2EVENT_CONNECT
| Return when the driver has successfully established a link layer connection (not an error).
|-
| S2EVENT_DISCONNECT
| Return when the driver has closed the link layer connection previously established by the S2_CONNECT command (not an error).
|}

=== S2EVENT_CONFIGCHANGED ===

For drivers such as those which implement the <tt>S2_GETPEERADDRESS</tt> and <tt>S2_GETDNSADDRESS</tt> commands it is vital that such changes can take place and be noticed by the client software. For this purpose a new event type is introduced, to be used with the SANA-II <tt>S2_ONEVENT</tt> command, using the following definition:

<tt>#define S2EVENT_CONFIGCHANGED (1L<<8)</tt>

This event should be triggered whenever client-visible configuration information changes, as can be queried via the <tt>S2_DEVICEQUERY</tt>, <tt>S2_GETSTATIONADDRESS</tt>, <tt>S2_GETSPECIALSTATS</tt>, <tt>S2_GETGLOBALSTATS</tt>, <tt>S2_GETPEERADDRESS</tt> and <tt>S2_GETDNSADDRESS</tt> commands. Here is a short list of what could change:

# S2_DEVICEQUERY: <tt>AddrFieldSize</tt>, <tt>MTU</tt>, <tt>BPS</tt>
# S2_GETSTATIONADDRESS: <tt>ios2_SrcAddr</tt>
# S2_GETGLOBALSTATS: <tt>Reconfigurations</tt>, <tt>LastStart</tt>
# S2_GETPEERADDRESS: <tt>ios2_SrcAddr</tt>, <tt>ios2_DstAddr</tt>
# S2_GETDNSADDRESS: <tt>ios2_SrcAddr</tt>, <tt>ios2_DstAddr</tt>

The purpose of this event '''is not''' to post a notification whenever another byte or event counter has changed so that a monitoring program may update its display. The purpose '''is''' to convey to the client software that an important device configuration option has changed and that it is supposed to react and adapt to it. For example, a TCP/IP stack may, upon learning that a device's IP address has changed, rebuild its routing table.

Since the <tt>S2EVENT_CONFIGCHANGED</tt> event may arrive at any time and does not indicate what exactly has changed, application software should query the information it expects to change during its life time, and keep a copy of it around for later reference. When the <tt>S2EVENT_CONFIGCHANGED</tt> event arrives, it can compare the contents of the copy against the current state of affairs and act according to the differences it finds.

=== S2EVENT_CONNECT ===

This event is a counterpart to <tt>S2EVENT_ONLINE</tt>, and is associated with the <tt>S2_CONNECT</tt> command. It has the following semantics:

<tt>#define S2EVENT_CONNECT (1L<<9) /* Driver has opened session */</tt>

The event is to be sent when the driver has successfully established a link layer connection.

=== S2EVENT_DISCONNECT ===

This event is a counterpart to <tt>S2EVENT_OFFLINE</tt>, and is associated with the <tt>S2_DISCONNECT</tt> command. It has the following semantics:

<tt>#define S2EVENT_DISCONNECT (1L<<10) /* Driver has closed session */</tt>

The event is to be sent when the driver has closed the link layer connection previously established by the <tt>S2_CONNECT</tt> command.

== S2_ONLINE and S2_OFFLINE ==

The <tt>S2_CONNECT</tt> and <tt>S2_DISCONNECT</tt> commands are somewhat related to the <tt>S2_ONLINE</tt> and <tt>S2_OFFLINE</tt> commands. How this relation works out shall be explained below. Note that the following text assumes that both the <tt>S2_CONNECT</tt>/<tt>S2_DISCONNECT</tt> and <tt>S2_ONLINE</tt>/<tt>S2_OFFLINE</tt> command pairs are implemented.

<tt>S2_CONNECT</tt> implies <tt>S2_ONLINE</tt> and, if successful, may report <tt>S2EVENT_ONLINE</tt> and <tt>S2EVENT_CONNECT</tt> events. If the unit is currently disconnected, but still online, only the <tt>S2EVENT_CONNECT</tt> event shall be sent. Invoking the <tt>S2_CONNECT</tt> command on a driver which is already connected must be rejected with <tt>ios2_Req.io_Error=S2ERR_BAD_STATE</tt> and <tt>ios2_WireError=S2WERR_UNIT_CONNECTED</tt>.

<tt>S2_DISCONNECT</tt> implies <tt>S2_OFFLINE</tt> and, if successful, may report <tt>S2EVENT_OFFLINE</tt> and <tt>S2EVENT_DISCONNECT</tt> events. If the unit is currently connected and offline, then only the <tt>S2EVENT_DISCONNECT</tt> event shall be sent. Invoking the <tt>S2_DISCONNECT</tt> command on a driver which is already disconnected must be rejected with <tt>ios2_Req.io_Error=S2ERR_BAD_STATE</tt> and <tt>ios2_WireError=S2WERR_UNIT_DISCONNECTED</tt>.

<tt>S2_OFFLINE</tt> may be used after the <tt>S2_CONNECT</tt> has successfully connected the unit. In this case the driver will release control over the link layer and report the <tt>S2EVENT_OFFLINE</tt> event. The connection established using the <tt>S2_CONNECT</tt> will, however, persist.

<tt>S2_ONLINE</tt> may be used after <tt>S2_CONNECT</tt> has successfully connected the unit and the <tt>S2_OFFLINE</tt> was used. In this case the driver will again try to obtain control over the link layer and report the <tt>S2EVENT_ONLINE</tt> event if successful.

If the <tt>S2_CONNECT</tt> command was never successfully executed, then the commands <tt>S2_ONLINE</tt> and <tt>S2_OFFLINE</tt> must be rejected with <tt>ios2_Req.io_Error=S2ERR_BAD_STATE</tt> and <tt>ios2_WireError=S2WERR_UNIT_DISCONNECTED</tt>.

== Wireless (IEEE 802.11) ==

Several new commands have been added to the SANA-II API to facilitate use of IEEE 802.11 wireless network devices in client and ad-hoc modes. The new commands are split into two overlapping sets. One set needs to be implemented by drivers for Soft-MAC wireless devices, while the other is implemented for Hard-MAC devices.

{| class="wikitable"
! Soft-MAC commands
|-
| S2_SETOPTIONS
|-
| S2_SETKEY
|-
| S2_WRITEMGMT
|-
| S2_READMGMT
|}

{| class="wikitable"
! Hard-MAC commands
|-
| S2_SETOPTIONS
|-
| S2_SETKEY
|-
| S2_GETNETWORKS
|-
| S2_GETNETWORKINFO
|-
| S2_GETSIGNALQUALITY
|}

=== sana2wireless.h ===

<syntaxhighlight lang="C" line>
#ifndef DEVICES_SANA2WIRELESS_H
#define DEVICES_SANA2WIRELESS_H

#include <exec/types.h>
#include <utility/tagitem.h>

/* Constants */
/* ========= */

/* Tags to get and set information */

#define S2INFO_SSID (TAG_USER + 0)
#define S2INFO_BSSID (TAG_USER + 1)
#define S2INFO_AuthTypes (TAG_USER + 2)
#define S2INFO_AssocID (TAG_USER + 3)
#define S2INFO_Encryption (TAG_USER + 4)
#define S2INFO_PortType (TAG_USER + 5)
#define S2INFO_BeaconInterval (TAG_USER + 6)
#define S2INFO_Channel (TAG_USER + 7)
#define S2INFO_Signal (TAG_USER + 8)
#define S2INFO_Noise (TAG_USER + 9)
#define S2INFO_Capabilities (TAG_USER + 10)
#define S2INFO_InfoElements (TAG_USER + 11)
#define S2INFO_WPAInfo (TAG_USER + 12)
#define S2INFO_Band (TAG_USER + 13)
#define S2INFO_DefaultKeyNo (TAG_USER + 14)

/* Wireless Commands */

#define S2_GETSIGNALQUALITY 0xc010
#define S2_GETNETWORKS 0xc011
#define S2_SETOPTIONS 0xc012
#define S2_SETKEY 0xc013
#define S2_GETNETWORKINFO 0xc014
#define S2_READMGMT 0xc015
#define S2_WRITEMGMT 0xc016
#define S2_GETRADIOBANDS 0xc017

/* Encryption types */

#define S2ENC_NONE 0
#define S2ENC_WEP 1
#define S2ENC_TKIP 2
#define S2ENC_CCMP 3

/* Radio modes */

#define S2BAND_A 0
#define S2BAND_B 1
#define S2BAND_G 2
#define S2BAND_N 3

/* Network topologies */

#define S2PORT_MANAGED 7
#define S2PORT_ADHOC 8

/* Structures */
/* ========== */

/* Structure for returning signal quality */

struct Sana2SignalQuality
{
LONG SignalLevel; /* signal level in dBm */
LONG NoiseLevel; /* noise level in dBm */
};

#endif
</syntaxhighlight>

= Driver requirements =

This section is an attempt to clarify parts of the specification and to lay down a few rules that every SANA-II driver must follow.

* A driver that does not use a broadcast medium, such as Ethernet, must not implement the <tt>S2_BROADCAST</tt> command. Likewise, if no multicast mechanism is supported, the <tt>S2_MULTICAST</tt> must not be implemented either.

* SANA-II standard commands which the driver does not implement must be rejected with the <tt>IOERR_NOCMD</tt> error code. Commands that are implemented, but which cannot perform the requested services, must be rejected with the <tt>S2ERR_NOT_SUPPORTED</tt> error code. The difference between the two cases is in when the decision is made whether a command can be handled or not. Which commands should return <tt>IOERR_NOCMD</tt> is decided upon at the time the driver is designed and implemented. At this stage the implementer knows for sure which capabilities the driver will have and which it will not have. Commands which the driver will never be able to execute will be made to return the <tt>IOERR_NOCMD</tt> error code. If the decision whether a command can be executed is made only at run time, by evaluating the conditions under which a command can be executed, then the error code <tt>S2ERR_NOT_SUPPORTED</tt> should be returned in case of failure.

* It must be possible to open the driver with an ordinary <tt>struct IOStdReq</tt>. This is necessary for the NewStyleDevices query command to work. In the command dispatcher, the driver must verify that all SANA-II commands are invoked with a proper size <tt>struct IOSana2Req</tt> I/O request. If the I/O request is shorter (as can be verified by looking at the embedded Message's <tt>mn_Length</tt> member), the command must be rejected with <tt>ios2_Req.io_Error=IOERR_BADLENGTH</tt>.

* A driver must implement the NewStyleDevices <tt>NSCMD_DEVICEQUERY</tt> command, in conformance with the NSD specification 1.6 or newer. The motivation for this is to have a mechanism available for probing the capabilities of the driver, and the supported command set can provide for vital clues. In this context, the absence of the <tt>S2_BROADCAST</tt> command would suggest that the driver cannot send or receive broadcast messages.

* A driver that does not allow its station address to be set with the <tt>S2_CONFIGINTERFACE</tt> command may silently ignore the command (returning it without setting an error condition) and even pretend that it can be configured more than once.

* In response to the <tt>S2_DEVICEQUERY</tt>, <tt>S2_GETSPECIALSTATS</tt> and <tt>S2_GETGLOBALSTATS</tt> commands a driver may return information that is not entirely correct if it has to go online before it can provide for the correct data. For example, the maximum transmission unit for PPP is a number in the range of [1..1500] which is negotiated during the protocol configuration process. It is unlikely that numbers greater than 1500 will be used, yet it is still not impossible. Since the actual number will be known only after the driver has configured the protocol, the MTU value returned before the session was opened can differ from the MTU value valid after it has been opened. A driver should therefore attempt to return 'safe' defaults in place of information that is unavailable at the time it is queried. The 'safe' values shall be set up to allow the driver to work even if the protocol stack is not aware of later changes to those values. Beware of zero-length buffer sizes or time intervals that may cause client software to perform zero-length memory allocations or divisions by zero.

* SANA-II assigns packet type numbers according to the underlying transport media. For example, Ethernet uses packet type 2048 for IP frames. No such packet type definition exists for PPP yet, which is why this standard proposes to assign packet type 31 for IP packets transmitted via PPP. To simplify client software configuration, drivers may treat packet type 2048 as equivalent to the packet number associated with IP frames. This association is permitted only if it does not introduce ambiguity. For example, this association would not be permitted if the driver would receive and transmit IP packets in two different frame types or if the driver already associates packet type 2048 with non-IP packets.

= Driver Installation =

The standard system location for SANA-II network device driver is in a directory called "Networks" which exists in the "DEVS:" directory.

Example:

<blockquote>
DEVS:Networks/eth3com.device
</blockquote>

This is the official location for the drivers. It may be necessary for your install program/script to create this directory if it doesn't exist in a user's system.

= Unresolved Issues =

* Unfortunately, it isn't possible to completely isolate network protocols from the hardware they run on. Hardware types and addressing both remain somewhat hardware-dependent in spite of our efforts. See the "Packet Type" section for an explanation of how packet types are handled and why protocols cannot be isolated from them. See the "Addressing" section for an explanation of how addressing is handled any why protocols cannot be isolated from it.

* Additionally, there are at least two cases where a hardware type has multiple framing methods in use (ethernet/802.3 and arcnet/(Novell) "ARCNET Packet Header Definition Standard"). In both cases, software which must interoperate with other platforms on this hardware may need to be aware of the distinctions and may have to do extra processing in order to use the appropriate frame type. See the sections on "Ethernet Packet Types" and on "ARCNET frames" for more details.

* Protocols like PPP can provide both for IPv4 and IPv6 addresses that should be used by the local client, the peer or any of the domain name servers. While the two addressing families are interoperable, there is a problem in how the driver should report them. Can you assume 128 bit addresses and encapsulate 32 bit addresses in them? If so, how do you make sure that the address format is unambiguous?

* Currently, only the device's hardware type provides a clue as to what packet type responds to which protocol transported via the link. For Ethernet, IP packets are encapsulated in type 2048 frames, PPP encapsulates IP packets in type 31 frames, Arcnet can use type 240 or 212. Matching a protocol with a frame type is not an easy process which could be handled more elegantly.

* How to extend the <tt>Sana2DeviceQuery</tt> structure in the future? The current layout separates standard, common and format specific information, but there is no hint as to where which each section starts and where the next begins. Now that there is a proposal to add a new field to the common section, how would you add fields to the format specific section?

= SANA-II network device driver Autodocs =

== AbortIO ==

<pre>
NAME
AbortIO -- Remove an existing device request.

SYNOPSIS
error = AbortIO(Sana2Req)
D0 A1

LONG AbortIO(struct IOSana2Req *);

FUNCTION
This is an exec.library call.

This function aborts an ioRequest. If the request is active, it may or
may not be aborted. If the request is queued it is removed. The
request will be returned in the same way as if it had normally
completed. You must WaitIO() after AbortIO() for the request to
return.

INPUTS
Sana2Req - Sana2Req to be aborted.

RESULTS
error - Zero if the request was aborted, non-zero otherwise.
io_Error in Sana2Req will be set to IOERR_ABORTED
if it was aborted.

SEE ALSO
exec.library/AbortIO(), exec.library/WaitIO()
</pre>

== CloseDevice ==

<pre>
NAME
CloseDevice -- Close the device.

SYNOPSIS
CloseDevice(Sana2Req)
A1

void CloseDevice(struct IOSana2Req *);

FUNCTION
This function is called by exec.library CloseDevice().

This function performs whatever cleanup is required at device closes.

Note that all IORequests MUST be complete before closing. If any are
pending, your program must AbortIO() then WaitIO() each outstanding
IORequest to complete them.

INPUTS
Sana2Req - Pointer to IOSana2Req initialized by OpenDevice().

SEE ALSO
exec.library/CloseDevice(), exec.library/OpenDevice()
</pre>

== CMD_CLEAR ==

<pre>
NAME
CMD_CLEAR -- Clear internal network interface read buffers.

FUNCTION
There are no device internal buffers, so CMD_CLEAR does not apply to
this class of device.

IO REQUEST
ios2_Command - CMD_CLEAR.

RESULTS
ios2_Error - IOERR_NOCMD.
</pre>

== CMD_FLUSH ==

<pre>
NAME
CMD_FLUSH -- Clear all queued I/O requests for the SANA-II device.

FUNCTION
This command aborts all I/O requests in both the read and write
request queues of the device. All pending I/O requests are
returned with an error message (IOERR_ABORTED). CMD_FLUSH does not
affect active requests.

IO REQUEST
ios2_Command - CMD_FLUSH.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
</pre>

== CMD_INVALID ==

<pre>
NAME
CMD_INVALID -- Return with error IOERR_NOCMD.

FUNCTION
This command causes device driver to reply with an error IOERR_NOCMD
as defined in <exec/errors.h> indicating the command is not supported.

IO REQUEST
ios2_Command - CMD_INVALID.

RESULTS
ios2_Error - IOERR_NOCMD.

BUGS
Not known to be useful.
</pre>

== CMD_READ ==

<pre>
NAME
CMD_READ -- Get a packet from the network.

FUNCTION
Get the next packet available of the requested packet type. The data
copied (via a call to the requestor-provided CopyToBuffer function)
into ios2_Data is normally the Data Link Layer packet data only. If
bit SANA2IOB_RAW is set in ios2_Flags, then the entire physical frame
will be returned.

Unlike most Exec devices, SANA-II device drivers do not have internal
buffers. If you wish to read data from a SANA-II device you should
have multiple CMD_READ requests pending at any given time. The
functions provided by you the requestor will be used for any incoming
packets of the type you've requested. If no read requests are
outstanding for a type which comes in and no read_orphan requests are
outstanding, the packet will be lost.

IO REQUEST
ios2_Command - CMD_READ
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_PacketType - Packet type desired.
ios2_Data - Abstract data structure to hold packet data.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
ios2_Flags - The following flags may be returned:
SANA2IOB_RAW
SANA2IOB_BCAST
SANA2IOB_MCAST
ios2_SrcAddr - Source interface address of packet.
ios2_DstAddr - Destination interface address of packet.
ios2_DataLength - Length of packet data.
ios2_Data - Abstract data structure which packet data is
contained in.

NOTES
The driver may not directly examine or modify anything pointed to by
ios2_Data. It *must* use the requester-provided functions to access
this data.

SEE ALSO
S2_READORPHAN, CMD_WRITE, any_protocol/CopyToBuffer
</pre>

== CMD_RESET ==

<pre>
NAME
CMD_RESET -- Reset the network interface to initialized state.

FUNCTION
Currently, SANA-II devices can only be configured once (with
CMD_CONFIGINTERFACE) and cannot be re-configured, hence,
CMD_RESET does not apply to this class of device.

IO REQUEST
ios2_Command - CMD_RESET.

RESULTS
ios2_Error - IOERR_NOCMD.
</pre>

== CMD_START ==

<pre>
NAME
CMD_START -- Restart device operation.

FUNCTION
There is no way for the driver to keep queuing requests without
servicing them, so CMD_STOP does not apply to this class of device.
S2_OFFLINE and S2_ONLINE do perform a similar function to CMD_STOP
and CMD_START

IO REQUEST
ios2_Command - CMD_START.

RESULTS
ios2_Error - IOERR_NOCMD.

SEE ALSO
S2_ONLINE, S2_OFFLINE
</pre>

== CMD_STOP ==

<pre>
NAME
CMD_STOP -- Pause device operation.

FUNCTION
There is no way for the driver to keep queuing requests without
servicing them, so CMD_STOP does not apply to this class of device.
S2_OFFLINE and S2_ONLINE do perform a similar function to CMD_STOP
and CMD_START

IO REQUEST
ios2_Command - CMD_STOP.

RESULTS
ios2_Error - IOERR_NOCMD.

NOTES

SEE ALSO
S2_ONLINE, S2_OFFLINE
</pre>

== CMD_UPDATE ==

<pre>
NAME
CMD_UPDATE -- Force packets out to device.

FUNCTION
Since there are no device internal buffers, CMD_UPDATE does not
apply to this class of device.

IO REQUEST
ios2_Command - CMD_UPDATE.

RESULTS
ios2_Error - IOERR_NOCMD.
</pre>

== CMD_WRITE ==

<pre>
NAME
CMD_WRITE -- Send packet to the network.

FUNCTION
This command causes the packet to be sent to the specified network
interface. Normally, appropriate packet header and trailer information
will be added to the packet data when it is sent. If bit SANA2IOB_RAW
is set in io_Flags, then the ios2_Data is assumed to contain an entire
physical frame and will be sent (copied to the wire via
CopyFromBuffer() unmodified.

Note that the device should not check to see if the destination
address is on the local hardware. Network protocols should realize
that the packet has a local destination long before it gets to a
SANA-II driver.

IO REQUEST
ios2_Command - CMD_WRITE.
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_PacketType - Packet type to send.
ios2_DstAddr - Destination interface address for this packet.
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
The driver may not directly examine or modify anything pointed to by
ios2_Data. It *must* use the requester-provided functions to access
this data.

SEE ALSO
CMD_READ, S2_BROADCAST, S2_MULTICAST, any_protocol/CopyFromBuffer
</pre>

== OpenDevice ==

<pre>
NAME
Open -- Request an opening of the network device.

SYNOPSIS
error = OpenDevice(unit, IOSana2Req, flags)
D0 D0 A1 D1

BYTE OpenDevice(ULONG, struct IOSana2Req *, ULONG);

FUNCTION
This function is called by exec.library OpenDevice().

This function performs whatever initialization is required per
device open and initializes the Sana2Req for use by the
device.

INPUTS
unit - Device unit to open.
Sana2Req - Pointer to IOSana2Req structure to be initialized by
the sana2.device.
flags - Supported flags are:
SANA2OPB_MINE
SANA2OPB_PROM
ios2_BufferManagement - A pointer to a tag list containing
pointers to buffer management functions.

RESULTS
error - same as io_Error
io_Error - Zero if successful; non-zero otherwise.
io_Device - A pointer to whatever device will handle the calls
for this unit. This pointer may be different
depending on what unit is requested.
ios2_BufferManagement - A pointer to device internal information
used to call buffer management functions.

NOTES
A SANA-II device must reject all open requests with a request
structure that is too short, e.g. an IOStdReq. A simple check of the
mn_Length field in the Message part of the request is needed to make
sure that a device does not dereference invalid data due to a wrong
device configuration.

A SANA-II device may open if no buffer management tags are provided to
make the configuration process and obtaining statistics easier. Buffer
management tags with a NULL value must be treated as not specified.
The device shall fail requests gracefully depending on the missing
tags in this case. Any malfunction is not acceptable.

SEE ALSO
exec.library/OpenDevice(), exec.library/CloseDevice()
</pre>

== S2_ADDMULTICASTADDRESS ==

<pre>
NAME
S2_ADDMULTICASTADDRESS -- Enable an interface multicast address.

FUNCTION
This command causes the device driver to enable multicast packet
reception for the requested address.

IO REQUEST
ios2_Command - S2_ADDMULTICASTADDRESS.
ios2_SrcAddr - Multicast address to enable.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Multicast addresses are added globally -- anyone using the device
may receive packets as a result of any multicast address which has
been added for the device.

Since multicast addresses are not "bound" to a particular packet type,
each enabled multicast address has an "enabled" count associated with
it so that if two protocols add the same multicast address and later
one removes it, it is still enabled until the second removes it.

SEE ALSO
S2_MULTICAST, S2_DELMULTICASTADDRESS
</pre>

== S2_BROADCAST ==

<pre>
NAME
S2_BROADCAST -- Broadcast a packet on network.

FUNCTION
This command works the same as CMD_WRITE except that it also performs
whatever special processing of the packet is required to do a
broadcast send. The actual broadcast mechanism is neccessarily
network/interface/device specific.

IO REQUEST
ios2_Command - S2_BROADCAST.
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_PacketType - Packet type to send.
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

RESULTS
ios2_DstAddr - The contents of this field are to be
considered trash upon return of the IOReq.
ios2_Error - Zero if successful; non-zero otherwise.
This command can fail for many reasons and
is not supported by all networks and/or
network interfaces.
ios2_WireError - More specific error number.

NOTES
The DstAddr field may be trashed by the driver because this function
may be implemented by filling DstAddr with a broadcast address and
internally calling CMD_WRITE.

SEE ALSO
CMD_WRITE, S2_MULTICAST
</pre>

== S2_CONFIGINTERFACE ==

<pre>
NAME
S2_CONFIGINTERFACE -- Configure the network interface.

FUNCTION
This command causes the device driver to initialize the interface
hardware and to set the network interface address to the address in
ios2_SrcAddr. This command can only be executed once and, if
successful, will leave the driver and network interface fully
operational and the network interface in ios2_SrcAddr.

To set the interface address to the factory address, the network
management software must use GetStationAddress first and then call
ConfigInterface with the result. If there is no factory address then
the network software must pick an address to use.

Until this command is executed the device will not listen for any
packets on the hardware.

IO REQUEST
ios2_Command - S2_CONFIGINTERFACE.
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_SrcAddr - Address for this interface.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
ios2_SrcAddr - Address of this interface as configured.

NOTES
Some networks have the interfaces choose a currently unused interface
address each time the interface is initialized. The caller must check
ios2_SrcAddr for the actual interface address after configuring the
interface.

SEE ALSO
S2_GETSTATIONADDRESS
</pre>

== S2_CONNECT ==

The driver model specified by the SANA-II standard really only covers networking hardware well. Software-only drivers, such as for dial-up networking, are, well, somehow mentioned in the standard, but they don't receive much attention. In particular, this means that a networking driver is assumed to be practically always attached to its link layer and no provisions exist to specify what kind of link layer that might be and how it might be accessed. This small oversight can probably be explained by the fact that at the time the SANA-II standard was adopted, dial-up networking had not yet gained the prominence it has today.

To bridge this gap, I propose a new command which will make a driver connect to its link layer and go online, which uses the following data structure:

<syntaxhighlight lang="C" line>
struct Sana2Connection
{
ULONG s2c_Size;
struct MinList s2c_Options;
struct Hook s2c_ErrorHook;
struct Hook s2c_ConnectHook;
struct Hook s2c_DisconnectHook;
STRPTR s2c_Login;
STRPTR s2c_Password;
};
</syntaxhighlight>

The individual structure members have the following purposes:

<tt>s2c_Size</tt>

The size of the entire data structure is stored here. This value '''must''' be >= 84. Smaller values '''must''' be rejected with <tt>ios2_Req.io_Error</tt>=<tt>IOERR_BADLENGTH</tt>. The purpose of <tt>s2c_Size</tt> is to allow for future expansion during which the structure may grow in size.

<tt>s2c_Options</tt>

This list contains options, to be used during the connection process. Each node has the following format:

<syntaxhighlight lang="C" line>
struct Sana2ConnectionOption
{
struct MinNode s2co_MinNode;
STRPTR s2co_Name;
STRPTR s2co_Value;
};
</syntaxhighlight>

The <tt>s2co_Name</tt> and <tt>s2co_Value</tt> entries point to <tt>NUL</tt>-terminated strings, which contain the name and the value of a parameter. ''Note that for numeric values, the respective number will be encoded in a text string.'' A number of parameters are reserved, which are [[#s2c_options|listed later]] in this text.

<tt>s2c_ErrorHook</tt>

This hook is called whenever an error message is to be reported during the connection/disconnection process. The hook function is invoked using the following parameters:

<pre>error_hook_func(hook,reserved,message);

VOID error_hook_func(struct Hook *hook,APTR reserved,
STRPTR message);</pre>
The <tt>reserved</tt> parameter '''must''' be <tt>NULL</tt>. The <tt>message</tt> parameter points to a <tt>NUL</tt>-terminated string. It '''must not''' be <tt>NULL</tt>.

Because the hook function may have to allocate memory, it '''must not''' be called from interrupt code.

<tt>s2c_ConnectHook</tt>

This hook is called when the link level device has been set up, but further initializations are necessary, such as telling a modem to dial out. The hook function is invoked with the following parameters:

<pre>
success = connect_hook_func(hook,reserved,s2cm);

BOOL connect_hook_func(struct Hook *hook,APTR reserved,
struct Sana2ConnectionMessage *s2cm);
</pre>

The <tt>reserved</tt> parameter '''must''' be <tt>NULL</tt>. The <tt>s2cm</tt> parameter points to a data structure, as follows:

<syntaxhighlight lang="C" line>
struct Sana2ConnectionMessage
{
ULONG s2cm_Size;
struct Sana2Connection * s2cm_Connection;
struct IORequest * s2cm_Request[2];
LONG s2cm_RequestType;
};
</syntaxhighlight>

In this structure, the members have the following purposes:

<tt>s2cm_Size</tt>

The size of this data structure; it '''must''' be at least 20 bytes in size. The purpose of <tt>s2cm_Size</tt> is to allow for future expansion, which may cause the size of this structure to grow.

<tt>s2cm_Connection</tt>

This points back to the <tt>Sana2Connection</tt> structure which the hook that was invoked with the <tt>Sana2ConnectionMessage</tt> is embedded in.

<tt>s2cm_Request</tt>

Here you will find two I/O requests which can be used for reading and writing data to the link layer. These pointers '''must not''' be <tt>NULL</tt> and they '''must''' refer to different I/O requests, it is not permitted to pass the same request twice.

The dialer can use these requests for communicating with the modem, but it is also permitted to clone these requests by creating new I/O requests of the same size, copying the original contents and filling in different reply ports.

There is a danger in that the hook code may not receive the right kind of I/O request, which is why the <tt>s2cm_RequestType</tt> field identifies the kind of device the requests were created for.

When the hook function returns, it '''must''' make sure that none of the I/O requests are still pending, i.e. asynchronous I/O '''must''' have been stopped.

<tt>s2cm_RequestType</tt>

This identifies the type of device the I/O requests passed in <tt>s2cm_Request</tt> were created for. Possible values for this entry come from the New Style Device specification, e.g. <tt>NSDEVTYPE_SERIAL</tt> for a <tt>serial.device</tt>-like device or <tt>NSDEVTYPE_SANA2</tt> for a networking driver.

The hook function '''must''' return <tt>TRUE</tt> if the connection could be established, and <tt>FALSE</tt> otherwise. Note that it is ''not'' sufficient to just return <tt>FALSE</tt> in case of failure. Your code '''must''' have called the <tt>s2c_ErrorHook</tt> with an explanation why things went wrong first.

<tt>s2c_DisconnectHook</tt>

This hook is called by <tt>S2_CONNECT</tt> when the connection could not be established (the <tt>s2c_ConnectHook</tt> returned <tt>FALSE</tt>), or by <tt>S2_DISCONNECT</tt>, shortly before the link level device is to be closed. The hook function is invoked with the following parameters:

<pre>
disconnect_hook_func(hook,reserved,s2cm);

VOID disconnect_hook_func(struct Hook *hook,APTR reserved,
struct Sana2ConnectionMessage *s2cm);
</pre>

The <tt>reserved</tt> parameter '''must''' be <tt>NULL</tt>. The <tt>s2cm</tt> parameter points to a data structure, as was described for the <tt>s2c_ConnectHook</tt>.

<tt>s2c_Login</tt>

<tt>s2c_Password</tt>

The purpose of these entries is to transport the authentication information the protocol may require. These entries are either <tt>NULL</tt> or contain pointers to <tt>NUL</tt>-terminated strings. If <tt>s2c_Login</tt> is <tt>NULL</tt>, then both login and password '''must''' be assumed to be empty. If <tt>s2c_Login</tt> is not <tt>NULL</tt> and <tt>s2c_Password</tt> is <tt>NULL</tt>, then the password '''must''' be assumed to be empty.

The list of options in <tt>s2c_Options</tt> supplies the necessary information on how the driver is to connect to the link layer. Each node contains an option, which bears a name and contains a value. This pair is what I call a ''parameter''. A number of parameter names are reserved, as will be listed below:

<tt>ppp</tt>.async.device

Name of device driver to use for asynchronous PPP.

Example: <tt>serial.device</tt>

<tt>ppp</tt>.async.unit

Device unit number to use for asynchronous PPP.

Example: <tt>0</tt>

<tt>ppp</tt>.async.speed

Transmission speed to use for asynchronous PPP in bits per second.

Example: <tt>115200</tt>

<tt>ppp.async.buffersize</tt>

Receive buffer size for asynchronous PPP.

Example: <tt>50000</tt>

<tt>ppp.async.checkcarrier</tt>

Whether the carrier signal of the link layer should be tested or not. This can be either 0 (do not test) or 1 (test the carrier signal).

Example: <tt>1</tt>

<tt>ppp.async.rtscts</tt>

Whether or not hardware handshaking should be used by the link layer. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.shared</tt>

Whether or not the link layer device should be opened in shared mode. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.nullmodem</tt>

Whether or not the link layer is a direct connection, such as a nullmodem. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.eof</tt>

Whether or not the underlying serial device driver's 'EOF mode' should be enabled. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.readrequests</tt>

Number of read requests to be used for asynchronous PPP.

Example: <tt>16</tt>

<tt>ppp.async.writerequests</tt>

Number of write requests to be used for asynchronous PPP.

Example: <tt>16</tt>

<tt>ppp.async.accm</tt>

Asynchronous control character map, expressed as a hexadecimal value.

Example: <tt>$000A0000</tt>

<tt>ppp.async.pfc</tt>

Whether or not protocol field compression should be used. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.aacfc</tt>

Whether or not address and control field compression should be used. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.vjhc</tt>

Whether or not Van Jacobson header compression should be used. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.ignorefcs</tt>

Whether or not frame check sequences should be ignored upon reception. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.initialize</tt>

The modem initialization command, with embedded control sequences, if possible.

Example: <tt>AT\r</tt>

<tt>ppp.async.dial</tt>

The modem dial command, with embedded control sequences, if possible.

Example: <tt>ATD12345\r</tt>

<tt>ppp.async.dialtimeout</tt>

The dial timeout, i.e. the number of seconds to wait after the dial command has been sent for the modem to establish a connection.

Example: <tt>60</tt>

<tt>ppp.async.hangup</tt>

The modem hangup command, with embedded control sequences, if possible.

Example: <tt>ATH0\r</tt>

<tt>ppp.idletimeout</tt>

Number of seconds the local host may remain idle, i.e. send no data to the peer, before a watchdog timeout elapses and proceeds to verify that the line is still operational.

Example: <tt>30</tt>

<tt>ppp.localaddress</tt>

The IP address to assign to the local host, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.remoteaddress</tt>

The IP address to assume for the peer, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.dns1address</tt>

The IP address to be used by the primary domain name server, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.dns2address</tt>

The IP address to be used by the secondary domain name server, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.maxfail</tt>

The maximum number of negative configuration acknowledgements to be sent before the PPP negotiation process switches to reject those options.

Example: <tt>5</tt>

<tt>ppp.maxterm</tt>

The maximum number of termination requests to be sent before the respective PPP network or link protocol gives up.

Example: <tt>2</tt>

<tt>ppp.maxconfig</tt>

The maximum number of configuration requests to be sent before the respective PPP network or link protocol gives up.

Example: <tt>10</tt>

<tt>ppp.timeout</tt>

The number of seconds that have to pass before the respective PPP network or link protocol will retry to do whatever didn't work during the last attempt.

Example: <tt>3</tt>

<tt>ppp.mtu</tt>

The maximum transmission unit to use.

Example: <tt>1500</tt>

<tt>ppp.peeridletimeout</tt>

Number of seconds the peer may remain idle, i.e. send no data to the local host, before a watchdog timeout elapses and proceeds to verify that the line is still operational.

Example: <tt>30</tt>

<tt>ppp.rejectpap</tt>

Whether or not the Password Authentication Protocol should be accepted, if offered by the peer. This can be either <tt>0</tt> (accept) or <tt>1</tt> (reject).

Example: <tt>0</tt>

<tt>ppp.sendid</tt>

A flag which controls whether the local host should send LCP identification packets or not. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.pap.timeout</tt>

The Password Authentication Protocol requires that the server answers to the client's request to log in. The server may be unable to respond immediately, which means that the client will have to repeat its request. A short delay should separate each request sent, such as three seconds.

Example: <tt>3</tt>

<tt>ppp.pap.retry</tt>

If the client does not manage to authenticate with the server immediately, it may resend the authentication request several times. But the attempts have to stop eventually, such as after having resent the message ten times.

Example: <tt>10</tt>

<tt>ppp.dummyremoteaddress</tt>

Whether or not the PPP driver should make up an IP address if the peer refuses to state its own IP address.

Example: <tt>1</tt>

<tt>logfile</tt>

The name of a log file to create. If the file already exists, then new data should be appended to it.

Example: <tt>t:logfile</tt>

<tt>logoptions</tt>

A list of options which control what exactly should be logged.

<tt>ppp.ethernet.device</tt>

Name of device driver to use for PPPoE (PPP over Ethernet).

Example: <tt>a2065.device</tt>

<tt>ppp.ethernet.unit</tt>

Device unit number to use for PPPoE.

Example: <tt>0</tt>

<tt>ppp.ethernet.raw</tt>

Whether or not raw link layer frames should be constructed for transmission or not. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.ethernet.bypass</tt>

Whether or not the IP packet transmission and reception should bypass several copying steps. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.ethernet.readpackets</tt>

The number of read requests to queue for the link layer.

Example: <tt>16</tt>

<tt>ppp.ethernet.writepackets</tt>

The number of write requests to queue for the link layer.

Example: <tt>16</tt>

<tt>ppp.ethernet.service</tt>

The name of the PPPoE service to request.

Example: <tt>?</tt>

<tt>ppp.ethernet.ac</tt>

The name of the PPPoE access concentrator to request.

Example: <tt>?</tt>

<tt>ppp.ethernet.connecttimeout</tt>

The number of seconds to wait for the PPPoE server to allow a session to be opened.

Example: <tt>3</tt>

While this list of parameters may suggest that the command described above can be used solely with the PPP protocol, do not let that put you off. This list is merely the starting point, but it is not set in stone that it cannot be extended.

The names of the parameters are not case sensitive. As the names suggest, the name space itself is hierarchic in construction, i.e. everything related to the PPP protocol bears a name starting with the letters 'ppp' with the dot '.' separating the individual items. By this rule, ppp.async refers to options that concern asynchronous PPP and ppp.ethernet to options that concern PPP over Ethernet wire.

To add your own parameter, register it with the maintainer of the SANA-II standard or prefix its name with the letters 'x-'. For example, to use your own kind of 'ppp.ethernet.connecttimeout' parameter, change the name of the last component like this: ppp.ethernet.x-connecttimeout. No officially-registered parameter will ever begin with the prefix 'x-'.

The command should work as follows:

# The client must set up the <tt>Sana2Connection</tt> data structure, initialize the <tt>s2c_Size</tt>, <tt>s2c_Options</tt>, <tt>s2c_ErrorHook</tt>, <tt>s2c_ConnectHook</tt>, <tt>s2c_DisconnectHook</tt>, <tt>s2c_Login</tt> and <tt>s2c_Password</tt> fields.
# The connection options must be filled in, which means that nodes containing the respective information must be stored in the <tt>s2c_Options</tt> list. The client must make sure that the syntax of the parameters conforms to the specifications described above.
# A pointer to the <tt>Sana2Connection</tt> data structure is placed in the <tt>ios2_Data</tt> member of an <tt>IOSana2Req</tt>, the command is set to <tt>S2_CONNECT</tt> and the request is sent via <tt>DoIO()</tt> or <tt>SendIO()</tt>.
# The driver receives the request and begins to examine the contents of the <tt>s2c_Options</tt> list, as provided in the data structure pointed to by the <tt>ios2_Data</tt> member of the request. Unknown options are ignored, options whose values do not conform to the syntax specification are rejected; this is done by calling the <tt>s2c_ErrorHook</tt> with an error message referring to the option in question and by returning the <tt>IOSana2Req</tt> with an error code of <tt>S2ERR_BAD_ARGUMENT</tt> and wire error code of <tt>S2WERR_INVALID_OPTION</tt>.
# If the options are all in good order, the driver proceeds to verify that all mandatory options are provided. If this is not the case, the <tt>s2c_ErrorHook</tt> is called with an error message referring to the option in question and the <tt>IOSana2Req</tt> is returned with an error code of <tt>S2ERR_BAD_ARGUMENT</tt> and wire error code of <tt>S2WERR_MISSING_OPTION</tt>.
# The driver proceeds to do its local initialization, which involves opening the link layer device, etc. If this initialization fails, the <tt>s2c_ErrorHook</tt> is called with an error message referring to the problem and the <tt>IOSana2Req</tt> is returned with an appropriate error code.
# When the initialization has finished, the driver may invoke the <tt>s2c_ConnectHook</tt> callback. Some drivers may require this, such as asynchronous PPP, some may not, such as PPPoE. The purpose of the hook function is to give the client a chance to perform modem initializations and connect to the peer. If the <tt>s2c_ConnectHook</tt> cannot perform its duties, it has to invoke the <tt>s2c_ErrorHook</tt> with an error message and eventually return <tt>FALSE</tt>. If <tt>FALSE</tt> is returned, the driver must invoke the <tt>s2c_DisconnectHook</tt>, reverse any initializations it had made and eventually returned the <tt>IOSana2Req</tt> with an appropriate error code. If the <tt>s2c_ConnectHook</tt> returned <tt>TRUE</tt>, then the driver must proceed with the actions that require that the link layer is operational. A protocol negotiation may follow, which, if successful, will make the driver return the <tt>IOSana2Req</tt> with an error code of zero, indicating success. If successful, the SANA-II events <tt>S2EVENT_CONNECT</tt> and <tt>S2EVENT_ONLINE</tt> must be sent.
# The command will eventually return, but the client '''must not''' release the memory allocated for the <tt>Sana2Connection</tt> structure and the option nodes in the <tt>s2c_Options</tt> list. This is because the driver may have to invoke the <tt>s2c_DisconnectHook</tt> hook due to the connection shutting down on its own accord.

The connect and disconnect hook functions '''must not''' be called from interrupt code. For each hook only a <tt>Task</tt> calling context of unknown priority must be assumed. Also, stack space is provided only to call <tt>exec.library</tt> and <tt>utility.library</tt> functions. The callback shall not place excessive data on the stack. Stack space should be considered limited.

I propose a command with the following semantics:

<pre>
NAME
S2_CONNECT -- Establish a link layer connection and go
online.

FUNCTION
This command is for use by networking devices which require
a special link layer device to transmit their data, such as
an asynchronous serial line and need to know about the
configuration parameters necessary to open the connection.

IO REQUEST
ios2_Command - S2_CONNECT
ios2_Data - Pointer to Sana2Connection structure
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number

NOTES
If successful, this command implies S2_ONLINE, i.e. the
link layer is allocated and used by the driver.

The contents of the Sana2Connection structure must be valid
until the connection is eventually shut down. The driver will
need to cache it, so it must not be deallocated or otherwise
modified.

Note that S2_ONLINE does not necessarily imply S2_CONNECT, if
the S2_CONNECT command is listed as supported by the driver via
NSCMD_DEVICEQUERY. If S2_CONNECT is not listed as supported,
S2_ONLINE obviously implies connect functionality.

S2_CONNECT/S2_DISCONNECT do not nest.

SEE ALSO
S2_DISCONNECT</pre>
I propose that the following command number should be assigned:

<tt>#define S2_CONNECT 0xC005</tt>

== S2_DELMULTICASTADDRESS ==

<pre>
NAME
S2_DELMULTICASTADDRESS -- Disable an interface multicast address.

FUNCTION
This command causes device driver to disable multicast packet
reception for the requested address.

It is an error to disable a multicast address that is not enabled.

IO REQUEST
ios2_Command - S2_DELMULTICASTADDRESS
ios2_SrcAddr - Multicast address to disable.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Multicast addresses are added globally -- anyone using the device
may receive packets as a result of any multicast address which has
been added for the device.

Since multicast addresses are not "bound" to a particular packet type,
each enabled multicast address has an "enabled" count associated with
it so that if two protocols add the same multicast address and later
one removes it, it is still enabled until the second removes it.

SEE ALSO
S2_ADDMULTICASTADDRESS
</pre>

== S2_DEVICEQUERY ==

<pre>
NAME
S2_DEVICEQUERY -- Return parameters for this network interface.

FUNCTION
This command causes the device driver to report information about the
device. Up to SizeAvailable bytes of the information is copied
into a buffer pointed to by ios2_StatData. The format of the data is
as follows:

struct Sana2DeviceQuery
{
/*
** Standard information
*/
ULONG SizeAvailble; /* bytes available */
ULONG SizeSupplied; /* bytes supplied */
LONG DevQueryFormat; /* this is type 0 */
LONG DeviceLevel; /* this document is level 0 */

/*
** Common information
*/
UWORD AddrFieldSize; /* address size in bits */
ULONG MTU; /* maximum packet data size */
LONG bps; /* line rate (bits/sec) */
LONG HardwareType; /* what the wire is */

/*
** Format specific information
*/
};

The SizeAvailable specifies the number of bytes that the caller
is prepared to accomodate, including the standard information fields.

SizeSupplied is the number of bytes actually supplied,
including the standard information fields, which will not exceed
SizeAvailable.

<devices/sana2.h> includes constants for these values. If your
hardware does not have a number assigned to it, you must contact
the AmigaOS development team to get a hardware number.

IO REQUEST
ios2_Command - S2_DEVICEQUERY.
ios2_StatData - Pointer to Sana2DeviceQuery structure to fill in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
</pre>

== S2_DISCONNECT ==

This command complements <tt>S2_CONNECT</tt> in that it tears down a connection. It uses the same <tt>Sana2Connection</tt> structure and hooks, but most of these members are ignored.

The command should work as follows:

# The client must set up the <tt>Sana2Connection</tt> data structure, initialize the <tt>s2c_Size</tt>, <tt>s2c_Options</tt>, <tt>s2c_ErrorHook</tt>, <tt>s2c_ConnectHook</tt>, <tt>s2c_DisconnectHook</tt>, <tt>s2c_Login</tt> and <tt>s2c_Password</tt> fields. The <tt>s2c_Options</tt>, <tt>s2c_ConnectHook</tt>, <tt>s2c_Login</tt> and <tt>s2c_Password</tt> fields will be ignored, but the client should play things safe.
# A pointer to the <tt>Sana2Connection</tt> data structure is placed in the <tt>ios2_Data</tt> member of an <tt>IOSana2Req</tt>, the command is set to <tt>S2_DISCONNECT</tt> and the request is sent via <tt>DoIO()</tt> or <tt>SendIO()</tt>.
# The driver receives the request and proceeds to reverse the steps that previously allowed it to establish a connection. This includes telling the peer to shut down the link, but it does not include cleaning up the link layer device access, i.e. no I/O requests used for accessing a modem may be shut down yet.
# The <tt>s2c_DisconnectHook</tt> may be invoked with the proper parameters. Some drivers, such as for asynchronous PPP, will need the hook to tell the modem to hang up the line. Some drivers, such as for PPPoE, may not need this hook and thus ignore it.
# The initialization is reversed completely, all resources allocated when the connection was previously opened are released. The <tt>IOSana2Req</tt> is returned with an error code of zero, indicating success. The SANA-II event <tt>S2EVENT_DISCONNECT</tt> must be sent, and, if necessary, <tt>S2EVENT_OFFLINE</tt>.

The connect and disconnect hook functions must not be called from interrupt code. For each hook only a <tt>Task</tt> calling context of unknown priority must be assumed. Also, stack space is provided only to call <tt>exec.library</tt> and <tt>utility.library</tt> functions. The callback shall not place excessive data on the stack. Stack space should be considered limited.

I propose a command with the following semantics:

<pre>
NAME
S2_DISCONNECT -- Go offline and close a link layer connection
previously established with S2_CONNECT.

FUNCTION
This command complements the S2_CONNECT command in that it
reverses the steps taken to establish a link layer connection.

IO REQUEST
ios2_Command - S2_DISCONNECT
ios2_Data - Pointer to Sana2Connection structure
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number

NOTES
If successful, this command implies S2_OFFLINE, i.e. the
link layer is deallocated.

The driver must ignore the S2_DISCONNECT command and
recover gracefully if the S2_CONNECT was never sent or
returned with an error.

The contents of the Sana2Connection structure are valid only
until the device driver has processed the command and returned
the IOSana2Req. Any data the driver may need to retain beyond
that point of time must be copied.

Once the S2_DISCONNECT command has returned, it is safe to dispose
of the Sana2Connection structure provided at S2_CONNECT time.

Note that S2_OFFLINE does not necessarily imply S2_DISCONNECT, if
the S2_DISCONNECT command is listed as supported by the driver via
NSCMD_DEVICEQUERY. If S2_DISCONNECT is not listed as supported,
S2_OFFLINE obviously implies disconnect functionality.

S2_CONNECT/S2_DISCONNECT do not nest.

SEE ALSO
S2_CONNECT
</pre>

I propose that the following command number should be assigned:

<tt>#define S2_DISCONNECT 0xC006</tt>

== S2_GETDNSADDRESS ==

The PPP negotiation process may produce information on which domain name and NetBIOS name servers are available to the client. I think that it is doubtful that the availability of NetBIOS name servers will be useful for Amiga software (let alone whether NetBIOS name resolution has a future), which is why I suggest that a SANA-II command for returning only the domain name servers is introduced.

I propose a command with the following semantics:

<pre>
NAME
S2_GETDNSADDRESS -- Obtain the addresses of the primary
and secondary domain name servers.

FUNCTION
Obtain the addresses of the domain name servers available to the
client using this driver's address.

IO REQUEST
ios2_Command - S2_GETDNSADDRESS
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number
ios2_SrcAddr - Address of primary domain name server
ios2_DstAddr - Address of secondary domain name server

NOTES
The size of the address returned by S2_GETPEERADDRESS must not be
different from the size as returned by the S2_DEVICEQUERY command. For
example, if a 32 bit IPv4 address was advertized, the driver must not
return a 128 bit IPv6 address instead.

If the driver is unable to return the primary domain name server
address (ios2_SrcAddr) or the secondary domain name server address
(ios2_DstAddr) it must fill the respective address fields with zeroes.
It is legal for a driver to respond to the S2_GETDNSADDRESS command
with two zero addresses (both ios2_SrcAddr and ios2_DstAddr filled
with zeroes).
</pre>

I propose that the following command number should be assigned:
<tt>#define S2_GETDNSADDRESS 0xC003</tt>

This command may be useful beyond the typical application (PPP) described above.

== S2_GETEXTENDEDGLOBALSTATS ==

There already exists a SANA-II command for querying global device statistics (<tt>S2_GETGLOBALSTATS</tt>) which should be common to all kinds of networking devices. Statistics that are particular to a certain device type are intended to be returned through the <tt>S2_GETSPECIALSTATS</tt> command. I feel that these mechanisms both fail to cater well enough for dial-up or session-oriented networking applications such as PPP or PPPoE. Since the data structure used by <tt>S2_GETGLOBALSTATS</tt> is of a fixed size and not intended to accomodate for new fields, I propose to introduce a new command which uses a different data structure, as follows:

<syntaxhighlight lang="C" line>
struct Sana2ExtDeviceStats
{
ULONG s2xds_Length;
ULONG s2xds_Actual;

S2QUAD s2xds_PacketsReceived;
S2QUAD s2xds_PacketsSent;
S2QUAD s2xds_BadData;
S2QUAD s2xds_Overruns;
S2QUAD s2xds_UnknownTypesReceived;
S2QUAD s2xds_Reconfigurations;
struct timeval s2xds_LastStart;

struct timeval s2xds_LastConnected;
struct timeval s2xds_LastDisconnected;
struct timeval s2xds_TimeConnected;
};
</syntaxhighlight>

Before I proceed to explain what purposes the individual members serve, a few words on the <tt>S2QUAD</tt> type, which is defined as follows:
<tt>typedef struct { ULONG s2q_High; ULONG s2q_Low; } S2QUAD;</tt>

In other words, the <tt>S2QUAD</tt> type stands for an unsigned 64 bit big endian integer, as expressed in ISO 'C' terms.

The structure members have the following purposes:

<tt>s2xds_Length</tt>

This is the size of the data structure to be filled in and should be initialized by the caller to <tt>sizeof(struct Sana2ExtDeviceStats)</tt>. Smaller values are permitted, but these '''must not''' be smaller than 8 (which covers the <tt>s2xds_Length</tt> and <tt>s2xds_Actual</tt> members). A driver which finds an <tt>s2xds_Length</tt> < 8 '''must''' treat this as an error and reject the command with <tt>ios2_Req.io_Error</tt>=<tt>IOERR_BADLENGTH</tt>.

<tt>s2xds_Actual</tt>

The size of the data structure filled with information. This member is initialized by the driver and '''must''' be <= <tt>s2xds_Length</tt>.

<tt>s2xds_PacketsReceived</tt>

Number of packets that this unit has received. This is a 64 bit integer.

<tt>s2xds_PacketsSent</tt>

Number of packets that this unit has sent. This is a 64 bit integer.

<tt>s2xds_BadData</tt>

Number of bad packets received (i.e., hardware CRC failed). This is a 64 bit integer.

<tt>s2xds_Overruns</tt>

Number of packets dropped due to insufficient resources available in the network interface. This is a 64 bit integer.

<tt>s2xds_UnknownTypesReceived</tt>

Number of packets received that had no pending read command with the appropriate packet type. This is a 64 bit integer.

<tt>s2xds_Reconfigurations</tt>

Number of network reconfigurations since this unit was last configured. This is a 64 bit integer.

<tt>s2xds_LastStart</tt>

The time when this unit last went on-line.

<tt>s2xds_LastConnected</tt>

The time when this unit last established a connection. For dial-up connections, this should be the time when the underlying serial line started to accumulate costs. <tt>s2xds_LastConnected</tt> '''must''' be set to zero if the unit never managed to make a connection.

<tt>s2xds_LastDisconnected</tt>

The time when this unit last shut down a connection. For dial-up connections, this should be the time when the underlying serial line stopped accumulating costs, e.g. when the modem's carrier signal was lost. <tt>s2xds_LastDisconnected</tt> '''must''' be set to zero if the unit never disconnected.

<tt>s2xds_TimeConnected</tt>

The time this unit has been connected. For dial-up connections this should be the time between now and when the underlying serial line started accumulating costs.

If this unit is not currently connected, then <tt>s2xds_TimeConnected</tt> '''must''' be set to zero. This means in particular that when the connection is lost, <tt>s2xds_TimeConnected</tt> '''must''' be immediately set to zero and <tt>s2xds_LastDisconnected</tt> '''must''' be filled in so that client software can query how long the unit was connected by subtracting <tt>s2xds_LastConnected</tt> from <tt>s2xds_LastDisconnected</tt>.

If this unit is currently connected, <tt>s2xds_TimeConnected</tt> '''must never''' be zero; if necessary, set <tt>s2xds_TimeConnected.tv_secs=0</tt> and <tt>s2xds_TimeConnected.tv_micros=1</tt>.

If <tt>s2xds_TimeConnected</tt> is zero, check <tt>s2xds_LastConnected</tt> and <tt>s2xds_LastDisconnected</tt>; if the latter two are not zero, you can calculate the previous connection time by subtracting <tt>s2xds_LastConnected</tt> from <tt>s2xds_LastDisconnected</tt>.

The layout and semantics used by the <tt>Sana2ExtDeviceStats</tt> data structure suggest that there is a difference between the underlying networking media (the link layer) and the state of the protocol that is running on top of it. With drivers for networking hardware such as Ethernet there was no difference between these two, but for protocols like SLIP, PPP or PPPoE there is a difference. The difference is in that a session or connection may exist for a certain time whereas the protocol running inside that session may be switched 'online' later. The primary purpose of the <tt>s2xds_LastConnected</tt>, <tt>s2xds_LastDisconnected</tt> and <tt>s2xds_TimeConnected</tt> fields is to allow for cost accounting and traffic monitoring (so that, for example, a driver may be disconnected after it has been idle for a while) to be written.

I propose a command with the following semantics:

<pre>
NAME
S2_GETEXTENDEDGLOBALSTATS -- Get interface accumulated statistics;
updated version.

FUNCTION
This command causes the device driver to retrieve various global
runtime statistics for this network interface. The format of the data
returned is as follows:

struct Sana2ExtDeviceStats
{
ULONG s2xds_Length;
ULONG s2xds_Actual;

S2QUAD s2xds_PacketsReceived;
S2QUAD s2xds_PacketsSent;
S2QUAD s2xds_BadData;
S2QUAD s2xds_Overruns;
S2QUAD s2xds_UnknownTypesReceived;
S2QUAD s2xds_Reconfigurations;
struct timeval s2xds_LastStart;

struct timeval s2xds_LastConnected;
struct timeval s2xds_LastDisconnected;
struct timeval s2xds_TimeConnected;
};

IO REQUEST
ios2_Command - S2_GETEXTENDEDGLOBALSTATS
ios2_StatData - Pointer to Sana2ExtDeviceStats structure
to fill in
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number
</pre>

I propose that the following command number should be assigned:
<tt>#define S2_GETEXTENDEDGLOBALSTATS 0xC004</tt>

== S2_GETGLOBALSTATS ==

<pre>
NAME
GetGlobalStats -- Get interface accumulated statistics.

FUNCTION
This command causes the device driver to retrieve various global
runtime statistics for this network interface. The format of the
data returned is as follows:

struct Sana2DeviceStats
{
ULONG PacketsReceived;
ULONG PacketsSent;
ULONG BadData;
ULONG Overruns;
ULONG UnknownTypesReceived;
ULONG Reconfigurations;
timeval LastStart;
};

IO REQUEST
ios2_Command - S2_GETGLOBALSTATS.
ios2_StatData - Pointer to Sana2DeviceStats structure to fill.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

SEE ALSO
S2_GETSPECIALSTATS
</pre>

== S2_GETNETWORKINFO ==

<pre>
NAME
S2_GETNETWORKINFO -- Get information on current network.

FUNCTION
This command provides information on the status of the currently
used network. If this command completes successfully, ios2_StatData
will contain a pointer to a tag list that contains information on
the network. The S2INFO_#? tags used are defined in the
devices/sana2wireless.h include file.

The returned taglist is allocated from the supplied memory pool.
To discard the results of this command, the entire memory pool
should be destroyed.

INPUTS
ios2_Data - Pointer to an Exec memory pool.

RESULTS
ios2_Data - Remains unchanged.
ios2_StatData - Pointer to a tag list.
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

== S2_GETNETWORKS ==

<pre>
NAME
S2_GETNETWORKS -- Scan for available networks.

FUNCTION
This command supplies details of available networks. If the scan
should be limited to one specific network, the S2INFO_SSID tag
should specify its name.

If this command completes successfully, ios2_StatData will contain
an array of pointers to tag lists, each of which contains
information on a single network. The device will set ios2_DataLength
to the number of elements in this array.

The returned taglists are allocated from the supplied memory pool.
To discard the results of this command, the entire memory pool
should be destroyed.

The S2INFO_#? tags used with this command are defined in the
devices/sana2wireless.h include file.

INPUTS
ios2_Data - Pointer to an Exec memory pool.
ios2_StatData - Pointer to taglist that specifies parameters to use.

RESULTS
ios2_DataLength - Number of tag lists returned.
ios2_Data - Remains unchanged.
ios2_StatData - Pointer to an array of tag lists.
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

== S2_GETPEERADDRESS ==

As part of the negotiation process, the PPP protocol can return the addresses used by the peer (the other side of the point-to-point connection PPP establishes; typically a dial-in server) and assigned to the client establishing the connection. The SANA-II standard does not provide for a mechanism to return such information. Existing drivers therefore had to resort to other means, such as by setting global environment variables containing this information.

I propose a command with the following semantics:

<pre>
NAME
S2_GETPEERADDRESS -- Obtain the addresses used by the peer
(server) and the client of a point-to-point connection.

FUNCTION
Obtain the address used by the peer of a point-to-point connection and
the address assigned to the local driver.

IO REQUEST
ios2_Command - S2_GETPEERADDRESS
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number
ios2_SrcAddr - Address assigned to the local driver
ios2_DstAddr - Address used by the peer

NOTES
The size of the address returned by S2_GETPEERADDRESS must not be
different from the size returned by the S2_DEVICEQUERY command. For
example, if a 32 bit IPv4 address was advertized, the driver must not
return a 128 bit IPv6 address instead.

If the driver is unable to return the local driver address
(ios2_SrcAddr) or the peer's address (ios2_DstAddr) it must fill the
respective address fields with zeroes. It is legal for a driver to
respond to the S2_GETPEERADDRESS command with two zero addresses (both
ios2_SrcAddr and ios2_DstAddr filled with zeroes).
</pre>

I propose that the following command number should be assigned:
<tt>#define S2_GETPEERADDRESS 0xC002</tt>

This command may be useful beyond the typical application (PPP) described above.

== S2_GETSIGNALQUALITY ==

<pre>
NAME
S2_GETSIGNALQUALITY -- Get signal quality statistics.

FUNCTION
This command fills in the supplied Sana2SignalQuality structure with
current signal and noise levels. The unit for these figures is dBm.
Typically, they are negative values.

INPUTS
ios2_StatData - Pointer to Sana2SignalQuality structure.

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
ios2_StatData - Pointer to filled Sana2SignalQuality structure.
</pre>

== S2_GETSPECIALSTATS ==

<pre>
NAME
S2_GETSPECIALSTATS -- Get network type specific statistics.

FUNCTION
This function returns statistics which are specific to the type of
network medium this driver controls. For example, this command could
return statistics common to all Ethernets which are not common to all
network mediums in general.

The supplied Sana2SpecialStatData structure is given below:

struct Sana2SpecialStatData
{
ULONG RecordCountMax;
ULONG RecordCountSupplied;
struct Sana2StatRecord[RecordCountMax];
};

The format of the data returned is:

struct Sana2StatRecord
{
ULONG Type; /* Amiga registered */
LONG Count; /* the stat itself */
char *String; /* null terminated */
};

The RecordCountMax field specifies the number of records that the
caller is prepared to accomodate.

RecordCountSupplied is the number of record actually supplied which
will not exceed RecordCountMax.

IO REQUEST
ios2_Command - S2_GETSPECIALSTATS.
ios2_StatData - Pointer to a Sana2SpecialStatData structure to fill.
RecordCountMax must be initialized.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Amiga will maintain registered statistic Types.

SEE ALSO
S2_GETGLOBALSTATS, <devices/sana2specialstats.h>
</pre>

== S2_GETSTATIONADDRESS ==

<pre>
NAME
S2_GETSTATIONADDRESS -- Get default and interface address.

FUNCTION
This command causes the device driver to copy the current interface
address into ios2_SrcAddr, and to copy the factory default station
address (if any) into ios2_DstAddr.

IO REQUEST
ios2_Command - S2_GETSTATIONADDRESS.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
ios2_SrcAddr - Current interface address.
ios2_DstAddr - Default interface address (if any).

SEE ALSO
S2_CONFIGINTERFACE
</pre>

== S2_GETTYPESTATS ==

<pre>
NAME
S2_GETTYPESTATS -- Get accumulated type specific statistics.

FUNCTION
This command causes the device driver to retrieve various packet type
specific runtime statistics for this network interface. The format of
the data returned is as follows:

struct Sana2TypeStatData
{
LONG PacketsSent;
LONG PacketsReceived;
LONG BytesSent;
LONG BytesReceived;
LONG PacketsDropped;
};

IO REQUEST
ios2_Command - S2_GETTYPESTATS.
ios2_PacketType - Packet type of interest.
ios2_StatData - Pointer to TypeStatData structure to fill in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Statistics for a particular packet type are only available while that
packet type is being ``tracked''.

SEE ALSO
S2_TRACKTYPE, S2_UNTRACKTYPE
</pre>

== S2_MULTICAST ==

<pre>
NAME
S2_MULTICAST -- Multicast a packet on network.

FUNCTION
This command works the same as CMD_WRITE except that it also performs
whatever special processing of the packet is required to do a
multicast send. The actual multicast mechanism is neccessarily
network/interface/device specific.

IO REQUEST
ios2_Command - S2_MULTICAST.
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_PacketType - Packet type to send.
ios2_DstAddr - Destination interface address for this packet.
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
This command can fail for many reasons and
is not supported by all networks and/or
network interfaces.
ios2_WireError - More specific error number.

NOTES
The address supplied in ios2_DstAddr will be sanity checked (if
possible) by the driver. If the supplied address fails this sanity
check, the multicast request will fail immediately with ios2_Error
set to S2WERR_BAD_MULTICAST.

Another Amiga will not receive a multicast packet unless it has had
the particular multicast address being used S2_ADDMULTICASTADRESS'd.

SEE ALSO
CMD_WRITE, S2_BROADCAST, S2_ADDMULTICASTADDRESS
</pre>

== S2_OFFLINE ==

<pre>
NAME
S2_OFFLINE -- Remove interface from service.

FUNCTION
This command removes a network interface from service.

IO REQUEST
ios2_Command - S2_OFFLINE.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Aborts all pending reads and writes with ios2_Error set to
S2ERR_OUTOFSERVICE.

While the interface is offline, all read, writes and any other
command that touches interface hardware will be rejected with
ios2_Error set to S2ERR_OUTOFSERVICE.

This command is intended to permit a network interface to be
tested on an otherwise live system.

SEE ALSO
S2_ONLINE
</pre>

== S2_ONEVENT ==

<pre>
NAME
S2_ONEVENT -- Return when specified event occures.

FUNCTION
This command returns when a particular event condition has occured
on the network or this network interface.

IO REQUEST
ios2_Command - S2_ONEVENT.
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_WireError - Mask of event(s) to wait for
(from <devices/sana2.h>).

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - Mask of events that occured.

NOTES
If this device driver does not understand the specified event
condition(s) then the command returns immediately with
ios2_Req.io_Error set to S2_ERR_NOT_SUPPORTED and ios2_WireError
S2WERR_BAD_EVENT. A successful return will have ios2_Error set to
zero ios2_WireError set to the event number.

All pending requests for a particular event will be returned when
that event occurs.

All event types that cover a particular condition are returned when
that condition occures. For instance, if an error is returned by
a buffer management function during receive processing, events of
types S2EVENT_ERROR, S2EVENT_RX and S2EVENT_BUFF would be returned if
pending.

Types ONLINE and OFFLINE return immediately if the device is
already in the state to be waited for.
</pre>

== S2_ONLINE ==

<pre>
NAME
S2_ONLINE -- Put a network interface back in service.

FUNCTION
This command places an offline network interface back into service.

IO REQUEST
ios2_Command - S2_ONLINE.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
This command is responsible for putting the network interface
hardware back into a known state (as close as possible to the
state before S2_OFFLINE) and resets the unit global and special
statistics.

SEE ALSO
S2_OFFLINE
</pre>

== S2_READMGMT ==

<pre>
NAME
S2_READMGMT -- Read a management frame.

FUNCTION
Reads a raw IEEE 802.11 management frame from the device. The buffer
management mechanism used is simpler than that used for data
packets (e.g. with CMD_READ): a buffer pointer and a length value
are passed to the device.

As with CMDREAD/S2_READORPHAN, multiple S2_READMGMT requests can
(and should) be queued concurrently to ensure no incoming frames are
missed.

INPUTS
ios2_DataLength - size of frame buffer.
ios2_Data - pointer to a frame buffer.

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
ios2_DataLength - actual size of received frame.
ios2_Data - pointer to the filled frame buffer.
</pre>

== S2_READORPHAN ==

<pre>
NAME
S2_READORPHAN -- Get a packet for which there is no reader.

FUNCTION
Get the next packet available that does not satisfy any then-pending
CMD_READ requests. The data returned in the ios2_Data structure is
normally the Data Link Layer packet type field and the packet data. If
bit SANA2IOB_RAW is set in ios2_Flags, then the entire Data Link Layer
packet, including both header and trailer information, will be
returned.

IO REQUEST
ios2_Command - CMD_READORPHAN.
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
ios2_Flags - The following flags may be returned:
SANA2IOB_RAW
SANA2IOB_BCAST
SANA2IOB_MCAST
ios2_SrcAddr - Source interface address of packet.
ios2_DstAddr - Destination interface address of packet.
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

NOTES
This is intended for debugging and management tools. Protocols should
not use this.

As with 802.3 packets on an ethernet, to determine which protocol
family the returned packet belongs to you may have to specify
SANA2IOB_RAW to get the entire data link layer wrapper (which is where
the protocol type may be kept). Notice this necessarily means that
this cannot be done in a network interface independent fashion. The
driver will, however, fill in the PacketType field to the best of its
ability.

SEE ALSO
CMD_READ, CMD_WRITE
</pre>

== S2_SAMPLE_THROUGHPUT ==

The SANA-II standard already allows for statistics to be returned on the amount of data that has passed through a driver. Unfortunately, that information is not very accurate in that no information is provided on the time span in which the data was accumulated. Such information would be helpful in trying to determine as accurately as possible how large the data throughput actually is. I therefore propose a new command which can be used to obtain that information, which uses the following data structure:

<syntaxhighlight lang="C" line>
struct Sana2ThroughputStats
{
ULONG s2ts_Length;
ULONG s2ts_Actual;

struct Task * s2ts_NotifyTask;
ULONG s2ts_NotifyMask;

struct timeval s2ts_StartTime;
struct timeval s2ts_EndTime;
S2QUAD s2ts_BytesSent;
S2QUAD s2ts_BytesReceived;
S2QUAD s2ts_Updates;
};
</syntaxhighlight>

Before I proceed to explain what purposes the individual members serve, a few words on the <tt>S2QUAD</tt> type, which is defined as follows:

<tt>typedef struct { ULONG s2q_High; ULONG s2q_Low; } S2QUAD;</tt>

In other words, the <tt>S2QUAD</tt> type stands for an unsigned 64 bit big endian integer, as expressed in ISO 'C' terms.

The structure members have the following purposes:

<tt>s2ts_Length</tt>

This is the size of the data structure to be filled in and should be initialized by the caller to <tt>sizeof(struct Sana2ThroughputStats)</tt>. Smaller values are permitted, but these must not be smaller than 8 (which covers the <tt>s2ts_Length</tt> and <tt>s2ts_Actual</tt> members). A driver which finds an <tt>s2ts_Length</tt> < 8 must treat this as an error and reject the command with <tt>ios2_Req.io_Error</tt>=<tt>IOERR_BADLENGTH</tt>.

<tt>s2ts_Actual</tt>

The size of the data structure filled with information. This member is initialized by the driver and must be <= <tt>s2ts_Length</tt>.

<tt>s2ts_NotifyTask</tt>

The <tt>Task</tt> to notify whenever the contents of this data structure change. This must be <tt>NULL</tt> if no notification is desired.

'''Note:''' This feature should be used carefully, as so much data may arrive that the driver will almost be constantly signalling this <tt>Task</tt> that a change has taken place.

It is recommend that periodic polling be used, such as to update displays of a link monitoring program.

<tt>s2ts_NotifyMask</tt>

The signal mask to use for notifying the <tt>Task</tt> whose address is found in <tt>s2ts_NotifyTask</tt> (via <tt>Signal(s2ts->s2ts_NotifyTask,s2ts->s2ts_NotifyMask);</tt>). This must be zero if no notification is desired.

<tt>s2ts_StartTime</tt>

The time when the driver started to fill in this data structure.

<tt>s2ts_EndTime</tt>

The time when the driver last updated the contents of this data structure.

<tt>s2ts_BytesSent</tt>

Total number of bytes sent since the driver started to fill in this data structure. This is a 64 bit integer.

<tt>s2ts_BytesReceived</tt>

Total number of bytes received since the driver started to fill in this data structure. This is a 64 bit integer.

<tt>s2ts_Updates</tt>

Number of times the driver has updated this data structure. This value will increase with every change. This is a 64 bit integer.

A driver implementing this command should take care to update the members <tt>s2ts_EndTime</tt>, <tt>s2ts_BytesSent</tt>, <tt>s2ts_BytesReceived</tt> and <tt>s2ts_Updates</tt> atomically each time changes are made.

I propose a command with the following semantics:

<pre>
NAME
S2_SAMPLE_THROUGHPUT -- Obtain accurate information on
driver data throughput.

FUNCTION
This command installs a data structure which is updated every time
data is sent or received by the driver.

This command must be sent via SendIO() or BeginIO(); until
the associated I/O request is recalled using AbortIO(), the
device unit will continue to update the Sana2ThroughputStats
structure in real time.

IO REQUEST
ios2_Command - S2_SAMPLE_THROUGHPUT
ios2_StatData - Pointer to Sana2ThroughputStats structure
to fill in
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise

NOTES
If this device driver does not understand this command,
it will immediately return the IOSana2Req with
ios2_Req.io_Error set to IOERR_NOCMD. Otherwise, the request will
remain queued until it is removed with AbortIO() later.
</pre>

I propose that the following command number should be assigned:

<tt>#define S2_SAMPLE_THROUGHPUT 0xC007</tt>

== S2_SANA2HOOK ==

The 'traditional' copy call-back functions are installed at <tt>OpenDevice()</tt> time, and they are found in a <tt>TagItem</tt> list which is passed along with the <tt>IOSana2Req</tt>. For the new <tt>Hook</tt>-based call-back functionality, I propose to introduce a new command. This command would take care of installing one single <tt>Hook</tt> which will be invoked with the parameters described in section 3.1. The hook function can key off the <tt>SANA2HookMsg->schm_Method</tt> field to figure out which function should be performed. Once the <tt>Hook</tt> is installed via the command as follows, the driver shall ignore any and all tags passed to it during <tt>OpenDevice()</tt> time.

<pre>
NAME
S2_SANA2HOOK -- Install a Hook to perform operations such as copying,
overriding the call-back functions installed at
OpenDevice() time.

FUNCTION
The S2_SANA2HOOK command is to replace the 'traditional' call-back
functions installed through the TagItem list found in the
IOSana2Req->ios2_BufferManagement field. Instead of assigning a
function pointer for each copying function, all operations are
to be performed through a Hook. This is intended to make the
interface more portable and less dependant on a certain hardware
architecture.

The hook message and the hook data structures allow for more than
copying to be done.

IO REQUEST
ios2_Command - S2_SANA2HOOK
ios2_Data - Points to a struct Sana2Hook, which looks
like this:

struct Sana2Hook
{
struct Hook s2h_Hook;
Tag * s2h_Methods;
};

The structure fields have the following purposes:

s2h_Hook
A standard Hook structure, ready to be
called. Once installed, the complete Hook
structure including its Node structure is
off limits! The s2h_Hook remains installed
until CloseDevice().

s2h_Methods
Points to a table of Tag values, each
identifying a copy method supported
(S2_CopyToBuff, S2_CopyFromBuff,
S2_CopyToBuff16, S2_CopyFromBuff16,
S2_CopyToBuff32, S2_CopyFromBuff32,
S2_DMACopyToBuff32, S2_DMACopyFromBuff32,
S2_DMACopyToBuff64 or S2_DMACopyFromBuff64)
or the logging facility (S2_Log).
The table must be terminated by TAG_END.

The driver will check the table and
verify that the mandatory S2_CopyToBuff
and S2_CopyFromBuff commands are present.
Additional functionality is used as
available if the driver supports it.

ios2_DataLength - Must be >= 20, which is the default length of
the Sana2Hook structure. This may grow in
the future, and larger values for ios2_DataLength
may indicate additional functionality associated
with the Sana2Hook.

RESULTS
ios2_Error - IOERR_NOCMD if this command is not supported
by the driver.

IOERR_BADLENGTH if IOSana2Req->ios2_DataLength
is < 20.

IOERR_UNITBUSY if the Hook was already
installed or if any of the CMD_READ, CMD_WRITE,
S2_MULTICAST or S2_BROADCAST have already been
invoked.

S2WERR_FUNCTIONS_MISSING if the table pointed
to by Sana2Hook->s2h_Methods does not
include the S2_CopyToBuff and S2_CopyFromBuff
tags.

NOTES
The S2_SANA2HOOK command shall be invoked right after OpenDevice()
as very first command.

When the command has been executed, the driver must use the
newly installed Hook for all its copying or logging and cease to
use the call-back functions provided at OpenDevice() time.

The contents of the Sana2Hook structure, as passed to the
driver, must not be modified. This includes the MinNode
at the beginning of the Hook structure which the driver may
need to use for its own purposes.

The table pointed to by Sana2Hook->s2h_Methods must
include at least the S2_CopyToBuff and S2_CopyFromBuff tags.
It must be valid until CloseDevice() is called.

This field is to be treated as private by a protocol stack.
IOSana2Req structures may be duplicated by copying
ios2_BufferManagement, io_Device, and io_Unit.
</pre>

The new command value is defined as follows:

<pre>
#define S2_SANA2HOOK 0xC008
</pre>

The new error code is defined as follows:

<pre>
#define S2WERR_FUNCTIONS_MISSING 24 /* mandatory copy functions are missing */
</pre>

== S2_SETKEY ==

<pre>
NAME
S2_SETKEY -- Set an encryption key.

FUNCTION
Sets one of the encryption keys for the device. Note that
ios2_StatData, if used, points to a byte array representing the RX
RX counter value.

INPUTS
ios2_WireError - Key index.
ios2_PacketType - Encryption type (e.g. S2ENC_WEP).
ios2_DataLength - Key length.
ios2_Data - Key.
ios2_StatData - RX counter number (NULL if unused).

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

== S2_SETOPTIONS ==

<pre>
NAME
S2_SETOPTIONS -- Set network options.

FUNCTION
Set various parameters for the network interface. This command
should be called before going online to set any essential parameters
not covered elsewhere. The S2INFO_#? tags used are defined in the
devices/sana2wireless.h include file.

INPUTS
ios2_Data - Pointer to a taglist that specifies parameters to use.

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

== S2_TRACKTYPE ==

<pre>
NAME
S2_TRACKTYPE -- Accumulate statistics about a packet type.

FUNCTION
This command causes the device driver to accumulate statistics about
a particular packet type. Packet type statistics, for the particular
packet type, are zeroed by this command.

IO REQUEST
ios2_Command - S2_TRACKTYPE.
ios2_PacketType - Packet type of interest.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

SEE ALSO
S2_UNTRACKTYPE, S2_GETTYPESTATS
</pre>

== S2_UNTRACKTYPE ==

<pre>
NAME
S2_UNTRACKTYPE -- End statistics about a packet type.

FUNCTION
This command causes the device driver to stop accumulating
statistics about a particular packet type.

IO REQUEST
ios2_Command - S2_UNTRACKTYPE.
ios2_PacketType - Packet type of interest.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

SEE ALSO
S2_TRACKTYPE, S2_GETTYPESTATS
</pre>

== S2_WRITEMGMT ==

<pre>
NAME
S2_WRITEMGMT -- Write a management frame.

FUNCTION
Writes a raw IEEE 802.11 management frame to the device. The buffer
management mechanism used is simpler than that used for data
packets (e.g. with CMD_WRITE): a buffer pointer and a length value
are passed to the device.

INPUTS
ios2_DataLength - full frame length.
ios2_Data - pointer to a complete IEEE 802.11 management frame.

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

= Callback mechanisms =

== CopyFromBuff ==

<pre>
NAME
CopyFromBuff -- Copy n bytes from an abstract data structure.

SYNOPSIS
success = CopyFromBuff(to, from, n)
d0 a0 a1 d0

BOOL CopyToBuff(VOID *, VOID *, ULONG);

FUNCTION
This function copies 'n' bytes of data in the abstract data structure
pointed to by 'from' into the contigous memory pointed to by 'to'.
'to' must contain at least 'n' bytes of usable memory or innocent
memory will be overwritten.

INPUTS
to - pointer to contiguous memory to copy to.
from - pointer to abstract structure to copy from.
n - number of bytes to copy.

RESULT
success - TRUE if operation was successful, else FALSE.

NOTES
This function must be callable from interrupts. In particular, this
means that this function may not directly or indirectly call any
system memory functions (since those functions rely on Forbid() to
protect themselves) and that you must not compile this function
with stack checking enabled. See the Exec Interrupts
chapter for more details on what is legal in a routine called from
an interrupt handler.

'C' programmers should not compile with stack checking (option '-v'
in SAS) and should geta4() or __saveds.</pre>

== CopyToBuff ==

<pre>
NAME
CopyToBuff -- Copy n bytes to an abstract data structure.

SYNOPSIS
success = CopyToBuff(to, from, n)
d0 a0 a1 d0

BOOL CopyToBuff(VOID *, VOID *, ULONG);

FUNCTION
This function first does any initialization and/or allocation
required to prepare the abstract data structure pointed at by 'to'
to be filled with 'n' bytes of data from 'from'. It then executes
the copy operation.

If, for example, there is not enough memory available to prepare
the abstract data structure, the call is failed and FALSE is returned.

The buffer management scheme should be such that any memory needed
to fulfill CopyToBuff() calls is already allocated from the system
before the call to CopyToBuff() is made.

INPUTS
to - pointer to abstract structure to copy to.
from - pointer to contiguous memory to copy from.
n - number of bytes to copy.

RESULT
success - TRUE if operation was successful, else FALSE.

NOTES
This function must be callable from interrupts. In particular, this
means that this function may not directly or indirectly call any
system memory functions (since those functions rely on Forbid() to
protect themselves) and that you must not compile this function
with stack checking enabled. See the Exec Interrupts
chapter for more details on what is legal in a routine called from
an interrupt handler.

'C' programmers should not compile with stack checking (option '-v'
in SAS) and should geta4() or __saveds.</pre>

== PacketFilter ==

<pre>
NAME
PacketFilter -- Perform filtering operation on CMD_READ's.

SYNOPSIS
keep = PacketFilter(hook, ios2, data)
d0 a0 a2 a1

BOOL PacketFilter(struct Hook *, struct IOSana2Req *, APTR);

FUNCTION
This function (if supplied by a protocol stack) may be used to
reject packets before they are copied into a protocol stack's
internal buffers.

The IOSana2Req structure should be set up to look (almost) exactly
as it would if it was successfully returned for the current packet.
Specifically, the fields that should be set up correctly are:

ios2->ios2_DataLength
ios2->ios2_SrcAddr
ios2->ios2_DstAddr

The "data" pointer must point to the beginning of the packet data
that is stored in contiguous memory. The data should NOT include
any hardware specific headers (unless of course the CMD_READ
request wanted RAW packets).

INPUTS
hook - pointer to the Hook originally supplied during
OpenDevice().
ios2 - The IOSana2Req CMD_READ request that will be used
(the "object" of the Hook call).
data - The packet data (the "message" of the Hook call).

RESULT
success - TRUE if the driver should provide the packet to
the protocol stack, FALSE if the packet should be
ignored.

NOTES
This function must be callable from interrupts. In particular, this
means that this function may not directly or indirectly call any
system memory functions (since those functions rely on Forbid() to
protect themselves) and that you must not compile this function
with stack checking enabled. See the Exec Interrupts
chapter for more details on what is legal in a routine called from
an interrupt handler.

'C' programmers should not compile with stack checking (option '-v'
in SAS) and should geta4() or __saveds.

What does packet filtering do? With the original ``SANA-II Network
Device Driver Specification'', a protocol stack could open a device
and ask for certain packet types. It got all the packets that matched
this type. As it turned out, this could be mighty inefficient if there
were packets that the protocol stack did not use at all. These would
go into read processing of the protocol stack and waste CPU time even
though they could have been easily identified on arrival.</pre>

= Ethernet description =

<pre>#define S2WireType_Ethernet 1

ios2_DataLength:
valid ethernet packets have 64 to 1500 bytes of data.

Address format:
Ethernet addresses consist of 47 bits of address information and
a 1 bit multicast flag. The standard for expressing ethernet
addresses is as 6 bytes (octets) in the order in which the bytes
are transmitted with the low-order bits in a byte transmitted
first. The multicast flag bit is the least-significant bit of the
first byte.

Ethernet addresses in a Sana2IOReq occupy the first 6 bytes of
an address field in transmission order with the low-order bits in
a byte transmitted first.

Station Address:
Each ethernet board must have a unique ethernet hardware address.
Drivers will override any attempt to set the address to anything
other than the ROM address.

Raw reads and writes:
6 bytes of destination address,
6 bytes of source address,
2 bytes of type,
64 to 1500 bytes of data
(followed by 4 byte CRC value covering all of the above
which is hardware generated and checked, hence not included
in even raw packets)

Multicast: Supported

Broadcast: Supported

Promiscuous: Supported

Packet Type Numbers for Ethernet are assigned by:

Xerox Corporation
Xerox Systems Institute
475 Oakmead Parkway, Sunnyvale, CA 94086
Attn: Ms. Fonda Pallone
(408) 737-4652

Some Common Packet Type Numbers:

decimal Hex Description
------- --- -----------
000 0000-05DC IEEE 802.3 Length Field
2048 0800 TCP/IP -- IP
2054 0806 TCP/IP -- ARP
32821 8035 TCP/IP -- RARP
32923 809B Appletalk
33011 80F3 AppleTalk AARP (Kinetics)
33100 814C SNMP
33079 8137-8138 Novell, Inc.</pre>
= ARCNET description =

<pre>S2WireType_Arcnet 7

ios2_DataLength:
506 byte MTU (because of the possibility of two byte Types).
Packets of size 254, 255, or 256 bytes are padded to 257 bytes before
transmition.

Station Address:
ARCNET hardware may have addresses set with jumpers, DIP switches
or software. Different drivers may therefore behave differently
with S2_CONFIGINTERFACE.

Hardware addresses should be assigned by users from highest to lowest
because there is some efficiency gained in the token passing scheme
this way. For example, on a three node network, hardware numbers 254,
253 and 252 should be used rather than 1, 2 and 3.

Raw reads and writes:
Short Packets (1-253 bytes)
Destination Address (1 byte)
Source Address (1 byte)
Count (256-N-Type length) (1 byte)
Padding (to byte number Count)
Type (1 or 2 bytes)
Data (N bytes)

Long Packets (257-506 bytes)
Destination Address (1 byte)
Source Address (1 byte)
zero (1 byte)
Count (512-N-Type length) (1 byte)
Padding (to byte number Count)
Type (1 or 2 bytes)
Data (N bytes)

Multicast: Not Supported

Broadcast: Supported

Promiscuous: Generally Not Supported

Packet Type Numbers for ARCNET are assigned by:
Datapoint Corporation

Some Common Packet Type Numbers

decimal hex description
------- --- -----------
221 DD AppleTalk
240 F0 TCP/IP -- IP (RFC 1051)
241 F1 TCP/IP -- ARP (RFC 1051)
212 F0 TCP/IP IP (RFC 1201, proposed)
213 F1 TCP/IP -- ARP (RFC 1201, proposed)
214 D6 TCP/IP -- RARP (RFC 1201, proposed)
247 F7 Banyan Vines
250 FA Novell IPX
</pre>

= Authors =

== Revision 2 & 3 ==

Copyright © 1992-2000 Amiga, Inc. All Rights Reserved 

Amiga is a registered trademark of Amiga, Inc. Ethernet is a trademark of Xerox Corporation. ARCNET is a trademark of Datapoint Corporation. DECNet is a trademark of Digital Equipment Corporation. AppleTalk is a trademark of Apple Computer, Inc.

== Revision 4 ==

Extending the SANA-II network driver specification 
by Olaf Barthel

(Last updated 02-Mar-2003)

== Revision 5 ==

Hook-based callback function extensions for SANA-II (SANA-IIR5) 
by Olaf Barthel and Heinz Wrobel

== Revision 6 ==

SANA-II IEEE 802.11 wireless API 
by Neil Cafferkey

= Acknowledgments =

== Revision 2 & 3 ==

Many people and companies have contributed to the "SANA-II Network Device Driver Specification". The original SANA-II Autodocs and includes were put together by Ray Brand, Perry Kivolowitz (ASDG) and Martin Hunt. Those original documents evolved to their current state and grew to include this document at the hands of Dale Larson and Greg Miller. Brian Jackson and John Orr provided valuable editing. Randell Jesup has provided sage advice on several occasions. The buffer management callback mechanism was his idea. Dale Luck (GfxBase) and Rick Spanbauer (Ameristar Technologies) have provided valuable comments throughout the process. Nicolas Benezan (ADONIS) provided many detailed and useful comments on weaknesses in late drafts of the specification. The enhancements for better buffer management, clarifications and notes for device implementers were added to the specification by Heinz Wrobel whilst consulting for Amiga Technologies GmbH, yielding revision 3.0 of the specification.

Thanks to all the above and the numerous others who have contributed with their comments, questions and discussions.

= Changes =

== Revision 4 ==

Changes since 24-Dec-2002:

* The <tt>Sana2Connection</tt> data structure used by the <tt>S2_CONNECT</tt> command now must remain valid until the <tt>S2_DISCONNECT</tt> command is sent (see [[#2.4|section 2.4]]).

Changes since 01-May-2002:

* Added the <tt>ppp.async.readrequests</tt> and <tt>ppp.async.eof</tt> configuration keywords.

Changes since 04-Jan-2002:

* Added the <tt>ppp.dummyremoteaddress</tt> and <tt>ppp.ethernet.ac</tt> configuration keywords.

Changes since 10-Dec-2001:

* Converted to HTML format.
* Added the <tt><devices/sana2.h></tt> header file to the appendix.
* The memory alignment for the <tt>S2_DMACopyToBuff64</tt> and <tt>S2_DMACopyFromBuff64</tt> hooks refers to bits and not to bytes.

Changes since 19-Nov-2001:

* Added to the list of reserved configuration keywords (<tt>ppp.idletimeout</tt>, <tt>ppp.peeridletimeout</tt>, <tt>ppp.sendid</tt>).
* Renamed the fields of the <tt>Sana2ExtDeviceStats</tt> structure.
* Clarified that the <tt>S2QUAD</tt> type is a big endian integer.
* More clarifications for the <tt>S2_CONNECT</tt>/<tt>S2_DISCONNECT</tt> and <tt>S2_ONLINE</tt>/<tt>S2_OFFLINE</tt> commands.
* Updated the discussion of the <tt>Sana2DeviceQuery.RawMTU</tt> field, clarifying what is included in the the Ethernet <tt>RawMTU</tt>.
* Updated the <tt><devices/sana2.h></tt> header file. Note that there is no equivalent <tt>"devices/sana2.i"</tt> header file yet.

Changes since 12-Nov-2001:

* Changed the command numbers of <tt>S2_GETPEERADDRESS</tt>, <tt>S2_GETDNSADDRESS</tt>, <tt>S2_GETEXTENDEDGLOBALSTATS</tt>, <tt>S2_CONNECT</tt>, <tt>S2_DISCONNECT</tt> and <tt>S2_SAMPLE_THROUGHPUT</tt> to be NSD-compliant. Also assigned a new number to the <tt>S2_SAMPLE_THROUGHPUT </tt> command.
* Added section 4 ("Extensions for existing commands").
* Added the last paragraph to section 9, relating to the future extension of the <tt>Sana2DeviceQuery</tt> structure.

Changes since 03-Nov-2001:

* Renamed <tt>S2_GETNEWGLOBALSTATS</tt> to <tt>S2_GETEXTENDEDGLOBALSTATS</tt> (see [[#2.3|section 2.3]]).
* The <tt>S2_GETEXTENDEDGLOBALSTATS</tt> now uses 64 bit quantities for the <tt>s2xds_PacketsReceived</tt>, <tt>s2xds_PacketsSent</tt>, <tt>s2xds_BadData</tt>, <tt>s2xds_Overruns</tt>, <tt>s2xds_UnknownTypesReceived</tt> and <tt>s2xds_Reconfigurations</tt> counters.
* In section 2.6 the <tt>S2_SAMPLE_THROUGHPUT</tt> command was modified to use 64 bit integers for all members of the <tt>Sana2ThroughputStats</tt> structure.
* All proposed commands are now listed with their numeric IDs.
* The command autodocs specifically mention the <tt>ios2_BufferManagement</tt> field.
* All references to <tt>ios2_Error</tt> have been replaced with <tt>ios2_Req.io_Error</tt>.
* In section 7 the use of the <tt>IOERR_NOCMD</tt>/<tt>S2ERR_NOT_SUPPORTED</tt> error codes is clarified.
* Section 7 takes a more detailed look at safe default values returned by the query commands.
* Inserted section 3 ("Annotations for existing commands").
* The <tt>S2_CONNECT</tt> and <tt>S2_DISCONNECT</tt> commands now specifically mention the life time of the data they have to deal with.

Changes since 14-Oct-2001:

* Added <tt>S2_CONNECT</tt> and <tt>S2_DISCONNECT</tt> commands.
* Added <tt>S2EVENT_CONNECT</tt> and <tt>S2EVENT_DISCONNECT</tt> events.
* Added section 4 ("New wire error codes").
* In section 5.2 the originally proposed log callback function has been wrapped into a standard Hook structure.
* Removed item on <tt>S2_CONNECT</tt>/<tt>S2_DISCONNECT</tt> from section 7 ("Unsolved problems").
* Added section 8 ("Changes").

== Revision 5 ==

22-Mar-2004:

* Conversion to HTML

21-Jan-2004:

* Added clarifications for <tt>schm_MsgSize</tt>, <tt>slhm_MsgSize</tt>, <tt>slhm_Priority</tt>, <tt>slhm_Name</tt>, <tt>slhm_Message</tt> and <tt>s2h_Hook</tt>.
* Updated the <tt>S2_SANA2HOOK</tt> documentation.
* Shortened section 4.
* Updated section 5.

30-Nov-2003:

* Extended the applicability of the <tt>Hook</tt> to logging.
* Renamed <tt>S2_COPYHOOK</tt> to <tt>S2_SANA2HOOK</tt>, which matches the extended scope it should cover.
* The message passed to the <tt>Hook</tt> now includes a size field which holds the size of the message, expressed in bytes.

06-Oct-2003:

* Replaced the list of new tag items with a single <tt>Hook</tt>, which is installed through a new command.
* Added "Caveats" and "Changes" sections
* Removed the documentation for the originally proposed <tt>TagItem</tt> (sections 3.2.1 through 3.2.10)

= History =

== Revision 2 and 3 ==

This standard has undergone several drafts with long periods for comment from developers and the Amiga community at large. These drafts include a UseNet release which was also distributed on the Fish Disks in June, 1991 (as well as published in the '91 DevCon notes), and the November 7 Draft for Final Comment and Approval distributed via Bix, ADSP and UseNet. There were also several intermediate drafts with more limited distribution.

== Revision 4 ==

(Olaf Barthel)

I've been working on a TCP/IP stack and PPP drivers to go with them for a while and found that there were some things that SANA-II did specifically not address, and which ought to be covered by it. In other areas clarification was needed. Also, discussions I had with Harald Frank suggested that the extensions made by Heinz Wrobel and Stefan Sticht in the SANA-IIR3 specification could need extending.

Layers Library

2025-01-26T19:34:52Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

{{WIP}}
== Layers Library ==

This article describes the layers library which provides routines that are used to manage overlapping rectangular drawing areas that share a common display. Intuition uses the layers library to manage its system of windows.

The Graphics Library describes the use of ''regions'', special structures used to mask off areas where drawing can take place. Regions are installed through the layers library function InstallClipRegion() but the routines for the creation, disposal and manipulation of regions are part of the graphics library.

== Layers ==

The concept of a ''layer'' is closely tied to Intuition windows. A layer is a rectangular drawing area. A layer can overlap other layers and has a display priority that determines whether it will appear in front or behind other layers. Every Intuition window has an associated Layer structure. Layers allow Intuition and application programs to :

* Share a display's BitMap among various tasks in an orderly way by creating layers, separate drawing rectangles, within the BitMap.
* Move, size or depth-arrange a layer while automatically keeping track of which portions of other layers are hidden or revealed by the operation.
* Manage the remapping of coordinates, so the application need not track the layer's offset into the BitMap.
* Maintain each layer as a separate entity, which may optionally have its own BitMap.
* Automatically update same newly visible portions.

The layers library takes care of housekeeping: the low level, repetitive tasks which are required to keep track of where to place bits. The layers library also provides a locking mechanism which coordinates display updating when multiple tasks are drawing graphics to layers. The windowing environment provided by the Intuition library is largely based on layers.

{{Note|title=WARNING|text=Layers may not be created or used directly with Intuition screens. Intuition windows are the only supported method of adding layers to Intuition screens. ''Only'' the layer locking and unlocking functions are safe to use with Intuition. An application must create and manage its own View if it will be creating layers directly on the display.}}

=== The Layer Structure ===

The internal representation of layers is essentially a set of clipping rectangles. Each layer is represented by an instance of the Layer structure. All the layers in a display are linked together through the Layer_Info structure. Any display shared by multiple layers (such as an Intuition screen) requires one Layer_Info data structure to handle interactions between the various layers.

Here is a partial listing of the Layer structure from <graphics/clip.h>. (For a complete listing refer to the SDK.)

<syntaxhighlight lang="C" line>
struct Layer
{
struct Layer *front,*back;
struct ClipRect *ClipRect; /* read by ROMs to find first cliprect */
struct RastPort *rp;
struct Rectangle bounds;
...

UWORD Flags; /* obscured ?, Virtual BitMap? */
struct BitMap *SuperBitMap;
...

struct Region *DamageList; /* list of rectangles to refresh through */
};
</syntaxhighlight>

{{Note|title=The Layer Structure is Read-Only|text=Applications should never directly modify any of the elements of the Layer structure. In addition, applications should only read the front, back, rp, bounds, Flags, SuperBitMap and DamageList elements of the Layer structure. (Some of these elements are subject to dynamic change by the system so proper layer locking procedures must be followed when relying on what the application has read.)}}

=== The Layer's RastPort ===

When a layer is created, a RastPort is automatically to go along with it. The pointer to the RastPort is contained in the layer data structure. Using this RastPort, the application may draw anywhere into the layer's bounds rectangle. If the application tries to draw outside of this rectangle, the graphics routines will clip the graphics.

Here is sample code showing how to access the layer's RastPort:

<syntaxhighlight lang="C" line>
struct RastPort *myRPort; /* allocate a RastPort pointer for each layer */

myRPort = layer->rp;

/* The layer's RastPort may be used with any of the graphics library calls
** that require this structure. For instance, to fill layer with color:
*/
IGraphics->SetRast(layer->rp, color);

/* set up for writing text into layer */
IGraphics->SetDrMd(layer->rp, JAM1);
IGraphics->SetAPen(layer->rp, 0);
IGraphics->Move(layer->rp, 5, 7);

/* write into layer */
IGraphics->Text(layer->rp, string, strlen(string));
</syntaxhighlight>

=== Types of Layers ===

The layers library supports three types of layers: simple refresh, smart refresh and super bitmap. The type of the layer, specified by the Flags field in the Layers structure, determines what facilities the layer provides.

{{Note|title=Use Only One Layer Type Flag|text=The three layer-type Flags are mutually exclusive. That is, only one layer-type flag (LAYERSIMPLE, LAYERSMART and LAYERSUPER) should be specified.}}

==== Simple Refresh Layer ====

When an application draws into the layer, any portion of the layer that is visible (not obscured) will be rendered into the common BitMap of the viewing area. All graphics rendering routines are "clipped" so that only exposed sections of the layer are drawn into. No back-up of obscured areas is provided.

If another layer operation is performed that causes an obscured part of a simple refresh layer to be exposed, the application must determine if the section need be refreshed, re-drawing the newly exposed part of the layer as required.

The basic advantage of simple refresh is that it does not require back-up area to save drawing sections that cannot be seen, saving memory. However, the application needs to monitor the layer to see if it needs refreshing. This is typically performed with statements like:

<syntaxhighlight lang="C" line>
if (layer->Flags & LAYERREFRESH)
refresh(layer);
</syntaxhighlight>

When an application restores the layer by performing a full-layer redraw, only the damaged areas are redrawn, making the operation fairly time efficient.

==== Smart Refresh Layer ====

Under smart refresh, the system provides dynamic backup of obscured sections of the layer. The graphics routines will automatically draw into these backup areas when they encounter an obscured part of the layer. The backup memory will be used to automatically update the display when obscured sections later become exposed.

With smart refresh layers, the system handles all of the refresh requirements of the layer, except when the layer is made larger. When parts of the layer are exposed by a sizing operation, the application must refresh the newly exposed areas.

The advantage of smart refresh is the speed of updating exposed regions of the layer and the ability of the system to manage part of the updating process for the application.. Its main disadvantage is the additional memory required to handle this automatic refresh.

==== Super Bitmap Layer ====

A super bitmap layer is similar to a smart refresh layer. It too has a back-up area for rendering graphics for currently obscured parts of the display. Whenever an obscured area is made visible, the corresponding part of the backup area is copied to the display automatically.

However, it differs from smart refresh in that:

<ul>
<li>The back-up BitMap is user-supplied, rather than being allocated dynamically by the system.
</li>
<li>The back-up BitMap may be as large or larger than the the current size of the layer. It may also be larger than the maximum size of the layer.</li></ul>

To see a larger portion of a super bitmap on-display, use SizeLayer(). To see a different portion of the super bitmap in the layer, use ScrollLayer().

When the graphics routines perform drawing commands, part of the drawing appears in the common BitMap (the on-display portion). Any drawing outside the displayed portion itself is rendered into the super bitmap. When the layer is scrolled or sized, the layer contents are copied into the super bitmap, the scroll or size positioning is modified, and the appropriate portions are then copied back into the layer. (Refer to the graphics library functions SyncSBitMap() and CopySBitMap().

==== Backdrop Layer ====

A layer of any type may be designated a backdrop layer which will always appear behind all other layers. They may not be moved, sized, or depth-arranged. Non-backdrop layers will always remain in front of backdrop layers regardless of how the non-backdrop layer is moved, sized or depth-arranged.

=== Opening the Layers Library ===

Like all libraries, the layers library must be opened before it may be used. Check the Layers Autodocs to determine what version of the library is required for any particular Layers function.

<syntaxhighlight lang="C" line>
#include <proto/layers.h>

struct Library *LayersBase = IExec->OpenLibrary("layers.library", 50);

struct LayersIFace *ILayers = (struct LayersIFace*)IExec->GetInterface(LayersBase, "main", 1, NULL);

if (ILayers != NULL)
{
/* use Layers library */
}

IExec->DropInterface((struct Interface*)ILayers);
IExec->CloseLibrary(LayersBase);
</syntaxhighlight>

=== Working With Existing Layers ===

A common operation performed by applications is to render text or graphics into an existing layer such as an Intuition window. To prevent Intuition from changing the layer (for instance when the user resizes or moves the window) during a series of graphic operations, the layers library provides locking functions for obtaining exclusive access to a layer.

These locking functions are also useful for applications that create their own layers if the application has more than one task operating on the layers asynchronously. These calls coordinate multiple access to layers.

{| class="wikitable"
|+ Functions for Intertask Control of Layers (Layers Library)
| LockLayer()
| Lock out rendering in a single layer.
|-
| UnlockLayer()
| Release LockLayer() lock.
|-
| LockLayers()
| Lock out rendering in all layers of a display.
|-
| UnlockLayers()
| Release LockLayers() lock.
|-
| LockLayerInfo()
| Gain exclusive access to the display's layers.
|-
| UnlockLayerInfo()
| Release LockLayerInfo() lock.
|}

The following routines from the graphics library also allow multitasking access to layer structures:

{| class="wikitable"
|+ Functions for Intertask Control of Layers (Graphics Library)
| LockLayerRom()
| Same as LockLayer(), from layers library.
|-
| UnlockLayerRom()
| Release LockLayerRom() lock.
|-
| AttemptLockLayerRom()
| Lock layer only if it is immediately available.
|}

These functions are similar to the layers LockLayer() and UnlockLayer() functions, but do not require the layers library to be open. See the SDK for details.

==== Intertask Operations ====

If multiple tasks are manipulating layers on the same display they will be sharing a Layer_Info structure and their use of it and its related data structures need to be coordinated. To ensure that a structure remains cohesive, it should be operated on by only one task at a time. The Layer_Info encompasses all the layers existing on a single display.

LockLayerInfo() must be called whenever the visible portions of layers may be affected, or when the Layer_Info structure is changed.

<syntaxhighlight lang="C" line>
VOID LockLayerInfo( struct Layer_Info *li );
</syntaxhighlight>

The lock should be obtained whenever a layer is created, deleted sized or moved, as the list of layers that is being managed by the Layer_Info data structure must be updated.

It is not necessary to lock the Layer_Info data structure while rendering, or when calling routines like ScrollLayer(), because layer sizes and on-display positions are not being affected.

Use UnlockLayerInfo() when you have finished the layer operation:

<syntaxhighlight lang="C" line>
VOID UnlockLayerInfo( struct Layer_Info *li );
</syntaxhighlight>

If you don't unlock the Layer_Info then any other task calling LockLayerInfo() on the same Layer_Info structure will be blocked creating a potential deadlock situation.

In addition to locking the Layer_Info structure, the layer itself should be locked if it is shared between tasks so that only one task at a time renders graphics to it. LockLayer() is used to get exclusive graphics output to a layer.

<syntaxhighlight lang="C" line>
VOID LockLayer( long dummy, struct Layer *layer );
</syntaxhighlight>

If a graphics function is in process, the lock will return when the function is completed. Other tasks are blocked only if they attempt to draw graphics into this layer, or try to obtain a lock on this layer. The MoveLayer(), SizeLayer() and ScrollLayer() functions automatically lock and unlock the layer they operate on.

UnlockLayer() should be used after the graphics operation to make the layer available to other tasks again.

<syntaxhighlight lang="C" line>
VOID UnlockLayer( struct Layer *layer );
</syntaxhighlight>

If more than one layer must be locked, then the LockLayer() calls should be surrounded by LockLayerInfo() and UnlockLayerInfo() calls, to prevent deadlock situations.

The layers library provides two additional functions, LockLayers() and UnlockLayers(), for locking multiple layers.

<syntaxhighlight lang="C" line>
VOID LockLayers( struct Layer_Info *li );
VOID UnlockLayers( struct Layer_Info *li );
</syntaxhighlight>

LockLayers() is used to lock all layers in a single command. UnlockLayers() releases the layers lock. The system calls these routines during the BehindLayer(), UpfrontLayer() and MoveLayerInFrontOf() operations (described below).

==== Determining Layer Position ====

If the viewing area has been separated into several layers, the application may need to find out which layer is topmost at a particular ''x,y'' coordinate. Use the WhichLayer() function for this:

<syntaxhighlight lang="C" line>
struct Layer *WhichLayer( struct Layer_Info *li, int32 x, int32 y );
</syntaxhighlight>

To be sure that no task adds, deletes, or changes the sequence of layers before this information is used, call LockLayerInfo() before calling WhichLayer(), and call UnlockLayerInfo() when the operation is complete. In this way, the program may ensure that it is acting on valid information. Always check for a NULL return value (coordinate not in a layer) from WhichLayer().

=== Creating and Using New Layers ===

The functions described in this section are generally not safe to use with Intuition. To create new layers for Intuition you use Intuition window calls (see [[Intuition_Windows|Intuition Windows]]).

Only applications that create and mange their own View will be able to call the layer creation and updating functions discussed here.

{| class="wikitable"
|+ Functions for Creating and Updating Layers
| NewLayerInfo() || Allocating a Layer_Info structure.
|-
| DisposeLayerInfo() || Deallocating a Layer_Info structure.
|-
| CreateUpfrontLayer() || Make a new layer in front of others.
|-
| CreateBehindLayer() || Make a new layer behind others.
|-
| DeleteLayer() || Remove and delete an existing layer.
|-
| MoveLayer() || Change the position (not depth) of a layer.
|-
| SizeLayer() || Change the size of a layer.
|-
| ScrollLayer() || Change the internal coordinates of a layer.
|-
| BehindLayer() || Depth arrange a layer behind others.
|-
| UpfrontLayer() || Depth arrange a layer in front of others.
|-
| MoveLayerInFrontOf() || Depth arrange a layer to a specific position.
|-
| SwapBitsRastPortClipRect() || Fast, non-layered and non-damaging display operation.
|-
| BeginUpdate() || Synchronize optimized refreshing for layer.
|-
| EndUpdate() || End optimized layer refresh.
|}

==== Creating a Viewing Workspace ====

A viewing workspace may be created by using the primitives InitVPort(), InitView(), MakeVPort(), MrgCop(), and LoadView(). Please reference [[Graphics_Primitives|Graphics Primitives]] for details on creating a low-level graphics display. Do not create Layers directly on Intuition screens. Windows are the only supported method of creating a layer on a screen.

==== Creating the Layers ====

The application must first allocate and initialize a Layer_Info data structure which the system uses to keep track of layers that are created, use statements like:

<syntaxhighlight lang="C" line>
struct Layer_Info *theLayerInfo;

if (NULL != (theLayerInfo = ILayers->NewLayerInfo()))
{
/* use Layer_Info */

ILayers->DisposeLayerInfo(theLayerInfo);
}
</syntaxhighlight>

Layers may be created in the common bit map by calling CreateUpfrontLayer() or CreateBehindLayer(), with a sequence such as the following:

<syntaxhighlight lang="C" line>
struct Layer *layer;
struct Layer_Info *theLayerInfo;
struct BitMap *theBitMap;

/* requests construction of a smart refresh layer. */
if (NULL == (layer = ILayers->CreateUpfrontLayer(theLayerInfo, theBitMap, 20, 20, 100, 80, LAYERSMART, NULL)))
error("CreateUpfrontLayer() failed.");
else
{
; /* layer successfully created here. */
}
</syntaxhighlight>

==== Allocating and Deallocating Layer_Info ====

Use NewLayerInfo() to allocate and initialize a Layer_Info structure and associated sub-structures.

<syntaxhighlight lang="C" line>
struct Layer_Info *NewLayerInfo( VOID );
</syntaxhighlight>

You ''must'' call this function before attempting to use any of the other layers functions described below. When you have finished with a Layer_Info structure, use DisposeLayerInfo() to deallocate it.

<syntaxhighlight lang="C" line>
VOID DisposeLayerInfo( struct Layer_Info *li );
</syntaxhighlight>

This function deallocates a Layer_Info and associated structures previously allocated with NewLayerInfo().

==== Allocating and Deallocating Layers ====

Layers are created using the routines CreateUpfrontLayer() and CreateBehindLayer(). CreateUpfrontLayer() creates a layer that will appear in front of any existing layers.

<syntaxhighlight lang="C" line>
struct Layer *CreateUpfrontLayer( struct Layer_Info *li, struct BitMap *bm, int32 x0, int32 y0, int32 x1, int32 y1, int32 flags, struct BitMap *bm2 );
</syntaxhighlight>

CreateBehindLayer() creates a layer that appears behind existing layers, but in front of backdrop layers.

<syntaxhighlight lang="C" line>
struct Layer *CreateBehindLayer( struct Layer_Info *li, struct BitMap *bm, int32 x0, int32 y0, int32 x1, int32 y1, int32 flags, struct BitMap *bm2 );
</syntaxhighlight>

Both of these routines return a pointer to a Layer data structure (as defined in the include file <graphics/layers.h>), or NULL if the operation was unsuccessful.

{{Note|title=A New Layer Also Gets a RastPort|text=When a layer is created, the routine automatically creates a RastPort to go along with it. If the layer's RastPort is passed to the drawing routines, drawing will be restricted to the layer. See "The Layer's RastPort" section above.}}

Use the DeleteLayer() call to remove a layer:

<syntaxhighlight lang="C" line>
int32 DeleteLayer( int32 dummy, struct Layer *layer );
</syntaxhighlight>

DeleteLayer() removes a layer from the layer list and frees the memory allocated by the layer creation calls listed above.

==== Moving and Sizing Layers ====

The layers library includes three functions for moving and sizing layers:

<syntaxhighlight lang="C" line>
int32 MoveLayer( int32 dummy, struct Layer *layer, int32 dx, int32 dy );
int32 SizeLayer( int32 dummy, struct Layer *layer, int32 dx, int32 dy );
int32 MoveSizeLayer( struct Layer *layer, int32 dx, int32 dy, int32 dw, int32 dh);
</syntaxhighlight>

MoveLayer() moves a layer to a new position relative to its current position. SizeLayer() changes the size of a layer by modifying the coordinates of the lower right corner of the layer. MoveSizeLayer() changes both the size and position of a layer in a single call.

==== Changing a Viewpoint ====

The ScrollLayer() function changes the portion of a super bitmap that is shown by a layer:

<syntaxhighlight lang="C" line>
VOID ScrollLayer( int32 dummy, struct Layer *layer, int32 dx, int32 dy );
</syntaxhighlight>

This function is most useful with super bitmap layers but can also simulate the effect on other layer types by adding the scroll offset to all future rendering.

==== Reordering Layers ====

The layers library provides three function calls for reordering layers:

<syntaxhighlight lang="C" line>
int32 BehindLayer ( int32 dummy, struct Layer *layer );
int32 UpfrontLayer( int32 dummy, struct Layer *layer );
int32 MoveLayerInFrontOf( struct Layer *layer_to_move, struct Layer *other_layer );
</syntaxhighlight>

BehindLayer() moves a layer behind all other layers. This function considers any backdrop layers, moving a current layer behind all others except backdrop layers. UpfrontLayer() moves a layer in front of all other layers. MoveLayerInFrontOf() is used to place a layer at a specific depth, just in front of a given layer.

As areas of simple refresh layers become exposed, due to layer movement or sizing for example, the newly exposed areas have not been drawn into, and need refreshing. The system keeps track of these areas by using a DamageList. To update only those areas that need it, the BeginUpdate() EndUpdate() functions are called.

<syntaxhighlight lang="C" line>
int32 BeginUpdate( struct Layer *l );
VOID EndUpdate ( struct Layer *layer, uint32 flag );
</syntaxhighlight>

BeginUpdate() saves the pointer to the current clipping rectangles and installs a pointer to a set of ClipRects generated from the DamageList in the layer structure. To repair the layer, use the graphics rendering routines as if to redraw the entire layer, and the routines will automatically use the new clipping rectangle list. So, only the damaged areas are actually rendered into, saving time.

{{Note|title=Never Modify the DamageList|text=The system generates and maintains the DamageList region. All application clipping should be done through the InstallClipRegion() function.}}

To complete the update process call EndUpdate() which will restore the original ClipRect list.

==== Sub-Layer Rectangle Operations ====

The SwapBitsRastPortClipRect() routine is for applications that do not want to worry about clipping rectangles.

<syntaxhighlight lang="C" line>
VOID SwapBitsRastPortClipRect( struct RastPort *rp, struct ClipRect *cr );
</syntaxhighlight>

For instance, you may use The SwapBitsRastPortClipRect() to produce a menu without using Intuition. There are two ways to produce such a menu:

# Create an up-front layer with CreateUpfrontLayer(), then render the menu in it. This could use lots of memory and require a lot of (very temporary) "slice-and-dice" operations to create all of the clipping rectangles for the existing windows and so on.
# Use SwapBitsRastPortClipRect(), directly on the display drawing area:
#* Render the menu in a back-up area off the display, then lock all of the on-display layers so that no task may use graphics routines to draw over the menu area on the display.
#* Next, swap the on-display bits with the off-display bits, making the menu appear.
#* When finished with the menu, swap again and unlock the layers.

The second method is faster and leaves the clipping rectangles and most of the rest of the window data structures untouched.

{{Note|title=Warning|text=All of the layers must be locked while the menu is visible if you use the second method above. Any task that is using any of the layers for graphics output will be halted while the menu operations are taking place. If, on the other hand, the menu is rendered as a layer, no task need be halted while the menu is up because the lower layers need not be locked.}}

=== Layers Example ===

For the sake of brevity, the example is a single task. No Layer locking is done. Also note that the routine myLabelLayer() is used to redraw a given layer. It is called only when a layer needs refreshing.

<syntaxhighlight lang="C" line>
/* Layers.c */

/* Force use of new variable names to help prevent errors */
#define INTUI_V36_NAMES_ONLY

#include <exec/types.h>
#include <graphics/gfxbase.h>
#include <graphics/layers.h>
#include <graphics/displayinfo.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/graphics.h>
#include <proto/layers.h>

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#define L_DELAY (100)
#define S_DELAY (50)

#define DUMMY (0L)

#define RED_PEN (1)
#define GREEN_PEN (2)
#define BLUE_PEN (3)

#define SCREEN_D (2)
#define SCREEN_W (320)
#define SCREEN_H (200)

/* the starting size of example layers, offsets are used for placement */
#define W_H (50)
#define W_T (5)
#define W_B ((W_T+W_H)-1)
#define W_W (80)
#define W_L ((SCREEN_W/2) - (W_W/2))
#define W_R ((W_L+W_W)-1)

/* size of the superbitmap */
#define SUPER_H SCREEN_H
#define SUPER_W SCREEN_W

/* starting size of the message layer */
#define M_H (10)
#define M_T (SCREEN_H-M_H)
#define M_B ((M_T+M_H)-1)
#define M_W (SCREEN_W)
#define M_L (0)
#define M_R ((M_L+M_W)-1)

struct GraphicsIFace *IGraphics = 0;
struct LayersIFace *ILayers = 0;

/* global constant data for initializing the layers */
LONG theLayerFlags[3] = { LAYERSUPER, LAYERSMART, LAYERSIMPLE };
UWORD colortable[] = { 0x000, 0xf44, 0x4f4, 0x44f };

/*
** Clear the layer then draw in a text string.
*/
VOID myLabelLayer(struct Layer *layer, LONG color, UBYTE *string)
{
/* fill layer with color */
IGraphics->SetRast(layer->rp, color);

/* set up for writing text into layer */
IGraphics->SetDrMd(layer->rp,JAM1);
IGraphics->SetAPen(layer->rp,0);
IGraphics->Move(layer->rp, 5, 7);

/* write into layer */
IGraphics->Text(layer->rp, string, strlen(string));
}

/*
** write a message into a layer with a delay.
*/
VOID pMessage(struct Layer *layer, UBYTE *string)
{
IDOS->Delay(S_DELAY);
myLabelLayer(layer, GREEN_PEN, string);
}

/*
** write an error message into a layer with a delay.
*/
VOID error(struct Layer *layer, UBYTE *string)
{
myLabelLayer(layer, RED_PEN, string);
IDOS->Delay(L_DELAY);
}

/*
** do some layers manipulations to demonstrate their abilities.
*/
VOID doLayers(struct Layer *msgLayer, struct Layer *layer_array[])
{
WORD ktr;
WORD ktr_2;

pMessage(msgLayer, "Label all Layers");
myLabelLayer(layer_array[0], RED_PEN, "Super");
myLabelLayer(layer_array[1], GREEN_PEN, "Smart");
myLabelLayer(layer_array[2], BLUE_PEN, "Simple");

pMessage(msgLayer, "MoveLayer 1 InFrontOf 0");
if (!ILayers->MoveLayerInFrontOf(layer_array[1], layer_array[0]))
error(msgLayer, "MoveLayerInFrontOf() failed.");

pMessage(msgLayer, "MoveLayer 2 InFrontOf 1");
if (!ILayers->MoveLayerInFrontOf(layer_array[2], layer_array[1]))
error(msgLayer, "MoveLayerInFrontOf() failed.");

pMessage(msgLayer, "Refresh Simple Refresh Layer");
myLabelLayer(layer_array[2], BLUE_PEN, "Simple");

pMessage(msgLayer, "Incrementally MoveLayers...");
for(ktr = 0; ktr < 30; ktr++)
{
if (!ILayers->MoveLayer(DUMMY, layer_array[1], -1, 0))
error(msgLayer, "MoveLayer() failed.");
if (!ILayers->MoveLayer(DUMMY, layer_array[2], -2, 0))
error(msgLayer, "MoveLayer() failed.");
}

pMessage(msgLayer, "Refresh Simple Refresh Layer");
myLabelLayer(layer_array[2], BLUE_PEN, "Simple");

pMessage(msgLayer, "make Layer 0 the UpfrontLayer");
if (!ILayers->UpfrontLayer(DUMMY, layer_array[0]))
error(msgLayer, "UpfrontLayer() failed.");

pMessage(msgLayer, "make Layer 2 the BehindLayer");
if (!ILayers->BehindLayer(DUMMY, layer_array[2]))
error(msgLayer, "BehindLayer() failed.");

pMessage(msgLayer, "Incrementally MoveLayers again...");
for(ktr = 0; ktr < 30; ktr++)
{
if (!ILayers->MoveLayer(DUMMY, layer_array[1], 0, 1))
error(msgLayer, "MoveLayer() failed.");
if (!ILayers->MoveLayer(DUMMY, layer_array[2], 0, 2))
error(msgLayer, "MoveLayer() failed.");
}

pMessage(msgLayer, "Refresh Simple Refresh Layer");
myLabelLayer(layer_array[2], BLUE_PEN, "Simple");

pMessage(msgLayer, "Big MoveLayer");
for(ktr = 0; ktr < 3; ktr++)
{
if (!ILayers->MoveLayer(DUMMY, layer_array[ktr], -layer_array[ktr]->bounds.MinX, 0))
error(msgLayer, "MoveLayer() failed.");
}

pMessage(msgLayer, "Incrementally increase size");
for(ktr = 0; ktr < 5; ktr++)
{
for(ktr_2 = 0; ktr_2 < 3; ktr_2++)
{
if (!ILayers->SizeLayer(DUMMY, layer_array[ktr_2], 1, 1))
error(msgLayer, "SizeLayer() failed.");
}
}

pMessage(msgLayer, "Refresh Smart Refresh Layer");
myLabelLayer(layer_array[1], GREEN_PEN, "Smart");
pMessage(msgLayer, "Refresh Simple Refresh Layer");
myLabelLayer(layer_array[2], BLUE_PEN, "Simple");

pMessage(msgLayer, "Big SizeLayer");
for(ktr = 0; ktr < 3; ktr++)
{
if (!ILayers->SizeLayer(DUMMY,layer_array[ktr],
SCREEN_W-(layer_array[ktr]->bounds.MaxX)-1,0))
error(msgLayer, "SizeLayer() failed.");
}

pMessage(msgLayer, "Refresh Smart Refresh Layer");
myLabelLayer(layer_array[1], GREEN_PEN, "Smart");
pMessage(msgLayer, "Refresh Simple Refresh Layer");
myLabelLayer(layer_array[2], BLUE_PEN, "Simple");

pMessage(msgLayer, "ScrollLayer down");
for(ktr = 0; ktr < 30; ktr++)
{
for(ktr_2 = 0; ktr_2 < 3; ktr_2++)
{
ILayers->ScrollLayer(DUMMY, layer_array[ktr_2], 0, -1);
}
}

pMessage(msgLayer, "Refresh Smart Refresh Layer");
myLabelLayer(layer_array[1], GREEN_PEN, "Smart");
pMessage(msgLayer, "Refresh Simple Refresh Layer");
myLabelLayer(layer_array[2], BLUE_PEN, "Simple");

pMessage(msgLayer, "ScrollLayer up");
for(ktr = 0; ktr < 30; ktr++)
{
for(ktr_2 = 0; ktr_2 < 3; ktr_2++)
{
ILayers->ScrollLayer(DUMMY, layer_array[ktr_2], 0, 1);
}
}

pMessage(msgLayer, "Refresh Smart Refresh Layer");
myLabelLayer(layer_array[1], GREEN_PEN, "Smart");
pMessage(msgLayer, "Refresh Simple Refresh Layer");
myLabelLayer(layer_array[2], BLUE_PEN, "Simple");

IDOS_>Delay(L_DELAY);
}

/*
** delete the layer array created by allocLayers().
*/
VOID disposeLayers(struct Layer *msgLayer, struct Layer *layer_array[])
{
WORD ktr;

for (ktr = 0; ktr < 3; ktr++)
{
if (layer_array[ktr] != NULL)
{
if (!ILayers->DeleteLayer(DUMMY, layer_array[ktr]))
error(msgLayer, "Error deleting layer");
}
}
}

/*
** Create some hard-coded layers. The first must be super-bitmap, with
** the bitmap passed as an argument. The others must not be super-bitmap.
** The pointers to the created layers are returned in layer_array.
**
** Return FALSE on failure. On a FALSE return, the layers are
** properly cleaned up.
*/
BOOL allocLayers(struct Layer *msgLayer, struct Layer *layer_array[],
struct BitMap *super_bitmap, struct Layer_Info *theLayerInfo,
struct BitMap *theBitMap)
{
WORD ktr;
BOOL create_layer_ok = TRUE;

for (ktr = 0;
(ktr < 3) && (create_layer_ok);
ktr++)
{
pMessage(msgLayer, "Create BehindLayer");
if (ktr == 0)
{
if ((layer_array[ktr] = ILayers->CreateBehindLayer(theLayerInfo, theBitMap,
W_L+(ktr*30), W_T+(ktr*30), W_R+(ktr*30), W_B+(ktr*30),
theLayerFlags[ktr], super_bitmap)) == NULL)
create_layer_ok = FALSE;
}
else
{
if ((layer_array[ktr] = ILayers->CreateBehindLayer(theLayerInfo, theBitMap,
W_L+(ktr*30), W_T+(ktr*30), W_R+(ktr*30), W_B+(ktr*30),
theLayerFlags[ktr], NULL)) == NULL)
create_layer_ok = FALSE;
}

if (create_layer_ok)
{
pMessage(msgLayer, "Fill the RastPort");
IGraphics->SetRast(layer_array[ktr]->rp, ktr + 1);
}
}

if (!create_layer_ok)
disposeLayers(msgLayer, layer_array);

return(create_layer_ok);
}

/*
** Free the bitmap and all bitplanes created by allocBitMap().
*/
VOID disposeBitMap(struct BitMap *bitmap, LONG depth, LONG width, LONG height)
{
WORD ktr;

if (NULL != bitmap)
{
for (ktr = 0; ktr < depth; ktr++)
{
if (NULL != bitmap->Planes[ktr])
IGraphics->FreeRaster(bitmap->Planes[ktr], width, height);
}

IExec->FreeMem(bitmap, sizeof(*bitmap));
}
}

/*
** Allocate and initialize a bitmap structure.
*/
struct BitMap *allocBitMap(LONG depth, LONG width, LONG height)
{
WORD ktr;
BOOL bit_map_failed = FALSE;
struct BitMap *bitmap = NULL;

if (NULL != (bitmap = IExec->AllocMem(sizeof(*bitmap),NULL)))
{
IGraphics->InitBitMap(bitmap,depth,width,height);

for (ktr = 0; ktr < depth; ktr++)
{
if (NULL == (bitmap->Planes[ktr] = (PLANEPTR)IGraphics->AllocRaster(width,height)))
bit_map_failed = TRUE;
else
IGraphics->BltClear(bitmap->Planes[ktr], RASSIZE(width,height), 1);
}
if (bit_map_failed)
{
disposeBitMap(bitmap,depth,width,height);
bitmap = NULL;
}
}
return(bitmap);
}

/*
** Set up to run the layers example, doLayers(). Clean up when done.
*/
VOID startLayers(struct Layer_Info *theLayerInfo, struct BitMap *theBitMap)
{
struct Layer *msgLayer;
struct BitMap *theSuperBitMap;
struct Layer *theLayers[3] = { NULL, NULL, NULL, };

if (NULL != (msgLayer = ILayers->CreateUpfrontLayer(theLayerInfo, theBitMap,
M_L, M_T, M_R, M_B, LAYERSMART, NULL)))
{
pMessage(msgLayer, "Setting up Layers");

if (NULL != (theSuperBitMap = allocBitMap(SCREEN_D, SUPER_W, SUPER_H)))
{
if (allocLayers(msgLayer, theLayers, theSuperBitMap, theLayerInfo, theBitMap))
{
doLayers(msgLayer, theLayers);

disposeLayers(msgLayer, theLayers);
}
disposeBitMap(theSuperBitMap, SCREEN_D, SUPER_W, SUPER_H);
}
if (!ILayers->DeleteLayer(DUMMY, msgLayer))
error(msgLayer, "Error deleting layer");
}
}

/*
** Set up a low-level graphics display for layers to work on. Layers
** should not be built directly on Intuition screens, use a low-level
** graphics view. If you need mouse or other events for the layers
** display, you have to get them directly from the input device. The
** only supported method of using layers library calls with Intuition
** (other than the InstallClipRegion() call) is through Intuition windows.
**
** See graphics primitives articles for details on creating and using the
** low-level graphics calls.
*/
VOID runNewView(VOID)
{
struct View theView;
struct View *oldview;
struct ViewPort theViewPort;
struct RasInfo theRasInfo;
struct ColorMap *theColorMap;
struct Layer_Info *theLayerInfo;
struct BitMap *theBitMap;
UWORD *colorpalette;
WORD ktr;

/* save current view, to be restored when done */
if (NULL != (oldview = GfxBase->ActiView))
{
/* get a LayerInfo structure */
if (NULL != (theLayerInfo = ILayers->NewLayerInfo()))
{
if (NULL != (theColorMap = IGraphics->GetColorMap(4)))
{
colorpalette = (UWORD *)theColorMap->ColorTable;
for(ktr = 0; ktr < 4; ktr++)
*colorpalette++ = colortable[ktr];

if (NULL != (theBitMap = allocBitMap(SCREEN_D, SCREEN_W, SCREEN_H)))
{
IGraphics->InitView(&theView);
IGraphics->InitVPort(&theViewPort);

theView.ViewPort = &theViewPort;

theViewPort.DWidth = SCREEN_W;
theViewPort.DHeight = SCREEN_H;
theViewPort.RasInfo = &theRasInfo;
theViewPort.ColorMap = theColorMap;

theRasInfo.BitMap = theBitMap;
theRasInfo.RxOffset = 0;
theRasInfo.RyOffset = 0;
theRasInfo.Next = NULL;

IGraphics->MakeVPort(&theView, &theViewPort);
IGraphics->MrgCop(&theView);
IGraphics->LoadView(&theView);
IGraphics->WaitTOF();

startLayers(theLayerInfo, theBitMap);

/* put back the old view, wait for it to become
** active before freeing any of our display
*/
IGraphics->LoadView(oldview);
IGraphics->WaitTOF();

/* free dynamically created structures */
IGraphics->FreeVPortCopLists(&theViewPort);
IGraphics->FreeCprList(theView.LOFCprList);

disposeBitMap(theBitMap, SCREEN_D, SCREEN_W, SCREEN_H);
}
IGraphics->FreeColorMap(theColorMap); /* free the color map */
}
ILayers->DisposeLayerInfo(theLayerInfo);
}
}
}

/*
** Open the libraries used by the example. Clean up when done.
*/
int main(int argc, char **argv)
{
struct Library *GfxBase = IExec->OpenLibrary("graphics.library", 50);
struct Library *LayersBase = IExec->OpenLibrary("layers.library", 50);
IGraphics = (struct GraphicsIFace*)IExec->GetInterface(GfxBase, "main", 1, NULL);
ILayers = (struct LayersIFace*)IExec->GetInterface(LayersBase, "main", 1, NULL);

if (IGraphics != NULL && ILayers != NULL)
{
runNewView();
}

IExec->DropInterface((struct Interface*)ILayers);
IExec->DropInterface((struct Interface*)IGraphics);
IExec->CloseLibrary(LayersBase);
IExec->CloseLibrary(GfxBase);

return 0;
}
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the layers library functions. See the SDK for details on each function call.

{| class="wikitable"
|+ Layers Library Functions
! Function
! Description
|-
| NewLayerInfo()
| Allocating a Layer_Info structure.
|-
| DisposeLayerInfo()
| Deallocating a Layer_Info structure.
|-
| CreateUpfrontLayer()
| Make a new layer in front of others.
|-
| CreateBehindLayer()
| Make a new layer behind others.
|-
| DeleteLayer()
| Remove and delete an existing layer.
|-
| MoveLayer()
| Change the position (not depth) of a layer.
|-
| SizeLayer()
| Change the size of a layer.
|-
| ScrollLayer()
| Change the internal coordinates of a layer.
|-
| BehindLayer()
| Depth arrange a layer behind others.
|-
| UpfrontLayer()
| Depth arrange a layer in front of others.
|-
| MoveLayerInFrontOf()
| Depth arrange a layer to a specific position.
|-
| WhichLayer()
| Find the frontmost layer at a position.
|-
| SwapBitsRastPortClipRect()
| Fast, non-layered and non-damaging display operation.
|-
| BeginUpdate()
| Synchronize optimized refreshing for layer.
|-
| EndUpdate()
| End optimized layer refresh.
|-
| LockLayer()
| Lock out rendering in a single layer.
|-
| UnlockLayer()
| Release LockLayer() lock.
|-
| LockLayers()
| Lock out rendering in all layers of a display.
|-
| UnlockLayers()
| Release LockLayers() lock.
|-
| LockLayerInfo()
| Gain exclusive access to the display‚Äôs layers.
|-
| UnlockLayerInfo()
| Release LockLayerInfo() lock.
|-
| InstallClipRegion()
| Add a clipping region to a layer.
|}

Using Crash-Logs for Debugging

2025-01-26T19:33:28Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

[[Category:Debug]]
= Introduction =

Bugs in software are a fact of life. It is almost impossible to write software with zero bugs. To date, no-one has come up with a method of even proving that a computer program is bug-free. Given these facts, it would be desirable to obtain as much information as possible about any crash that occurs. This is essential for debugging purposes.

AmigaOS provides substantial information via the Grim-Reaper. The Grim-Reaper pops up whenever a program performs an illegal operation, and provides a whole host of information about the crash. Details that are listed include the name of the program/library in which the crash occurred is listed along with the state of the CPU, a stack trace, and other state information. This information could be used in order to isolate the specific line of code at which the program crashed. However, this requires suitable preparation.

[[File:UsingCrashLogs1.jpg|center|frame|The Grim Reaper displaying a DSI error.]]

It is possible to embed debug information into a binary. However, this is undesirable in software being released to consumers as the binaries are inflated to several times the original size (tens of megabytes in size is easily obtainable in this manner). From the customers perspective, this is completely wasted space. Also, it gives a wealth of information about the internals of your program, which is undesirable. As will be shown below, there is a methodt hat can be used to provide compact binaries to end-users whilst still being able to use their crash-logs in order to locate and fix bugs.

= Enabling Debugging =

It is very easy to enable debugging in GCC. Simply add the compiler flag "-gstabs" when compiling and linking. This tells GCC that you wish to include debugging symbols in the binary, and even works if optimizations are enabled. "Stabs" is a particular format in which the debugging symbol; "-ggdb" is another option that also adds debugging symbols, but in a different format. However, I have been told that there are issues with "-ggdb" and large applications, so it is best to stick to "-gstabs."

= Debug Binaries =

As was mentioned previously, enabling debug symbols inflates the binray size significantly. What many people do not realize is that it is possible to create a separate file that contains all the debug information; here is an excerpt from the make-file that achieves this:

$(TARGET): $(OBJS)
$(CC) $(CFLAGS) -o $@.debug $(OBJS) $(LIBS) $(LINK)
$(STRIP) $@.debug -o $@

Where CFLAGS = -mcrt=newlib $(OPTIMIZE) -Wall -gstabs

In the [[Media:usingcrashlogs.lha|example template]] this translates to:
gcc -mcrt=newlib -O3 -Wall -gstabs -c -o badboy.o badboy.c
gcc -mcrt=newlib -O3 -Wall -gstabs -o badboy.debug badboy.o
strip badboy.debug badboy

The first line compiles the single source-file, badboy.c. The next one links it, and creates an executable called badboy.debug, which contains all the debugging symbols. Finally, strip removes all the debugging symbols and creates a binary called badboy. This stripped binary can then be distributed to end-users; badboy.debug is kept by the developer for interpreting crash-logs.

= Interpreting Crash-Logs =

This is best understood by example. Download and extract the [[Media:usingcrashlogs.lha|example template]]. Open a shell window and change to the directory containing the template code. Type make, and press enter. This will compile a program called badboy that deliberately performs an illegal operation. It performs a classical NULL-pointer dereferencing for a write operation; a very common bug. Now run badboy; the grim-reaper should pop up and display the error message below.

[[File:UsingCrashLogs1.jpg|center|frame|The Grim Reaper displaying a DSI error.]]

''Note about the "redzone" message:''
The lower part of the stack is made up of unmapped virtual pages that throw an exception when accessed, to prevent the program from wreaking havoc.
A redzone is a stack barrier that makes the program exhausting it's stack space crash. With memory, the term "electric fence" has been established for "hot" barriers (due to the name given to a tool under Linux that was used for this purpose).

Now click on "More..." and select the "Stack Trace" tab. Clicking on the "Generate Stack Trace" button will generate a stack trace.

[[File:UsingCrashLogs2.jpg|center|frame|A stack trace for the program "badboy"]]

This shows that the crash occurred within "badboy" in section 5 at 0x608. Open a new shell window and change to the directory containing "badboy" once again. Enter the following line:

addr2line -e badboy.debug --section=.text 0x608

This performs a lookup of 0x608 inside "badboy.debug," which contains the debug symbols. Addr2line will respond by giving the file and line number of this address.

[[File:UsingCrashLogs3.jpg|center|frame|A stack trace for the program "badboy"]]

Line 25 performs a write to address zero:

<syntaxhighlight lang="C" line>
int *a = NULL;
*a = 0;
</syntaxhighlight>

The procedure above has identified the exact source-line at which the crash occurred. In this case the crash was deliberate in order to present an easy to understand example. However, in a real application, the*.debug version of each release would be kept by the developer so that crash-logs submitted by users can be used in order to identify the source-line at which the crash occurred. If you look at the [http://hdrlab.org.nz/articles/amiga-os-articles/minigl-templates/ MiniGL templates] that I have written, you will notice that all of them use this technique.

= Download =

[[Media:usingcrashlogs.lha|Using crash-logs template and example]]

= Wish-List =

Whilst the technique above works, a more automated bug tracking system would be nice. The first component of such a system would be an automated crash-log submission system. If Grim Reaper provided a singl-click method of submitting a bug report to the developer via the internet, more crash-logs are likely to be submitted. Having a tool that would parse the crash-log and automatically find file names and line numbers for the entry in the crash-log would also be useful.

= Author =

Copyright (c) 2008 Hans de Ruiter. 
Reproduced with permission. 
See the original article [http://hdrlab.org.nz/articles/amiga-os-articles/using-crash-logs/ here].

AmiWest Setup

2025-01-26T19:33:15Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= Setup =

Developing software on and for AmigaOS involves three major components: the '''AmigaOS SDK''' or "Software Development Kit", a source code '''Editor''' and your '''imagination'''.

The first part of this equation, the AmigaOS Software Development Kit or '''AmigaOS SDK''', is a collection of files and tools that will convert your source code into an Amiga application. The SDK consists of a collection of the latest documentation, "include" files, example code, utilities and the GCC compiler. With each major version of AmigaOS a new SDK is issued that allows developers and their applications take advantage of the latest OS features.

The second part of the equation is a means to edit and manage your programming project and its source code. While you can edit source code in the AmigaOS '''NotePad''' text editor, there are much better & easier ways. The most powerful programming environment on AmigaOS is called [http://codebench.co.uk/ CodeBench]. In addition to providing a source code editor that provide syntax highlighting, help as you type and context sensitive help, CodeBench takes care of building "makefiles", runs the compiler, collects & presents errors and can interact to remote source code servers.

Finally there is '''you'''! Obviously, developing AmigaOS applications with the SDK requires a working understanding of the C language. To take advantage of the specific powers of AmigaOS, there are more methodologies and functions to learn. The SDK provides a number of example programs to learn from and a bounty of "autodocs" that document AmigaOS functions. Every day there are new things to learn.

== Installing the SDK ==

The latest version of the SDK can be downloaded from the Hyperion Entertainment [http://www.hyperion-entertainment.biz/index.php?option=com_registration&view=files&parent=30&Itemid=63 SDK webpage].

Once downloaded, you can double-click on the SDK archive file to use the AmigaOS '''Unarc''' utility to decompress the SDK to your RAM Disk. This will create a directory that includes all the SDK files to be installed.

In that directory you will find the '''Install SDK''' installer program. If you run that, it will ask you what you want to install and for a location to install to. Unless you have a severe limitation on hard disk space, it's recommended you make a "Full" install. As part of the install process, a few commands will be added to your "user-startup" script to assign SDK: to your system.

Once the SDK installation is complete, your SDK: path will include the following directories:

* '''Documentation''' - This drawer contains various documentation, AutoDocs, and other information related to the SDK. It also contains documentation on the various tools and compilers.

* '''Examples''' - This drawer contains example source code on how to program for AmigaOS 4.x. Examples are sorted by theme/topic.

* '''Local''' - The Local drawer is our means of isolating the compilers and third-party additions. See SDK documentation PDF file for more information on the Local drawer.

* '''gcc''' - The gcc drawer contains the GNU C/C++ compiler. It is set up in a way that there are no user-serviceable parts inside. This makes it easy to exchange the compiler when later versions become available.

* '''Include''' - This drawer contains system-level include files. Like the gcc drawer, it should not need to be modified.

* '''Contrib''' - The Contrib drawer contains various files that where contributed to the SDK. Among other things, it contains the latest source code for the static C runtime library clib2.

You can test the installation of SDK and its GCC compiler by opening a shell and typing the following command:

gcc --version

This should cause a text to be printed by the compiler, including the version number.

== Testing the SDK ==

Open the '''NotePad''' text editor and type the following text:

<syntaxhighlight lang="C" line>
#include <proto/dos.h>

int main(void)
{
IDOS->Printf("Hello, World\n");
return 0;
}
</syntaxhighlight>

Then save the file to "hello_world.c" and go back to the shell, CD to the directory with your file and enter this command:

gcc -o hello_world hello_world.c

After a few seconds, the gcc compiler should return. As long the source was correctly entered and no errors or warnings were displayed by GCC, then you will have successfully compiled your first Amiga program. Just type "hello_world" into the command line to see it run. Congratulations!

== Installing CodeBench ==

You may have used the '''NotePad''' text editor and your Shell console to create the sample C program above, but there are much better ways to edit and compile C programs. Such development systems provide more specialized editors suited for coding and means for managing compilation, handling warnings and errors, etc.

On AmigaOS we have '''CodeBench''' to improve and automate our coding sessions. CodeBench provides a text editor with "syntax highlighting" which means that it color-codes text on the basis of what it is: comments, commands, strings, etc. CodeBench also provides a GUI for GCC - click a button to compile, review the results in a window. There are even more features for more serious projects.

CodeBench can be downloaded from the [http://codebench.co.uk/downloads.php website] of the developer, SImon Archer. Once downloaded, you can double-click on the archive to open it in the AmigaOS '''Unarc''' utility and decompress the files to your RAM Disk. Once finished, you will find an "Install CodeBench" installer program icon. When you run the installer, it will confirm whether you are upgrading or making a new install and ask you for a location.

Once this process is done, you're ready to start a project in CodeBench. CodeBench comes with comprehensive documentation on itself in web format (that can also be accessed [http://codebench.co.uk/docs/codebench.html here]).

== Testing CodeBench: Hello World ==

The first thing you can do with CodeBench is to start a test project to how things work. At [http://codebench.co.uk/docs/started.html this page] you can find information on on starting a project. Basically, it's a matter of clicking the Start Project button, setting a few names and variables and entering a path for your project.

Once the new project is established, then you can use the "Editor/Create New File..." menu item to start a new source file. If you copy the above "Hello World" source code and paste it into the editor and save the source as "hello-world.c" then you will be ready for compiling.

In the CodeBench tool bar window, click the green "Build" button and CodeBench will automatically prepare, compile and link your project into an executable program.
A Build window will appear that will show the status of the building of your project. Assuming your code compiles without errors, you will then see a Run button with a play icon in the CodeBench toolbar. Clicking that button will bring up a window to let you run your program.

== Testing CodeBench: Hello with a GUI ==

Once you start coding with CodeBench, you will find it provides a number of aids to help with coding: such as highlighting or coloring the source code by type, letting you work with a number of sources at one time, letting you access AmigaOS documents by shift-double-clicking on AmigaOS functions and providing a quick way to track compiling errors into the source code.

With CodeBench you can easily jump into more advanced coding, such as our old "Hello World" program with a modern GUI. Just copy and paste the following source into a new project and try to compile it:

<syntaxhighlight lang="C" line>
#include <dos/dos.h>
#include <classes/window.h>
#include <gadgets/button.h>
#include <gadgets/layout.h>
#include <images/label.h>

#include <proto/intuition.h>
#include <proto/exec.h>

int main(void)
{
// Create a window with a label and button.

Object* winobj = IIntuition->NewObject(NULL, "window.class",
WA_Title, "Hello World Example",
WA_Activate, TRUE,
WA_DepthGadget, TRUE,
WA_DragBar, TRUE,
WA_CloseGadget, TRUE,
WA_SizeGadget, TRUE,
WINDOW_Position, WPOS_CENTERMOUSE,

WINDOW_Layout, IIntuition->NewObject(NULL, "layout.gadget",
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_DeferLayout, TRUE,

LAYOUT_AddImage, IIntuition->NewObject(NULL, "label.image",
LABEL_Text, "Hello, World",
TAG_END),

LAYOUT_AddChild, IIntuition->NewObject(NULL, "button.gadget",
GA_RelVerify, TRUE,
GA_Text, "Quit",
TAG_END),
TAG_END),
TAG_END);

if (winobj != NULL)
{
// Open the window.
struct Window *window = (struct Window *) IIntuition->IDoMethod(winobj, WM_OPEN);

if (window != NULL)
{
// Obtain the window wait signal mask.

uint32 signal = 0;
IIntuition->GetAttr(WINDOW_SigMask, winobj, &signal);

// Input Event Loop

BOOL done = FALSE;

while (!done)
{
uint32 wait = IExec->Wait(signal | SIGBREAKF_CTRL_C);

if ( wait & SIGBREAKF_CTRL_C )
{
done = TRUE;
break;
}

if ( wait & signal )
{
uint32 result = WMHI_LASTMSG;
int16 code = 0;

while ((result = IIntuition->IDoMethod(winobj, WM_HANDLEINPUT, &code)) != WMHI_LASTMSG)
{
switch (result & WMHI_CLASSMASK)
{
case WMHI_GADGETUP:
done = TRUE;
break;

case WMHI_CLOSEWINDOW:
window = NULL;
done = TRUE;
break;
}
}
}
}
}

/* Disposing of the window object will also close the window if it is
* already opened and all attached objects.
*/
IIntuition->DisposeObject(winobj);
}

return RETURN_OK;
}
</syntaxhighlight>

Once you have built and run this example program the following GUI will be produced:

[[File:HelloWorldWindow.png]]

Intuition Borders

2025-01-26T19:32:23Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= Creating Borders =

This data type is called a Border since it was originally used to create border lines around display objects. It is actually a general purpose structure for drawing connected lines between any series of points.

A Border is easier to use than an Image structure. Only the following need be specified to define a border:

* An internal position component which is used in determining the final position of the border.
* A set of coordinate pairs for each vertex.
* A color for the lines.
* One of several drawing modes.

== Border Structure Definition ==

To use a border, the application must create one or more instances of the Border structure. Here is the specification:

<syntaxhighlight lang="C" line>
struct Border
{
WORD LeftEdge, TopEdge;
UBYTE FrontPen, BackPen;
UBYTE DrawMode;
BYTE Count;
WORD *XY;
struct Border *NextBorder;
};
</syntaxhighlight>

Here is a brief description of the fields of the Border structure.

; LeftEdge, TopEdge
: These fields are used to determine the position of the Border relative to its base position (the base position is the upper left corner for requesters, menus, or gadgets and is specified in the call to DrawBorder() for windows and screens).

; FrontPen, BackPen
: These fields contain color registers numbers. FrontPen is the color used to draw the lines. BackPen is currently unused.

;DrawMode
: Set the DrawMode field to one of the following:
:{| class="wikitable"
| JAM1
| Use FrontPen to draw the line.
|-
| COMPLEMENT
| Change the pixels within the lines to their complement color.
|}

; Count
: Specify the number of data points used in this border. Each data point is described by two words of data in the XY array.

; XY
: A pointer to an array of coordinate pairs, one pair for each point. These coordinates are measured relative to the position of the border.

; NextBorder
: This field is a pointer to another instance of a Border structure. Set this field to NULL if this is the last Border structure in the linked list.

= Directly Drawing the Borders =

Borders may be directly drawn by the application by calling the function DrawBorder().

<syntaxhighlight lang="C" line>
VOID DrawBorder( struct RastPort *rp, struct Border *border,
LONG leftOffset, LONG topOffset );
</syntaxhighlight>

The rp argument is a pointer to the RastPort into which the border should be drawn. This rastport may come from a Window or Screen structure.

The border argument is a pointer to a list of Border structures which are to be rendered. The list may contain a single Border structure.

The leftOffset and topOffset arguments are the external component, or base position, for this list of Borders. The LeftEdge and TopEdge values of each Border structure are added to these to determine the Border position.

Borders may also be indirectly drawn by attaching them to gadgets, menus or requesters.

= Border Example =

The following example draws a double border using two pens to create a shadow effect. The border is drawn in two positions to show the flexibility in positioning borders, note that it could also be attached to a menu, gadget or requester.

<syntaxhighlight lang="C" line>
/*
** shadowborder.c - program to show the use of an Intuition Border.
*/
#include <exec/types.h>
#include <intuition/intuition.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>

struct Library *IntuitionBase = NULL;

#define MYBORDER_LEFT (0)
#define MYBORDER_TOP (0)

/* This is the border data. */
int16 myBorderData[] =
{
0,0, 50,0, 50,30, 0,30, 0,0,
};

/*
** main routine. Open required library and window and draw the images.
** This routine opens a very simple window with no IDCMP. See the
** articles on "Windows" and "Input and Output Methods" for more info.
** Free all resources when done.
*/
int main()
{
struct Screen *screen;
struct DrawInfo *drawinfo;
struct Window *win;
struct Border shineBorder;
struct Border shadowBorder;

uint32 mySHADOWPEN = 1; /* set default values for pens */
uint32 mySHINEPEN = 2; /* in case can't get info... */

struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);

if (IIntuition != NULL)
{
if (screen = IIntuition->LockPubScreen(NULL))
{
if (drawinfo = IIntuition->GetScreenDrawInfo(screen))
{
/* Get a copy of the correct pens for the screen.
** This is very important in case the user or the
** application has the pens set in a unusual way.
*/
mySHADOWPEN = drawinfo->dri_Pens[SHADOWPEN];
mySHINEPEN = drawinfo->dri_Pens[SHINEPEN];

IIntuition->FreeScreenDrawInfo(screen,drawinfo);
}

IIntuition->UnlockPubScreen(NULL,screen);
}

/* open a simple window on the workbench screen for displaying
** a border. An application would probably never use such a
** window, but it is useful for demonstrating graphics...
*/
if (win = IIntuition->OpenWindowTags(NULL,
WA_PubScreen, screen,
WA_RMBTrap, TRUE,
TAG_END))
{
/* set information specific to the shadow component of the border */
shadowBorder.LeftEdge = MYBORDER_LEFT + 1;
shadowBorder.TopEdge = MYBORDER_TOP + 1;
shadowBorder.FrontPen = mySHADOWPEN;
shadowBorder.NextBorder = &shineBorder;

/* set information specific to the shine component of the border */
shineBorder.LeftEdge = MYBORDER_LEFT;
shineBorder.TopEdge = MYBORDER_TOP;
shineBorder.FrontPen = mySHINEPEN;
shineBorder.NextBorder = NULL;

/* the following attributes are the same for both borders. */
shadowBorder.BackPen = shineBorder.BackPen = 0;
shadowBorder.DrawMode = shineBorder.DrawMode = JAM1;
shadowBorder.Count = shineBorder.Count = 5;
shadowBorder.XY = shineBorder.XY = myBorderData;

/* Draw the border at 10,10 */
IIntuition->DrawBorder(win->RPort,&shadowBorder,10,10);

/* Draw the border again at 100,10 */
IIntuition->DrawBorder(win->RPort,&shadowBorder,100,10);

/* Wait a bit, then quit.
** In a real application, this would be an event loop, like the
** one described in the Intuition Input and Output Methods article.
*/
IDOS->Delay(200);

IIntuition->CloseWindow(win);
}
}

IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);

return 0;
}
</syntaxhighlight>

= Border Colors and Drawing Modes =

Borders can select their colors from the values set in the color registers for the screen in which they are rendered. The available number of colors and palette settings are screen attributes and may not be changed through border rendering.

Two drawing modes pertain to border lines: JAM1 and COMPLEMENT. To draw the line in a specific color, use the JAM1 draw mode. This mode converts each pixel in the line to the color set in the FrontPen field.

Selecting the COMPLEMENT draw mode causes the line to be drawn in an exclusive-or mode that inverts the color of each pixel within the line. The data bits of the pixel are changed to their binary complement. This complement is formed by reversing all bits in the binary representation of the color register number. In a three bitplane display, for example, color 6 is 110 in binary. In COMPLEMENT draw mode, if a pixel is color 6, it will be changed to the 001 (binary), which is color 1. Note that a border drawn in COMPLEMENT mode can be removed from a static display by drawing the border again in the same position.

= Border Coordinates =

Intuition draws lines between points that are specified as sets of X, Y coordinates. Border data does not have to be in Chip memory.

The XY field contains a pointer to an array of coordinate pairs. All of these coordinates are offsets relative to the Border position, which is determined by the sum of the external and internal position components as described above. The coordinate pairs are ordered sequentially. The first two numbers make up the first coordinate pair, the next two numbers make up the second pair, and so on. Within a coordinate pair, the first number is the X offset and the second number is the Y offset.

The first coordinate pair describes the starting point of the first line. When the Border is rendered, a line is drawn between each pair of points. The first line is drawn from point one to point two, the second line is drawn from point two to point three, and so on, until the final point is reached.

The numbers specified in the XY array may be positive or negative. Negative values move up and to the left relative to the Border position, positive values move down and to the right. Again, the Border position is determined by adding the external position component and the internal position component. For example, a Border attached to a Gadget has an external component equal to the upper left corner of the gadget’s select box. The internal component is set within the Border structure itself. These two components are added together and offsets from the resulting position, specified within the XY array, determine where the lines of the Border will appear.

Suppose the top left corner of the select box of the gadget is at window position (10,5). If the Border has LeftEdge set to 10 and TopEdge set to 10, then the Border is positioned at (10+10,5+10), that is (20,15). All XY coordinates will be relative to this Border position. If the XY array contains ‘0,5, 15,5, 15,0’, then the relative coordinates will be (0,5), (15,5) and (15,0). Adding each coordinate to the Border position gives the absolute position of the lines within the window. This Border will draw two lines in the window, one from (20,20) to (35,20) and the second from (35,20) to (35,15).

[[File:LibFig8-3.png|frame|center|Example of Border Relative Position]]

To create a border that is outside the select box of a gadget, specify negative values in the internal component or use negative values for the initial XY values. For example, setting LeftEdge to -1 and TopEdge to -1 moves the position of the Border one pixel above and one pixel to the left of the gadget’s select box.

= Linking Borders =

The NextBorder field can point to another instance of a Border structure. This allows complex graphic objects to be created by linking together Border structures, each with its own data points, color and draw mode. This might be used, for instance, to draw a double border around a requester or gadget where the outer border is a second Border structure, linked to the first inner border.

Note that the borders can share data. For instance, to create a border with a shadow, link two borders together each of which points to the same XY data. Set the first border to draw in a dark pen (such as the SHADOWPEN from the screen’s DrawInfo structure) and position the border down and to the right a few pixels by changing LeftEdge and TopEdge in the Border structure.

The second border should be set to a bright pen (such as the SHINEPEN in the screen’s DrawInfo structure). When the border is drawn, the first border will draw in a dark color and then the second border will be drawn over it in a light color. Since they use the same data set, and the dark border is shifted down and to the right, the border will have a three dimensional appearance. This technique is demonstrated in the example listed earlier in this section.

Gameport Device

2025-01-26T19:32:20Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

[[Category:Devices|Gameport]]{{NeedUpdate}}
== Gameport Device ==

The gameport device manages access to the Amiga gameport connectors for the operating system. It enables the Amiga to interface with various external pointing devices like mice (two and three button), joysticks, trackballs and light pens. There are two units in the gameport device, unit 0 and unit 1.

'''Amiga Gameport Controllers'''

{| class="wikitable"
!
! Unit 0
! Unit 1
|-
| A3000
| Front Connector
| Back Connector
|-
| A2000
| Left Connector
| Right Connector
|-
| A1000
| 1
| 2
|-
| A500
| 1 JOYSTICK
| 2 JOYSTICK
|}

== Gameport Device Commands and Functions ==

{| class="wikitable"
! Command
! Command Operation
|-
| CMD_CLEAR
| Clear the gameport input buffer.
|-
| GPD_ASKCTYPE
| Return the type of gameport controller being used.
|-
| GPD_ASKTRIGGER
| Return the conditions that have been preset for triggering.
|-
| GPD_READEVENT
| Read one or more gameport events.
|-
| GPD_SETCTYPE
| Set the type of the controller to be used.
|-
| GPD_SETTRIGGER
| Preset the conditions that will trigger a gameport event.
|}

{{Note|title=Who Runs The Mouse?|text=When the input device or Intution is operating, unit 0 is usually dedicated to gathering mouse events. The input device uses the gameport device to read the mouse events. (For applications that take over the machine without starting up the input device or Intuition, unit 0 can perform the same functions as unit 1.) See [[Input_Device|Input Device]] for more information on the input device.}}

== Device Interface ==

The gameport device operates like the other Amiga devices. To use it, you must first open the gameport device, then send I/O requests to it, and then close it when finished. See [[Exec_Device_I/O|Exec Device I/O]] for general information on device usage.

The I/O request used by the gameport device is called IOStdReq.

<syntaxhighlight lang="C" line>
struct IOStdReq
{
struct Message io_Message;
struct Device *io_Device; /* device node pointer */
struct Unit *io_Unit; /* unit (driver private)*/
UWORD io_Command; /* device command */
UBYTE io_Flags;
BYTE io_Error; /* error or warning num */
ULONG io_Actual; /* actual number of bytes transferred */
ULONG io_Length; /* requested number bytes transferred*/
APTR io_Data; /* points to data area */
ULONG io_Offset; /* offset for block structured devices */
};
</syntaxhighlight>

See the include file exec/io.h for the complete structure definition.

=== Opening the Gameport Device ===

Three primary steps are required to open the gameport device:

* Create a message port using CreatePort(). Reply messages from the device must be directed to a message port.
* Create an I/O request structure of type IOStdReq. The IOStdReq structure is created by the CreateExtIO() function. CreateExtIO() will initialize the I/O request with your reply port.
* Open the gameport device. Call OpenDevice(), passing the I/O request and and indicating the unit you wish to use.

<pre>struct MsgPort *GameMP; /* Message port pointer */
struct IOStdReq *GameIO; /* I/O request pointer */

/* Create port for gameport device communications */
if (!(GameMP = CreatePort("RKM_game_port",0)))
cleanexit(" Error: Can't create port\n",RETURN_FAIL);

/* Create message block for device I/O */
if (!(GameIO = CreateExtIO(GameMP,sizeof(struct IOStdReq))))
cleanexit(" Error: Can't create I/O request\n",RETURN_FAIL);

/* Open the right/back (unit 1, number 2) gameport.device unit */
if (error=OpenDevice("gameport.device",1,GameIO,0))
cleanexit(" Error: Can't open gameport.device\n",RETURN_FAIL);</pre>
The gameport commands are unit specific. The unit number specified in the call to OpenDevice() determines which unit is acted upon.

=== Gameport Device Controllers ===

The Amiga has five gameport device controller types.

'''Gameport Device Controllers'''

{| class="wikitable"
! Controller Type
! Description
|-
| GPCT_MOUSE
| Mouse controller
|-
| GPCT_ABSJOYSTICK
| Absolute (digital) joystick
|-
| GPCT_RELJOYSTICK
| Relative (digital) joystick
|-
| GPCT_ALLOCATED
| Custom controller
|-
| GPCT_NOCONTROLLER
| No controller
|}

To use the gameport device, you must define the type of device connected to the gameport and define how the device is to respond. The gameport device can be set up to return the controller status immediately or only when certain conditions have been met.

When a gameport device unit reponds to a request for input, it creates an input event. The contents of the input event will vary based on the type of device and the trigger conditions you have declared.

* A mouse controller can report input events for one, two, or three buttons and for positive or negative (x,y) movements. A trackball controller or car-driving controller is generally of the same type and can be declared as a mouse controller.

* An absolute joystick reports one single event for each change of its current location. If, for example, the joystick is centered and the user pushes the stick forward and holds it in that position, only one single forward-switch event will be generated.

* A relative joystick, on the other hand, is comparable to an absolute joystick with “autorepeat” installed. As long as the user holds the stick in a position other than centered, the gameport device continues to generate position reports.

* There is currently no system software support for proportional joysticks or proportional controllers (e.g., paddles). If you write custom code to read proportional controllers or other controllers (e.g., light pen) make certain that you issue GPD_SETCTYPE (explained below) with controller type GPCT_ALLOCATED to insure that other applications know the connector is being used.

{| class="wikitable"
| ''GPCT_NOCONTROLLER'' The controller type GPCT_NOCONTROLLER is not a controller at all, but a flag to indicate that the unit is not being used at the present time.
|}

=== Closing the Gameport Device ===

Each OpenDevice() must eventually be matched by a call to CloseDevice().

All I/O requests must be complete before CloseDevice(). If any requests are still pending, abort them with AbortIO() and remove them with WaitIO().

<pre>if (!(CheckIO(GameIO)))
{
AbortIO(GameIO); /* Ask device to abort request, if pending */
}
WaitIO((GameIO); /* Wait for abort, then clean up */
CloseDevice(GameIO);</pre>

== Gameport Events ==

A gameport event is an InputEvent structure which describes the following:

* The class of the event - always set to IECLASS_RAWMOUSE for the gameport device.
* The subclass of the event - 0 for the left port; 1 for the right port.
* The code - which button and its state. (No report = 0xFF)
* The qualifier - only button and relative mouse bits are set.
* The position - either a data address or mouse position count.
* The time stamp - delta time since last report, returned as frame count in tv_secs field.
* The next event - pointer to next event.

<pre>struct InputEvent GameEV
{
struct InputEvent *ie_NextEvent; /* next event */
UBYTE ie_Class; /* input event class */
UBYTE ie_SubClass; /* subclass of the class */
UWORD ie_Code; /* input event code */
UWORD ie_Qualifier; /* event qualifiers in effect */
union
{
struct
{
WORD ie_x; /* x position for the event */
WORD ie_y; /* y position for the event */
} ie_xy;
APTR ie_addr;
} ie_position;
struct timeval ie_TimeStamp; /* delta time since last report
}</pre>
See the include file devices/inputevent.h for the complete structure definition and listing of input event fields.

=== Reading Gameport Events ===

You read gameport events by passing an I/O request to the device with GPD_READEVENT set in io_Command, the address of the InputEvent structure to store events set in io_Data and the size of the structure set in io_Length.

<pre>struct InputEvent GameEV;
struct IOStdRequest *GameIO; /* Must be initialized prior to using */

void send_read_request()
{
GameIO->io_Command = GPD_READEVENT; /* Read events */
GameIO->io_Length = sizeof (struct InputEvent);
GameIO->io_Data = (APTR)&GameEV; /* put events in GameEV*/
SendIO(GameIO); /* Asynchronous */
}</pre>
=== Setting Gameport Event Trigger Conditions ===

You set the conditions that can trigger a gameport event by passing an I/O request to the device with GPD_SETTRIGGER set in io_Command and the address of a GamePortTrigger structure set in io_Data.

The information needed for gameport trigger setting is placed into a GamePortTrigger data structure which is defined in the include file devices/gameport.h.

<syntaxhighlight lang="C" line>
struct GamePortTrigger
{
UWORD gpt_Keys; /* key transition triggers */
UWORD gpt_Timeout; /* time trigger (vertical blank units) */
UWORD gpt_XDelta; /* X distance trigger */
UWORD gpt_YDelta; /* Y distance trigger */
}
</syntaxhighlight>

A few points to keep in mind with the GPD_SETTRIGGER command are:

* Setting GPTF_UPKEYS enables the reporting of upward transitions. Setting GPTF_DOWNKEYS enables the reporting of downward transitions. These flags may both be specified.

* The field gpt_Timeout specifies the time interval (in vertical blank units) between reports in the absence of another trigger condition. In other words, an event is generated every gpt_Timeout ticks. Vertical blank units may differ from country to country (e.g 60 Hz NTSC, 50 Hz PAL). To find out the exact frequency use this code fragment:

<pre>
#include <exec/execbase.h>
extern struct ExecBase *SysBase;

UBYTE get_frequency(void)
{
return((UBYTE)SysBase->VBlankFrequency);
}
</pre>

* The gpt_XDelta and gpt_YDelta fields specify the x and y distances which, if exceeded, trigger a report.

For a mouse controller, you can trigger on a certain minimum-sized move in either the x or y direction, on up or down transitions of the mouse buttons, on a timed basis, or any combination of these conditions.

For example, suppose you normally signal mouse events if the mouse moves at least 10 counts in either the x or y directions. If you are moving the cursor to keep up with mouse movements and the user moves the mouse less than 10 counts, after a period of time you will want to update the position of the cursor to exactly match the mouse position. Thus the timed report of current mouse counts would be preferred. The following structure would be used:

<pre>
#define XMOVE 10
#define YMOVE 10

struct GamePortTrigger GameTR =
{
GPTF_UPKEYS | GPTF_DOWNKEYS, /* trigger on all key transitions */
1800, /* and every 36(PAL) or 30(NTSC) seconds */
XMOVE, /* for any 10 in an x or y direction */
YMOVE
};
</pre>

For a joystick controller, you can select timed reports as well as button-up and button-down report trigger conditions. For an absolute joystick specify a value of one (1) for the GameTR_XDelta and GameTR_YDelta fields or you will not get any direction events. You set the trigger conditions by using the following code or its equivalent:

<pre>
struct IOStdReq *GameIO;

void set_trigger_conditions(struct GamePortTrigger *GameTR)
{
GameIO->io_Command = GPD_SETTRIGGER; /* set trigger conditions */
GameIO->io_Data = (APTR)GameTR; /* from GameTR */
GameIO->io_Length = sizeof(struct GamePortTrigger);
DoIO(GameIO);
}
</pre>

{| class="wikitable"
| ''Triggers and Reads.'' If a task sets trigger conditions and does not ask for the position reports the gameport device will queue them up anyway. If the trigger conditions occur again and the gameport device buffer is filled, the additional triggers will be ignored until the buffer is read by a device read request (GPD_READEVENT) or a system CMD_CLEAR command flushes the buffer.
|}

=== Determining the Trigger Conditions ===

You determine the conditions required for triggering gameport events by passing an I/O request to the device with GPD_ASKTRIGGER set in io_Command, the length of the GamePortTrigger structure set in io_Length and the address of the structure set in io_Data. The gameport device will respond with the event trigger conditions currently set.

<pre>struct IOStdReq *GameIO; /* Must be initialized prior to using */

struct GamePortTrigger GameTR;

void get_trigger_conditions(struct GamePortTrigger *GameTR)
{
GameIO->io_Command = GPD_ASKTRIGGER; /* get type of triggers */
GameIO->io_Data = (APTR)GameTR; /* place data here */
GameIO->io_Length= sizeof(GameTR);
DoIO(GameIO);
}</pre>
== Setting and Reading the Controller Type ==

=== Determining the Controller Type ===

You determine the type of controller being used by passing an I/O request to the device with GPD_ASKCTYPE set in io_Command, 1 set in io_Length and the number of the unit set in io_Unit. The gameport device will respond with the type of controller being used.

<pre>struct IOStdReq *GameIO; /* Must be initialized prior to using */

BYTE GetControllerType()
{
BYTE controller_type = 0;

GameIO->io_Command = GPD_ASKCTYPE; /* get type of controller */
GameIO->io_Data = (APTR)&controller_type; /* place data here */
GameIO->io_Length = 1;
DoIO(GameIO);
return (controller_type);
}</pre>
The BYTE value returned corresponds to one of the five controller types noted above.

=== Setting the Controller Type ===

You set the type of gameport controller by passing an I/O request to the device with GPD_SETCTYPE set in io_Command, 1 set in io_Length and the address of the byte variable describing the controller type set in io_Data.

The gameport device is a shared device; many tasks may have it open at any given time. Hence, a high level protocol has been established to prevent multiple tasks from reading the same unit at the same time.

==== Three Step Protocol for Using the Gameport Device ====

Send GPD_ASKCTYPE to the device and check for a GPCT_NOCONTROLLER return. ''Never'' issue GPD_SETCTYPE without checking whether the desired gameport unit is in use.

If GPCT_NOCONTROLLER is returned, you have access to the gameport. Set the allocation flag to GPCT_MOUSE, GPCT_ABSJOYSTICK or GPCT_RELJOYSTICK if you use a system supported controller, or GPCT_ALLOCATED if you use a custom controller.

<pre>
struct IOStdReq *GameIO; /* Must be initialized prior to using */

BOOL set_controller_type(type)
BYTE type;
{

BOOL success = FALSE;
BYTE controller_type = 0;

Forbid(); /*critical section start */
GameIO->io_Command = GPD_ASKCTYPE; /* inquire current status */
GameIO->io_Length = 1;
GameIO->io_Flags = IOF_QUICK;
GameIO->io_Data = (APTR)&controller_type; /* put answer in here */
DoIO(GameIO);

/* No one is using this device unit, let's claim it */
if (controller_type == GPCT_NOCONTROLLER)
{
GameIO->io_Command = GPD_SETCTYPE;/* set controller type */
GameIO->io_Length = 1;
GameIO->io_Data = (APTR)&type; /* set to input param */
DoIO( GameIO);
success = TRUE;
UnitOpened = TRUE;
}
Permit(); /* critical section end */

/* success can be TRUE or FALSE, see above */
return(success);
}
</pre>

The program must set the controller type back to GPCT_NOCONTROLLER upon exiting your program:

<pre>
struct IOStdReq *GameIO; /* Must be initialized prior to using */

void free_gp_unit()
{
BYTE type = GPCT_NOCONTROLLER;
GameIO->io_Command = GPD_SETCTYPE; /* set controller type */
GameIO->io_Length = 1;
GameIO->io_Data = (APTR)&type; /* set to unused */
DoIO( GameIO);
}
</pre>

This three step protocol allows applications to share the gameport device in a system compatible way.

{| class="wikitable"
| ''A Word About The Functions.'' The functions shown above are designed to be included in any application using the gameport device. The first function, set_controller_type(), would be the first thing done after opening the gameport device. The second function, free_gp_unit(), would be the last thing done before closing the device.
|}

== Joystick Example Program ==

<pre>/*
* Absolute_Joystick.c
*
* Gameport device absolute joystick example
*
* Compile with SAS 5.10 lc -b1 -cfistq -v -y -L
*
* Run from CLI only
*/

#include <exec/types.h>
#include <exec/io.h>
#include <exec/memory.h>
#include <intuition/intuition.h>
#include <exec/exec.h>
#include <dos/dos.h>
#include <devices/gameport.h>
#include <devices/inputevent.h>

#include <clib/exec_protos.h>
#include <clib/alib_protos.h>
#include <clib/dos_protos.h>
#include <clib/intuition_protos.h>

#include <stdio.h>

#ifdef LATTICE
int CXBRK(void) { return(0); } /* Disable SAS CTRL/C handling */
int chkabort(void) { return(0); } /* really */
#endif

#define JOY_X_DELTA (1)
#define JOY_Y_DELTA (1)
#define TIMEOUT_SECONDS (10)

extern struct ExecBase *SysBase;

/*-----------------------------------------------------------------------
** Routine to print out some information for the user.
*/
VOID printInstructions(VOID)
{
printf("\n >>> gameport.device Absolute Joystick Demo <<<\n\n");

if (SysBase->VBlankFrequency==60)
printf(" Running on NTSC system (60 Hz).\n");
else if (SysBase->VBlankFrequency==50)
printf(" Running on PAL system (50 Hz).\n");

printf( " Attach joystick to rear connector (A3000) and (A1000).\n"
" Attach joystick to right connector (A2000).\n"
" Attach joystick to left connector (A500).\n"
" Then move joystick and click its button(s).\n\n"
" To exit program press and release fire button 3 consecutive times. \n"
" The program also exits if no activity occurs for 1 minute.\n\n");
}

/*-----------------------------------------------------------------------
** print out information on the event received.
*/
BOOL check_move(struct InputEvent *game_event)
{
WORD xmove, ymove;
BOOL timeout=FALSE;

xmove = game_event->ie_X;
ymove = game_event->ie_Y;

if (xmove == 1)
{
if (ymove == 1) printf("RIGHT DOWN\n");
else if (ymove == 0) printf("RIGHT\n");
else if (ymove ==-1) printf("RIGHT UP\n");
else printf("UNKNOWN Y\n");
}
else if (xmove ==-1)
{
if (ymove == 1) printf("LEFT DOWN\n");
else if (ymove == 0) printf("LEFT\n");
else if (ymove ==-1) printf("LEFT UP\n");
else printf("UNKNOWN Y\n");
}
else if (xmove == 0)
{
if (ymove == 1) printf("DOWN\n");
/* note that 0,0 can be a timeout, or a direction release. */
else if (ymove == 0)
{
if (game_event->ie_TimeStamp.tv_secs >=
(UWORD)(SysBase->VBlankFrequency) * TIMEOUT_SECONDS)
{
printf("TIMEOUT\n");
timeout=TRUE;
}
else printf("RELEASE\n");
}
else if (ymove ==-1) printf("UP\n");
else printf("UNKNOWN Y\n");
}
else
{
printf("UNKNOWN X ");
if (ymove == 1) printf("unknown action\n");
else if (ymove == 0) printf("unknown action\n");
else if (ymove ==-1) printf("unknown action\n");
else printf("UNKNOWN Y\n");
}

return(timeout);

}

/*-----------------------------------------------------------------------
** send a request to the gameport to read an event.
*/
VOID send_read_request( struct InputEvent *game_event,
struct IOStdReq *game_io_msg)
{
game_io_msg->io_Command = GPD_READEVENT;
game_io_msg->io_Flags = 0;
game_io_msg->io_Data = (APTR)game_event;
game_io_msg->io_Length = sizeof(struct InputEvent);
SendIO(game_io_msg); /* Asynchronous - message will return later */
}

/*-----------------------------------------------------------------------
** simple loop to process gameport events.
*/
VOID processEvents( struct IOStdReq *game_io_msg,
struct MsgPort *game_msg_port)
{
BOOL timeout;
SHORT timeouts;
SHORT button_count;
BOOL not_finished;
struct InputEvent game_event; /* where input event will be stored */

/* From now on, just read input events into the event buffer,
** one at a time. READEVENT waits for the preset conditions.
*/
timeouts = 0;
button_count = 0;
not_finished = TRUE;

while ((timeouts < 6) && (not_finished))
{
/* Send the read request */
send_read_request(&game_event,game_io_msg);

/* Wait for joystick action */
Wait(1L << game_msg_port->mp_SigBit);
while (NULL != GetMsg(game_msg_port))
{
timeout=FALSE;
switch(game_event.ie_Code)
{
case IECODE_LBUTTON:
printf(" FIRE BUTTON PRESSED \n");
break;

case (IECODE_LBUTTON | IECODE_UP_PREFIX):
printf(" FIRE BUTTON RELEASED \n");
if (3 == ++button_count)
not_finished = FALSE;
break;

case IECODE_RBUTTON:
printf(" ALT BUTTON PRESSED \n");
button_count = 0;
break;

case (IECODE_RBUTTON | IECODE_UP_PREFIX):
printf(" ALT BUTTON RELEASED \n");
button_count = 0;
break;

case IECODE_NOBUTTON:
/* Check for change in position */
timeout = check_move(&game_event);
button_count = 0;
break;

default:
break;
}

if (timeout)
timeouts++;
else
timeouts=0;
}
}
}

/*-----------------------------------------------------------------------
** allocate the controller if it is available.
** you allocate the controller by setting its type to something
** other than GPCT_NOCONTROLLER. Before you allocate the thing
** you need to check if anyone else is using it (it is free if
** it is set to GPCT_NOCONTROLLER).
*/
BOOL set_controller_type(BYTE type, struct IOStdReq *game_io_msg)
{
BOOL success = FALSE;
BYTE controller_type = 0;

/* begin critical section
** we need to be sure that between the time we check that the controller
** is available and the time we allocate it, no one else steals it.
*/
Forbid();

game_io_msg->io_Command = GPD_ASKCTYPE; /* inquire current status */
game_io_msg->io_Flags = IOF_QUICK;
game_io_msg->io_Data = (APTR)&controller_type; /* put answer in here */
game_io_msg->io_Length = 1;
DoIO(game_io_msg);

/* No one is using this device unit, let's claim it */
if (controller_type == GPCT_NOCONTROLLER)
{
game_io_msg->io_Command = GPD_SETCTYPE;
game_io_msg->io_Flags = IOF_QUICK;
game_io_msg->io_Data = (APTR)&type;
game_io_msg->io_Length = 1;
DoIO( game_io_msg);
success = TRUE;
}

Permit(); /* critical section end */
return(success);
}

/*-----------------------------------------------------------------------
** tell the gameport when to trigger.
*/
VOID set_trigger_conditions(struct GamePortTrigger *gpt,
struct IOStdReq *game_io_msg)
{
/* trigger on all joystick key transitions */
gpt->gpt_Keys = GPTF_UPKEYS | GPTF_DOWNKEYS;
gpt->gpt_XDelta = JOY_X_DELTA;
gpt->gpt_YDelta = JOY_Y_DELTA;
/* timeout trigger every TIMEOUT_SECONDS second(s) */
gpt->gpt_Timeout = (UWORD)(SysBase->VBlankFrequency) * TIMEOUT_SECONDS;

game_io_msg->io_Command = GPD_SETTRIGGER;
game_io_msg->io_Flags = IOF_QUICK;
game_io_msg->io_Data = (APTR)gpt;
game_io_msg->io_Length = (LONG)sizeof(struct GamePortTrigger);
DoIO(game_io_msg);
}

/*-----------------------------------------------------------------------
** clear the buffer. do this before you begin to be sure you
** start in a known state.
*/
VOID flush_buffer(struct IOStdReq *game_io_msg)
{
game_io_msg->io_Command = CMD_CLEAR;
game_io_msg->io_Flags = IOF_QUICK;
game_io_msg->io_Data = NULL;
game_io_msg->io_Length = 0;
DoIO(game_io_msg);
}

/*-----------------------------------------------------------------------
** free the unit by setting its type back to GPCT_NOCONTROLLER.
*/
VOID free_gp_unit(struct IOStdReq *game_io_msg)
{
BYTE type = GPCT_NOCONTROLLER;

game_io_msg->io_Command = GPD_SETCTYPE;
game_io_msg->io_Flags = IOF_QUICK;
game_io_msg->io_Data = (APTR)&type;
game_io_msg->io_Length = 1;
DoIO(game_io_msg);
}

/*-----------------------------------------------------------------------
** allocate everything and go. On failure, free any resources that
** have been allocated. this program fails quietly--no error messages.
*/
VOID main(int argc,char **argv)
{
struct GamePortTrigger joytrigger;
struct IOStdReq *game_io_msg;
struct MsgPort *game_msg_port;

/* Create port for gameport device communications */
if (game_msg_port = CreatePort("RKM_game_port",0))
{
/* Create message block for device IO */
if (game_io_msg = (struct IOStdReq *)
CreateExtIO(game_msg_port,sizeof(*game_io_msg)))
{
game_io_msg->io_Message.mn_Node.ln_Type = NT_UNKNOWN;

/* Open the right/back (unit 1, number 2) gameport.device unit */
if (!OpenDevice("gameport.device",1,game_io_msg,0))
{
/* Set controller type to joystick */
if (set_controller_type(GPCT_ABSJOYSTICK,game_io_msg))
{
/* Specify the trigger conditions */
set_trigger_conditions(&joytrigger,game_io_msg);

printInstructions();

/* Clear device buffer to start from a known state.
** There might still be events left
*/
flush_buffer(game_io_msg);

processEvents(game_io_msg,game_msg_port);

/* Free gameport unit so other applications can use it ! */
free_gp_unit(game_io_msg);
}
CloseDevice(game_io_msg);
}
DeleteExtIO(game_io_msg);
}
DeletePort(game_msg_port);
}
}</pre>
== Additional Information on the Gameport Device ==

Additional programming information on the gameport device can be found in the include files and the Autodocs for the gameport and input devices. Both are contained in the SDK.

{| class="wikitable"
! Includes
|-
| devices/gameport.h
|-
| devices/inputevent.h
|}

{| class="wikitable"
! AutoDocs
|-
| gameport.doc
|}

AmiWest 2013 Lesson 4

2025-01-26T19:31:42Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Such applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual file system device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one3 opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

When Roadshow gets online, it creates a virtual TCP: device. To open
a connection, one opens a virtual file on the TCP: device to the URL and
port in question using this format:

<syntaxhighlight lang="C" line>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight lang="C" line>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a web server of the "Weather Underground"
website.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protocol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of an "HTTP" (or a "Hypertext Transfer Protocol") connection to
a web server, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets mimic submitting a "GET" request (as if from IBrowse).
A simple HTTP version 1.1 GET request would include the following lines:

<syntaxhighlight lang="C" line>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The '''<path>''' would be the rest of the URL (if any) on that system and
'''<domain>''' is the name of the server.

Using the "WeatherUnderground" website URL from above and their path name for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight lang="C" line>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Such a GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our open
TCP: file handle, as follows:

<syntaxhighlight lang="C" line>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The empty line at the end (with just a "\r\n") completes the
GET request, after which the server will reply to your program.

===Listen to the Server===

Once the GET request has been sent to the web server, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server in this example, you can
combine the domain and path values above and enter them in your web
browser's URL string gadget, like this:

<syntaxhighlight lang="C" line>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded in your browser, viewing the page source (f.e., IBrowse
menu item "Page/Display Source...") will show you the same HTML text that your
program will receive after sending the GET request.

As such, your program needs to start reading from the file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight lang="C" line>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your application can parse the received lines for whatever
data your application is trying to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want to find.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight lang="C" line>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of the above elements are combined in the following example program
"IPClient.c" that asks you for an IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned WeatherUnderground.com web page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information. Should this happen, you get to use what
you learned above to upgrade or replace this example.

<syntaxhighlight lang="C" line>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used, in formatting the request and processing
received data.

Public web servers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any web browser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
and more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or one which invites such
connections (some even publish API's and example code for you to use),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecessary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external elements, your
code should provide for the possibility things may not
succeed or the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make modifying those things easy as possible (even
by the user?).

For example, the parsing strings could be kept in the program's tooltype
or a config text file, you could provide a GUI for managing the strings, or
employ an external, editable ARexx macro for processing.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demonstrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

* Check stock quotes from a financial site.
* Get package tracking information from a shipping site.
* Check for new emails on a POP email server.
* Convert currencies with a financial or travel web site.
* Check for files on an FTP server.
* Send messages with a SMTP email server.
* Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player? The AmiNet
also has many examples of simple clients (with C source code or in
readable ARexx) that can be studied for means and methods.

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then responds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight lang="C" line>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
of the loop if we read 100 lines - that's a sign something else is
wrong, we should never see so long a request with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use another protocol, the processing of
the received data would likely happe3n elsewhere.

As you see, we do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). With the above code, the diagnostics
output will show the entire incoming request on the serial port. Of course,
there's a reason why we have to use "DebugPrintf" for diagnostics output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of strings (in the '''lines''' array)
of a very simple webpage through Roadshow, to our web visitor:

<syntaxhighlight lang="C" line>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a fail-safe). Then we "flush" the output
stream and quit our program.

While our two samples of code simply receive and respond to an incoming web request,
one can imagine where this code can be expanded provide useful service and more
complex interactions.

===EXAMPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight lang="C" line>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
" <TABLE WIDTH=90%><TR><TD><H1>WELCOME</H1> </TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3>AmigaOS IPserver example</TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
" <TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4>And so it begins...</TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this server out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide, as described below. Both of these can
be configured using Internet Prefs. You can also make this configuration by
manually editing the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight lang="C" line>
SYS:Documentation/Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Critically, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight lang="C" line>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could manually be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight lang="C" line>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight lang="C" line>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can otherwise make this adjustment to Roadshow's server list by manually adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight lang="C" line>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight lang="C" line>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight lang="C" line>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga (at the port number
following the colon - ":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? Webpages? More?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight lang="C" line>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an image file
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can process them and respond to web visitors. To dig deeper you can
search the many sources online or in your local bookstore on HTTP communications
and the formatting of HTML webpages. Of course, you should make sure your
server can optionally send diagnostics output so you know what requests are
being received and how they are responded to.

===Just Webpages?===

There's also no reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that you could write a server for. Or you could
create your own online client and server pair of applications that
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is critically important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized path names and requests are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server program will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using inter-process
communications (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each instance of the internet server handles each incoming request, quickly
relays the necessary information from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this tutorial.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there are RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosyncrasies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interrupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities - that isn't reflected in the simple examples above.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a server should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

Programming AmigaOS 4: GUI Toolkit ReAction

2025-01-26T19:31:21Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

''This article was adapted from Amiga Future magazine's series on developing for AmigaOS....''

We mainly worked with shell programs or simple windows in the previous parts of this workshop. However, today's topic will be how to create a completely interactive GUI.

For this purpose we will use ReAction, which provides great flexibility for defined windows and controls that lay themselves out automatically. But before we dive into this subject, let us take a look at the past and see how interface development on the Amiga has changed over the years.

= History =

With Kickstart 1.x you had to create gadgets (the controls, which were back then - a button, a panel and a slide bar) directly as a structure and connect them with each other as well as calculate their positions. This procedure was very time consuming and a different font or another window size could sometimes cause significant trouble. Therefore, the gadtools.library, which was supplied with Kickstart 2.x, greatly simplified the creation of gadgets and menus. Additionally, a great number of new gadget types (e.g. ListView, Checkbox, Cycle) was launched. However, there was still a problem with the fixed positions. In this step the BOOPSI (Basic Object Oriented Programming System for Intuition) was also created. It offered an object-orientated approach, that could readily be used with Workbench 3.5 in the form of ReAction gadgets. This made it possible for windows to lay themselves out correctly automatically. That means that the gadgets automatically re-position themselves and their size is adjusted, if needed, when the window size is changed. The calculation of the minimized window size when opening a window is handled automatically by the system.

= The end of Gadtools =

By introducing ReAction all gadget types from the gadtools.library became superfluous. The same procedure is still used with AmigaOS 4, but this time it is used to create menus. All the functions required to create and layout menus are now available in the window class and no longer need to be made automatically. In other words, gadtools.library no longer has this role to perform!

A side note: the MUI (Magic User Interface) is used as a second GUI library and it is provided with the Operating System since AmigaOS 4. However, it remains an external toolkit. Its standard appearance has been made in the style of AmigaOS 4 so it would not look like an 'alien element'. In principle, it applies the same approach as for ReAction, but it is programmed differently.

= ReAction step by step =

After that brief introduction it is now time for our first example, a window with a gadget and a menu. What used to take a long time, is now done in just a few steps. These necessary steps will be explained here in detail, because you can create big applications with them as well.

All ReAction objects (gadgets, window and Requester) are set up with IIntuition->NewObject(). The result is a generic 'Object' pointer. However, most of the old functions still expect a pointer on a gadget structure (or a window structure), so that you must decide whether you want to cast the return value immediately, or once you activate the respective functions. There is no standard notation in SDK at the moment. Right now, casting the result pointer is the best option. This way you can immediately see what it is about, in case you have selected an unfavourable name for the variable. You can create a button as follows:

<syntaxhighlight lang="C" line>
struct Gadget *gb_ButtonGad;
#define GAD_ID_Quit 2

if((gb_ButtonGad = (struct Gadget *) IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
GA_ID, GAD_ID_Quit,
GA_RelVerify, TRUE,
GA_Text, "_end",
TAG_DONE)))
</syntaxhighlight>

There is an example for various gadget classes at the end of this article. The GA_xxx tags are general and applicable to all kinds of gadgets. A specific gadget for a button would be, for instance, BUTTON_BevelStyle, which you can find under "gadgets/...". With the underscore in the button text the shortcut is defined, which can start the button without a mouse.

You can also use the same procedure to create a window, but this time you must use the WINDOW_xxx Defines from "classes/window.h". In addition, you can also use a great number of old WA tags.

<syntaxhighlight lang="C" line>
Object *gb_WindowObj;
if((gb_WindowObj = (Object *) IIntuition->NewObject(IWindow->WINDOW_GetClass(),NULL,
WA_IDCMP, IDCMP_GADGETUP | IDCMP_CLOSEWINDOW | IDCMP_MENUPICK,
WA_SizeGadget, TRUE,
WA_DepthGadget, TRUE,
WA_DragBar, TRUE,
WA_CloseGadget, TRUE,
WA_Activate, TRUE,
WA_Title, "Example with reaction gadgets and window class",
WINDOW_Position, WPOS_CENTERSCREEN,
</syntaxhighlight>

A ReAction window requires implicitly a layout object, which automatically handles the size adjustment and distribution of the individual gadgets. In our example with only one gadget we need a central layout method. The layout object serves the horizontal and vertical arrangement of several gadgets within the window. This way, you can also realise very complex layouts by dividing them into horizontal and vertical groups.

<syntaxhighlight lang="C" line>
struct Gadget *gb_MainLayout;
WINDOW_ParentGroup, gb_MainLayout = (struct Gadget *)
IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,
LAYOUT_AddChild, gb_ButtonGad,
TAG_DONE),
TAG_DONE)))
</syntaxhighlight>

As already mentioned, creating menus has become a very simple task in the meantime. All you need to do is create the NewMenu structure (from "libraries/gadtools.h") dating from gadtools times, which describes the individual menu points. This structure is given then when you create the window object. You no longer need to take care of deleting the menu structure; this happens automatically when the window object is released.

<syntaxhighlight lang="C" line>
struct NewMenu gb_MenuDescribe[] =
{
{ NM_TITLE, "Project", NULL, 0, 0, NULL },
{ NM_ITEM, "Quit", NULL, 0, 0, NULL },
{ NM_END, NULL, NULL, 0, 0, NULL }
};

#define MENU_ID_Quit FULLMENUNUM(0,0,NOSUB)

IIntuition->NewObject(IWindow->WINDOW_GetClass(),
WINDOW_NewMenu, gb_MenuDescribe,
</syntaxhighlight>

Since AmigaOS 4's release the ReAction gadgets have been included in the BubbleHelp. If you move the mouse cursor over such an element, a bubble with help text will be displayed soon afterwards. You need to do just a little bit of programming for this. Mainly, you must fill out the HintInfo structure from "classes/window.h":

<syntaxhighlight lang="C" line>
struct HintInfo gb_HintInfo[] =
{
{ GAD_ID_Help, -1, "activate/deactivate the BubbleHelp hints", 0 },
{ GAD_ID_Quit, -1, "quit program", 0 },
{ -1, -1, NULL, 0 }
};
</syntaxhighlight>

The fourth value is reserved for the future flags and a 0 is assigned to it at the moment. The structure must be indicated when you create the window object.

<syntaxhighlight lang="C" line>
IIntuition->NewObject(IWindow->WINDOW_GetClass(),
WINDOW_HintInfo, gb_HintInfo,
WINDOW_GadgetHelp, TRUE,
</syntaxhighlight>

With the WINDOW_GadgetHelp you can turn on/off the help. With 'WINDOW_GadgetHelp, FALSE' you can deactivate it, so it will not be displayed again. With TRUE you can re-activate it. You can change this tag during runtime. Other settings such as influencing the waiting time until the display, the display duration, the colour, etc. are still not possible, but users should be able to change them by using a global Prefs adjuster in the future.

<syntaxhighlight lang="C" line>
IIntuition->SetAttrs(gb_WindowObj, WINDOW_GadgetHelp, FALSE, TAG_DONE);
</syntaxhighlight>

We will add a checkbox to the sample program in order to put this possibility to use. We can turn on and off the help any time with it. In reality, you will set this option on a menu point or in the program settings, if there are any. A tooltype in the icon information is also an alternative.

<syntaxhighlight lang="C" line>
struct Gadget *gb_CheckboxGad;
#define GAD_ID_Help 1

if((gb_CheckboxGad = (struct Gadget *) IIntuition->NewObject(ICheckBox->CHECKBOX_GetClass(),NULL,
GA_ID, GAD_ID_Help,
GA_RelVerify, TRUE,
GA_Text, "Bubble_Help active",
TAG_DONE)))

WINDOW_ParentGroup,
LAYOUT_AddChild, gb_CheckboxGad,
</syntaxhighlight>

All GUI elements are now created, but they are still not visible. You should certainly check, whether the window pointer is present. If not, a gadget could probably not be created. To display the window you can use the RA_OpenWindow() macros from "reaction/reaction_macros.h", to close it RA_CloseWindow() and to edit news RA_HandleInput().

Since these are macros, you cannot use the typical interface notation. The news editing loop looks in practice as follows:

<syntaxhighlight lang="C" line>
if((gb_Win = RA_OpenWindow(gb_WindowObj)))
{
ULONG winsig;
IIntuition->GetAttr(WINDOW_SigMask,gb_WindowObj,&winsig);

BOOL run = TRUE;
while(run)
{
ULONG result, code, val;

const ULONG sigs = IExec->Wait(winsig | SIGBREAKF_CTRL_C);

while((result = RA_HandleInput(gb_WindowObj,&code)) != WMHI_LASTMSG)
{
switch(result & WMHI_CLASSMASK)
{
case WMHI_GADGETUP:
switch(result & WMHI_GADGETMASK)
{
case GAD_ID_Help:
IIntuition->GetAttr(CHECKBOX_Checked,gb_CheckboxGad,(ULONG*)&val);
IIntuition->SetAttrs(gb_WindowObj,
WINDOW_GadgetHelp, val,
TAG_DONE);
break;

case GAD_ID_Quit:
run = FALSE;
break;
}
break;

case WMHI_CLOSEWINDOW:
run = FALSE;
break;

case WMHI_MENUPICK:
switch(result & WMHI_MENUMASK)
{
case MENU_ID_Quit:
run = FALSE;
break;
}
break;
}
}

if(sigs & SIGBREAKF_CTRL_C) run = FALSE;
}

RA_CloseWindow(gb_WindowObj);
}
</syntaxhighlight>

You can see the various news types like press gadget (WMHI_GADGETUP), select menu (WMHI_MENUPICK) and the closing symbol for the window (WMHI_CLOSEWINDOW). But you can only get news, which has been defined explicitly as IDCMP_xxx Bits when creating the window.

To close the program, that is, to release all created objects all you need to do is activate IIntuition->DisposeObject(). It automatically makes sure that all elements included in the object are also released. If you specify the window pointer here, all included gadgets, menus and helptexts will be also deleted and can no longer be used!

<syntaxhighlight lang="C" line>
IIntuition->DisposeObject(gb_WindowObj);
</syntaxhighlight>

What is missing now are only the Includes and a main function. Then the program is complete and can be found as an example below.

== ReAction Example ==

<syntaxhighlight lang="C" line>
/* Michael Christoph
* ReActionEx.c
*
* gcc ReActionEx.c -o ReActionEx -l auto
*/

/******************************* INCLUDES *************************************/

#include <intuition/gadgetclass.h>
#include <classes/window.h>
#include <reaction/reaction_macros.h>
#include <libraries/gadtools.h>
#include <gadgets/checkbox.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/window.h>
#include <proto/layout.h>
#include <proto/button.h>
#include <proto/checkbox.h>

#define MENU_ID_Quit FULLMENUNUM(0,0,NOSUB)

#define GAD_ID_Help 1
#define GAD_ID_Quit 2

/******************************************************************************/

static const char *version USED = "\0$VER: ReActionEx 1.00 (16.12.2004) - (c) Dec.2004 by Meicky-Soft\n";

/******************************************************************************/

Object *gb_WindowObj;
struct Window *gb_Win;
struct Gadget *gb_MainLayout;
struct Gadget *gb_ButtonGad;
struct Gadget *gb_CheckboxGad;

struct NewMenu gb_MenuDescribe[] =
{
{ NM_TITLE, "Project", NULL, 0, 0, NULL },
{ NM_ITEM, "Quit", NULL, 0, 0, NULL },

{ NM_END, NULL, NULL, 0, 0, NULL }
};

struct HintInfo gb_HintInfo[] =
{
{ GAD_ID_Help, -1, "Activate/Deactive BubbleHelp Tips", 0 },
{ GAD_ID_Quit, -1, "Quit Program", 0 },
{ -1, -1, NULL, 0 }
};

/******************************************************************************/

int main()
{
/* create a Checkbox Gadget */
if((gb_CheckboxGad = (struct Gadget *) IIntuition->NewObject(ICheckBox->CHECKBOX_GetClass(),NULL,
GA_ID, GAD_ID_Help,
GA_RelVerify, TRUE,
GA_Text, "Bubble_Help Active",
TAG_DONE)))
{
/* create the Button */
if((gb_ButtonGad = (struct Gadget *) IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
GA_ID, GAD_ID_Quit,
GA_RelVerify, TRUE,
GA_Text, "_Quit",
TAG_DONE)))
{
/* create the Window Object */
if((gb_WindowObj = (Object *) IIntuition->NewObject(IWindow->WINDOW_GetClass(),NULL,
WA_IDCMP, IDCMP_GADGETUP | IDCMP_CLOSEWINDOW | IDCMP_MENUPICK,
WA_SizeGadget, TRUE,
WA_DepthGadget, TRUE,
WA_DragBar, TRUE,
WA_CloseGadget, TRUE,
WA_Activate, TRUE,
WA_Title, "Example with ReAction gadgets and window class",
WINDOW_Position, WPOS_CENTERSCREEN,
WINDOW_NewMenu, gb_MenuDescribe,
WINDOW_HintInfo, gb_HintInfo,
WINDOW_GadgetHelp, FALSE,

/* create the Layout Object and include it into the Window */
WINDOW_ParentGroup, gb_MainLayout = (struct Gadget *)
IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,
LAYOUT_AddChild, gb_CheckboxGad,
LAYOUT_AddChild, gb_ButtonGad,
TAG_DONE),
TAG_DONE)))
{
/* open the Window */
if((gb_Win = RA_OpenWindow(gb_WindowObj)))
{
/* query the Signal Bit of the Window */
ULONG winsig;
IIntuition->GetAttr(WINDOW_SigMask,gb_WindowObj,&winsig);

BOOL laufen = TRUE;
while(laufen)
{
ULONG result, code, val;

/* wait till either Button or Close Icon are clicked */
const ULONG sigs = IExec->Wait(winsig | SIGBREAKF_CTRL_C);

/* process the received Messages */
while((result = RA_HandleInput(gb_WindowObj,&code)) != WMHI_LASTMSG)
{
/* mask out the Messages part */
switch(result & WMHI_CLASSMASK)
{
/* process the Gadget Messages */
case WMHI_GADGETUP:
switch(result & WMHI_GADGETMASK)
{
case GAD_ID_Help:
IIntuition->GetAttr(CHECKBOX_Checked,
(Object*)gb_CheckboxGad,
(ULONG*)&val);
IIntuition->SetAttrs(gb_WindowObj,
WINDOW_GadgetHelp, val,
TAG_DONE);
break;

case GAD_ID_Quit:
laufen = FALSE;
break;
}
break;

/* query the Window Close Icon */
case WMHI_CLOSEWINDOW:
laufen = FALSE;
break;

/* query the Menu Selection */
case WMHI_MENUPICK:
switch(result & WMHI_MENUMASK)
{
case MENU_ID_Quit:
laufen = FALSE;
break;
}
break;
}
}

/* query if CTRL-C received from the Shell */
if(sigs & SIGBREAKF_CTRL_C) laufen = FALSE;
}

/* close the Window */
RA_CloseWindow(gb_WindowObj);
}
}
}

/* release Window Object, dump also Layout and Gadget Objects */
IIntuition->DisposeObject(gb_WindowObj);
}

return 0;
}
</syntaxhighlight>

[[File:AF110_reactionex.png|frame|center]]

= AllGadgets Example =

We can deal with programming with ReAction here only in theory. But for this purpose we have put "AllGadgets.c" as a bonus. Here all available gadgets are used and you can see how they can be created and queried. The use of page gadgets is also shown. In conjunction with the Clicktab gadget you can also realise tabs, which always show another 'page' with gadgets. For instance, you can divide comprehensive setting windows into individual pages.

<syntaxhighlight lang="C" line>
/* Michael Christoph
* AllGadgets.c
*
* gcc AllGadgets.c -o AllGadgets -l auto
*/

/******************************* INCLUDES *************************************/

#include <exec/types.h>
#include <intuition/gadgetclass.h>
#include <intuition/icclass.h>
#include <classes/window.h>
#include <classes/requester.h>
#include <reaction/reaction_macros.h>
#include <libraries/gadtools.h>
#include <clib/macros.h>

#include <gadgets/button.h>
#include <gadgets/space.h>
#include <gadgets/checkbox.h>
#include <gadgets/listbrowser.h>
#include <gadgets/string.h>
#include <gadgets/integer.h>
#include <gadgets/radiobutton.h>
#include <gadgets/scroller.h>
#include <gadgets/slider.h>
#include <gadgets/getfile.h>
#include <gadgets/getfont.h>
#include <gadgets/getscreenmode.h>
#include <gadgets/getcolor.h>
#include <gadgets/chooser.h>
#include <gadgets/texteditor.h>
#include <gadgets/colorwheel.h>
#include <gadgets/gradientslider.h>
#include <gadgets/datebrowser.h>
#include <gadgets/fuelgauge.h>
#include <gadgets/listview.h>
#include <gadgets/layout.h>
#include <gadgets/clicktab.h>
#include <gadgets/page.h>
#include <gadgets/palette.h>
#include <gadgets/virtual.h>

#include <images/label.h>
#include <images/bevel.h>
#include <images/bitmap.h>
#include <images/drawlist.h>
#include <images/filler.h>
#include <images/glyph.h>
#include <images/penmap.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/graphics.h>
#include <proto/utility.h>
#include <proto/asl.h>
#include <proto/locale.h>
#include <proto/application.h>
#include <proto/timer.h>
#include <proto/window.h>
#include <proto/layout.h>
#include <proto/button.h>
#include <proto/slider.h>
#include <proto/scroller.h>
#include <proto/space.h>
#include <proto/label.h>
#include <proto/integer.h>
#include <proto/string.h>
#include <proto/listbrowser.h>
#include <proto/clicktab.h>
#include <proto/chooser.h>
#include <proto/radiobutton.h>
#include <proto/checkbox.h>
#include <proto/palette.h>
#include <proto/datebrowser.h>
#include <proto/fuelgauge.h>
#include <proto/getfile.h>
#include <proto/getfont.h>
#include <proto/getscreenmode.h>
#include <proto/getcolor.h>
#include <proto/texteditor.h>
#include <proto/colorwheel.h>
#include <proto/label.h>
#include <proto/bevel.h>
#include <proto/bitmap.h>
#include <proto/drawlist.h>
#include <proto/filler.h>
#include <proto/glyph.h>
#include <proto/penmap.h>

#include <string.h>

/******************************************************************************/

static const char *version USED = "\0$VER: AllGadgets 1.01 (14.04.2014) - (c) Apr.2014 by Meicky-Soft\n";

/******************************************************************************/

enum GADIDs
{
GAD_ID_ButtonV,
GAD_ID_Button,
GAD_ID_String,
GAD_ID_Integer,
GAD_ID_Slider,
GAD_ID_Scroller,

GAD_ID_Chooser,
GAD_ID_Chooser2,
GAD_ID_Chooser3,
GAD_ID_Checkbox,
GAD_ID_Radio,
GAD_ID_Listbrowser,
GAD_ID_Palette,

GAD_ID_File,
GAD_ID_Font,
GAD_ID_Screenmode,
GAD_ID_Color,

GAD_ID_Fuelgauge,
GAD_ID_Colorwheel,
GAD_ID_Gradientslider,
GAD_ID_Texteditor,
GAD_ID_Datebrowser,

GAD_ID_Space,
GAD_ID_Page,
GAD_ID_Clicktab,

GAD_ID_Pages,
GAD_ID_PagesClicktab,
};

/******************************************************************************/

struct List gb_List;

struct ColumnInfo gb_ListbrowserColumn[] =
{
{ 30, "Nummer", 0 },
{ 170, "Eintrag", 0 },
{ -1, (STRPTR)~0, (ULONG)-1 }
};

struct Hook gb_RenderHook;
struct Hook gb_IDCMPHook;

STRPTR gb_ChooserLabels[] = { "Amiga 1000", "Amiga 1200", "AmigaOne", NULL };
STRPTR gb_Chooser2Labels[] = { "Amiga 1000", "Amiga 1200", "AmigaOne", NULL };
STRPTR gb_Chooser3Labels[] = { "Amiga 1000", "Amiga 1200", "AmigaOne", NULL };

STRPTR gb_RadioLabels[] = { "Amiga 1000", "Amiga 1200", "AmigaOne", NULL };

STRPTR gb_ClicktabLabels[] = { "Amiga 1000", "Amiga 1200", "AmigaOne", NULL };

STRPTR gb_PagesLabels[] = { "_Grundtypen", "_Auswahllisten", "ASL-Aus_wahl",
"Sonstige _Typen", "_Seitengestalltung",
"_Images", NULL };

UWORD gb_GradientArray[] = { ~0, ~0, ~0, ~0, ~0, ~0, ~0 };

/******************************************************************************/

struct Gadget *gb_ButtonVGad;
struct Gadget *gb_ButtonGad;
struct Gadget *gb_StringGad;
struct Gadget *gb_IntegerGad;
struct Gadget *gb_SliderGad;
struct Gadget *gb_ScrollerGad;
struct Gadget *gb_ChooserGad;
struct Gadget *gb_Chooser2Gad;
struct Gadget *gb_Chooser3Gad;
struct Gadget *gb_CheckboxGad;
struct Gadget *gb_RadioGad;
struct Gadget *gb_ListbrowserGad;
struct Gadget *gb_PaletteGad;
struct Gadget *gb_FileGad;
struct Gadget *gb_FontGad;
struct Gadget *gb_ScreenmodeGad;
struct Gadget *gb_ColorGad;
struct Gadget *gb_FuelgaugeGad;
struct Gadget *gb_GradientsliderGad;
struct Gadget *gb_ColorwheelGad;
struct Gadget *gb_TexteditorGad;
struct Gadget *gb_DatebrowserGad;
struct Gadget *gb_SpaceGad;
struct Gadget *gb_PageGad;
struct Gadget *gb_ClicktabGad;

struct Image *gb_LabelImg;
struct Image *gb_BevelImg;
struct Image *gb_BitmapImg;
struct Image *gb_BitmapSImg;
struct Image *gb_BitmapDImg;
struct Image *gb_DrawlistImg;
struct Image *gb_FillerImg;
struct Image *gb_GlyphImg[27];
struct Image *gb_PenmapImg;

struct Gadget *gb_MainLayout;
struct Gadget *gb_Page1Layout;
struct Gadget *gb_Page2Layout;
struct Gadget *gb_Page3Layout;
struct Gadget *gb_Page4Layout;
struct Gadget *gb_Page5Layout;
struct Gadget *gb_Page6Layout;
struct Gadget *gb_PagesLayout;
struct Gadget *gb_PagesClicktab;

Object *gb_WindowObj;
struct Window *gb_Win;
struct Screen *gb_Scr;

ULONG image_object_palette[] =
{
2,
0x00000000, 0x00000000, 0x00000000,
0xEEEEEEEE, 0xDDDDDDDD, 0x00000000
};

UBYTE happy_data[] =
{
0,16, 0,14,
0,0,0,0,0,1,1,1,1,1,1,0,0,0,0,0,
0,0,0,1,1,2,2,2,2,2,2,1,1,0,0,0,
0,0,1,2,2,2,2,2,2,2,2,2,2,1,0,0,
0,1,2,2,2,2,2,2,2,2,2,2,2,2,1,0,
0,1,2,2,2,1,1,2,2,1,1,2,2,2,1,0,
1,2,2,2,2,1,1,2,2,1,1,2,2,2,2,1,
1,2,2,2,2,1,1,2,2,1,1,2,2,2,2,1,
1,2,2,2,2,2,2,2,2,2,2,2,2,2,2,1,
1,2,2,2,2,2,2,2,2,2,2,2,2,2,2,1,
0,1,2,2,2,1,2,2,2,2,1,2,2,2,1,0,
0,1,2,2,2,2,1,1,1,1,2,2,2,2,1,0,
0,0,1,2,2,2,2,2,2,2,2,2,2,1,0,0,
0,0,0,1,1,2,2,2,2,2,2,1,1,0,0,0,
0,0,0,0,0,1,1,1,1,1,1,0,0,0,0,0
};

UBYTE scared_data[] =
{
0,16, 0,14,
0,0,0,0,0,1,1,1,1,1,1,0,0,0,0,0,
0,0,0,1,1,2,2,2,2,2,2,1,1,0,0,0,
0,0,1,2,2,2,2,2,2,2,2,2,2,1,0,0,
0,1,2,2,2,1,1,2,2,1,1,2,2,2,1,0,
0,1,2,2,1,2,2,2,2,2,2,1,2,2,1,0,
1,2,2,2,2,1,1,2,2,1,1,2,2,2,2,1,
1,2,2,2,2,1,1,2,2,1,1,2,2,2,2,1,
1,2,2,2,2,2,2,2,2,2,2,2,2,2,2,1,
1,2,2,2,2,2,2,2,2,2,2,2,2,2,2,1,
0,1,2,2,2,2,1,1,1,1,2,2,2,2,1,0,
0,1,2,2,2,1,1,1,1,1,1,2,2,2,1,0,
0,0,1,2,2,2,2,2,2,2,2,2,2,1,0,0,
0,0,0,1,1,2,2,2,2,2,2,1,1,0,0,0,
0,0,0,0,0,1,1,1,1,1,1,0,0,0,0,0
};

struct DrawList gb_DrawList[] =
{
{ DLST_LINE, 0,30,15,0, 1},
{ DLST_LINE, 30,30,15,0, 1},
{ DLST_LINE, 9,15,23,15, 1},
{ DLST_END }
};

/******************************************************************************/

BOOL CreateEntry(ULONG num, CONST_STRPTR number, CONST_STRPTR text)
{
/* create a List entry */

/* ATTENTION:
** Use this function only if the List is *not* assigned to the ListView!
** If applicable, deselect via
** SetGadgetAttrs(gad,win,NULL, LISTBROWSER_Labels,~0, TAG_END);
** then modify the List, then assign the List via
** SetGadgetAttrs(gad,win,NULL, LISTBROWSER_Labels,liste, TAG_END);
** back to the ListView.

struct Node *node;

if((node = IListBrowser->AllocListBrowserNode(2,
LBNA_Column, 0,
LBNCA_Text, number,
LBNCA_Justification, LCJ_LEFT,
LBNCA_Editable, FALSE,
LBNCA_CopyText, TRUE,
LBNCA_MaxChars, 4,
LBNA_Column, 1,
LBNCA_Text, text,
LBNCA_Justification, LCJ_LEFT,
LBNCA_Editable, FALSE,
LBNCA_CopyText, TRUE,
LBNCA_MaxChars, 100,
TAG_END)))
{
node->ln_Pri = num;
IExec->AddTail(&gb_List,node);
}
else
{
IDOS->Printf("Out of memory while creating list entry\n");
}

return( node ? TRUE : FALSE );
}

/******************************************************************************/

void FreigebenList()
{
/* release the List with all its data */

/* ATTENTION:
** Use this function only if the List is *not* assigned to the ListView!
** If applicable, deselect via
** SetGadgetAttrs(gad,win,NULL, LISTBROWSER_Labels,~0, TAG_END);
** then modify the List, then assign the (empty) List via
** SetGadgetAttrs(gad,win,NULL, LISTBROWSER_Labels,liste, TAG_END);
** back to the ListView.
*/

struct Node *node, *nextnode;
node = gb_List.lh_Head;

while((nextnode = node->ln_Succ))
{
IExec->Remove(node);
IListBrowser->FreeListBrowserNode(node);

node = nextnode;
}
}

/******************************************************************************/

void RenderHookFunc(struct Hook *hook, Object *obj, struct gpRender *gpr)
{
/*
** Hook Function to refresh the Space Gadgets
*/

/* only if the Window is visible we can draw into it */
if(gb_Win)
{
/* determine the size of our Output Area */
struct IBox *gb_DrawArea;
IIntuition->GetAttr(SPACE_AreaBox,(Object*)gb_SpaceGad,(ULONG *)&gb_DrawArea);

/* empty the complete Area with Background Color */
IGraphics->SetAPen(gpr->gpr_RPort,0);
IGraphics->RectFill(gpr->gpr_RPort,gb_DrawArea->Left,gb_DrawArea->Top,
gb_DrawArea->Left+gb_DrawArea->Width-1,gb_DrawArea->Top+gb_DrawArea->Height-1);
}
}

/******************************************************************************/

void IDCMPHookFunc(struct Hook *hook, Object *winobj, struct IntuiMessage *msg)
{
/*
** Hook Function for listening to IDCMP_UPDATE Messages
*/

struct TagItem *taglist = (struct TagItem *) msg->IAddress;
const LONG gadid = IUtility->GetTagData(GA_ID,-1,taglist);

if(msg->Class == IDCMP_GADGETDOWN)
{
/* Press Mouse Button: Set start position without drawing */
IGraphics->SetAPen(gb_Win->RPort,4);
IGraphics->Move(gb_Win->RPort,msg->MouseX,msg->MouseY);
}

if(msg->Class == IDCMP_IDCMPUPDATE && gadid == GAD_ID_Space)
{
//ULONG mx, my;
//IIntuition->GetAttr(SPACE_MouseX,gb_SpaceGad,(ULONG*)&mx);
//IIntuition->GetAttr(SPACE_MouseY,gb_SpaceGad,(ULONG*)&my);

/* determine the size of our Output Area */
/* so we don't draw outside of this area */
struct IBox *gb_DrawArea;
IIntuition->GetAttr(SPACE_AreaBox,(Object*)gb_SpaceGad,(ULONG *)&gb_DrawArea);

const LONG mx = msg->MouseX;
const LONG my = msg->MouseY;

if(mx >= gb_DrawArea->Left &&
my >= gb_DrawArea->Top &&
mx <= gb_DrawArea->Left+gb_DrawArea->Width-1 &&
my <= gb_DrawArea->Top+gb_DrawArea->Height-1)
{
IGraphics->Draw(gb_Win->RPort,msg->MouseX,msg->MouseY);
}
}
}

/******************************************************************************/

BOOL CreateAll()
{
int i;

/* Screen Pointer is needed for single Gadgets */
gb_Scr = IIntuition->LockPubScreen(NULL);

if(gb_Scr)
{
/* request and set pens for the Gradient Slider */
struct ColorMap *cm = gb_Scr->ViewPort.ColorMap;

gb_GradientArray[0] = IGraphics->ObtainPen(cm,~0,0xFF,0xFF,0xFF,PENF_EXCLUSIVE);
gb_GradientArray[1] = IGraphics->ObtainPen(cm,~0,0xCC,0xCC,0xCC,PENF_EXCLUSIVE);
gb_GradientArray[2] = IGraphics->ObtainPen(cm,~0,0x99,0x99,0x99,PENF_EXCLUSIVE);
gb_GradientArray[3] = IGraphics->ObtainPen(cm,~0,0x66,0x66,0x66,PENF_EXCLUSIVE);
gb_GradientArray[4] = IGraphics->ObtainPen(cm,~0,0x33,0x33,0x33,PENF_EXCLUSIVE);
gb_GradientArray[5] = IGraphics->ObtainPen(cm,~0,0x00,0x00,0x00,PENF_EXCLUSIVE);

struct ViewPort *vp = &gb_Scr->ViewPort;

if((WORD)gb_GradientArray[0] != ~0) IGraphics->SetRGB4(vp,gb_GradientArray[0],0xFF,0xFF,0xFF);
if((WORD)gb_GradientArray[1] != ~0) IGraphics->SetRGB4(vp,gb_GradientArray[1],0xCC,0xCC,0xCC);
if((WORD)gb_GradientArray[2] != ~0) IGraphics->SetRGB4(vp,gb_GradientArray[2],0x99,0x99,0x99);
if((WORD)gb_GradientArray[3] != ~0) IGraphics->SetRGB4(vp,gb_GradientArray[3],0x66,0x66,0x66);
if((WORD)gb_GradientArray[4] != ~0) IGraphics->SetRGB4(vp,gb_GradientArray[4],0x33,0x33,0x33);
if((WORD)gb_GradientArray[5] != ~0) IGraphics->SetRGB4(vp,gb_GradientArray[5],0x00,0x00,0x00);
}

/* create Listbrowser entries */
IExec->NewList(&gb_List);
CreateEntry(0,"1","Amiga 1000");
CreateEntry(1,"2","Amiga 1200");
CreateEntry(2,"3","AmigaOne");

/* initialize RenderHook */
gb_RenderHook.h_Entry = (ULONG (*)())RenderHookFunc;
gb_RenderHook.h_SubEntry = NULL;

/* initialize IDCMPHook for listening to IDCMP_UPDATE Messages */
gb_IDCMPHook.h_Entry = (ULONG (*)())IDCMPHookFunc;
gb_IDCMPHook.h_SubEntry = NULL;

/* create Gadget Object */
gb_ButtonVGad = (struct Gadget *) IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
BUTTON_BevelStyle, BVS_THIN,
BUTTON_Justification, BCJ_LEFT,
GA_ID, GAD_ID_ButtonV,
GA_Text, "Info-Anzeige",
GA_ReadOnly, TRUE,
TAG_END);

gb_ButtonGad = (struct Gadget *) IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
GA_ID, GAD_ID_Button,
GA_Text, "Button",
TAG_END);

gb_StringGad = (struct Gadget *) IIntuition->NewObject(IString->STRING_GetClass(),NULL,
GA_ID, GAD_ID_String,
GA_RelVerify, TRUE,
GA_TabCycle, TRUE,
STRINGA_MaxChars, 30+1,
STRINGA_MinVisible, 30,
STRINGA_TextVal, "Amiga 1000",
TAG_END);

gb_IntegerGad = (struct Gadget *) IIntuition->NewObject(IInteger->INTEGER_GetClass(),NULL,
GA_ID, GAD_ID_Integer,
GA_RelVerify, TRUE,
GA_TabCycle, TRUE,
INTEGER_MaxChars, 4,
INTEGER_Arrows, TRUE,
INTEGER_MinVisible, 3,
INTEGER_Minimum, 1,
INTEGER_Maximum, 100,
TAG_END);

gb_SliderGad = (struct Gadget *) IIntuition->NewObject(ISlider->SLIDER_GetClass(),NULL,
GA_ID, GAD_ID_Slider,
GA_Immediate, TRUE,
GA_RelVerify, TRUE,
SLIDER_Min, 0,
SLIDER_Max, 100,
SLIDER_Level, 10,
SLIDER_Orientation, SLIDER_HORIZONTAL,
SLIDER_Ticks, 11,
SLIDER_KnobDelta, 50,
SLIDER_LevelFormat, "%3ld",
SLIDER_LevelMaxLen, 3+1,
SLIDER_LevelPlace, PLACETEXT_IN,
TAG_END);

gb_ScrollerGad = (struct Gadget *) IIntuition->NewObject(IScroller->SCROLLER_GetClass(),NULL,
GA_ID, GAD_ID_Scroller,
GA_Immediate, TRUE,
GA_RelVerify, TRUE,
SCROLLER_Top, 1,
SCROLLER_Visible, 5,
SCROLLER_Total, 105,
SCROLLER_Orientation, SCROLLER_HORIZONTAL,
SCROLLER_Arrows, TRUE,
SCROLLER_Stretch, TRUE,
SCROLLER_ArrowDelta, 10,
TAG_END);

gb_ChooserGad = (struct Gadget *) IIntuition->NewObject(IChooser->CHOOSER_GetClass(),NULL,
GA_ID, GAD_ID_Chooser,
GA_RelVerify, TRUE,
GA_Underscore, '#',
CHOOSER_PopUp, TRUE,
CHOOSER_DropDown, FALSE,
CHOOSER_LabelArray, gb_ChooserLabels,
CHOOSER_Selected, 0,
CHOOSER_MaxLabels, 10,
TAG_END);

gb_Chooser2Gad = (struct Gadget *) IIntuition->NewObject(IChooser->CHOOSER_GetClass(),NULL,
GA_ID, GAD_ID_Chooser2,
GA_RelVerify, TRUE,
GA_Underscore, '#',
CHOOSER_PopUp, FALSE,
CHOOSER_DropDown, TRUE,
CHOOSER_Title, "Eintrâ°ge",
CHOOSER_LabelArray, gb_Chooser2Labels,
CHOOSER_Selected, 0,
CHOOSER_MaxLabels, 10,
TAG_END);

gb_Chooser3Gad = (struct Gadget *) IIntuition->NewObject(IChooser->CHOOSER_GetClass(),NULL,
GA_ID, GAD_ID_Chooser3,
GA_RelVerify, TRUE,
GA_Underscore, '#',
CHOOSER_PopUp, FALSE,
CHOOSER_DropDown, TRUE,
CHOOSER_LabelArray, gb_Chooser3Labels,
CHOOSER_Selected, 0,
CHOOSER_MaxLabels, 10,
TAG_END);

gb_CheckboxGad = (struct Gadget *) IIntuition->NewObject(ICheckBox->CHECKBOX_GetClass(),NULL,
GA_ID, GAD_ID_Checkbox,
GA_Text, "Anwahl",
CHECKBOX_TextPlace, PLACETEXT_RIGHT,
CHECKBOX_Checked, TRUE,
TAG_END);

gb_RadioGad = (struct Gadget *) IIntuition->NewObject(IRadioButton->RADIOBUTTON_GetClass(),NULL,
GA_ID, GAD_ID_Radio,
GA_RelVerify, TRUE,
GA_Text, gb_RadioLabels,
//RADIOBUTTON_LabelArray, gb_RadioLabels,
RADIOBUTTON_Selected, 2,
RADIOBUTTON_LabelPlace, PLACETEXT_RIGHT,
RADIOBUTTON_Spacing, 4,
TAG_END);

gb_ListbrowserGad = (struct Gadget *) IIntuition->NewObject(IListBrowser->LISTBROWSER_GetClass(),NULL,
GA_ReadOnly, FALSE,
GA_ID, GAD_ID_Listbrowser,
GA_RelVerify, TRUE,
LISTBROWSER_ColumnInfo, &gb_ListbrowserColumn,
LISTBROWSER_ColumnTitles, TRUE,
LISTBROWSER_Labels, &gb_List,
LISTBROWSER_VertSeparators, TRUE,
LISTBROWSER_Spacing, 1,
LISTBROWSER_ShowSelected, TRUE,
LISTBROWSER_AutoFit, TRUE,
LISTBROWSER_Editable, FALSE,
LISTBROWSER_MinVisible, 2,
TAG_END);

gb_PaletteGad = (struct Gadget *) IIntuition->NewObject(IPalette->PALETTE_GetClass(),NULL,
GA_ReadOnly, FALSE,
GA_ID, GAD_ID_Palette,
GA_RelVerify, TRUE,
PALETTE_Colour, 1,
PALETTE_ColourOffset, 0,
PALETTE_NumColours, 8,
TAG_END);

gb_FileGad = (struct Gadget *) IIntuition->NewObject(IGetFile->GETFILE_GetClass(),NULL,
GA_ID, GAD_ID_File,
GA_RelVerify, TRUE,
GA_TabCycle, TRUE,
GETFILE_TitleText, ""Select File ...",
GETFILE_Pattern, "#?",
GETFILE_DoSaveMode, FALSE,
GETFILE_RejectIcons, TRUE,
GETFILE_ReadOnly, TRUE,
GETFILE_DrawersOnly, FALSE,
TAG_END);

gb_FontGad = (struct Gadget *) IIntuition->NewObject(IGetFont->GETFONT_GetClass(),NULL,
GA_ID, GAD_ID_Font,
GA_RelVerify, TRUE,
GETFONT_TitleText, "Select Font ...",
GETFONT_MinHeight, 6,
GETFONT_MaxHeight, 30,
TAG_END);

gb_ScreenmodeGad = (struct Gadget *) IIntuition->NewObject(IGetScreenMode->GETSCREENMODE_GetClass(),NULL,
GA_ID, GAD_ID_Screenmode,
GA_RelVerify, TRUE,
GETSCREENMODE_TitleText, "Select Screen Mode ...",
GETSCREENMODE_MinDepth, 2,
GETSCREENMODE_MaxDepth, 8,
TAG_END);

gb_ColorGad = (struct Gadget *) IIntuition->NewObject(IGetColor->GETCOLOR_GetClass(),NULL,
GA_ID, GAD_ID_Color,
GA_RelVerify, TRUE,
GETCOLOR_TitleText, "Choose Color ...",
GETCOLOR_Screen, gb_Scr,
GETCOLOR_Color, 0x00aaccee,
GETCOLOR_ColorWheel, TRUE,
GETCOLOR_RGBSliders, TRUE,
GETCOLOR_ShowRGB, TRUE,
TAG_END);

gb_FuelgaugeGad = (struct Gadget *) IIntuition->NewObject(IFuelGauge->FUELGAUGE_GetClass(),NULL,
GA_ReadOnly, FALSE,
GA_ID, GAD_ID_Fuelgauge,
GA_RelVerify, TRUE,
FUELGAUGE_Min, 0,
FUELGAUGE_Max, 100,
FUELGAUGE_Level, 10,
FUELGAUGE_Orientation, FGORIENT_HORIZ,
FUELGAUGE_Percent, TRUE,
FUELGAUGE_Ticks, 10,
FUELGAUGE_ShortTicks, 10,
FUELGAUGE_Justification, FGJ_CENTER,
TAG_END);

gb_GradientsliderGad = (struct Gadget *) IIntuition->NewObject(NULL,"gradientslider.gadget",
GA_ID, GAD_ID_Gradientslider,
GA_RelVerify, TRUE,
GA_TabCycle, TRUE,
GRAD_PenArray, gb_GradientArray,
PGA_Freedom, LORIENT_VERT,
TAG_END);

/* set Color Wheel to this RGB value */
struct ColorWheelRGB rgbval = { 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF };

gb_ColorwheelGad = (struct Gadget *) IIntuition->NewObject(NULL,"colorwheel.gadget",
GA_ID, GAD_ID_Colorwheel,
GA_RelVerify, TRUE,
GA_TabCycle, TRUE,
WHEEL_Screen, gb_Scr,
//WHEEL_GradientSlider, gb_GradientsliderGad,
WHEEL_BevelBox, FALSE,
WHEEL_RGB, rgbval,
TAG_END);

gb_TexteditorGad = (struct Gadget *) IIntuition->NewObject(ITextEditor->TEXTEDITOR_GetClass(),NULL,
GA_ID, GAD_ID_Texteditor,
GA_RelVerify, TRUE,
GA_TabCycle, TRUE,
GA_TEXTEDITOR_FixedFont, FALSE,
TAG_END);

gb_DatebrowserGad = (struct Gadget *) IIntuition->NewObject(IDateBrowser->DATEBROWSER_GetClass(),NULL,
GA_ID, GAD_ID_Datebrowser,
GA_RelVerify, TRUE,
GA_TabCycle, TRUE,
DATEBROWSER_Day, 27,
DATEBROWSER_Month, 10,
DATEBROWSER_Year, 2007,
DATEBROWSER_ShowTitle, TRUE,
DATEBROWSER_ShowWeek, TRUE,
DATEBROWSER_MultiSelect, FALSE,
TAG_END);

gb_SpaceGad = (struct Gadget *) IIntuition->NewObject(ISpace->SPACE_GetClass(),NULL,
GA_ID, GAD_ID_Space,
GA_RelVerify, TRUE, /* send Gadget Up */
GA_Immediate, TRUE, /* send Gadget Down */
GA_ReadOnly, FALSE,
SPACE_Transparent, TRUE, /* Background not deleted automatically */
SPACE_MinWidth, 10,
SPACE_MinHeight, 10,
SPACE_BevelStyle, BVS_DROPBOX,
SPACE_RenderHook, &gb_RenderHook,
ICA_TARGET, ICTARGET_IDCMP, /* send a Message to the Program */
TAG_END);

gb_PageGad = (struct Gadget *) IIntuition->NewObject(ILayout->PAGE_GetClass(),NULL,
GA_ID, GAD_ID_Page,
LAYOUT_Orientation, LAYOUT_VERTICAL,
LAYOUT_FixedHoriz, FALSE,
LAYOUT_FixedVert, FALSE,
LAYOUT_SpaceInner, TRUE,

PAGE_Add, IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_AddChild, IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
BUTTON_BevelStyle, BVS_NONE, BUTTON_Transparent, TRUE, GA_Text, "Amiga 1000", GA_ReadOnly, TRUE, TAG_END),
TAG_END),
PAGE_Add, IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_AddChild, IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
BUTTON_BevelStyle, BVS_NONE, BUTTON_Transparent, TRUE, GA_Text, "Amiga 1200", GA_ReadOnly, TRUE, TAG_END),
TAG_END),
PAGE_Add, IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_AddChild, IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
BUTTON_BevelStyle, BVS_NONE, BUTTON_Transparent, TRUE, GA_Text, "AmigaOne", GA_ReadOnly, TRUE, TAG_END),
TAG_END),
TAG_END);

gb_ClicktabGad = (struct Gadget *) IIntuition->NewObject(IClickTab->CLICKTAB_GetClass(),NULL,
GA_ID, GAD_ID_Clicktab,
GA_Text, &gb_ClicktabLabels,
GA_RelVerify, TRUE,
CLICKTAB_PageGroup, gb_PageGad,
TAG_END);

gb_LabelImg = (struct Image *) IIntuition->NewObject(ILabel->LABEL_GetClass(),NULL,
LABEL_Text, "Beschriftung",
//LABEL_SoftStyle, FSF_BOLD,
//LABEL_Justification, LJ_LEFT,
TAG_END);

gb_BevelImg = (struct Image *) IIntuition->NewObject(IBevel->BEVEL_GetClass(),NULL,
BEVEL_Style, BVS_BOX,
TAG_END);

gb_BitmapImg = (struct Image *) IIntuition->NewObject(IBitMap->BITMAP_GetClass(),NULL,
BITMAP_Screen, gb_Scr,
BITMAP_Masking, FALSE,
BITMAP_SourceFile, "amiga1000-normal.iff",
BITMAP_SelectSourceFile, "amiga1000-selected.iff",
BITMAP_DisabledSourceFile, "amiga1000-disabled.iff",
IA_SupportsDisable, TRUE,
TAG_END);

gb_BitmapSImg = (struct Image *) IIntuition->NewObject(IBitMap->BITMAP_GetClass(),NULL,
BITMAP_Screen, gb_Scr,
BITMAP_Masking, FALSE,
BITMAP_SourceFile, "amiga1000-selected.iff",
IA_SupportsDisable, TRUE,
TAG_END);

gb_BitmapDImg = (struct Image *) IIntuition->NewObject(IBitMap->BITMAP_GetClass(),NULL,
BITMAP_Screen, gb_Scr,
BITMAP_Masking, FALSE,
BITMAP_SourceFile, "amiga1000-disabled.iff",
TAG_END);

gb_DrawlistImg = (struct Image *) IIntuition->NewObject(IDrawList->DRAWLIST_GetClass(),NULL,
DRAWLIST_Directives, gb_DrawList,
TAG_END);

gb_FillerImg = (struct Image *) IIntuition->NewObject(IFiller->FILLER_GetClass(),NULL,
FILLER_Screen, gb_Scr,
FILLER_BackgroundColor, 0xffaaaaaa,
FILLER_ImageFilename, "amigaball.iff",
FILLER_ImageMode, FILLER_MODE_TILED,
IA_Width, 30,
IA_Height, 30,
TAG_END);

gb_PenmapImg = (struct Image *) IIntuition->NewObject(IPenMap->PENMAP_GetClass(),NULL,
PENMAP_RenderData, happy_data,
PENMAP_Palette, image_object_palette,
PENMAP_Screen, gb_Scr,
PENMAP_Transparent, TRUE,
TAG_END);

for(i=1; i<=26; i++)
{
/* 13-17 and 19 do not exist */
gb_GlyphImg[i] = (struct Image *) IIntuition->NewObject(IGlyph->GLYPH_GetClass(),NULL,
GLYPH_Glyph, i, /*GLYPH_xxx */
IA_Width, 20,
IA_Height, 20,
TAG_END);
}

/* create the single pages of the Drag Bar */
gb_Page1Layout = (struct Gadget *) IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,
LAYOUT_BevelStyle, BVS_GROUP,
LAYOUT_Label, "Grundtypen",
LAYOUT_LabelPlace, BVJ_TOP_CENTER,

LAYOUT_AddChild, gb_ButtonVGad,
CHILD_WeightedHeight, 80,
LAYOUT_AddChild, gb_ButtonGad,
CHILD_WeightedHeight, 10,
LAYOUT_AddChild, gb_StringGad,
LAYOUT_AddChild, gb_IntegerGad,
LAYOUT_AddChild, gb_SliderGad,
CHILD_WeightedHeight, 10,
LAYOUT_AddChild, gb_ScrollerGad,
TAG_END);

gb_Page2Layout = (struct Gadget *) IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,
LAYOUT_BevelStyle, BVS_GROUP,
LAYOUT_Label, "Auswahllisten",
LAYOUT_LabelPlace, BVJ_TOP_CENTER,

LAYOUT_AddChild, IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_HORIZ,
LAYOUT_AddChild, gb_ChooserGad,
LAYOUT_AddChild, gb_Chooser2Gad,
LAYOUT_AddChild, gb_Chooser3Gad,
TAG_END),
CHILD_WeightedHeight, 0,

LAYOUT_AddChild, gb_CheckboxGad,
CHILD_WeightedHeight, 0,
LAYOUT_AddChild, gb_RadioGad,
CHILD_WeightedHeight, 0,
LAYOUT_AddChild, gb_ListbrowserGad,
CHILD_WeightedHeight, 90,
LAYOUT_AddChild, gb_PaletteGad,
CHILD_WeightedHeight, 10,
TAG_END);

gb_Page3Layout = (struct Gadget *) IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,
LAYOUT_BevelStyle, BVS_GROUP,
LAYOUT_Label, "ASL-Auswahl",
LAYOUT_LabelPlace, BVJ_TOP_CENTER,

LAYOUT_AddChild, gb_FileGad,
CHILD_WeightedHeight, 0,
LAYOUT_AddChild, gb_FontGad,
CHILD_WeightedHeight, 0,
LAYOUT_AddChild, gb_ScreenmodeGad,
CHILD_WeightedHeight, 0,
LAYOUT_AddChild, gb_ColorGad,
CHILD_WeightedHeight, 0,
TAG_END);

gb_Page4Layout = (struct Gadget *) IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,
LAYOUT_BevelStyle, BVS_GROUP,
LAYOUT_Label, "Sonstige Typen",
LAYOUT_LabelPlace, BVJ_TOP_CENTER,

LAYOUT_AddChild, gb_FuelgaugeGad,
CHILD_WeightedHeight, 10,

LAYOUT_AddChild, IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_HORIZ,
LAYOUT_AddChild, gb_ColorwheelGad,
//CHILD_WeightedWidth, 0,
//CHILD_WeightedHeight, 0,
LAYOUT_AddChild, gb_GradientsliderGad,
LAYOUT_AddChild, IIntuition->NewObject(ISpace->SPACE_GetClass(),NULL,
SPACE_Transparent, FALSE,
SPACE_MinWidth, 10,
SPACE_MinHeight, 10,
TAG_END),
TAG_END),
CHILD_WeightedHeight, 70,

LAYOUT_AddChild, gb_TexteditorGad,
CHILD_WeightedHeight, 10,
LAYOUT_AddChild, gb_DatebrowserGad,
CHILD_WeightedHeight, 10,
TAG_END);

gb_Page5Layout = (struct Gadget *) IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,
LAYOUT_BevelStyle, BVS_GROUP,
LAYOUT_Label, "Seitengestalltung",
LAYOUT_LabelPlace, BVJ_TOP_CENTER,

LAYOUT_AddChild, gb_SpaceGad,
LAYOUT_AddChild, gb_ClicktabGad,
TAG_END);

gb_Page6Layout = (struct Gadget *) IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,
LAYOUT_BevelStyle, BVS_GROUP,
LAYOUT_Label, "Images",
LAYOUT_LabelPlace, BVJ_TOP_CENTER,

LAYOUT_AddImage, gb_LabelImg,

LAYOUT_AddImage, gb_BevelImg,
CHILD_MinHeight, 10,

LAYOUT_AddChild, IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_HORIZ,
LAYOUT_AddImage, gb_BitmapImg,
LAYOUT_AddImage, gb_BitmapSImg,
LAYOUT_AddImage, gb_BitmapDImg,
TAG_END),
CHILD_WeightedHeight, 0,

LAYOUT_AddImage, gb_DrawlistImg,
CHILD_MinWidth, 30,
CHILD_MinHeight, 30,
CHILD_WeightedWidth, 0,
CHILD_WeightedHeight, 0,

LAYOUT_AddImage, gb_FillerImg,
CHILD_MinWidth, 30,
CHILD_MinHeight, 30,
CHILD_MaxWidth, 200,
CHILD_MaxHeight, 60,

LAYOUT_AddImage, gb_PenmapImg,
CHILD_WeightedWidth, 0,
CHILD_WeightedHeight, 0,

LAYOUT_AddChild, IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_HORIZ,

LAYOUT_AddImage, gb_GlyphImg[ 1],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[ 2],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[ 3],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[ 4],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[ 5],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[ 6],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[ 7],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[ 8],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[ 9],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[10],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[11],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[12],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[18],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[20],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[21],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[22],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[23],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[24],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[25],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[26],
CHILD_MinWidth, 20,
TAG_END),
CHILD_MinHeight, 20,
CHILD_WeightedHeight, 10,

TAG_END);

gb_PagesLayout = (struct Gadget *) IIntuition->NewObject(ILayout->PAGE_GetClass(),NULL,
GA_ID, GAD_ID_Pages,
LAYOUT_Orientation, LAYOUT_VERTICAL,
LAYOUT_FixedHoriz, FALSE,
LAYOUT_FixedVert, FALSE,
LAYOUT_SpaceInner, TRUE,

PAGE_Add, gb_Page1Layout,
PAGE_Add, gb_Page2Layout,
PAGE_Add, gb_Page3Layout,
PAGE_Add, gb_Page4Layout,
PAGE_Add, gb_Page5Layout,
PAGE_Add, gb_Page6Layout,

TAG_END);

gb_PagesClicktab = (struct Gadget *) IIntuition->NewObject(IClickTab->CLICKTAB_GetClass(),NULL,
GA_ID, GAD_ID_PagesClicktab,
GA_Text, &gb_PagesLabels,
CLICKTAB_PageGroup, gb_PagesLayout,
TAG_END);

IIntuition->UnlockPubScreen(NULL,gb_Scr);

/* create Layout Object */
gb_MainLayout = (struct Gadget *) IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,

LAYOUT_AddChild, gb_PagesClicktab,

TAG_END);

if(gb_MainLayout)
{

/* create the Window Object */
if((gb_WindowObj = (Object *) IIntuition->NewObject(IWindow->WINDOW_GetClass(),NULL,
WA_IDCMP, IDCMP_GADGETUP | IDCMP_GADGETDOWN |
IDCMP_MOUSEMOVE |
IDCMP_VANILLAKEY | IDCMP_RAWKEY |
IDCMP_CLOSEWINDOW,
WA_SizeGadget, TRUE,
WA_DepthGadget, TRUE,
WA_DragBar, TRUE,
WA_Activate, TRUE,
WA_Title, "All ReAction Gadgets",
WA_InnerWidth, 100,
WA_InnerHeight, 100,
WA_AutoAdjust, TRUE,
WA_CloseGadget, TRUE,
WA_RMBTrap, TRUE,
WINDOW_ParentGroup, gb_MainLayout,
WINDOW_IDCMPHook, &gb_IDCMPHook,
WINDOW_IDCMPHookBits, IDCMP_IDCMPUPDATE | IDCMP_GADGETDOWN,
TAG_END)))
{
/* everything created correctly */

/* the Window can be shown now */
gb_Win = RA_OpenWindow(gb_WindowObj);
}
}

return gb_WindowObj ? TRUE : FALSE;
}

/******************************************************************************/

void DestroyAll()
{
/* close Window and release included Objects */
RA_CloseWindow(gb_WindowObj);
IIntuition->DisposeObject(gb_WindowObj);

/* release Listview entries */
FreigebenList();

/* release the reserved pens */
struct ColorMap *cm = (gb_Scr ? gb_Scr->ViewPort.ColorMap : NULL);

if((WORD)gb_GradientArray[0] != ~0) IGraphics->ReleasePen(cm,gb_GradientArray[0]);
if((WORD)gb_GradientArray[1] != ~0) IGraphics->ReleasePen(cm,gb_GradientArray[1]);
if((WORD)gb_GradientArray[2] != ~0) IGraphics->ReleasePen(cm,gb_GradientArray[2]);
if((WORD)gb_GradientArray[3] != ~0) IGraphics->ReleasePen(cm,gb_GradientArray[3]);
if((WORD)gb_GradientArray[4] != ~0) IGraphics->ReleasePen(cm,gb_GradientArray[4]);
if((WORD)gb_GradientArray[5] != ~0) IGraphics->ReleasePen(cm,gb_GradientArray[5]);
}

/******************************************************************************/

void MsgLoop()
{
ULONG winsig;
ULONG result, code;
BOOL laufen = TRUE;

/* save Signal Bits of the Window */
IIntuition->GetAttr(WINDOW_SigMask,gb_WindowObj,&winsig);

while(laufen)
{
/* wait for user actions */
const ULONG sigs = IExec->Wait(winsig | SIGBREAKF_CTRL_C);

/* process the received Messages */
while((result = RA_HandleInput(gb_WindowObj,&code)) != WMHI_LASTMSG)
{
/* mask out the Messages part */
switch(result & WMHI_CLASSMASK)
{
/* process Gadget Messages */
case WMHI_GADGETUP:
switch(result & WMHI_GADGETMASK)
{
case GAD_ID_ButtonV:
{
}
break;

case GAD_ID_Button:
{
IDOS->Printf("Button: [released]\n");
}
break;

case GAD_ID_String:
{
STRPTR val;
IIntuition->GetAttr(STRINGA_TextVal,(Object*)gb_StringGad,(ULONG*)&val);
IDOS->Printf("String: [%s]\n",val);
}
break;

case GAD_ID_Integer:
{
ULONG val;
IIntuition->GetAttr(INTEGER_Number,(Object*)gb_IntegerGad,(ULONG*)&val);
IDOS->Printf("Integer: [%ld]\n",val);
}
break;

case GAD_ID_Slider:
{
ULONG val;
IIntuition->GetAttr(SLIDER_Level,(Object*)gb_SliderGad,(ULONG*)&val);
IDOS->Printf("Slieder: [%ld]\n",val);
}
break;

case GAD_ID_Scroller:
{
ULONG val;
IIntuition->GetAttr(SCROLLER_Top,(Object*)gb_ScrollerGad,(ULONG*)&val);
IDOS->Printf("Scroller: [%ld]\n",val);
}
break;

case GAD_ID_Chooser:
{
ULONG val;
IIntuition->GetAttr(CHOOSER_Selected,(Object*)gb_ChooserGad,(ULONG*)&val);
IDOS->Printf("Chooser: [%ld]\n",val);
}
break;

case GAD_ID_Chooser2:
{
ULONG val;
IIntuition->GetAttr(CHOOSER_Selected,(Object*)gb_Chooser2Gad,(ULONG*)&val);
IDOS->Printf("Chooser2: [%ld]\n",val);
}
break;

case GAD_ID_Chooser3:
{
ULONG val;
IIntuition->GetAttr(CHOOSER_Selected,(Object*)gb_Chooser3Gad,(ULONG*)&val);
IDOS->Printf("Chooser3: [%ld]\n",val);
}
break;

case GAD_ID_Checkbox:
{
ULONG val;
IIntuition->GetAttr(GA_Selected,(Object*)gb_CheckboxGad,(ULONG*)&val);
IDOS->Printf("Checkbox: [%s]\n",(val ? "selectet" : "not selected"));
}
break;

case GAD_ID_Radio:
{
ULONG val;
IIntuition->GetAttr(RADIOBUTTON_Selected,(Object*)gb_RadioGad,(ULONG*)&val);
IDOS->Printf("Radio: [%ld]\n",val);
}
break;

case GAD_ID_Listbrowser:
{
//ULONG action, column;
struct Node *node;
//IIntuition->GetAttr(LISTBROWSER_RelEvent,(Object*)gb_WordlistGad,(ULONG*)&action);
//IIntuition->GetAttr(LISTBROWSER_RelColumn,(Object*)gb_WordlistGad,(ULONG*)&column);
IIntuition->GetAttr(LISTBROWSER_SelectedNode,(Object*)gb_ListbrowserGad,(ULONG*)&node);
//struct UserDictEntry *ude = LBNode2UserDictNode(node);
IDOS->Printf("Listview: [%ld]\n",node->ln_Pri);
}
break;

case GAD_ID_Palette:
{
ULONG val;
IIntuition->GetAttr(PALETTE_Colour,(Object*)gb_PaletteGad,(ULONG*)&val);
IDOS->Printf("Palette: [%ld]\n",val);
}
break;

case GAD_ID_File:
{
STRPTR val;
ULONG res = gfRequestFile((Object *)gb_FileGad,gb_Win);
IIntuition->GetAttr(GETFILE_FullFile,(Object*)gb_FileGad,(ULONG*)&val);
if(res) IDOS->Printf("File: [%s]\n",val);
}
break;

case GAD_ID_Font:
{
struct TextAttr *val;
ULONG res = gfRequestFont((Object *)gb_FontGad,gb_Win);
IIntuition->GetAttr(GETFONT_TextAttr,(Object*)gb_FontGad,(ULONG*)&val);
if(res) IDOS->Printf("Font: [%s %ld]\n",val->ta_Name,val->ta_YSize);
}
break;

case GAD_ID_Screenmode:
{
ULONG id, width, height, depth;
ULONG res = RequestScreenMode((Object *)gb_ScreenmodeGad,gb_Win);
IIntuition->GetAttr(GETSCREENMODE_DisplayID,(Object*)gb_ScreenmodeGad,(ULONG*)&id);
IIntuition->GetAttr(GETSCREENMODE_DisplayWidth,(Object*)gb_ScreenmodeGad,(ULONG*)&width);
IIntuition->GetAttr(GETSCREENMODE_DisplayHeight,(Object*)gb_ScreenmodeGad,(ULONG*)&height);
IIntuition->GetAttr(GETSCREENMODE_DisplayDepth,(Object*)gb_ScreenmodeGad,(ULONG*)&depth);
if(res) IDOS->Printf("Screenmode: [$%lx %ld x %ld x %ld]\n",id,width,height,depth);
}
break;

case GAD_ID_Color:
{
ULONG val;
ULONG res = RequestColor((Object *)gb_ColorGad,gb_Win);
IIntuition->GetAttr(GETCOLOR_Color,(Object*)gb_ColorGad,(ULONG*)&val);
if(res) IDOS->Printf("Color: [$%08lx]\n",val);
}
break;

case GAD_ID_Fuelgauge:
{
ULONG val;
IIntuition->GetAttr(FUELGAUGE_Level,(Object*)gb_FuelgaugeGad,(ULONG*)&val);
IDOS->Printf("Fuelgauge: [%ld]\n",val);
}
break;

case GAD_ID_Colorwheel:
{
struct ColorWheelRGB val;
IIntuition->GetAttr(WHEEL_RGB,(Object*)gb_ColorwheelGad,(ULONG*)&val);
IDOS->Printf("Colorwheel: [red=%08lx green=%08lx blue=%08lx]\n",val.cw_Red,val.cw_Green,val.cw_Blue);

/* reset the Gradient Slider depending on the new color selection */
struct ViewPort *vp = &gb_Scr->ViewPort;

if((WORD)gb_GradientArray[0] != ~0)
IGraphics->SetRGB32(vp,gb_GradientArray[0],val.cw_Red,val.cw_Green,val.cw_Blue);
if((WORD)gb_GradientArray[1] != ~0)
IGraphics->SetRGB32(vp,gb_GradientArray[1],val.cw_Red/15*12,val.cw_Green/15*12,val.cw_Blue/15*12);
if((WORD)gb_GradientArray[2] != ~0)
IGraphics->SetRGB32(vp,gb_GradientArray[2],val.cw_Red/15*9,val.cw_Green/15*9,val.cw_Blue/15*9);
if((WORD)gb_GradientArray[3] != ~0)
IGraphics->SetRGB32(vp,gb_GradientArray[3],val.cw_Red/15*6,val.cw_Green/15*6,val.cw_Blue/15*6);
if((WORD)gb_GradientArray[4] != ~0)
IGraphics->SetRGB32(vp,gb_GradientArray[4],val.cw_Red/15*3,val.cw_Green/15*3,val.cw_Blue/15*3);
IIntuition->RefreshGadgets(gb_GradientsliderGad,gb_Win,NULL);
}
break;

case GAD_ID_Gradientslider:
{
ULONG val;
IIntuition->GetAttr(GRAD_CurVal,(Object*)gb_GradientsliderGad,(ULONG*)&val);
IDOS->Printf("Gradientslieder: [%ld]\n",val);
}
break;

case GAD_ID_Texteditor:
{
STRPTR val;
val = (STRPTR) IIntuition->DoGadgetMethod(gb_TexteditorGad,gb_Win,NULL,GM_TEXTEDITOR_ExportText,NULL);
if(val) IDOS->Printf("Texteditor: [%s]\n",val);
}
break;

case GAD_ID_Datebrowser:
{
ULONG day, month, year;
IIntuition->GetAttr(DATEBROWSER_Day,(Object*)gb_DatebrowserGad,(ULONG*)&day);
IIntuition->GetAttr(DATEBROWSER_Month,(Object*)gb_DatebrowserGad,(ULONG*)&month);
IIntuition->GetAttr(DATEBROWSER_Year,(Object*)gb_DatebrowserGad,(ULONG*)&year);
IDOS->Printf("Datebrowser: [%ld.%ld.%ld]\n",day,month,year);
}
break;

case GAD_ID_Space:
{
// ULONG mx, my;
// IIntuition->GetAttr(SPACE_MouseX,(Object*)gb_SpaceGad,(ULONG*)&mx);
// IIntuition->GetAttr(SPACE_MouseY,(Object*)gb_SpaceGad,(ULONG*)&my);
// IDOS->Printf("Space: [%ld : %ld]\n",mx,my);
}
break;

case GAD_ID_Page:
{
ULONG val;
IIntuition->GetAttr(PAGE_Current,(Object*)gb_PageGad,(ULONG*)&val);
IDOS->Printf("Page: [%ld]\n",val);
}
break;

case GAD_ID_Clicktab:
{
ULONG val;
IIntuition->GetAttr(CLICKTAB_Current,(Object*)gb_ClicktabGad,(ULONG*)&val);
IDOS->Printf("Clicktab: [%ld]\n",val);
}
break;

}
break;

/* RawKey of pressed key */
case WMHI_RAWKEY:
{
//struct InputEvent *ie;
//IIntuition->GetAttr(WINDOW_InputEvent,gb_WindowObj,(ULONG *)&ie);
// code = result & WMHI_KEYMASK
// qualifier = ie->ie_Qualifier
}
break;

/* ASCII code of pressed key */
case WMHI_MENUPICK:
switch(result & WMHI_MENUMASK)
{
//case MENU_ID_xxx:
// break;
}
break;

/* Window Close Icon clicked */
case WMHI_CLOSEWINDOW:
{
/* Window Close Icon executed */
laufen = FALSE;
}
break;
}
}

/* CTRL-C typed into the Shell or received as signal */
if(sigs & SIGBREAKF_CTRL_C) laufen = FALSE;
}
}

/******************************************************************************/

int main(int argc, char *argv[])
{

if( CreateAll() )
{
MsgLoop();

DestroyAll();
}
else IDOS->Printf("Createing GUI failed !\n");

return 0;
}
</syntaxhighlight>

Here are the support graphics files to go with it: [[Media:allgadgets-gfx.lha|allgadgets-gfx.lha]]

[[File:AF110_allgadgets.png|frame|center]]

Reactor's approach, which you could use to 'click together' graphically a GUI under the Workbench 3.5 and 3.9, hasn't been developed any further. However, as shown in the previous example, you can basically copy the required GUI elements in your own sources with copy & paste.

= ClickTab-Test Example =

Another bonus is "ClickTab-Test" which deals exclusively with the Clicktab gadget. As I already mentioned, you can use it to create tabs. The tabs can in the meantime be dynamically added and deleted again. Moreover, you can use both tags, so all tags have the same width and the tab labeling is not shortened.

<syntaxhighlight lang="C" line>
/* Michael Christoph
* ClickTab-Test.c
*
* gcc ClickTab-Test.c -o ClickTab-Test -l auto
*/

/******************************* INCLUDES *************************************/

#include <exec/types.h>
#include <intuition/gadgetclass.h>
#include <classes/window.h>
#include <classes/requester.h>
#include <reaction/reaction_macros.h>
#include <libraries/gadtools.h>
#include <gadgets/button.h>
#include <gadgets/checkbox.h>
#include <gadgets/string.h>
#include <gadgets/clicktab.h>
#include <gadgets/layout.h>
#include <gadgets/page.h>
#include <images/label.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/utility.h>
#include <proto/window.h>
#include <proto/layout.h>
#include <proto/button.h>
#include <proto/label.h>
#include <proto/string.h>
#include <proto/clicktab.h>
#include <proto/checkbox.h>
#include <proto/label.h>

/******************************************************************************/

static const char *version USED = "\0$VER: ClickTab-Test 1.0 (13.02.2009) - (c) Feb.2009 by Meicky-Soft\n";

/******************************************************************************/

enum GADID
{
GAD_ID_Name = 1,
GAD_ID_Add,
GAD_ID_Del,

GAD_ID_Evensize,
GAD_ID_Labeltruncate,

GAD_ID_Clicktab,
};

struct Gadget *gb_NameGad;
struct Gadget *gb_AddGad;
struct Gadget *gb_DelGad;
struct Gadget *gb_EvensizeGad;
struct Gadget *gb_LabeltruncateGad;
struct Gadget *gb_ClicktabGad;
struct Gadget *gb_MainLayout;

#define MAX_CLICKTABS 15
STRPTR gb_ClicktabLabels[MAX_CLICKTABS + 1] = { NULL };

Object *gb_WindowObj;
struct Window *gb_Win;
struct Screen *gb_Scr;

/******************************************************************************/

BOOL CreateGUI()
{
if((gb_ClicktabLabels[0] = (STRPTR) IExec->AllocVecTags(31, AVT_Type, MEMF_SHARED, TAG_END)))
{
IUtility->Strlcpy(gb_ClicktabLabels[0], "_Muster", 30);
}

gb_NameGad = (struct Gadget *) IIntuition->NewObject(IString->STRING_GetClass(),NULL,
GA_ID, GAD_ID_Name,
GA_RelVerify, TRUE,
GA_TabCycle, TRUE,
STRINGA_MaxChars, 30+1,
STRINGA_MinVisible, 30,
TAG_END);

gb_AddGad = (struct Gadget *) IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
GA_ID, GAD_ID_Add,
GA_RelVerify, TRUE,
GA_Text, "_Add",
TAG_END);

gb_DelGad = (struct Gadget *) IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
GA_ID, GAD_ID_Del,
GA_RelVerify, TRUE,
GA_Text, "_Del",
TAG_END);

gb_EvensizeGad = (struct Gadget *) IIntuition->NewObject(ICheckBox->CHECKBOX_GetClass(),NULL,
GA_ID, GAD_ID_Evensize,
GA_Text, "EvenSize",
GA_RelVerify, TRUE,
CHECKBOX_TextPlace, PLACETEXT_RIGHT,
CHECKBOX_Checked, FALSE,
TAG_END);

gb_LabeltruncateGad = (struct Gadget *) IIntuition->NewObject(ICheckBox->CHECKBOX_GetClass(),NULL,
GA_ID, GAD_ID_Labeltruncate,
GA_Text, "LabelTruncate",
GA_RelVerify, TRUE,
CHECKBOX_TextPlace, PLACETEXT_RIGHT,
CHECKBOX_Checked, TRUE,
TAG_END);

gb_ClicktabGad = (struct Gadget *) IIntuition->NewObject(IClickTab->CLICKTAB_GetClass(),NULL,
GA_ID, GAD_ID_Clicktab,
GA_Text, &gb_ClicktabLabels,
GA_RelVerify, TRUE,
CLICKTAB_EvenSize, FALSE,
CLICKTAB_LabelTruncate, TRUE,
//CLICKTAB_PageGroup, gb_PagesLayout,
TAG_END);

gb_MainLayout = (struct Gadget *) IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_VERTICAL,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,

LAYOUT_AddChild, gb_NameGad,
LAYOUT_AddChild, gb_AddGad,
LAYOUT_AddChild, gb_DelGad,
LAYOUT_AddChild, gb_EvensizeGad,
LAYOUT_AddChild, gb_LabeltruncateGad,
LAYOUT_AddChild, gb_ClicktabGad,

TAG_END);

if(gb_MainLayout)
{

/* Create the window object */
if((gb_WindowObj = (Object *) IIntuition->NewObject(IWindow->WINDOW_GetClass(),NULL,
WA_IDCMP, IDCMP_GADGETUP |
IDCMP_VANILLAKEY |
IDCMP_CLOSEWINDOW,
WA_SizeGadget, TRUE,
WA_DepthGadget, TRUE,
WA_DragBar, TRUE,
WA_Activate, TRUE,
WA_Title, "Variable Number of Tabs",
WA_InnerWidth, 150,
WA_InnerHeight, 100,
WA_AutoAdjust, TRUE,
WA_CloseGadget, TRUE,
WINDOW_ParentGroup, gb_MainLayout,
TAG_END)))
{
/* Everything created successfully */

/* The window can be opened now */
gb_Win = RA_OpenWindow(gb_WindowObj);
}
}

return ( gb_Win ? TRUE : FALSE );
}

/******************************************************************************/

void FreeGUI()
{
RA_CloseWindow(gb_WindowObj);
IIntuition->DisposeObject(gb_WindowObj);

ULONG i;
for(i=0; i<MAX_CLICKTABS; i++)
{
if(gb_ClicktabLabels[i]) IExec->FreeVec(gb_ClicktabLabels[i]);
}
}

/******************************************************************************/

void MsgLoop()
{
ULONG winsig;
ULONG result, code;
BOOL running = TRUE;

/* Get the window signal bit mask */
IIntuition->GetAttr(WINDOW_SigMask, gb_WindowObj, &winsig);

while(running)
{
/* Wait for user actions */
const ULONG sigs = IExec->Wait(winsig | SIGBREAKF_CTRL_C);

/* Process all messages */
while((result = RA_HandleInput(gb_WindowObj, &code)) != WMHI_LASTMSG)
{
/* Mask out the message class ! */
switch(result & WMHI_CLASSMASK)
{
/* Handle gadget message */
case WMHI_GADGETUP:
switch(result & WMHI_GADGETMASK)
{
case GAD_ID_Name:
{
/* Update caption */
ULONG val;
IIntuition->GetAttr(CLICKTAB_Current,(Object*)gb_ClicktabGad,(ULONG*)&val);
STRPTR name;
IIntuition->GetAttr(STRINGA_TextVal,(Object*)gb_NameGad,(ULONG*)&name);
IUtility->Strlcpy(gb_ClicktabLabels[val],name,30);
IDOS->Printf("Update CT [%ld] <%s>\n",val,name);
IIntuition->RefreshSetGadgetAttrs(gb_ClicktabGad,gb_Win,NULL, GA_Text,gb_ClicktabLabels, TAG_END);
}
break;

case GAD_ID_Add:
{
/* Add a new tab */
ULONG max;
IIntuition->GetAttr(CLICKTAB_Total,(Object*)gb_ClicktabGad,(ULONG*)&max);
if(max < MAX_CLICKTABS-1)
{
STRPTR name;
IIntuition->GetAttr(STRINGA_TextVal,(Object*)gb_NameGad,(ULONG*)&name);
if(name[0])
{
IDOS->Printf("Add CT [%ld] <%s>\n",max,name);
if((gb_ClicktabLabels[max] = (STRPTR) IExec->AllocVecTags(31,AVT_Type,MEMF_SHARED,TAG_END)))
{
IUtility->Strlcpy(gb_ClicktabLabels[max],name,30);
}
else IDOS->Printf("out of memory\n");
IIntuition->RefreshSetGadgetAttrs(gb_ClicktabGad,gb_Win,NULL, GA_Text,gb_ClicktabLabels, TAG_END);
}
else IDOS->Printf("Name for tab required\n");
}
else IDOS->Printf("No more tabs possible\n");
}
break;

case GAD_ID_Del:
{
/* Erase the current tab */
ULONG val, i;
IIntuition->GetAttr(CLICKTAB_Current,(Object*)gb_ClicktabGad,(ULONG*)&val);
IDOS->Printf("Del CT [%ld] <%s>\n",val,gb_ClicktabLabels[val]);
IExec->FreeVec(gb_ClicktabLabels[val]);
for(i=val; i<MAX_CLICKTABS; i++)
{
gb_ClicktabLabels[i] = gb_ClicktabLabels[i + 1];
}
IIntuition->RefreshSetGadgetAttrs(gb_ClicktabGad,gb_Win,NULL, GA_Text,gb_ClicktabLabels, TAG_END);
}
break;

case GAD_ID_Evensize:
{
/* All tabs have the same width */
/* V53: WORKS ONLY DURING INITIALIZATION ! */
ULONG val;
IIntuition->GetAttr(GA_Selected,(Object*)gb_EvensizeGad,(ULONG*)&val);
IIntuition->RefreshSetGadgetAttrs(gb_ClicktabGad,gb_Win,NULL, CLICKTAB_EvenSize,val, TAG_END);
/* !!! MUST DO to layout the changed tag !!! */
IIntuition->RefreshSetGadgetAttrs(gb_ClicktabGad,gb_Win,NULL, GA_Text,gb_ClicktabLabels, TAG_END);
}
break;

case GAD_ID_Labeltruncate:
{
/* Truncates label if necessary */
/* V53: WORKS ONLY DURING INITIALIZATION ! */
ULONG val;
IIntuition->GetAttr(GA_Selected,(Object*)gb_LabeltruncateGad,(ULONG*)&val);
IIntuition->RefreshSetGadgetAttrs(gb_ClicktabGad,gb_Win,NULL, CLICKTAB_LabelTruncate,val, TAG_END);
/* !!! MUST DO to layout the changed tag !!! */
IIntuition->RefreshSetGadgetAttrs(gb_ClicktabGad,gb_Win,NULL, GA_Text,gb_ClicktabLabels, TAG_END);
}
break;

case GAD_ID_Clicktab:
{
/* Use tab name for editing */
ULONG val;
IIntuition->GetAttr(CLICKTAB_Current,(Object*)gb_ClicktabGad, (ULONG*)&val);
IDOS->Printf("Update STR [%ld] <%s>\n", val, gb_ClicktabLabels[val]);
IIntuition->SetGadgetAttrs(gb_NameGad,gb_Win,NULL, STRINGA_TextVal,gb_ClicktabLabels[val], TAG_END);
}
break;
}
break;

case WMHI_VANILLAKEY:
{
const LONG code = result & WMHI_KEYMASK;

if(code == ' ')
{
IDOS->Printf("---- Label List:\n");
ULONG i;
for(i=0; i<MAX_CLICKTABS; i++)
{
if(gb_ClicktabLabels[i]) IDOS->Printf("[%ld] <%s> $%lx\n",i,gb_ClicktabLabels[i],gb_ClicktabLabels[i]);
}
IDOS->Printf("----------------\n");
}
}
break;

/* Window close gadget clicked */
case WMHI_CLOSEWINDOW:
{
running = FALSE;
}
break;
}
}

/* CTRL-C typed in the shell or via a signal */
if(sigs & SIGBREAKF_CTRL_C) laufen = FALSE;
}
}

/******************************************************************************/

int main(int argc, char *argv[])
{
/* AmigaOS 4.1 is required */
if(SysBase->lib_Version < 53)
{
IDOS->Printf("Program requires AmigaOS 4.1\n");
return( 20 );
}

if( CreateGUI() )
{
MsgLoop();

FreeGUI();
}
else IDOS->Printf("GUI creation failed !\n");

return 0;
}
</syntaxhighlight>

[[File:AF110_clicktab-test.png|frame|center]]

Irrespective of the programing side, the user can influence the appearance and partly the behaviour of gadgets and windows system-wide using the Prefs options. Angular or rounded edges, the thickness of the window frame, and also the complex colour scheme are all widely configurable. There are ready-made styles so everything works perfectly in the visual sense.

= Authors =

Written by Michael Christoph and Aleksandra Schmidt-Pendarovska 
Copyright (c) 2013 Michael Christoph

ANIM IFF CEL Animations

2025-01-26T19:30:52Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= ANIM =

An IFF Format For CEL Animations

Revision date: 6 June 2013

Originally prepared by:
: SPARTA Inc.
: 23041 de la Carlota
: Laguna Hills, Calif 92653
: (714) 768-8161
: Contact: Gary Bonham

Also by:
: Aegis Development Co.
: 2115 Pico Blvd.
: Santa Monica, Calif 90405
: (213) 392-9972

= Introduction =

The ANIM IFF format was developed at Sparta originally for the production of animated video sequences on the Amiga computer. The intent was to be able to store, and play back, sequences of frames and to minimize both the storage space on disk (through compression) and playback time (through efficient decompression algorithms). It was desired to maintain maximum compatibility with existing IFF formats and to be able to display the initial frame as a normal still IFF picture.

Several compression schemes have been introduced in the ANIM format. Most of these are strictly of historical interest as the only one currently being placed in new code is the vertical run length encoded byte encoding developed by Jim Kent.

== ANIM Format Overview ==

The general philosophy of ANIMs is to present the initial frame as a normal, run-length-encoded, IFF picture. Subsequent
frames are then described by listing only their differences from a previous frame. Normally, the "previous" frame is two frames back as that is the frame remaining in the hidden screen buffer when double-buffering is used. To better understand this, suppose one has two screens, called A and B, and the ability to instantly switch the display from one to the other. The normal playback mode is to load the initial frame into A and duplicate it into B. Then frame A is displayed on the screen. Then the differences for frame 2 are used to alter screen B and it is displayed. Then the differences for frame 3 are used to alter screen A and it is displayed, and so on. Note that frame 2 is stored as differences from frame 1, but all other frames are stored as differences from two frames back.

ANIM is an IFF FORM and its basic format is as follows (this assumes the reader has a basic understanding of IFF format
files):
FORM ANIM
. FORM ILBM first frame
. . BMHD normal type IFF data
. . ANHD optional animation header
chunk for timing of 1st frame.
. . CMAP
. . BODY
. FORM ILBM frame 2
. . ANHD animation header chunk
. . DLTA delta mode data
. FORM ILBM frame 3
. . ANHD
. . DLTA
...

The initial FORM ILBM can contain all the normal ILBM chunks, such as CRNG, etc. The BODY will normally be a standard
run-length-encoded data chunk (but may be any other legal compression mode as indicated by the BMHD). If desired, an ANHD
chunk can appear here to provide timing data for the first frame. If it is here, the operation field should be =0.

The subsequent FORMs ILBM contain an ANHD, instead of a BMHD, which duplicates some of BMHD and has additional parameters
pertaining to the animation frame. The DLTA chunk contains the data for the delta compression modes. If the older XOR compression mode is used, then a BODY chunk will be here. In addition, other chunks may be placed in each of these as deemed necessary (and as code is placed in player programs to utilize them). A good example would be CMAP chunks to alter the color palette. A basic assumption in ANIMs is that the size of the bitmap, and the display mode (e.g. HAM) will not change through the animation. Take care when playing an ANIM that if a CMAP occurs with a frame, then the change must be applied to both buffers.

Note that the DLTA chunks are not interleaved bitmap representations, thus the use of the ILBM form is inappropriate for these frames. However, this inconsistency was not noted until there were a number of commercial products either released or close to release which generated/played this format. Therefore, this is probably an inconsistency which will have to stay with us.

== Recording ANIMs ==

To record an ANIM will require three bitmaps - one for creation of the next frame, and two more for a "history" of the previous two frames for performing the compression calculations (e.g. the delta mode calculations).

There are five frame-to-frame compression methods currently defined. The first three are mainly for historical interest.
The product Aegis VideoScape 3D utilizes the third method in version 1.0, but switched to method 5 on 2.0. This is the only instance known of a commercial product generating ANIMs of any of the first three methods. The fourth method is a general short or long word compression scheme which has several options including whether the compression is horizontal or vertical, and whether or not it is XOR format. This offers a choice to the user for the optimization of file size and/or playback speed. The fifth method is the byte vertical run length encoding as designed by Jim Kent. Do not confuse this with Jim's RIFF file format which is different than ANIM. Here we utilized his compression/decompression routines within the ANIM file structure.

The following paragraphs give a general outline of each of the methods of compression currently included in this spec.

=== XOR mode ===

This mode is the original and is included here for historical interest. In general, the delta modes are far superior. The creation of XOR mode is quite simple. One simply performs an exclusive-or (XOR) between all corresponding bytes of the new frame and two frames back. This results in a new bitmap with 0 bits wherever the two frames were identical, and 1 bits where they are different. Then this new bitmap is saved using run-length-encoding. A major obstacle of this mode is in the time consumed in performing the XOR upon reconstructing the image.

=== Long Delta mode ===

This mode stores the actual new frame long-words which are different, along with the offset in the bitmap. The exact format is shown and discussed in section 2 below. Each plane is handled separately, with no data being saved if no changes take place in a given plane. Strings of 2 or more long-words in a row which change can be run together so offsets do not have to be saved for each one.

Constructing this data chunk usually consists of having a buffer to hold the data, and calculating the data as one compares the new frame, long-word by long-word, with two frames back.

=== Short Delta mode ===

This mode is identical to the Long Delta mode except that short-words are saved instead of long-words. In most instances, this mode results in a smaller DLTA chunk. The Long Delta mode is mainly of interest in improving the playback speed when used on a 32-bit 68020 Turbo Amiga.

=== General Delta mode ===

The above two delta compression modes were hastily put together. This mode was an attempt to provide a well-thought-out delta compression scheme. Options provide for both short and long word compression, either vertical or horizontal compression, XOR mode (which permits reverse playback), etc. About the time this was being finalized, the fifth mode, below, was developed by Jim Kent. In practice the short-vertical-run-length-encoded deltas in this mode play back faster than the fifth mode (which is in essence a byte-vertical-run-length-encoded delta mode) but does not compress as well - especially for very noisy data such as digitized images. In most cases, playback speed not being terrifically slower, the better compression (sometimes 2x) is preferable due to limited storage media in most machines.

Details on this method are contained in section 2.2.2 below.

=== Byte Vertical Compression ===

This method does not offer the many options that method 4 offers, but is very successful at producing decent compression even for very noisy data such as digitized images. The method was devised by Jim Kent and is utilized in his RIFF file format which is different than the ANIM format. The description of this method in this document is taken from Jim's writings. Further, he has released both compression and decompression code to public domain.

Details on this method are contained in section 2.2.3 below.

== Playing ANIMs ==

Playback of ANIMs will usually require two buffers, as mentioned above, and double-buffering between them. The frame data from the ANIM file is used to modify the hidden frame to the next frame to be shown. When using the XOR mode, the usual run-length-decoding routine can be easily modified to do the exclusive-or operation required. Note that runs of zero bytes,
which will be very common, can be ignored, as an exclusive or of any byte value to a byte of zero will not alter the original byte value.

The general procedure, for all compression techniques, is to first decode the initial ILBM picture into the hidden buffer and double-buffer it into view. Then this picture is copied to the other (now hidden) buffer. At this point each frame is displayed with the same procedure. The next frame is formed in the hidden buffer by applying the DLTA data (or the XOR data from the BODY chunk in the case of the first XOR method) and the new frame is double-buffered into view. This process continues to the end of the file.

A master colormap should be kept for the entire ANIM which would be initially set from the CMAP chunk in the initial ILBM. This colormap should be used for each frame. If a CMAP chunk appears in one of the frames, then this master colormap is updated and the new colormap applies to all frames until the occurrance of another CMAP chunk.

Looping ANIMs may be constructed by simply making the last two frames identical to the first two. Since the first two frames are special cases (the first being a normal ILBM and the second being a delta from the first) one can continually loop the animation by repeating from frame three. In this case the delta for creating frame three will modify the next to the last frame which is in the hidden buffer (which is identical to the first frame), and the delta for creating frame four will modify the last frame which is identical to the second frame.

Multi-File ANIMs are also supported so long as the first two frames of a subsequent file are identical to the last two frames of the preceeding file. Upon reading subsequent files, the ILBMs for the first two frames are simply ignored, and the remaining frames are simply appended to the preceding frames. This permits splitting ANIMs across multiple floppies and also permits playing each section independently and/or editing it independent of the rest of the ANIM.

Timing of ANIM playback is easily achieved using the vertical blank interrupt of the Amiga. There is an example of setting up such a timer in the SDK. Be sure to remember the timer value when a frame is flipped up, so the next frame can be flipped up relative to that time. This will make the playback independent of how long it takes to decompress a frame (so long as there is enough time between frames to accomplish this decompression).

= Chunk Formats =

== ANHD Chunk ==

The ANHD chunk consists of the following data structure:

; UBYTE operation
: The compression method:
:{| class="wikitable"
| 0 || set directly (normal ILBM BODY)
|-
| 1 || XOR ILBM mode
|-
| 2 || Long Delta mode
|-
| 3 || Short Delta mode
|-
| 4 || Generalized short/long Delta mode
|-
| 5 || Byte Vertical Delta mode
|-
| 6 || Stereo op 5 (third party)
|-
| 7 || short/long Vertical Delta mode
|-
| 74 (ASCII 'J') || reserved for Eric Graham's compression technique (details to be released later).
|}

; UBYTE mask
: (XOR mode only - plane mask where each bit is set =1 if there is data and =0 if not.)

; UWORD w,h
: (XOR mode only - width and height of the area represented by the BODY to eliminate unnecessary unchanged data)

; WORD x,y
: (XOR mode only - position of rectangular area represented by the BODY)

; ULONG abstime
: (currently unused - timing for a frame relative to the time the first frame was displayed - in jiffies (1/60 sec))

; ULONG reltime
: (timing for frame relative to time previous frame was displayed - in jiffies (1/60 sec))

; UBYTE interleave
: (unused so far - indicates how may frames back this data is to modify. =0 defaults to indicate two frames back (for double buffering). =n indicates n frames back. The main intent here is to allow values of =1 for special applications where frame data would modify the immediately previous frame)

; UBYTE pad0
: Pad byte, not used at present.

; ULONG bits
: 32 option bits used by options=4 and 5. At present only 6 are identified, but the rest are set =0 so they can be used to implement future ideas. These are defined for option 4 only at this point. It is recommended that all bits be set =0 for option 5 and that any bit settings used in the future (such as for XOR mode) be compatible with the option 4 bit settings. Player code should check undefined bits in options 4 and 5 to assure they are zero.

: The six bits for current use are:
:{| class="wikitable"
! bit # !! set =0 !! set =1
|-
| 0 || short data || long data
|-
| 1 || set || XOR
|-
| 2 || separate info for each plane || one info list for all planes
|-
| 3 || not RLC || RLC (run length coded)
|-
| 4 || horizontal || vertical
|-
| 5 || short info offsets || long info offsets
|}

; UBYTE pad[16]
: This is a pad for future use for future compression modes.

== DLTA Chunk ==

This chunk is the basic data chunk used to hold delta compression data. The format of the data will be dependent upon the exact compression format selected. At present there are two basic formats for the overall structure of this chunk.

=== Format for methods 2 & 3 ===

This chunk is a basic data chunk used to hold the delta compression data. The minimum size of this chunk is 32 bytes as the first 8 long-words are byte pointers into the chunk for the data for each of up to 8 bit planes. The pointer for the
plane data starting immediately following these 8 pointers will have a value of 32 as the data starts in the 33-rd byte of the chunk (index value of 32 due to zero-base indexing).

The data for a given plane consists of groups of data words. In
Long Delta mode, these groups consist of both short and long
words - short words for offsets and numbers, and long words for
the actual data. In Short Delta mode, the groups are identical
except data words are also shorts so all data is short words.
Each group consists of a starting word which is an offset. If
the offset is positive then it indicates the increment in long
or short words (whichever is appropriate) through the bit plane.
In other words, if you were reconstructing the plane, you would
start a pointer (to shorts or longs depending on the mode) to
point to the first word of the bit plane. Then the offset would
be added to it and the following data word would be placed at
that position. Then the next offset would be added to the
pointer and the following data word would be placed at that
position. And so on... The data terminates with an offset
equal to 0xFFFF.

A second interpretation is given if the offset is negative. In
that case, the absolute value is the offset+2. Then the
following short-word indicates the number of data words that
follow. Following that is the indicated number of contiguous
data words (longs or shorts depending on mode) which are to
be placed in contiguous locations of the bit plane.

If there are no changed words in a given plane, then the pointer
in the first 32 bytes of the chunk is =0.

=== Format for method 4 ===

The DLTA chunk is modified slightly to have 16 long pointers at
the start. The first 8 are as before - pointers to the start of
the data for each of the bit planes (up to a theoretical max of 8
planes). The next 8 are pointers to the start of the offset/numbers
data list. If there is only one list of offset/numbers for all
planes, then the pointer to that list is repeated in all positions
so the playback code need not even be aware of it. In fact, one
could get fancy and have some bit planes share lists while others
have different lists, or no lists (the problems in these schemes
lie in the generation, not in the playback).

The best way to show the use of this format is in a sample playback
routine.

<syntaxhighlight lang="C" line>
SetDLTAshort(bm,deltaword)
struct BitMap *bm;
WORD *deltaword;
{
int i;
LONG *deltadata;
WORD *ptr,*planeptr;
register int s,size,nw;
register WORD *data,*dest;

deltadata = (LONG *)deltaword;
nw = bm->BytesPerRow >>1;

for (i=0;i<bm->Depth;i++) {
planeptr = (WORD *)(bm->Planes[i]);
data = deltaword + deltadata[i];
ptr = deltaword + deltadata[i+8];
while (*ptr != 0xFFFF) {
dest = planeptr + *ptr++;
size = *ptr++;
if (size < 0) {
for (s=size;s<0;s++) {
*dest = *data;
dest += nw;
}
data++;
}
else {
for (s=0;s<size;s++) {
*dest = *data++;
dest += nw;
}
}
}
}
return(0);
}
</syntaxhighlight>

The above routine is for short word vertical compression with
run length compression. The most efficient way to support
the various options is to replicate this routine and make
alterations for, say, long word or XOR. The variable nw
indicates the number of words to skip to go down the vertical
column. This one routine could easily handle horizontal
compression by simply setting nw=1. For ultimate playback
speed, the core, at least, of this routine should be coded in
assembly language.

=== Format for method 5 ===

In this method the same 16 pointers are used as in option 4.
The first 8 are pointers to the data for up to 8 planes.
The second set of 8 are not used but were retained for several
reasons. First to be somewhat compatible with code for option
4 (although this has not proven to be of any benefit) and
second, to allow extending the format for more bit planes (code
has been written for up to 12 planes).

Compression/decompression is performed on a plane-by-plane basis.
For each plane, compression can be handled by the skip.c code
(provided Public Domain by Jim Kent) and decompression can be
handled by unvscomp.asm (also provided Public Domain by Jim Kent).

Compression/decompression is performed on a plane-by-plane basis.
The following description of the method is taken directly from
Jim Kent's code with minor re-wording. Please refer to Jim's
code (skip.c and unvscomp.asm) for more details:

Each column of the bit plane is compressed separately.
A 320x200 bit plane would have 40 columns of 200 bytes each.
Each column starts with an op-count followed by a number
of ops. If the op-count is zero, that's OK, it just means
there's no change in this column from the last frame.
The ops are of three classes, and followed by a varying
amount of data depending on which class:

# Skip ops - this is a byte with the hi bit clear that says how many rows to move the "dest" pointer forward, i.e. to skip. It is non-zero.
# Uniq ops - this is a byte with the hi bit set. The hi bit is masked down and the remainder is a count of the number of bytes of data to copy literally. It's of course followed by the data to copy.
# Same ops - this is a 0 byte followed by a count byte, followed by a byte value to repeat count times.

Do bear in mind that the data is compressed vertically rather
than horizontally, so to get to the next byte in the destination
we add the number of bytes per row instead of one!

= ANIM.op6 =

== OpCode 6 Addition to ANIM IFF Format ==

Stereo (3D) Animations

Submitted by William J. Coldwell (08/23/91)

Revision Date: 20.8.91

Prepared by:
: Cryogenic Software
: 13045 SouthEast Stark St
: Suite 144
: Portland, OR 97233-1557
: Contact: William J. Coldwell

: Voice: (503) 254-8147 (11a-4p PDT/PST)
: Data: (503) 257-4823 (EMail to SYSOP)
: Portal: Cryogenic
: UUCP: uunet!m2xenix!percy!cryo!billc
: Internet: billc@cryo.rain.com

== Introduction ==

In 1989, we added support into one of our commercial products to
support the Haitex X-Specs glasses. This documentation will not
go into a detailed description of this product. Contact Haitex
for more information concerning the hardware:

: Haitex Resources, Inc.
: Post Office Box 20609
: Charleston, SC 29413
: Voice: (803) 881-7518
: Fax: (803) 881-7522
: Contact: Shawn Glisson

We found that there was not a supported way to display stereo
animations using the current IFF ANIM OpCode 5 specification.

Cryogenic supported OpCode 6 as an internal format in our
commercial programs (see below) and provided Public Domain
players. It is our intention at this time, to release this
format to other developers wishing to support stereo animations
using this OpCode.

When we first started this project, the current Amiga machines
had a 512K of CHIP RAM maximum. This caused some memory problems
with some of the higher resolution stereo animations, since the
Quad Buffers were in CHIP RAM for our players. It was our
intention to attempt to do some memory magic to require only
two of the four bitmaps to be in CHIP RAM at one time. It was
our feeling that this would have caused the animations to slow
down, due to data swapping that may or may not have needed to
be done. By the end of 1989, all development had stopped on
OpCode 6. This left all buffers in CHIP, and the format has
remained the same since then.

== OpCode 6 Additions to OpCode 5 ==

The format is exactly the same as OpCode 5 but is QUAD buffered
instead of DOUBLE buffered. This allows the player to show 2
screens at one time for the X-Specs Glasses. Each picture MUST
be viewed for 1/60th of a second, therefore to see a 3-D Picture
the viewer can only play ANIMs at 30 frames per second.
(2 pictures = 1 frame).

The IFF file is stored exactly the same except that instead
of having each DLTA (delta) modify bitmap two frames back, it
modifies the bitmap four frames back.

Example:

------------------------
| |
| BMHD |
| |
------------------------
| DLTA (1) |
------------------------
| DLTA (2) |
------------------------
| DLTA (3) |
------------------------
| DLTA (4) |
------------------------
| DLTA (5) |
------------------------
| DLTA (6) |
------------------------
.
.
.
------------------------
| DLTA (x) |
------------------------

== Playing OpCode 6 ANIMs ==

Four bitmaps are allocated. Bitmaps 1 and 3 are the left views,
and bitmaps 2 and 4 are the right.

The First bitmap is gets its image from the bitmap in the file
(BMHD). The Second bitmap is a copy of the first with DLTA (1)
performed on it. The Third Bitmap is a copy of the first with
DLTA (2) performed on it. The Fourth Bitmap is a copy of the
first with DLTA (3) performed on it.

We now have the first two 3-D Pictures:

One in bitmaps 1 and 2 and the other in bitmaps 3 and 4

DLTA (6) is used to create the third left view from bitmap 1.

DLTA (7) is used to create the third right view from bitmap 2.

DLTA (8) is used to create the forth left view from bitmap 3.

DLTA (9) is used to create the forth right view from bitmap 4.

NOTE: This technique requires 4 Loop frames at the end to
perform looping.

== Chunk Changes ==

In the ANHDChunk structure the only differences between OpCode
5 and OpCode 6 are the _Operation_ field which should be set to
6, and the _Interleave_ field which should be set to 4.

== Supporting Software ==

* 3-D Professional 1.0+ (Progressive Peripherals and Software)
* View 1.7 and above (Public Domain) on a Fred Fish Disk
* MSA: Make Stereo ANIM (internal) Available upon request.
* PSA: Play Stereo ANIM (internal) Available upon request.

= ANIM.op7 =

== Appendix for Anim7 Formats ==

Anim7 (July 92) by:
: Wolfgang Hofer
: A-2722 Winzendorf
: Wr. Neustaedterstr. 140

Anim method 7 is designed for maximum playback speed and acceptable packing rates (packing usually not as good as method 5, but more efficient than methods 1 -- 4)

Method 7 was not originally in the IFF specification but supported by the Public Domain Programs AAP/AAC.

== Chunk Sequence ==

Method 7 Anims should use the same Chunk Sequence as methods 1..5. Alternatively the first frame may have a DLTA chunk instead of the BODY chunk.

In that case the DLTA is the difference to a 'black frame'. A player has to clear all bit planes of the first bitmap to zero, and then call his DLTA unpack routines for this frame.

FORM ANIM
. FORM ILBM first frame
. . BMHD normal type IFF data
. . ANHD optional animation header chunk for timing of 1st frame.
. . CMAP
. . { BODY | DLTA } full picture or difference to 'black frame'
. FORM ILBM frame 2
. . ANHD animation header chunk
. . DLTA delta mode data
. . [CMAP]
. FORM ILBM frame 3
. . ANHD
. . DLTA
. . [CMAP]
...

The initial FORM ILBM can contain all the normal ILBM chunks, such as CRNG, etc. The BODY will normally be a standard
run-length-encoded data chunk (but may be any other legal compression mode as indicated by the BMHD). If desired, an ANHD chunk can appear here to provide timing data for the first frame. If it is here, the operation field should be =0.

If the initial FORM ILBM uses a DLTA chunk, the ANHD chunk must appear, and the operation field must be set to the according anim method.

== Chunk Formats ==

=== ANHD Chunk for method 7 ===

The ANHD chunk consists of the following data structure:

UBYTE operation The compression method=7 short/long Vertical Delta mode
UBYTE mask unused
UWORD w,h unused
WORD x,y unused
ULONG abstime unused
ULONG reltime (timing for frame relative to time previous frame was displayed - in jiffies (1/60 sec))
UBYTE interleave = 0 (see ANHD description above)
UBYTE pad0 unused
ULONG bits 32 option bits used by method=4 and 5.
method 7 uses only bit #0

bit # set =0 set =1
===============================================
0 short data long data

UBYTE pad[16] unused

=== DLTA Chunk ===

The DLTA Chunks of method 7 consists of
* 8 pointers to opcode lists
* 8 pointers to data lists
* data lists (long/short)
* opcode lists (bytes)

In this method the DLTA Chunk begins with 16 pointers. The first 8 longwords are pointers to the opcode lists for up to 8 planes. The second set of 8 longwords are pointers to the corresponding data lists. If there are less than 8 Planes all unused pointers are set to zero.

Compression/decompression is performed on a plane-by-plane basis. The following description of the method is similar to
Jim Kent's method 5, except that data is stored in a separated data list (long or short, depending on bit#0 of the ANHD bits) and doesn't follow immediate after the opcode.

In method 7 the bit plane is split into vertical columns. Each column of the bit plane is compressed separately. A 320x200 bitplane would have 20 columns of 200 short datas each. (or 10 columns of 200 long datas)

Each column starts with an op-count followed by a number of ops. If the op-count is zero, that's OK, it just means
there's no change in this column from the last frame. The ops are of three classes. The ops refer to a varying
amount of data (to fetch from the corresponding data list) depending on which class:

# Skip ops - this is a byte with the hi bit clear that says how many rows to move the "dest" pointer forward, i.e. to skip. It is non-zero. Skip ops have no corresponding data-items in the data list.
# Uniq ops - this is a byte with the hi bit set. The hi bit is masked down and the remainder is a count of the number of data to copy literally from the data list to the "dest" pointer column. (Each data item to the next destination row) Data items may be long or short organized.
# Same ops - this is a 0 byte followed by a count byte. The count byte says how many rows of the current column are to be set to the same data-item. the data-item (long or short) is fetched from the data list.

{{Note|text=Do bear in mind that the data is compressed vertically rather than horizontally, so to get to the next address in the destination we have to add the number of bytes per row instead of 2 (or 4)!}}

= ANIM.op8 =

== Appendix for Anim8 ==

Joe Porkka 10-jan-92

Anim method 8 is designed for maximum playback speed and acceptable packing rates (packing usually not as good as method 5, but more efficient than methods 1 -- 4). In addition, it is easier to convert existing Anim5 code to support Anim8 than Anim7.

== Chunk Sequence ==

Method 8 Anims should use the same Chunk Sequence as methods 1..5. Alternatively the first frame may have a DLTA chunk instead of the BODY chunk.

In that case the DLTA is the difference to a 'black frame'. A player has to clear all bit planes of the first bitmap to zero, and then call his DLTA unpack routines for this frame. The same rules about copying the first frame into both frame buffers still applies in this case.

FORM ANIM
. FORM ILBM first frame
. . BMHD normal type IFF data
. . ANHD optional animation header chunk for timing of 1st frame.
. . CMAP
. . { BODY | DLTA } full picture or difference to 'black frame'
. FORM ILBM frame 2
. . ANHD animation header chunk
. . DLTA delta mode data
. . [CMAP]
. FORM ILBM frame 3
. . ANHD
. . DLTA
. . [CMAP]
...

The initial FORM ILBM can contain all the normal ILBM chunks, such as CRNG, etc. The BODY will normally be a standard run-length-encoded data chunk (but may be any other legal compression mode as indicated by the BMHD). If desired, an ANHD chunk can appear here to provide timing data for the first frame. If it is here, the operation field should be =0.

If the initial FORM ILBM uses a DLTA chunk, the ANHD chunk must appear, and the operation field must be set to the
according anim method.

Each of the frames from frame 2 on up may use an anhd->operation of 0, 5 or 8. Note that only for the first frame in the file do you copy the image data into two buffers, not every time you get an ANHD->operation==0.

== Chunk Formats ==

=== ANHD Chunk for method 8 ===

The ANHD chunk consists of the following data structure:

UBYTE operation The compression method=8 short/long Vertical Delta mode
UBYTE mask unused
UWORD w,h unused
WORD x,y unused
ULONG abstime unused
ULONG reltime (timing for frame relative to time previous frame was displayed - in jiffies (1/60 sec))
UBYTE interleave = 0 (see ANHD description above)
UBYTE pad0 unused
ULONG bits 32 option bits used by method=4 and 5.
method 8 uses only bit #0
bit # set =0 set =1
=============================================
0 short data long data
UBYTE pad[16] unused

=== DLTA Chunk ===

The DLTA Chunks of method8 consists of
* 16 pointers same as in method 5

In this method the DLTA Chunk begins with 16 pointers. The first 8 longwords are pointers to the opcode lists for up to 8
planes. The second set of 8 longwords are unused. If there are less than 8 Planes all unused pointers are set to zero.

Compression/decompression is performed on a plane-by-plane basis. The following description of the method is similar to Jim Kent's methode 5, except that data is either in WORDs or LONGS, depending on bit 0 of the ANHD bits.

In method 8 the bit plane is split into vertical columns. Each column of the bit plane is compressed separately. A 320x200 bit plane would have 20 columns of 200 short data each (or 10 columns of 200 long data).

Each column of the bit plane is compressed separately. A 320x200 bit plane would have 20 (WORD) or 10 (LONG)columns of 200 bytes each. Each column starts with an op-count followed by a number of ops. If the op-count is zero, that's OK, it just means there's no change in this column from the last frame. The ops are of three classes, and followed by a varying amount of data depending on which class:

# Skip ops - this is a word or long with the hi bit clear that says how many rows to move the "dest" pointer forward, i.e. to skip. It is non-zero. Note that the range of values is much larger for word and long data, 0x7fff and 0x7fffffff.
# Uniq ops - this is a word or long with the hi bit set. The hi bit is masked down and the remainder is a count of the number of bytes of data to copy literally. It's of course followed by the data to copy. Note that the range of values is much larger for word and long data, 0x7fff and 0x7fffffff.
# Same ops - this is a 0 word or long followed by a count word or long, followed by a word or long value to repeat count times. Note that the range of values is much larger for word and long data, 0xffff and 0xffffffff.

{{Note|text=Do bear in mind that the data is compressed vertically rather than horizontally, so to get to the next word or long in the destination we add the number of bytes per row instead of one!}}

There is a slight complication in the case of long data. Normally an Amiga BitMap is and even number of 16bit WORDs wide, so it is possible to have an image which is not an even number or LONGs wide. For example, an image which is 336 pixels wide is 42 bytes wide, 21 words wide, and 10.5 longs wide. In the case that the data is not an even number of longs wide, and the data is to be long compressed, then the last column of data is to be word compressed instead. So, that 336 pixel wide image would be compress as 10 long columns and 1 word column.

= ANIM.brush =

Dpaint Anim Brush IFF Format

From a description by the author of DPaint, Dan Silva, Electronic Arts.

The "Anim Brushes" of DPaint III are saved on disk in the IFF "ANIM" format. Basically, an ANIM Form consists of an initial ILBM which is the first frame of the animation, and any number of subsequent "ILBM"S (which aren't really ILBM's) each of which contains an ANHD animation header chunk and a DLTA chunk comprised of the encoded difference between a frame and a previous one.

To use ANIM terminology (for a description of the ANIM format, see the IFF Anim Spec, by Gary Bonham). Anim Brushes use a "type 5" encoding, which is a vertical, byte-oriented delta encoding (based on Jim Kent's RIFF). The deltas have an interleave of 1, meaning deltas are computed between adjacent frames, rather than between frames 2 apart, which is the usual ANIM custom for the purpose of fast hardware page-flipping. Also, the deltas use Exclusive Or to allow reversable play.

However, to my knowledge, all the existing Anim players in the Amiga world will only play type 5 "Anim"s which have an interleave of 0 (i.e. 2) and which use a Store operation rather than Exclusive Or, so no existing programs will read Anim Brushes anyway. The job of modifying existing Anim readers to read Anim Brushes should be simplified, however.

Here is an outline of the structure of the IFF Form output by DPaint III as an "Anim Brush". The IFF Reader should of course be flexible enough to tolerate variation in what chunks actually appear in the initial ILBM.

FORM ANIM
. FORM ILBM first frame
. . BMHD
. . CMAP
. . DPPS
. . GRAB
. . CRNG
. . CRNG
. . CRNG
. . CRNG
. . CRNG
. . CRNG
. . DPAN my own little chunk.
. . CAMG
. . BODY

. FORM ILBM frame 2
. . ANHD animation header chunk
. . DLTA delta mode data

. FORM ILBM frame 3
. . ANHD animation header chunk
. . DLTA delta mode data

. FORM ILBM frame 4
. . ANHD animation header chunk
. . DLTA delta mode data

...

. FORM ILBM frame N
. . ANHD animation header chunk
. . DLTA delta mode data

== DPAN ==

Here is the format of the DPAN chunk:

<syntaxhighlight lang="C" line>
typedef struct {
UWORD version; /* current version=4 */
UWORD nframes; /* number of frames in the animation.*/
ULONG flags; /* Not used */
} DPAnimChunk;
</syntaxhighlight>

The version number was necessary during development. At present all I look at is "nframes".

== ANHD ==

Here is the ANHD chunk format:

<syntaxhighlight lang="C" line>
typedef struct {
UBYTE operation; /* =0 set directly
=1 XOR ILBM mode,
=2 Long Delta mode,
=3 Short Delta mode
=4 Generalize short/long Delta mode,
=5 Byte Vertical Delta (riff)
=74 (Eric Grahams compression mode)
*/
UBYTE mask; /* XOR ILBM only: plane mask where data is*/
UWORD w,h;
WORD x,y;
ULONG abstime;
ULONG reltime;
UBYTE interleave; /* 0 defaults to 2 */
UBYTE pad0; /* not used */
ULONG bits; /* meaning of bits:
bit# =0 =1
0 short data long data
1 store XOR
2 separate info one info for
for each plane for all planes
3 not RLC RLC (run length encoded)
4 horizontal vertical
5 short info offsets long info offsets
-------------------------*/
UBYTE pad[16];
} AnimHdr;
</syntaxhighlight>

for Anim Brushes, I set:
<syntaxhighlight lang="C" line>
animHdr.operation = 5; /* RIFF encoding */
animHdr.interleave = 1;
animHdr.w = curAnimBr.bmob.pict.box.w;
animHdr.h = curAnimBr.bmob.pict.box.h;
animHdr.reltime = 1;
animHdr.abstime = 0;
animHdr.bits = 4; /* indicating XOR */
</syntaxhighlight>

everything else is set to 0.

{{Note|text=The "bits" field was actually intended ( by the original creator of the ANIM format, Gary Bonham of SPARTA, Inc.) for use with only with compression method 4. I am using bit 2 of the bits field to indicate the Exclusive OR operation in the context of method 5, which seems like a reasonable generalization.}}

== DLTA ==

For an Anim Brush with 10 frames, there will be an initial frame followed by 10 Delta's (i.e ILBMS containing ANHD and DLTA
chunks). Applying the first Delta to the initial frame generates the second frame, applying the second Delta to the second frame
generates the third frame, etc. Applying the last Delta thus brings back the first frame.

The DLTA chunk begins with 16 LONG plane offets, of which DPaint only uses the first 6 (at most). These plane offsets are either
the offset (in bytes ) from the beginning of the DLTA chunk to the data for the corresponding plane, or Zero, if there was no
change in that plane. Thus the first plane offset is either 0 or 64.

(The following description of the method is based on Gary Bonham's rewording of Jim Kent's RIFF documentation.)

Compression/decompression is performed on a plane-by-plane basis.

Each byte-column of the bit plane is compressed separately. A 320x200 bit plane would have 40 columns of 200 bytes each. In
general, the bit planes are always an even number of bytes wide, so for instance a 17x20 bit plane would have 4 columns of 20
bytes each.

Each column starts with an op-count followed by a number of ops. If the op-count is zero, that's OK, it just means there's no change in this column from the last frame. The ops are of three kinds, and followed by a varying amount of data depending on which kind:

# SKIP - this is a byte with the hi bit clear that says how many rows to move the "dest" pointer forward, i.e. to skip. It is non-zero.
# DUMP - this is a byte with the hi bit set. The hi bit is masked off and the remainder is a count of the number of bytes of data to XOR directly. It is followed by the bytes to copy.
# RUN - this is a 0 byte followed by a count byte, followed by a byte value to repeat "count" times, XOR'ing it into the destination.

{{Note|text=Bear in mind that the data is compressed vertically rather than horizontally, so to get to the next byte in the destination you add the number of bytes per row instead of one.}}

The Format of DLTA chunks is as described in section 2.2.2 of the Anim Spec. The encoding for type 5 is described in section 2.2.3 of the Anim Spec.

Window Display Preservation

2025-01-26T19:30:48Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= Preserving the Window Display =

The layers library is what allows the display and manipulation of multiple overlapping rectangles, or ''layers''. Intuition uses the layers library to manage its windows, by associating a layer to each window.

Each window is a virtual display. When rendering, the application does not have to worry about the current size or position of its window, and what other windows might be partly or fully obscuring its window. The window's RastPort is the handle to the its virtual display space. Intuition and graphics library rendering calls will recognize that this RastPort belongs to a layer, and act accordingly.

As windows are moved, resized, rearranged, opened, or closed, the on-screen representation changes. When part of a window which was visible now needs to appear in a new location, the layers library will move that imagery without involving the application. However, when part of a window that was previously obscured is revealed, or when a window is made larger, the imagery for the newly-visible part of the window needs to be redrawn. Intuition, through layers, offers three choices for how this is managed, trading off speed, memory usage, and application complexity.

* The most basic type of window is called ''Simple Refresh''. When any graphics operation takes place in this kind of window, the visible parts are updated, but rendering to the obscured parts is discarded. When the window arrangement changes to reveal a previously obscured part of such a window, the application must refresh that area.

* Alternately, a window may be made ''Smart Refresh'', which means that when rendering occurs, the system will not only update the visible parts of the window, but it will maintain the obscured parts as well, by using off-screen buffers. This means that when an obscured part of the window is revealed, the system will restore the imagery that belongs there. The application needs only to refresh parts of the window that appear when the window is made bigger. Smart Refresh windows use more memory than Simple Refresh windows (for the storage of obscured areas), but they are faster.

* The third kind of window is called ''SuperBitMap''. In such a window, the system can refresh the window even when it is sized bigger. For this to work, the application must store a complete bitmap for the window's maximum size. Such a window is more work to manage, and uses yet more memory. SuperBitMap windows are used less often than the other two types.

Intuition helps your application manage window refresh. First, Intuition will take care of redrawing the window border and any system and application gadgets in the window. Your application never has to worry about that. Second, Intuition will notify your application when it needs to refresh its window (by sending the IDCMP_REFRESHWINDOW event). Third, Intuition provides functions that restrict your rendering to the newly-revealed (damaged) areas only, which speeds up your refresh rendering and makes it look cleaner.

The Intuition, layers, and graphics libraries work together to make rendering into and managing windows easy. You obtain your windows through Intuition, which uses the Layers library to manage the overlapping, resizing, and re-positioning of the window layers. The layers library is responsible for identifying the areas of each window that are visible, obscured but preserved off-screen, or obscured and not preserved. The rendering functions in the graphics library and Intuition library know how to render into the multiple areas that layers library establishes.

Note that you may not directly manipulate layers on an Intuition screen. You cannot create your own layers on an Intuition screen, nor can you use the layers movement, sizing, or arrangement functions on Intuition windows. Use the corresponding Intuition calls instead. Some other Layers library calls (such as the locking calls) are sometimes used on Intuition screens and windows.

= Damage Regions =

The layers library and Intuition maintain a ''damage region'' for each window, which is the part of the window whose imagery is in need of repair, or refreshing. Several things can add areas of the window to the damage region:

* Revealing an obscured part of a Simple Refresh window adds that area to the damage region
* Sizing a Simple or Smart Refresh window bigger along either axis adds the new area to the damage region
* Resizing a Simple or Smart Refresh window (smaller or bigger) adds the old and new border areas, and the areas occupied by certain gadgets (those whose position or size depend on window size) to the damage region.

= Refreshing Intuition Windows =

When the user or an application performs an Intuition operation which causes damage to a window, Intuition notifies that window's application. It does this by sending a message of the class IDCMP_REFRESHWINDOW to that window's IDCMP.

In response to this message, your application should update the damaged areas. Rendering proceeds faster and looks cleaner if it is restricted to the damaged areas only. The BeginRefresh()/EndRefresh() pair achieve that. The application should call BeginRefresh() for the window, and then do its rendering. Any rendering that would have gone into undamaged areas of the window is automatically discarded; only the area in need of repair is affected. Finally, the application should call EndRefresh(), which removes the restriction on rendering, and informs the system that the damage region has been dealt with. Even if your application intends to do no rendering, it must at least call BeginRefresh()/EndRefresh(), to inform the system that the damage region is no longer needed. If your application never needs to render in response to a refresh event, it can avoid having to call BeginRefresh()/EndRefresh() by setting the WFLG_NOCAREREFRESH flag or the WA_NoCareRefresh tag in the OpenWindowTagList() call.

Note that by the time that your application receives notification that refresh is needed, Intuition will have already refreshed your window's border and all gadgets in the window, as needed. Thus, it is unnecessary to use any of the gadget-refreshing functions in response to an IDCMP_REFRESHWINDOW event.

Operations performed between the BeginRefresh()/EndRefresh() pair should be restricted to simple rendering. All of the rendering functions in Intuition library and Graphics library are safe. Avoid RefreshGList() or RefreshGadgets(), or you risk deadlocking the computer. Avoid calls that may lock the LayerInfo or get complicated in Intuition, since BeginRefresh() leaves the window's layer or layers locked. Avoid AutoRequest() and EasyRequest(), and therefore all direct or indirect disk related DOS calls. See the [[Intuition_Gadgets|Intuition Gadgets]] section for more information on gadget restrictions with BeginRefresh() and EndRefresh().

== Simple Refresh ==

For a Simple Refresh window, only those pixels actually on-screen are maintained by the system. When part of a Simple Refresh window is obscured, the imagery that was there is lost. As well, any rendering into obscured portions of such a window is discarded.

When part of the window is newly revealed (either because the window was just made larger, or because that part used to be obscured by another window), the application must refresh any rendering it wishes to appear into that part. The application will learn that refresh is needed because Intuition sends an IDCMP_REFRESHWINDOW event.

== Smart Refresh ==

If a window is of the Smart Refresh type, then the system will not only preserve those pixels which are actually on-screen, but it will save all obscured pixels that are within the current window's size. The system will refresh those parts of the window revealed by changes in the overlapping with other windows on the screen, without involving the application. However, any part of the window revealed through the sizing of the window must be redrawn by the application. Again, Intuition will notify the application through the IDCMP_REFRESHWINDOW event.

Because the obscured areas are kept in off-screen buffers, Smart Refresh windows are refreshed faster than Simple Refresh windows are, and often without involving the application. Of course, for the same reason, they use more display memory.

== SuperBitMap Refresh ==

The SuperBitMap refresh type allows the application to provide and maintain bitmap memory for graphics in the window. The bitmap can be any size as long as the window sizing limits respect the maximum size of the bitmap.

SuperBitMap windows have their own memory for maintaining all obscured parts of the window up to the size of the defined bitmap, including those parts outside of the current window. Intuition will update all parts of the window that are revealed through changes in sizing and changes in window overlapping. The application never needs to redraw portions of the window that were revealed by sizing or positioning windows in the screen.

SuperBitMap windows require the application to allocate a bitmap for use as off-screen memory, instead of using Intuition managed buffers. This bitmap must be as large as, or larger than, the inner window's maximum dimensions (that is, the window's outside dimensions less the border sizes).

SuperBitMap windows are almost always WFLG_GIMMEZEROZERO, which renders the borders and system gadgets in a separate bitmap. If the application wishes to create a SuperBitMap window that is not GimmeZeroZero, it must make the window borderless with no system gadgets, so that no border imagery is rendered by Intuition into the application's bitmap.

= Intuition Refresh Events =

When using a Simple Refresh or a Smart Refresh windows, the program may receive refresh events, informing it to update the display. See the above discussion for information on when refresh events are sent.

A message of the class IDCMP_REFRESHWINDOW arrives at the IDCMP, informing the program of the need to update the display. The program must take some action when it receives a refresh event, even if it is just the acceptable minimum action described below.

On receiving a refresh event, BeginRefresh() must be called, then the program should redraw its display, and, finally, call EndRefresh(). The minimum required action is to call the BeginRefresh()/EndRefresh() pair. This allows Intuition and the Layers library keep things sorted and organized.

= Optimized Window Refreshing =

Bracketing the display updating in the BeginRefresh()/EndRefresh() pair automatically restricts all rendering to the "damaged" areas.

<syntaxhighlight lang="C" line>
VOID BeginRefresh( struct Window *window );
VOID EndRefresh ( struct Window *window, LONG complete );
</syntaxhighlight>

These functions makes sure that refreshing is done in the most efficient way, only redrawing those portions of the window that really need to be redrawn. The rest of the rendering commands are discarded.

Operations performed between the BeginRefresh()/EndRefresh() pair should be restricted to simple rendering. All of the rendering functions in Intuition library and Graphics library are safe. Calls to RefreshGadgets() are not permitted. Avoid calls that may lock the LayerInfo, or get complicated in Intuition, since BeginRefresh() leaves the window's layer or layers locked. Avoid AutoRequest(), and therefore all direct or indirect disk related DOS calls. See [[Intuition_Gadgets|Intuition Gadgets]] for more information on gadget restrictions with BeginRefresh()/EndRefresh().

Certain applications do not need to receive refresh events, and can avoid having to call BeginRefresh() and EndRefresh() by setting the WFLG_NOCAREREFRESH flag or the WA_NoCareRefresh tag in the OpenWindowTagList() call.

The EndRefresh() function takes a boolean value as an argument (complete in the prototype above). This value determines whether refreshing is completely finished. When set to FALSE, further refreshing may be performed between subsequent BeginRefresh()/ EndRefresh() pairs. Set the boolean to TRUE for the last call to EndRefresh().

It is critical that applications performing multiple BeginRefresh() and EndRefresh() pairs using EndRefresh(win,FALSE) hold layers locked through the entire process. The layer lock may only be released after the final call to EndRefresh(win,TRUE). See [[Layers_Library|Layers Library]] for more details.

The procedures outlined in this section take care of refreshing what is inside the window. Another function named RefreshWindowFrame() refreshes window borders, including the title region and gadgets:

<syntaxhighlight lang="C" line>
VOID RefreshWindowFrame( struct Window *window );
</syntaxhighlight>

Applications can use this function to update window borders after overwriting them with graphics.

= Setting up a SuperBitMap Window =

SuperBitMap windows are created by setting the WFLG_SUPER_BITMAP flag, or by specifying the WA_SuperBitMap tag in the OpenWindowTagList() call. A pointer to an allocated and initialized BitMap structure must be provided.

A SuperBitMap window requires the application to allocate and initialize its own bitmap. This entails allocating a BitMap structure, initializing the structure and allocating memory for the bit planes.

Allocate a BitMap structure with the Exec AllocMem() function. Then use the graphics function InitBitMap() to initialize the BitMap structure:

<syntaxhighlight lang="C" line>
VOID InitBitMap( struct BitMap *bitMap, LONG depth, LONG width, LONG height );
</syntaxhighlight>

InitBitMap() fills in fields in the BitMap structure describing how a linear memory area is organized as a series of one or more rectangular bit-planes.

Once you have allocated and initialized the BitMap structure, use the graphics library function AllocRaster() to allocate the memory space for all the bit planes.

<syntaxhighlight lang="C" line>
PLANEPTR AllocRaster( ULONG width, ULONG height );
</syntaxhighlight>

The example listed in the next section shows how to allocate a BitMap structure, initialize it with InitBitMap() and use AllocRaster() function to set up memory for the bitplanes.

= Graphics and Layers Functions for SuperBitMap Windows =

The portion of the bitmap showing within a SuperBitMap window is controlled by the application. Initially, the window shows the bitmap starting from its origin (0,0) and clipped to fit within the window layer. The visible portion of the bitmap can be scrolled around within the window using the layers library ScrollLayer() function:

<syntaxhighlight lang="C" line>
VOID ScrollLayer(LONG unused, struct Layer *layer, LONG dx, LONG dy)
</syntaxhighlight>

Pass this function a pointer to the window's layer in layer and the scroll offsets in dx and dy. (A pointer to the window's layer can be obtained from Window.RPort->Layer.)

When rendering operations are performed in a SuperBitMap window, any rendering that falls outside window boundaries is done in the application's bitmap. Rendering that falls within window bounds is done in the screen's bitmap. Before performing an operation such as a save on the application bitmap, the graphics library function SyncSBitMap() should be called:

<syntaxhighlight lang="C" line>
VOID SyncSBitMap(struct Layer *layer)
</syntaxhighlight>

Pass this function a pointer to the window's layer. SyncSBitMap() copies the window contents to the corresponding part of the application bitmap, bringing it up to date. (If no rendering operations have been performed this call is not necessary.)

Similarly, after making any changes to the application bitmap such as loading a new one, the window's layer should be locked and the CopySBitMap() function should be called.

<syntaxhighlight lang="C" line>
VOID CopySBitMap(struct Layer *)
</syntaxhighlight>

This function copies the new information in the appropriate area of the underlying bitmap to the window's layer.

For more information about bitmaps and layers, see the [[Graphics_Primitives|Graphics Primitives]] and [[Layers_Library|Layers Library]]. Also see the <graphics/clip.h>, <graphics/gfx.h>, <graphics/layers.h > files in the SDK.

== SuperBitMap Window Example ==

This example shows how to implement a superbitmap, and uses a host of Intuition facilities. Further reading of other Intuition, BOOPSI and graphics chapters may be required for a complete understanding of this example.

<syntaxhighlight lang="C" line>
/**
** lines.c -- Window SuperBitMap example.
**
** gcc -o lines lines.c
**
**/

#include <dos/dos.h>
#include <intuition/icclass.h>
#include <classes/window.h>
#include <gadgets/scroller.h>
#include <gadgets/layout.h>

#include <proto/intuition.h>
#include <proto/exec.h>
#include <proto/utility.h>
#include <proto/layers.h>
#include <proto/graphics.h>

#define WIDTH_SUPER (800)
#define HEIGHT_SUPER (600)
#define MINWIDTH (150)
#define MINHEIGHT (150)

#define LAYERXOFFSET(x) (x->RPort->Layer->Scroll_X)
#define LAYERYOFFSET(x) (x->RPort->Layer->Scroll_Y)

enum
{
WID_MAIN = 0,
WID_LAST
};

enum
{
OID_MAIN = 0,
OID_VPROP,
OID_HPROP,
OID_LAST
};

struct IntuitionIFace *IIntuition;
struct GraphicsIFace *IGraphics;
struct LayersIFace *ILayers;

static struct Window *windows[WID_LAST];
static Object *objects[OID_LAST];
static struct Hook idcmphook;

/* Prototypes for our functions */

void initBorderProps(struct Screen *screen);
void doNewSize();
void doDrawStuff();
void doMsgLoop();
void superWindow(struct Screen *screen);
void slideBitMap(struct Window *win, int16 dX, int16 dY);

int main()
{
struct Screen *screen;

struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace *) IExec->GetInterface(IntuitionBase,
"main", 1, NULL);

struct Library *GfxBase = IExec->OpenLibrary("graphics.library", 50);
IGraphics = (struct GraphicsIFace *) IExec->GetInterface(GfxBase, "main", 1, NULL);

struct Library *LayersBase = IExec->OpenLibrary("layers.library", 50);
ILayers = (struct LayersIFace *) IExec->GetInterface(LayersBase, "main", 1, NULL);

if (IIntuition != NULL && IGraphics != NULL && ILayers != NULL) {
if ((screen = IIntuition->LockPubScreen(NULL)) != NULL) {
superWindow(screen);
IIntuition->UnlockPubScreen(NULL, screen);
}
}

IExec->DropInterface((struct Interface *) ILayers);
IExec->CloseLibrary(LayersBase);

IExec->DropInterface((struct Interface *) IGraphics);
IExec->CloseLibrary(GfxBase);

IExec->DropInterface((struct Interface *) IIntuition);
IExec->CloseLibrary(IntuitionBase);

return 0;
}

void IDCMPHook(struct Hook *hook, Object *object, struct IntuiMessage *msg)
{
if (msg->Class == IDCMP_IDCMPUPDATE) {
int16 dX = 0;
int16 dY = 0;
int32 pos;

struct Window *win = windows[WID_MAIN];
if (win != NULL) {
uint32 gadgetid = IUtility->GetTagData(GA_ID, 0, (struct TagItem *) msg->IAddress);
if (IIntuition->GetAttr(SCROLLER_Top, objects[gadgetid], (uint32 *) &pos)) {
switch (gadgetid) {
case OID_VPROP:
dY = pos - LAYERYOFFSET(win);
break;
case OID_HPROP:
dX = pos - LAYERXOFFSET(win);
break;
}
if (dX || dY) {
slideBitMap(win, dX, dY);
}
}
}
}
}

void superWindow(struct Screen *myscreen)
{
struct BitMap *bigBitMap = IGraphics->AllocBitMapTags(WIDTH_SUPER, HEIGHT_SUPER, myscreen->BitMap.Depth,
BMATags_Friend, myscreen->BitMap, BMATags_Displayable, TRUE, BMATags_Clear, 0, TAG_END);

if (bigBitMap != NULL) {
struct MsgPort *AppPort = IExec->AllocSysObjectTags(ASOT_PORT, TAG_DONE);

if ( AppPort != NULL )
{
idcmphook.h_Entry = (uint32 (*)())IDCMPHook;
idcmphook.h_SubEntry = NULL;

if ((objects[OID_MAIN] = IIntuition->NewObject(NULL, "window.class",
WA_ScreenTitle, "SuperBitmap",
WA_Title, "Lines",
WA_Activate, TRUE,
WA_DepthGadget, TRUE,
WA_DragBar, TRUE,
WA_CloseGadget, TRUE,
WA_SizeGadget, TRUE,
WA_Top, 10,
WA_Left, 10,
WA_MinWidth, MINWIDTH,
WA_MinHeight, MINHEIGHT,
WA_Width, MINWIDTH,
WA_Height, MINHEIGHT,
WA_IDCMP, IDCMP_NEWSIZE | IDCMP_IDCMPUPDATE,
WA_PubScreen, myscreen, WA_SuperBitMap, bigBitMap,
WA_NoCareRefresh, TRUE,
WA_GimmeZeroZero, TRUE,
WINDOW_IDCMPHook, &idcmphook,
WINDOW_IDCMPHookBits, IDCMP_IDCMPUPDATE,
WINDOW_HorizProp, 1,
WINDOW_VertProp, 1,
WINDOW_AppPort, AppPort, TAG_DONE)) != NULL) {
// Open the window.
if (windows[WID_MAIN] = (struct Window *) IIntuition->IDoMethod(objects[OID_MAIN], WM_OPEN)) {
/* adjust props to represent portion visible */
doNewSize();
doDrawStuff();
/* process the window, return on IDCMP_CLOSEWINDOW */
doMsgLoop();
}
IIntuition->DisposeObject(objects[OID_MAIN]);
}
IExec->FreeSysObject(ASOT_PORT, AppPort);
}
IGraphics->FreeBitMap(bigBitMap);
}
}

void slideBitMap(struct Window *win, int16 Dx, int16 Dy)
{
ILayers->ScrollLayer(0, win->RPort->Layer, Dx, Dy);
}

/*
** Update the prop gadgets and bitmap positioning when the size changes.
*/

void doNewSize()
{
struct Window *win = windows[WID_MAIN];
if (win != NULL) {
IIntuition->GetAttr(WINDOW_HorizObject, objects[OID_MAIN], (uint32 *) &objects[OID_HPROP]);
if (objects[OID_HPROP]) {
if (win->GZZWidth >= WIDTH_SUPER)
slideBitMap(win, -LAYERXOFFSET(win), 0);
IIntuition->RefreshSetGadgetAttrs((APTR) objects[OID_HPROP], win, NULL,
GA_ID, OID_HPROP,
SCROLLER_Top, LAYERXOFFSET(win),
SCROLLER_Total, WIDTH_SUPER,
SCROLLER_Visible, win->GZZWidth,
ICA_TARGET, ICTARGET_IDCMP,
TAG_DONE);
}

IIntuition->GetAttr(WINDOW_VertObject, objects[OID_MAIN], (uint32 *) &objects[OID_VPROP]);
if (objects[OID_VPROP]) {
if (win->GZZHeight >= HEIGHT_SUPER)
slideBitMap(win, 0, -LAYERYOFFSET(win));

IIntuition->RefreshSetGadgetAttrs((APTR) objects[OID_VPROP], win, NULL,
GA_ID, OID_VPROP,
SCROLLER_Top, LAYERYOFFSET(win),
SCROLLER_Total, HEIGHT_SUPER,
SCROLLER_Visible, win->GZZHeight,
ICA_TARGET, ICTARGET_IDCMP,
TAG_DONE);
}
}
}

int16 RangeRand(uint32 maxValue)
{
static struct RandomState range = {0xFFFF, 0};
return IUtility->Random(&range) % maxValue;
}

void doDrawStuff()
{
struct Window *win = windows[WID_MAIN];
if (win != NULL) {
/* clear the bitplanes */
IGraphics->SetRast(win->RPort, 0);
IGraphics->SetDrMd(win->RPort, JAM1);
int16 x1, y1, x2, y2;
int16 pen, ncolors, deltx, delty;
ncolors = 1 << win->WScreen->BitMap.Depth;
deltx = RangeRand(6) + 2;
delty = RangeRand(6) + 2;
pen = RangeRand(ncolors - 1) + 1;
IGraphics->SetAPen(win->RPort, pen);
for (x1 = 0, y1 = 0, x2 = WIDTH_SUPER - 1, y2 = HEIGHT_SUPER - 1;
x1 < WIDTH_SUPER; x1 += deltx, x2 -= deltx) {
IGraphics->Move(win->RPort, x1, y1);
IGraphics->Draw(win->RPort, x2, y2);
}

pen = RangeRand(ncolors - 1) + 1;
IGraphics->SetAPen(win->RPort, pen);
for (x1 = 0, y1 = 0, x2 = WIDTH_SUPER - 1, y2 = HEIGHT_SUPER - 1;
y1 < HEIGHT_SUPER; y1 += delty, y2 -= delty) {
IGraphics->Move(win->RPort, x1, y1);
IGraphics->Draw(win->RPort, x2, y2);
}
}
}

void doMsgLoop()
{
uint32 signal = 0;
BOOL done = FALSE;

// Obtain the window wait signal mask.
IIntuition->GetAttr(WINDOW_SigMask, objects[OID_MAIN], &signal);

// Input Event Loop
while (!done) {
uint32 wait = IExec->Wait(signal | SIGBREAKF_CTRL_C);
if ( wait & SIGBREAKF_CTRL_C ) {
done = TRUE;
break;
}

if ( wait & signal ) {
uint32 result = WMHI_LASTMSG;
int16 code = 0;
while ((result = IIntuition->IDoMethod(objects[OID_MAIN], WM_HANDLEINPUT, &code)) != WMHI_LASTMSG) {
switch (result & WMHI_CLASSMASK) {
case WMHI_NEWSIZE:
doNewSize();
doDrawStuff();
break;
case WMHI_CLOSEWINDOW:
windows[WID_MAIN] = NULL;
done = TRUE;
break;
case WMHI_ICONIFY:
IIntuition->IDoMethod(objects[OID_MAIN], WM_ICONIFY);
windows[WID_MAIN] = NULL;
break;
case WMHI_UNICONIFY:
windows[WID_MAIN] = (struct Window *) IIntuition->IDoMethod(objects[OID_MAIN], WM_OPEN);
doNewSize();
doDrawStuff();
break;
}
}
}
}
}
</syntaxhighlight>

Graphics Sprites, Bobs and Animation

2025-01-26T19:30:36Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

{{WIP}}
== Graphics Sprites, Bobs and Animation ==

This article describes how to use the functions provided by the graphics library to manipulate and animate Graphic Elements (also called GELs). It is divided into six sections:

* An overview of the GELs animation system, including fundamental terms and structures
* Explanation of simple (hardware) Sprites and an example showing their usage
* Explanation of VSprites and an example showing their usage
* Explanation of Bobs and an example showing their usage
* Discussion of topics that apply to all GELs such as collision detection and data structure extensions.
* Discussion of animation, using AnimComps and AnimObs and an example showing their usage

== About the GELs System ==

Before going into details, a quick glossary is in order. A ''playfield'' forms the background that GELs operate in. It encompasses the View, ViewPort, and RastPort data structures. (VSprites appear ''over'', and Bobs appear ''in'' the playfield.) Playfields can be created and controlled at several levels. Refer to [[Graphics_Primitives|Graphics Primitives]] and [[Layers_Library|Layers Library]] for details on lower-level playfield control. [[Intuition_Screens|Intuition Screens]] explains how to get higher-level access to playfields.

GELs, or graphic elements, are special graphic objects that appear in the foreground and can be moved easily around the display. They are software constructs based on the Amiga's sprite and blitter hardware. The GELs system is compatible with all playfield modes, including dual-playfield. All the various types of GELs are defined by data structures found in <graphics/gels.h>.

=== Types of GELs ===

The GEL types are (in order of increasing complexity):

; VSprites
: for Virtual Sprites. These are represented by the VSprite data structure and implemented with sprite hardware.

; Bobs
: Blitter Objects. These are represented by the VSprite and Bob data structures and implemented with blitter hardware.

; AnimComps
: Animation Components. These are represented by the VSprite, Bob and AnimComp data structures and implemented with blitter hardware.

; AnimObjs
: Animation Objects. These are used to group AnimComps. They are not strictly GELs, but are described here.

==== Simple Sprites ====

Simple Sprites (also known as hardware sprites) are not really part of the GELs system but are the basis for VSprites. Simple Sprites are graphic objects implemented in hardware that are easy to define and easy to animate. The Amiga hardware has the ability to handle up to eight such sprite objects. Each Simple Sprite is produced by one of the Amiga's eight sprite DMA channels. They are 16-bits wide and arbitrarily tall.

The Amiga system software offers a choice of how to use these hardware sprites. After a sprite DMA channel has displayed the last line of a Simple Sprite, the system can reuse the channel for a different sprite lower on the screen. This is how VSprites are implemented; as a software construct based on the sprite hardware.

Hence, Simple Sprites are not really part of the animation system (they are ''not'' GELs). In fact, if Simple Sprites and GELs are used in the same display, the GELs system must be told specifically which Simple Sprites to avoid. Simple Sprites are described in this article because they are alternatives to VSprites.

==== VSprites ====

The VSprite, or virtual sprite, is the simplest type of GEL. The VSprite data structure contains just a bit more information than is needed to define a hardware sprite. VSprites take advantage of the system's ability to reuse sprite DMA channels - each VSprite can be temporarily assigned to a hardware sprite, as needed. This makes it appear to an application program that it has a ''virtually'' unlimited supply of VSprites.

Since VSprites are based on hardware sprites, rules that apply to hardware sprites apply to VSprites too. VSprites are not rendered into the underlying BitMap of the playfield and so do not affect any bits in the BitMap. Because they are hardware based, ''they are positioned at absolute display coordinates and are not affected by the movement of screens''. The starting position of a sprite must not occur before scanline 20, because of certain hardware DMA time constraints. VSprites have the same size limitations as hardware sprites, they are 16-bits wide and arbitrarily tall.

The VSprite data structure also serves as the root structure of more complex GEL types: Bobs and AnimComps.

==== Bobs and AnimComps ====

Like VSprites, Bobs and AnimComps are graphics objects that make animation easier. They are rendered using the blitter. The blitter is a special Amiga hardware component used to move data quickly and efficiently, optionally performing logical operations as it does. It can be used to move any kind of data but is especially well suited to moving rectangular blocks of display data.

It is important to keep in mind that Bobs and AnimComps are based on the blitter hardware while VSprites use the sprite hardware. However all three GEL types use the VSprite structure as their root data structure. The system uses pointers to link the VSprite, Bob and AnimComp structures, "extending" the VSprite structure to include all GEL types.

Since Bobs and AnimComps are rendered with the blitter they actually change the underlying playfield BitMap. The BitMap area where the GEL is rendered can be saved. By moving the GEL to new locations in small increments while also saving and restoring the Bitmap as you proceed, you can create an animation effect. Bobs and AnimComps use the same coordinates as the playfield and can be any size.

==== AnimObs ====

The AnimOb (Animation Object) is a data structure that is used to group one or more AnimComps for convenient movement. For example, an AnimOb could be created that consists of two AnimComps, one that looks like a planet and another containing a sequence that describes orbiting moons. By moving just the AnimOb the image of the planet can be moved across the display and the moons will travel along with it, orbiting the planet the entire time. The system automatically manages the movement of all the AnimComps associated with the AnimOb.

==== VSprites vs. Bobs ====

If you are going to manage the movement and sequencing of GELS yourself, you need to decide if sprite animation (VSprites) or blitter animation (Bobs, AnimComps and AnimObs) best suit your needs. If you've got simple requirements or lots of coding time, you may even opt to use only Simple Sprites, and control them yourself. On the other hand if you want the system to manage your animations, AnimComps ''must'' be used and they are Bobs at heart.

Some fundamental differences between VSprites and Bobs are:

* VSprite images and coordinates currently low-resolution pixels, even on a high resolution display. Bob images and coordinates have the same resolution as the playfield they are rendered into.

* VSprites have a maximum width of 16 (low resolution) pixels. Bobs can be any width (although large Bobs tend to slow down the system). The height of either VSprites or Bobs can be as tall as the display.

* VSprites have a maximum of three colors (Simple Sprites can have fifteen if they're attached). Because the system uses the Copper to control VSprite colors on the fly, the colors are not necessarily the same as those in the background playfield. Bobs can use any or all of the colors in the background playfield. Limiting factors include playfield resolution and display time. Bobs with more colors take longer to display.

* VSprites are positioned using absolute display coordinates, and don't move with screens. Bobs follow screen movement.

In general, VSprites offer speed, while Bobs offer flexibility.

The following figure shows how the various GEL data structures, VSprites, Bobs and AnimComps are linked together.

[[File:LibFig28-1.png|frame|center|GEL Structure Layout]]

=== The GELs System ===

Before you can use the GELs system, you must set up a playfield. The GELs system requires access to a View, ViewPort, and RastPort structure. These structures may be set up through the graphics library or Intuition. For most examples in this article, the Intuition library is used for this purpose.

All GELs have a VSprite structure at their core. The system keeps track of all the GELs that it will display (the active GELs) by using a standard Exec list structure to link the VSprites. This list is accessed via the GelsInfo data structure, which in turn is associated with the RastPort. The GelsInfo structure is defined in the file <graphics/rastport.h>.

A new GEL is introduced to the system by calling AddGel() to link it into the GelsInfo list. The new GEL is added immediately ahead of the first existing GEL whose ''x,y'' value is greater than or equal to that of the new GEL, always trying to keep the list sorted.

As GELs are moved about the screen, their ''x,y'' values are constantly changing. SortGList() re-sorts this list by the ''x,y'' values. (Although this is a list of VSprite structures, bear in mind that some or all may really be Bobs or AnimComps.)

The basic set up of the GelsInfo structure requires three important fields: sprRsrvd, gelHead and gelTail. The sprRsrvd field tells the system which hardware sprites not to use when managing true VSprites. For instance, Intuition uses sprite 0 for the mouse pointer so this hardware sprite is not available for assignment to a VSprite. The gelHead and gelTail are VSprite structures that are used to manage the list of GELs. They are never displayed. To activate or deactivate a GEL, a system call is made to add it to or delete it from this list.

Other fields must be set up to provide for collision detection, color optimization, and other features. A complete example for setting up the GelsInfo structure is shown in the animtools.c lisitng at the end of this article.

==== Initializing the GEL System ====

To initialize the animation system, call the system function InitGels(). It takes the form:

<syntaxhighlight lang="C" line>
struct VSprite *vsHead;
struct VSprite *vsTail;
struct GelsInfo *gInfo;

IGraphics->InitGels(vsHead, vsTail, gInfo);
</syntaxhighlight>

The vsHead argument is a pointer to the VSprite structure to be used as the GEL list head. (You must allocate an actual VSprite structure for vsHead to point to.) The vsTail argument is a pointer to the VSprite structure to be used as the GEL list tail. (You must allocate an actual VSprite structure for vsTail to point to.) The gInfo argument is a pointer to the GelsInfo structure to be initialized.

InitGels() forms these structures into a linked list of GELs that is empty except for these two dummy elements (the head and tail). It gives the head VSprite the maximum negative ''x'' and ''y'' positions and the tail VSprite the maximum positive ''x'' and ''y'' positions. This is to aid the system in keeping the list sorted by ''x, y'' values, so GELs that are closer to the top and left of the display are nearer the head of the list. The memory space that the VSprites and Gelsinfo structures take up must already have been allocated. This can be done either by declaring them statically or explicitly allocating memory for them.

Once the GelsInfo structure has been allocated and initialized, GELs can be added to the system. Refer to the setupGelSys() and cleanupGelsys() functions in the "animtools.c" lisitng at the end of the article for examples of allocating, initializing and freeing a GelsInfo structure.

== Collisions and GEL Structure Extensions ==

This section covers two topics that are applicable to all GELs: how to extend GEL data structures for your own purposes and how to detect collisions between GELs and other graphics objects.

==== Detecting GEL Collisions ====

All GELs, including VSprites, can participate in the software collision detection features of the graphics library. Simple Sprites must use ''hardware'' collision detection. See the ''Amiga Hardware Reference Manual'' for information about hardware collision detection.

Two kinds of collisions are handled by the system routines: GEL-to-boundary hits and GEL-to-GEL hits. You can set up as many as 16 different routines to handle different collision combinations; one routine to handle the boundary hits, and up to fifteen more to handle different inter-GEL hits.

You supply the actual collision handling routines, and provide their addresses to the system so that it can call them as needed (when the hits are detected). These addresses are kept in a collision handler table pointed to by the CollHandler field of the GelsInfo list. Which routine is called depends on the 16-bit MeMask and HitMask members of the VSprite structures involved in the collision.

When you call DoCollision(), the system goes through the GelsInfo list which, is constantly kept sorted by ''x,y'' position. If a GEL intersects the display boundaries and the GELs HitMask indicates it is appropriate, the boundary collision routine is called. When DoCollision() finds that two GELs overlap, it compares the MeMask of one with the HitMask of the other. If corresponding bits are set in both, it calls the appropriate inter-GEL collision routine at the table position corresponding to the bits in the HitMask and MeMask, as outlined below.

==== Preparing for Collision Detection ====

Before you can use the system to detect collisions between GELS, you must allocate and initialize a table of collision-detection routines and place the address of the table in the GelsInfo.CollHandler field. This table is an array of pointers to the actual routines that you have provided for your collision types. You must also prepare some members of the VSprite structure: CollMask, BorderLine, HitMask, and MeMask.

==== Building a Table of Collision Routines ====

The collision handler table is a structure, CollTable, defined in <graphics/gels.h>. It is accessed as the CollHandler member of the GelsInfo structure. The table only needs to be as large as the number of bits for which you wish to provide collision processing. It is safest, though, to allocate space for all 16 entries, considering the small amount of space required.

Call the routine SetCollision() to initialize the table entries that correspond to the HitMask and MeMask bits that you plan to use. Do not set any of the table entries directly, instead give the address to SetCollision() routine and let it handle the set up of the GelsInfo.CollTable field.

For example, SetCollision() could be called as follows:

<syntaxhighlight lang="C" line>
ULONG num;
VOID (*routine)();
struct GelsInfo *GInfo;

VOID myCollisionRoutine(GELA, GELB) /* sample collision routine */
struct VSprite *GELA;
struct VSprite *GELB;
{
/* process GELs here - GELA and GELB point to the base VSprites of */
/* the GELs, you can use the user extensions to identify what hit */
/* (if you need the info). */
}

/* GelsInfo must be allocated and initialized */

routine = myCollisionRoutine;

IGraphics->SetCollision(num, routine, GInfo)
</syntaxhighlight>

The num argument is the collision table vector number (0-15). The (*routine)() argument is a pointer to your collision routine. And the GInfo argument is a pointer to the GelsInfo structure.

==== VSprite Collision Mask ====

The CollMask member of the VSprite is a pointer to a memory area allocated for holding the collision mask of that GEL. This area must be in Chip memory and its size is the equivalent of one bitplane of the GEL's image. The collision mask is ''usually'' the same as the shadow mask of the GEL, formed from a logical-'''OR''' combination of all planes of the image. The following figure shows an example collision mask.

[[File:LibFig28-3.png|frame|center|A Collision Mask]]

Alternatively, you may have a collision mask that is not derived from the image. In this case, the actual image isn't relevant. The system will not register collisions unless the other objects touch the collision mask. If the collision mask is smaller than the image, other objects will pass through the edges without a collision.

==== VSprite BorderLine ====

For faster collision detection, the system uses the BorderLine member of the VSprite structure. BorderLine specifies the location of the horizontal logical-'''OR''' combination of all of the bits of the object. It may be compared to taking the whole object's shadow/collision mask and squishing it down into a single horizontal line. You provide the system with a place to store this line. The size of the data area you allocate must be at least as large as the image width.

In other words, if it takes three 16-bit words to hold one line of a GEL, then you must reserve three words for the BorderLine. In the VSprite examples, the routine makeVSprite() correctly allocates and initializes the collision mask and borderline. For example:

<syntaxhighlight lang="C" line>
WORD myBorderLineData[3]; /* reserve space for BorderLine for this Bob */

myVSprite.BorderLine = myBorderLineData; /* tell the system where it is */
</syntaxhighlight>

Here is a sample of an object and its BorderLine image:

<pre>
011000001100 Object
001100011000
001100011000
000110110000
000010100000

011110111100 BorderLine image
</pre>

Using this squished image, the system can quickly determine if the image is touching the left or rightmost boundary of the drawing area.

To establish default BorderLine and CollMask data, call the InitMasks() function.

==== VSprite HitMask and MeMask ====

Software collision detection is independently enabled and disabled for each GEL. Further, you can specify which of 16 possible collision routines you wish to have automatically executed. DoCollision(), in addition to sensing an overlap between objects, uses these masks to determine which routine (if any) the system will call when a collision occurs.

When the system determines a collision, it performs a logical-'''AND''' of the HitMask of the upper-leftmost object in the colliding pair with the MeMask of the lower-rightmost object of the pair. The bits that are 1s after the logical-'''AND''' operation choose which one of the 16 possible collision routines to perform.

* If the collision is with the boundary, bit 0 is always a 1 and the system calls the collision handling routine number 0. Always assign the routine that handles boundary collisions to vector 0 in the collision handling table.

* The system uses the flag called BORDERHIT to indicate that an object has landed on or moved beyond the outermost bounds of the drawing area (the edge of the clipping region). The VSprite example earlier in this article uses collision detection to check for border hits.

* If any one of the other bits (1 to 15) is set, then the system calls your collision handling routine corresponding to the bit set.

* If more than one bit is set in both masks, the system calls the vector corresponding to the rightmost (the least significant) bit ''only''.

==== Using HitMask and MeMask ====

This section illustrates the use of the HitMask and MeMask to define one type of collision.

Suppose there are two classes of objects that you wish to control on the display: ENEMYTANK and MYMISSILE. Objects of class ENEMYTANK should be able to pass across one another without registering any collisions. Objects of class MYMISSILE should also be able to pass across one another without collisions. However, when MYMISSILE and ENEMYTANK collide, the system should generate a call to a collision routine.

Choose a pair of collision detect bits not yet assigned within MeMask, one to represent ENEMYTANK, the other to represent MYMISSILE. You will use the same two bits in the corresponding HitMask. In this example, bit 1 represents ENEMYTANK objects and bit 2 represents MYMISSLE objects.

{| class="wikitable"
!
! colspan="2"|MeMask
! colspan="2"|HitMask
|-
! Bit Number !! 2 !! 1 !! 2 !! 1
|-
| ENEMYTANK 1 || align="center"|0 || align="center"|1 || align="center"|1 || align="center"|0
|-
| ENEMYTANK 2 || align="center"|0 || align="center"|1 || align="center"|1 || align="center"|0
|-
| MYMISSLE || align="center"|1 || align="center"|0 || align="center"|0 || align="center"|1
|}

In the MeMask, bit 1 is set to indicate that this object is an ENEMYTANK. Bit 2 is clear (zero) indicating this object is ''not'' a MYMISSILE object. In the HitMask for ENEMYTANK objects, bit 1 is clear (zero) which means, "I will not register collisions with other ENEMYTANK objects." However, bit 2 is set (one) which means, "I ''will'' register collisions with MYMISSILE objects."

Thus when a call to DoCollision() occurs, for any objects that appear to be colliding, the system '''AND'''s the MeMask of one object with the HitMask of the other object. If there are non-zero bits present, the system will call one of your collision routines.

In this example, suppose that the system senses a collision between ENEMYTANK 1 and ENEMYTANK 2. Suppose also that ENEMYTANK 1 is the top/leftmost object of the pair. Here is the way that the collision testing routine performs the test to see if the system will call any collision-handling routines:

{| class="wikitable"
! Bit Number !! 2 !! 1
|-
| ENEMYTANK 1 MeMask || 0 || 1
|-
| ENEMYTANK 2 HitMask || 1 || 0
|-
| Result of logical-AND || 0 || 0
|}

Therefore, the system does not call a collision routine. But suppose that DoCollision() finds an overlap between ENEMYTANK 1 and MYMISSILE, where MYMISSILE is the top/leftmost of the pair:

{| class="wikitable"
! Bit Number !! 2 !! 1
|-
| MYMISSLE MeMask || 1 || 0
|-
| ENEMYTANK 2 HitMask || 1 || 0
|-
| Result of logical-AND || 1 || 0
|}

Therefore, the system calls the collision routine at position 2 in the table of collision-handling routines.

=== Setting up for Boundary Collisions ===

To specify the region in the playfield that the system will use to define the outermost limits of the GEL boundaries, you use these GelsInfo members: topmost, bottommost, leftmost, and rightmost.

The DoCollision() routine tests these boundaries when determining boundary collisions within this RastPort. They have nothing whatsoever to do with graphical clipping. Graphical clipping makes use of the RastPort's clipping rectangle.

Here is a typical program segment that assigns the members correctly (for boundaries 50, 100, 80, 240). It assumes that you already have a RastPort structure pointer named myRastPort.

<syntaxhighlight lang="C" line>
myRastPort->GelsInfo->topmost = 50;
myRastPort->GelsInfo->bottommost = 100;
myRastPort->GelsInfo->leftmost = 80;
myRastPort->GelsInfo->rightmost = 240;
</syntaxhighlight>

==== Parameters To Your Boundary Collision Routine ====

During the operation of the DoCollision() routine, if you have enabled boundary collisions for a GEL (by setting the least significant bit of its HitMask) and it has crossed a boundary, the system calls the boundary routine you have defined. The system will call the routine once for every GEL that has hit, or gone outside of the boundary. The system will call your routine with the following two arguments:

* A pointer to the VSprite structure of the GEL that hit the boundary
* A flag word containing one to four bits set, representing top, bottom, left and right boundaries, telling you which of the boundaries it has hit or exceeded.
* To test these bits, compare to the constants TOPHIT, BOTTOMHIT, LEFTHIT, and RIGHTHIT.

See the VSprite example given earlier for an example of using boundary collision.

==== Parameters To Your Inter-GEL Collision Routines ====

If, instead of a GEL-to-boundary collision, DoCollision() senses a GEL-to-GEL collision, the system calls your collision routine with the following two arguments:

* Address of the VSprite that is the uppermost (or leftmost if ''y'' coordinates are identical) GEL of a colliding pair.
* Address of the VSprite that is the lowermost (or rightmost if ''y'' coordinates are identical) GEL of the pair.

==== Handling Multiple Collisions ====

When multiple elements collide within the same display field, the following set of sequential calls to the collision routines occurs:

* The system issues each call in a sorted order for GELs starting at the upper left-hand corner of the screen and proceeding to the right and down the screen.
* For any colliding GEL pair, the system issues only one call, to the collision routine for the object that is the topmost and leftmost of the pair.

=== Adding User Extensions to GEL Data Structures ===

This section describes how to expand the size and scope of the VSprite, Bob and AnimOb data structures. In the definition for these structures, there is an item called UserExt at the end of each. If you want to expand these structures (to hold your own special data), you define the UserExt member before the <graphics/gels.h> file is included. If this member has already been defined when the <graphics/gels.h> file is parsed, the compiler preprocessor will extend the structure definition automatically. If these members have not been defined, the system will make them SHORTs, and you may still consider these as being reserved for your private use.

To show the kind of use you can make of this feature, the example below adds speed and acceleration figures to each GEL by extending the VSprite structure. When your collision routine is called, it could use these values to transfer energy between the two colliding objects (say, billiard balls). You would have to set up additional routines, executed between calls to DoCollision(), that would add the values to the GELs position appropriately. You could do this with code similar o the following:

<syntaxhighlight lang="C" line>
struct myInfo
{
short xvelocity;
short yvelocity;
short xaccel;
short yaccel;
};
</syntaxhighlight>

These members are for example only. You may use any definition for your user extensions. You would then also provide the following line, to extend the VSprites structure, use:

<syntaxhighlight lang="C" line>
/* Redefine VUserStuff for my own use. */
#define VUserStuff struct myInfo
</syntaxhighlight>

To extend the Bobs structure, use:

<syntaxhighlight lang="C" line>
#define BUserStuff struct myInfo
</syntaxhighlight>

To extend the AnimObs structure, use:

<syntaxhighlight lang="C" line>
#define AUserStuff struct myInfo
</syntaxhighlight>

When the system is compiling the <graphics/gels.h> file with your program, the compiler preprocessor substitutes "struct myInfo" everywhere that UserExt is used in the header. The structure is thereby customized to include the items you wish to associate with it.

{{Note|title=Typedef Cannot Be Used|text=You cannot use the C-language construct typedef for the above statements. If you want to substitute your own data type for one of the UserStuff variables, you must use a #define.}}

== Animation with GELs ==

An animation sequence is composed of a series of drawings. Each drawing differs from the preceding one so that when they are arranged in a stack and viewed sequentially, the images appear to flow naturally.

In classic film animation, image drawing is done in two stages. The background for each scene is painted just once. Then, the cartoon characters and any other foreground objects are painted on transparent sheets of celluloid called ''cells'' which are placed over the background. With cells, animation can be achieved by redrawing only the parts of the scene that move while the background stays the same. Animation on the Amiga works similarly. The background is formed by the playfield while the objects that move can be conveniently handled with the GELs system.

=== Animation Data Structures ===

There are two main data structures involved in Amiga animation: AnimComp and AnimOb.

The AnimComp (Animation Component), is an extension of the Bob structure discussed in the previous section. An AnimComp provides a convenient way to link together a series of images so that they can be sequenced automatically, and so multiple sequences can be grouped together. An AnimComp is analogous to one sheet of celluloid representing a single image to be placed over the background.

<syntaxhighlight lang="C" line>
struct AnimComp
{
WORD Flags; /* AnimComp flags for system & user */
WORD Timer;
WORD TimeSet;
struct AnimComp *NextComp;
struct AnimComp *PrevComp;
struct AnimComp *NextSeq;
struct AnimComp *PrevSeq;
WORD (*AnimCRoutine)();
WORD YTrans;
WORD XTrans;
struct AnimOb *HeadOb; /* Pointer back to the controlling AnimOb */
struct Bob *AnimBob; /* Underlying Bob structure for this AnimComp */
};
</syntaxhighlight>

The AnimComp structure contains pointers, PrevSeq and NextSeq, that lets you group these cells into stacks that will be viewed sequentially. The AnimComp structure also has PrevComp and NextComp pointers that let you group stacks into complex objects containing multiple independently moving parts.

The second animation data structure is the AnimOb which provides the variables needed for overall control over a group of AnimComps. The AnimOb itself contains no imagery; it simply provides a common reference point for the sequenced images and specifies how the system should move that point.

<syntaxhighlight lang="C" line>
struct AnimOb
{
struct AnimOb *NextOb, *PrevOb;
LONG Clock;
WORD AnOldY, AnOldX; /* old y,x coordinates */
WORD AnY, AnX; /* y,x coordinates of the AnimOb*/
WORD YVel, XVel; /* velocities of this object */
WORD YAccel, XAccel; /* accelerations of this object */
WORD RingYTrans, RingXTrans; /* ring translation values */
WORD (*AnimORoutine)(); /* address of user procedure */
struct AnimComp *HeadComp; /* pointer to first component */
AUserStuff AUserExt; /* AnimOb user extension */
};
</syntaxhighlight>

These structures can be used in various ways. A simple animation of a rotating ball could be created with three or four AnimComps linked together in a circular list by their NextSeq and PrevSeq fields. The system displays the initial AnimComp (the "top of the stack"), then switches to the AnimComp pointed to by NextSeq, and then switches to ''its'' NextSeq and so on until it reaches the end of the sequence. The sequence starts over again automatically if the last AnimComp.NextSeq points back to the first AnimComp in the stack.

For a more complex animation of a walking human, you could use five stacks, i.e., five circular lists of AnimComps; four stacks for the arms and legs and a single stack for the head and torso. To group these stacks into one cohesive unit showing a human figure, you use the PrevComp and NextComp pointers in the AnimComp structure. All the stacks would also share a common AnimOb, so that the combined sequences can be moved as a single object.

[[File:LibFig28-4.png|frame|center|Linking AnimComps For a Multiple Component AnimOb]]

=== Animation Types ===

The GELs system provides several ways of setting up automatic animation, loosely based on some categories of movement in real life. Some things (like balls or arrows) can move independently of the background, and look even more realistic if they tumble or rotate as they move; other things (like worms, wheels, and people) must be anchored to the background, or they will appear to ''slide'' unnaturally.

The system software allows these types of animation through simple motion control, motion control with sequenced drawing, and sequenced drawing using Ring Motion Control.

==== Simple Motion Control ====

To produce motion of a simple object, such as a ball, the object is simply moved relative to a background display, a little at a time. This is simple motion control, and can be accomplished with one AnimComp and one AnimOb, by simply changing the AnimOb's position every N video frames. The apparent speed of the object is a combination of how often it is moved (every frame, every other frame, etc.) and how far it is moved (how much the AnimOb's AnX and AnY are changed).

==== Sequenced Drawing ====

To make the ball appear to rotate is a little more complex. To produce apparent movement within the image, sequencing is used. This is done by having a stack of AnimComp's that are laid down one after the other, a frame at a time. The stack can be arranged in a circular list for repeating movement. So, when you combine a sequence of drawings using AnimComps with simple motion control using an AnimOb, you can perform more complex animations such as having a rotating ball bounce around.

==== Ring Motion Control ====

Making a worm appear to crawl is similar to the rotating ball. There is still a stack of AnimComps that are sequenced automatically, and one controlling AnimOb. But each AnimCop image is drawn so that it appears to move relative to an internal point that remains stationary throughout the stack. So instead of the Anim's common reference point moving in each frame, you tell the system how far to move only ''at the end'' of each AnimComp sequence.

[[File:LibFig28-5.png|frame|center|Ring Motion Control]]

As illustrated in the figure, the sequence of events for Ring Motion Control look like this:

Draw AnimComp1, Draw AnimComp2, Draw AnimComp3, Move AnimOb, 
Draw AnimComp1, Draw AnimComp2, Draw AnimComp3, Move AnimOb, 
Draw AnimComp1 ...

=== Specifying Animation Components ===

For each AnimComp, you initially specify:

* A pointer to the AnimComp's controlling AnimOb.
* Initial and alternate views, their timing and order.
* The initial inter-component drawing priorities (for multiple AnimComp sequences, this specifies which sequence to display frontmost).
* A pointer to a special animation routine related to this component (optional).
* Your own extensions to this structure (optional).

==== Sequencing AnimComps ====

To specify the sequencing of AnimComp images, the pointers called PrevSeq and NextSeq are used to build a doubly-linked list. The sequence can be made circular (and usually is) by linking the first and last AnimComps in the sequence: the NextSeq of the last AnimComp must point back to the first AnimComp, and the PrevSeq of the first AnimComp must point to the last AnimComp. If the list is a loop, then the system will continue to cycle through the list until it is stopped. If the list is not a loop, then the program must act to restart the sequence after the last item is displayed. The AnimCRoutine field of the last AnimComp can be used to do this.

==== Position of an AnimComp ====

To specify the placement of each AnimComp relative to its controlling AnimOb, you set the AnimComp members XTrans and YTrans. These values can be positive or negative.

The system is designed so that only one of the AnimComps in any given sequence is "active" (being displayed) at a given point in time. It is the only image in the sequence that is (or is about to be) linked into the GelsInfo list. The Timer determines how long each Component in the sequence remains active, as described below.

==== Specifying Time for Each Image ====

The AnimComp members Timer and TimeSet are used to specify how long the system should keep each sequential image on the screen.

When the system makes an animation component active, it copies the value you have put in the TimeSet member into the Timer member. As the animation proceeds, the system decrements Timer; as long as it is greater than zero, then that AnimComp remains active. When the Timer value reaches zero, the system makes the next AnimComp in the sequence active, and the process repeats.

If you initialize the value in TimeSet to zero, the system will ''not sequence this component at all'' (and Timer will remain zero).

==== Linking Multiple AnimComp Sequences ====

When an AnimOb is built from multiple AnimComp sequences, the sequences are linked together by the the PrevComp and NextComp fields of the AnimComps. These pointers must be initialized ''only in the initial'' AnimComp ''of each sequence''. The other components that are not initially active should have their PrevComp and NextComp pointers set to NULL.

{{Note|title=Do Not Use Empty Fields|text=You cannot store data in the empty PrevComp and NextComp fields. As the system cycles through the AnimComps, the NextComp and PrevComp fields are set to NULL when an old AnimComps is replaced by a new AnimComp. The new AnimComp is then linked in to the list of sequences ''in place of the old one''.}}

==== Component Ordering ====

The PrevSeq, NextSeq, PrevComp and NextComp linkages have no bearing on the order in which AnimComps in any given video frame are drawn. To specify the inter-component priorities (so that the closest objects appear frontmost) the Before and After pointers in the initially active AnimComp's underlying Bob structure are linked in to the rest of the system, as described previously in the discussion of Bobs.

This setup needs to be done once, ''for the initially active AnimComps of the AnimOb only''.

The animation system adjusts the Before and After pointers of all the underlying Bob structures to constantly maintain the inter-component drawing sequence, even though different components are being made active as sequencing occurs.

These pointers also assure that one complete ''object'' always has priority over another object. The Bob Before and After pointers are used to link together the last AnimComp's Bob of one AnimOb to the first AnimComp's Bob of the next AnimOb.

=== Specifying the Animation Object ===

For each AnimOb, you initially specify:

* The starting position of this object
* Its velocity and acceleration (optional).
* A pointer to the first of its AnimComps.
* A pointer to a special animation routine related to this object (optional).
* Your own extensions to this structure (optional).

==== Linking the AnimComp Sequences to the AnimOb ====

Within each AnimOb there may be one or more AnimComp sequences. The HeadComp of the AnimOb points to the first AnimComp in the list of sequences.

Each sequence is identified by its "active" AnimComp. There can only be one active AnimComp in each sequence. The sequences are linked together by their active AnimComps; for each of these the NextComp and PrevComp fields link the sequences together to create a list. The first sequence in the list (HeadComp of the AnimOb), has its PrevComp set to NULL. The last sequence in the list has its NextComp set to NULL. None of the inactive AnimComps should have NextComp or PrevComp fields set.

To find the active AnimComp at run time, you can look in the AnimOb's HeadComp field. To find the active AnimComp from any another AnimComp, use the HeadOb field to find the controlling AnimOb first and then look in its HeadComp field to find the active AnimComp.

The figure below shows all the linkages in data structures needed to create the animation GELs.

[[File:LibFig28-6.png|frame|center|Linking of an AnimOb]]

==== Position of an AnimOb ====

To position the object and its component parts, use the AnimOb structure members AnX and AnY. The following figure illustrates how each component has its own offset from the AnimOb's common reference point.

[[File:LibFig28-7.png|frame|center|Specifying an AnimOb Position]]

When you change the animation object's AnX and AnY, all of the component parts will be redrawn relative to it the next time DrawGList() is called.

==== Setting Up Simple Motion Control ====

In this form of animation, you can specify objects that have independently controllable velocities and accelerations in the ''X'' and ''Y'' directions. Components can still sequence.

The variables that control this motion are located in the AnimOb structure and are called:

; YVel, XVel
: the velocities in the ''y'' and ''x'' directions. These values are added to the position values on each call to Animate() (see below).

; YAccel, XAccel
: the accelerations in the ''x'' and ''y'' directions. These values are added to the velocity values on each call to Animate() (see below). The velocity values are updated ''before'' the position values.

==== Setting Up Ring Motion Control ====

To make a given component ''trigger'' a move of the AnimOb you set the RINGTRIGGER bit of that AnimComp's Flags field.

When the system software encounters this flag, it adds the values of RingXTrans and RingYTrans to the AnX and AnY values of the controlling AnimOb. The ''next'' time you execute DrawGList(), the drawing sequence will use the new position.

You usually set RINGTRIGGER in only one of the animation components in a sequence (the last one); however, you can use this flag and the translation variables any way you wish.

==== Using Sequenced Drawing and Motion Control ====

If you are using Ring Motion Control, you will probably set the velocity and acceleration variables to zero. For instance, consider the example of a person walking. With Ring Motion Control, as each foot falls it is positioned on the ground exactly where originally drawn. If you included a velocity value, the person's foot would not be stationary with respect to the ground, and the person would appear to "skate" rather than walk. If you set the velocity and acceleration variables at zero, you avoid this problem.

When the system activates a new AnimComp, it checks the Flags field to see if the RINGTRIGGER bit is set. If so, the system adds RingYTrans and RingXTrans to AnY and AnX respectively.

=== The AnimKey ===

The system uses one pointer, known as the AnimKey, to keep track of all the AnimObs via their PrevOb and NextOb linkage fields. The AnimKey acts as the anchor for the list of AnimObs you are using and is initialized with code such as the following:

<syntaxhighlight lang="C" line>
struct AnimOb *animKey;

IGraphics->InitAnimate(&animKey); /* Only do this once to initialize the AnimOb list */
</syntaxhighlight>

As each new object is added (via AddAnimOb()), it is linked in at the beginning of the list, so AnimKey will always point to the object most recently added to the list. To search forward through the list, start with the AnimKey and move forward on the NextOb link. Continue to move forward until the NextOb is NULL, indicating the end of the list. The PrevOb link will allow you to move back to a previous object.

{{Note|title=Set Up PrevOb and NextOb Correctly|text=It is important that the NextOb link of the last object is NULL, and that the PrevOb of the first object is NULL. In fact, the system expects the animation object lists to be ''exactly'' the way that they are described above. If they are not, the system will produce unexpected results.}}

=== Adding Animation Objects ===

Use the routine AddAnimOb() to add animation objects to the controlled object list. This routine will link the PrevOb and NextOb pointers to chain all the AnimObs that the system is controlling.

<syntaxhighlight lang="C" line>
struct RastPort myRPort;
struct AnimOb myAnimOb;
struct AnimOb *animKey; /* Must be initialized with InitAnimate() */

IGraphics->AddAnimOb(&myAnimOb, &animKey, &myRPort);
</syntaxhighlight>

=== Moving the Objects ===

When you have defined all of the structures and have established all of the links, you can call the Animate() routine to move the objects. Animate() adjusts the positions of the objects as described above, and calls the various subroutines (AnimCRoutines and AnimORoutines) that you have specified.

After the system has completed the Animate() routine, some GELs may have been moved, so the GelsInfo list order may possibly be incorrect. Therefore, the list must be re-sorted with SortGList() before passing it to a system routine.

If you are using collision detection, you then perform DoCollision(). Your collision routines may also have an effect on the relative position of the GELs. Therefore, you should again call SortGList() to assure that the system correctly orders the objects before you call DrawGList().

When you call DrawGList(), the system renders all the GELs it finds in the GelsInfo list and any changes caused by the previous call to Animate() can then be seen.

This is illustrated in the following typical call sequence:

<syntaxhighlight lang="C" line>
struct AnimOb **myAnimKey;
struct RastPort *rp;
struct ViewPort *vp;

/* ... setup of graphics elements and objects */

IGraphics->Animate(myAnimKey, rp); /* "move" objects per instructions */
IGraphics->SortGList(rp); /* put them in order */
IGraphics->DoCollision(rp); /* software collision detect/action */
IGraphics->SortGList(rp); /* put them back into right order */
IGraphics->DrawGList(vp, rp); /* draw into current RastPort */
</syntaxhighlight>

==== Your own Animation Routine Calls ====

The AnimOb and AnimComp structures can include pointers for your own routines that you want the system to call. These pointers are stored in the AnimOb's AnimORoutine field and in the AnimComp's AnimCRoutine field, respectively.

When Animate() is called, the system performs the following steps for every AnimOb in the AnimKey list:

* Updates the AnimOb's location and velocities.
* Calls the AnimOb.AnimORoutine routine if one is supplied.
* Then for each AnimComp of the AnimOb:
** If this sequence times out, switches to the new AnimComp.
** Calls the AnimComp.AnimCRoutine if one is supplied.
** Sets the underlying VSprite's ''x,y'' coordinates.

If you want a routine to be called, you put the address of the routine in either AnimComp.AnimCRoutine or AnimOb.AnimORoutine member as needed. If no routine is to be called, you must set these fields to NULL. Your routines will be passed one parameter, a pointer to the AnimOb or AnimComp it was related to. You can use the user structure extensions discussed earlier to hold the variables you need for your own routines.

For example, if you provide a routine such as this:

<syntaxhighlight lang="C" line>
VOID MyOCode(struct AnimOb *anOb)
{
/* whatever needs to be done */
}
</syntaxhighlight>

Then, if you put the address of the routine in an AnimOb structure:

<syntaxhighlight lang="C" line>
myAnimOb.AnimORoutine = MyOCode;
</syntaxhighlight>

MyOCode() will be called with the address of this AnimOb when Animate() processes this AnimOb.

=== Standard GEL Rules Still Apply ===

Before you use the animation system, you must have called the routine InitGels(). The section called "Bob Priorities" describes how the system maintains the list of GELs to draw on the screen according to their various data fields. The animation system selectively adds GELs to and removes GELs from this list of screen objects during the Animate() routine. On the next call to DrawGList(), the system will draw the GELs in the list into the selected RastPort.

=== Animations Special Numbering System ===

Velocities and accelerations can be either positive or negative. The system treats the velocity, acceleration and Ring values as fixed-point binary fractions, with the decimal point at position 6 in the word. That is: vvvvvvvvvv.ffffff where v stands for actual values that you add to the x or y (AnX, AnY) positions of the object for each call to Animate(), and f stands for the fractional part. By using a fractional part, you can specify the speed of an object in increments as precise as 1/64th of an interval.

If you set the value of XVel at 0x0001, it will take 64 calls to the Animate() routine before the system will modify the object's ''x'' coordinate position by a step of one.

The system constant ANFRACSIZE can be used to shift values correctly. So if you set the value to (1 << ANFRACSIZE), it will be set to 0x0040, the value required to move the object one step per call to Animate().

The system constant ANIMHALF can be used if you want the object to move every other call to Animate().

Each call you make to Animate() simply adds the value of XAccel to the current value of XVel, and YAccel to the current value of YVel, modifying these values accordingly.

=== "animtools.h" and "animtools.c" ===

Here is the listing of the "animtools.h" header file and the "animtools.c" link file used by the examples in this article. The makeSeq() and makeComp() subroutines here demonstrate how to use the GELs animation system.

<pre>
/* animtools.h */
#ifndef GELTOOLS_H
#define GELTOOLS_H

/*
** These data structures are used by the functions in animtools.c to
** allow for an easier interface to the animation system.
*/

/* Data structure to hold information for a new VSprite. */
typedef struct newVSprite {
WORD *nvs_Image; /* image data for the vsprite */
WORD *nvs_ColorSet; /* color array for the vsprite */
SHORT nvs_WordWidth; /* width in words */
SHORT nvs_LineHeight; /* height in lines */
SHORT nvs_ImageDepth; /* depth of the image */
SHORT nvs_X; /* initial x position */
SHORT nvs_Y; /* initial y position */
SHORT nvs_Flags; /* vsprite flags */
USHORT nvs_HitMask; /* Hit mask. */
USHORT nvs_MeMask; /* Me mask. */
} NEWVSPRITE;

/* Data structure to hold information for a new Bob. */
typedef struct newBob {
WORD *nb_Image; /* image data for the bob */
SHORT nb_WordWidth; /* width in words */
SHORT nb_LineHeight; /* height in lines */
SHORT nb_ImageDepth; /* depth of the image */
SHORT nb_PlanePick; /* planes that get image data */
SHORT nb_PlaneOnOff; /* unused planes to turn on */
SHORT nb_BFlags; /* bob flags */
SHORT nb_DBuf; /* 1=double buf, 0=not */
SHORT nb_RasDepth; /* depth of the raster */
SHORT nb_X; /* initial x position */
SHORT nb_Y; /* initial y position */
USHORT nb_HitMask; /* Hit mask. */
USHORT nb_MeMask; /* Me mask. */
} NEWBOB ;

/* Data structure to hold information for a new animation component. */
typedef struct newAnimComp {
WORD (*nac_Routine)(); /* routine called when Comp is displayed. */
SHORT nac_Xt; /* initial delta offset position. */
SHORT nac_Yt; /* initial delta offset position. */
SHORT nac_Time; /* Initial Timer value. */
SHORT nac_CFlags; /* Flags for the Component. */
} NEWANIMCOMP;

/* Data structure to hold information for a new animation sequence. */
typedef struct newAnimSeq {
struct AnimOb *nas_HeadOb; /* common Head of Object. */
WORD *nas_Images; /* array of Comp image data */
SHORT *nas_Xt; /* arrays of initial offsets. */
SHORT *nas_Yt; /* arrays of initial offsets. */
SHORT *nas_Times; /* array of Initial Timer value. */
WORD (**nas_Routines)(); /* Array of fns called when comp drawn */
SHORT nas_CFlags; /* Flags for the Component. */
SHORT nas_Count; /* Num Comps in seq (= arrays size) */
SHORT nas_SingleImage; /* one (or count) images. */
} NEWANIMSEQ;

#define INTUITIONNAME "intuition.library" /* intuitionbase.h does not define a library name. */

#include "animtools_proto.h" /* Include Prototyping. */
#endif

/* animtools_proto.h */
#include <clib/dos_protos.h>
#include <clib/exec_protos.h>
#include <clib/graphics_protos.h>
#include <clib/intuition_protos.h>

struct GelsInfo *setupGelSys(struct RastPort *rPort, BYTE reserved);
VOID cleanupGelSys(struct GelsInfo *gInfo, struct RastPort *rPort);
struct VSprite *makeVSprite(NEWVSPRITE *nVSprite);
struct Bob *makeBob(NEWBOB *nBob);
struct AnimComp *makeComp(NEWBOB *nBob, NEWANIMCOMP *nAnimComp);
struct AnimComp *makeSeq(NEWBOB *nBob, NEWANIMSEQ *nAnimSeq);
VOID freeVSprite(struct VSprite *vsprite);
VOID freeBob(struct Bob *bob, LONG rasdepth);
VOID freeComp(struct AnimComp *myComp, LONG rasdepth);
VOID freeSeq(struct AnimComp *headComp, LONG rasdepth);
VOID freeOb(struct AnimOb *headOb, LONG rasdepth);

/* animtools.c
**
** This file is a collection of tools which are used with the VSprite, Bob and Animation
** system software. It is intended as a useful EXAMPLE, and while it shows what must be
** done, it is not the only way to do it. If Not Enough Memory, or error return, each
** cleans up after itself before returning. NOTE that these routines assume a very specific
** structure to the GEL lists. Make sure that you use the correct pairs together
** (i.e. makeOb()/freeOb(), etc.)
**
** Compile with SAS/C 5.10b: lc -b1 -cfist -v -y -oanimtools.o animtools.c
*/
#include <exec/types.h>
#include <exec/memory.h>
#include <graphics/gfx.h>
#include <graphics/gels.h>
#include <graphics/clip.h>
#include <graphics/rastport.h>
#include <graphics/view.h>
#include <graphics/gfxbase.h>
#include "animtools.h"

/* Setup the GELs system. After this call is made you can use VSprites, Bobs, AnimComps
** and AnimObs. Note that this links the GelsInfo structure into the RastPort, and calls
** InitGels(). It uses information in your RastPort structure to establish boundary collision
** defaults at the outer edges of the raster. This routine sets up for everything - collision
** detection and all. You must already have run LoadView before ReadyGelSys is called.
*/
struct GelsInfo *setupGelSys(struct RastPort *rPort, BYTE reserved)
{
struct GelsInfo *gInfo;
struct VSprite *vsHead;
struct VSprite *vsTail;

if (NULL != (gInfo = (struct GelsInfo *)AllocMem(sizeof(struct GelsInfo), MEMF_CLEAR)))
{
if (NULL != (gInfo->nextLine = (WORD *)AllocMem(sizeof(WORD) * 8, MEMF_CLEAR)))
{
if (NULL != (gInfo->lastColor = (WORD **)AllocMem(sizeof(LONG) * 8, MEMF_CLEAR)))
{
if (NULL != (gInfo->collHandler = (struct collTable *)
AllocMem(sizeof(struct collTable),MEMF_CLEAR)))
{
if (NULL != (vsHead = (struct VSprite *)
AllocMem((LONG)sizeof(struct VSprite), MEMF_CLEAR)))
{
if (NULL != (vsTail = (struct VSprite *)
AllocMem(sizeof(struct VSprite), MEMF_CLEAR)))
{
gInfo->sprRsrvd = reserved;
/* Set left- and top-most to 1 to better keep items */
/* inside the display boundaries. */
gInfo->leftmost = gInfo->topmost = 1;
gInfo->rightmost = (rPort->BitMap->BytesPerRow << 3) - 1;
gInfo->bottommost = rPort->BitMap->Rows - 1;
rPort->GelsInfo = gInfo;
InitGels(vsHead, vsTail, gInfo);
return(gInfo);
}
FreeMem(vsHead, (LONG)sizeof(*vsHead));
}
FreeMem(gInfo->collHandler, (LONG)sizeof(struct collTable));
}
FreeMem(gInfo->lastColor, (LONG)sizeof(LONG) * 8);
}
FreeMem(gInfo->nextLine, (LONG)sizeof(WORD) * 8);
}
FreeMem(gInfo, (LONG)sizeof(*gInfo));
}
return(NULL);
}

/* Free all of the stuff allocated by setupGelSys(). Only call this routine if
** setupGelSys() returned successfully. The GelsInfo structure is the one returned
** by setupGelSys(). It also unlinks the GelsInfo from the RastPort.
*/
VOID cleanupGelSys(struct GelsInfo *gInfo, struct RastPort *rPort)
{
rPort->GelsInfo = NULL;
FreeMem(gInfo->collHandler, (LONG)sizeof(struct collTable));
FreeMem(gInfo->lastColor, (LONG)sizeof(LONG) * 8);
FreeMem(gInfo->nextLine, (LONG)sizeof(WORD) * 8);
FreeMem(gInfo->gelHead, (LONG)sizeof(struct VSprite));
FreeMem(gInfo->gelTail, (LONG)sizeof(struct VSprite));
FreeMem(gInfo, (LONG)sizeof(*gInfo));
}

/* Create a VSprite from the information given in nVSprite. Use freeVSprite()
** to free this GEL.
*/
struct VSprite *makeVSprite(NEWVSPRITE *nVSprite)
{
struct VSprite *vsprite;
LONG line_size;
LONG plane_size;

line_size = sizeof(WORD) * nVSprite->nvs_WordWidth;
plane_size = line_size * nVSprite->nvs_LineHeight;

if (NULL != (vsprite = (struct VSprite *)AllocMem((LONG)sizeof(struct VSprite), MEMF_CLEAR)))
{
if (NULL != (vsprite->BorderLine = (WORD *)AllocMem(line_size, MEMF_CHIP)))
{
if (NULL != (vsprite->CollMask = (WORD *)AllocMem(plane_size, MEMF_CHIP)))
{
vsprite->Y = nVSprite->nvs_Y;
vsprite->X = nVSprite->nvs_X;
vsprite->Flags = nVSprite->nvs_Flags;
vsprite->Width = nVSprite->nvs_WordWidth;
vsprite->Depth = nVSprite->nvs_ImageDepth;
vsprite->Height = nVSprite->nvs_LineHeight;
vsprite->MeMask = nVSprite->nvs_MeMask;
vsprite->HitMask = nVSprite->nvs_HitMask;
vsprite->ImageData = nVSprite->nvs_Image;
vsprite->SprColors = nVSprite->nvs_ColorSet;
vsprite->PlanePick = vsprite->PlaneOnOff = 0x00;
InitMasks(vsprite);
return(vsprite);
}
FreeMem(vsprite->BorderLine, line_size);
}
FreeMem(vsprite, (LONG)sizeof(*vsprite));
}
return(NULL);
}

/* Create a Bob from the information given in nBob. Use freeBob() to free this GEL.
** A VSprite is created for this bob. This routine properly allocates all double
** buffered information if it is required.
*/
struct Bob *makeBob(NEWBOB *nBob)
{
struct Bob *bob;
struct VSprite *vsprite;
NEWVSPRITE nVSprite ;
LONG rassize;

rassize = (LONG)sizeof(UWORD) * nBob->nb_WordWidth * nBob->nb_LineHeight * nBob->nb_RasDepth;

if (NULL != (bob = (struct Bob *)AllocMem((LONG)sizeof(struct Bob), MEMF_CLEAR)))
{
if (NULL != (bob->SaveBuffer = (WORD *)AllocMem(rassize, MEMF_CHIP)))
{
nVSprite.nvs_WordWidth = nBob->nb_WordWidth;
nVSprite.nvs_LineHeight = nBob->nb_LineHeight;
nVSprite.nvs_ImageDepth = nBob->nb_ImageDepth;
nVSprite.nvs_Image = nBob->nb_Image;
nVSprite.nvs_X = nBob->nb_X;
nVSprite.nvs_Y = nBob->nb_Y;
nVSprite.nvs_ColorSet = NULL;
nVSprite.nvs_Flags = nBob->nb_BFlags;
/* Push the values into the NEWVSPRITE structure for use in makeVSprite(). */
nVSprite.nvs_MeMask = nBob->nb_MeMask;
nVSprite.nvs_HitMask = nBob->nb_HitMask;

if ((vsprite = makeVSprite(&nVSprite)) != NULL)
{
vsprite->PlanePick = nBob->nb_PlanePick;
vsprite->PlaneOnOff = nBob->nb_PlaneOnOff;
vsprite->VSBob = bob;
bob->BobVSprite = vsprite;
bob->ImageShadow = vsprite->CollMask;
bob->Flags = 0;
bob->Before = NULL;
bob->After = NULL;
bob->BobComp = NULL;

if (nBob->nb_DBuf)
{
if (NULL != (bob->DBuffer = (struct DBufPacket *)
AllocMem((LONG)sizeof(struct DBufPacket), MEMF_CLEAR)))
{
if (NULL != (bob->DBuffer->BufBuffer = (WORD *)AllocMem(rassize, MEMF_CHIP)))
return(bob);
FreeMem(bob->DBuffer, (LONG)sizeof(struct DBufPacket));
}
}
else
{
bob->DBuffer = NULL;
return(bob);
}
freeVSprite(vsprite);
}
FreeMem(bob->SaveBuffer, rassize);
}
FreeMem(bob, (LONG)sizeof(*bob));
}
return(NULL);
}

/*
** Create a Animation Component from the information given in nAnimComp and nBob. Use
** freeComp() to free this GEL. makeComp() calls makeBob(), and links the Bob into an AnimComp.
*/
struct AnimComp *makeComp(NEWBOB *nBob, NEWANIMCOMP *nAnimComp)
{
struct Bob *compBob;
struct AnimComp *aComp;

if ((aComp = AllocMem((LONG)sizeof(struct AnimComp),MEMF_CLEAR)) != NULL)
{
if ((compBob = makeBob(nBob)) != NULL)
{
compBob->After = compBob->Before = NULL;
compBob->BobComp = aComp; /* Link 'em up. */
aComp->AnimBob = compBob;
aComp->TimeSet = nAnimComp->nac_Time; /* Num ticks active. */
aComp->YTrans = nAnimComp->nac_Yt; /* Offset rel to HeadOb */
aComp->XTrans = nAnimComp->nac_Xt;
aComp->AnimCRoutine = nAnimComp->nac_Routine;
aComp->Flags = nAnimComp->nac_CFlags;
aComp->Timer = 0;
aComp->NextSeq = aComp->PrevSeq = NULL;
aComp->NextComp = aComp->PrevComp = NULL;
aComp->HeadOb = NULL;
return(aComp);
}
FreeMem(aComp, (LONG)sizeof(struct AnimComp));
}
return(NULL);
}

/* Create an Animation Sequence from the information given in nAnimSeq and nBob. Use
** freeSeq() to free this GEL. This routine creates a linked list of animation components
** which make up the animation sequence. It links them all up, making a circular list of
** the PrevSeq and NextSeq pointers. That is to say, the first component of the sequences'
** PrevSeq points to the last component; the last component of * the sequences' NextSeq
** points back to the first component. If dbuf is on, the underlying Bobs will be set up
** for double buffering. If singleImage is non-zero, the pImages pointer is assumed to
** point to an array of only one image, instead of an array of 'count' images, and all
** Bobs will use the same image.
*/
struct AnimComp *makeSeq(NEWBOB *nBob, NEWANIMSEQ *nAnimSeq)
{
int seq;
struct AnimComp *firstCompInSeq = NULL;
struct AnimComp *seqComp = NULL;
struct AnimComp *lastCompMade = NULL;
LONG image_size;
NEWANIMCOMP nAnimComp;

/* get the initial image. this is the only image that is used
** if nAnimSeq->nas_SingleImage is non-zero.
*/
nBob->nb_Image = nAnimSeq->nas_Images;
image_size = nBob->nb_LineHeight * nBob->nb_ImageDepth * nBob->nb_WordWidth;

/* for each comp in the sequence */
for (seq = 0; seq < nAnimSeq->nas_Count; seq++)
{
nAnimComp.nac_Xt = *(nAnimSeq->nas_Xt + seq);
nAnimComp.nac_Yt = *(nAnimSeq->nas_Yt + seq);
nAnimComp.nac_Time = *(nAnimSeq->nas_Times + seq);
nAnimComp.nac_Routine = nAnimSeq->nas_Routines[seq];
nAnimComp.nac_CFlags = nAnimSeq->nas_CFlags;
if ((seqComp = makeComp(nBob, &nAnimComp)) == NULL)
{
if (firstCompInSeq != NULL)
freeSeq(firstCompInSeq, (LONG)nBob->nb_RasDepth);
return(NULL);
}
seqComp->HeadOb = nAnimSeq->nas_HeadOb;
/* Make a note of where the first component is. */
if (firstCompInSeq == NULL) firstCompInSeq = seqComp;
/* link the component into the list */
if (lastCompMade != NULL) lastCompMade->NextSeq = seqComp;
seqComp->NextSeq = NULL;
seqComp->PrevSeq = lastCompMade;
lastCompMade = seqComp;
/* If nAnimSeq->nas_SingleImage is zero, the image array has nAnimSeq->nas_Count images. */
if (!nAnimSeq->nas_SingleImage)
nBob->nb_Image += image_size;
}
/* On The last component in the sequence, set Next/Prev to make */
/* the linked list a loop of components. */
lastCompMade->NextSeq = firstCompInSeq;
firstCompInSeq->PrevSeq = lastCompMade;

return(firstCompInSeq);
}

/* Free the data created by makeVSprite(). Assumes images deallocated elsewhere. */
VOID freeVSprite(struct VSprite *vsprite)
{
LONG line_size;
LONG plane_size;

line_size = (LONG)sizeof(WORD) * vsprite->Width;
plane_size = line_size * vsprite->Height;
FreeMem(vsprite->BorderLine, line_size);
FreeMem(vsprite->CollMask, plane_size);
FreeMem(vsprite, (LONG)sizeof(*vsprite));
}

/* Free the data created by makeBob(). It's important that rasdepth match the depth you */
/* passed to makeBob() when this GEL was made. Assumes images deallocated elsewhere. */
VOID freeBob(struct Bob *bob, LONG rasdepth)
{
LONG rassize = sizeof(UWORD) * bob->BobVSprite->Width * bob->BobVSprite->Height * rasdepth;

if (bob->DBuffer != NULL)
{
FreeMem(bob->DBuffer->BufBuffer, rassize);
FreeMem(bob->DBuffer, (LONG)sizeof(struct DBufPacket));
}
FreeMem(bob->SaveBuffer, rassize);
freeVSprite(bob->BobVSprite);
FreeMem(bob, (LONG)sizeof(*bob));
}

/* Free the data created by makeComp(). It's important that rasdepth match the depth you */
/* passed to makeComp() when this GEL was made. Assumes images deallocated elsewhere. */
VOID freeComp(struct AnimComp *myComp, LONG rasdepth)
{
freeBob(myComp->AnimBob, rasdepth);
FreeMem(myComp, (LONG)sizeof(struct AnimComp));
}

/* Free the data created by makeSeq(). Complimentary to makeSeq(), this routine goes through
** the NextSeq pointers and frees the Components. This routine only goes forward through the
** list, and so it must be passed the first component in the sequence, or the sequence must
** be circular (which is guaranteed if you use makeSeq()). It's important that rasdepth match
** the depth you passed to makeSeq() when this GEL was made. Assumes images deallocated elsewhere!
*/
VOID freeSeq(struct AnimComp *headComp, LONG rasdepth)
{
struct AnimComp *curComp;
struct AnimComp *nextComp;

/* Break the NextSeq loop, so we get a NULL at the end of the list. */
headComp->PrevSeq->NextSeq = NULL;

curComp = headComp; /* get the start of the list */
while (curComp != NULL)
{
nextComp = curComp->NextSeq;
freeComp(curComp, rasdepth);
curComp = nextComp;
}
}

/* Free an animation object (list of sequences). freeOb() goes through the NextComp
** pointers, starting at the AnimObs' HeadComp, and frees every sequence. It only
** goes forward. It then frees the Object itself. Assumes images deallocated elsewhere!
*/
VOID freeOb(struct AnimOb *headOb, LONG rasdepth)
{
struct AnimComp *curSeq;
struct AnimComp *nextSeq;

curSeq = headOb->HeadComp; /* get the start of the list */
while (curSeq != NULL)
{
nextSeq = curSeq->NextComp;
freeSeq(curSeq, rasdepth);
curSeq = nextSeq;
}
FreeMem(headOb, sizeof(struct AnimOb));
}
</pre>

== Function Reference ==

The following are brief descriptions of the Amiga's graphics animation functions. See the SDK for details on each function call.

{| class="wikitable"
! Animation Function
! Description
|-
| AddAnimOb()
| Add an AnimOb to the linked list of AnimObs.
|-
| AddBob()
| Add a Bob to the current GEL list.
|-
| AddVSprite()
| Add a VSprite to the current GEL list.
|-
| Animate()
| Process every AnimOb in the current animation list.
|-
| ChangeSprite()
| Change the sprite image pointer.
|-
| DoCollision()
| Test every GEL in a GEL list for collisions.
|-
| DrawGList()
| Process the GEL list, queueing VSprites, drawing Bobs.
|-
| FreeGBuffers()
| Deallocate memory obtained by GetGBuffers().
|-
| FreeSprite()
| Return sprite for use by others and virtual sprite machine.
|-
| GetGBuffers()
| Attempt to allocate all buffers of an entire AnimOb.
|-
| GetSprite()
| Attempt to get a sprite for the simple sprite manager.
|-
| InitGels()
| Initialize a GEL list; must be called before using GELs.
|-
| InitGMasks()
| Initialize all of the masks of an AnimOb.
|-
| InitMasks()
| Initialize the BorderLine and CollMask masks of a VSprite.
|-
| MoveSprite()
| Move sprite to a point relative to top of ViewPort.
|-
| RemBob()
| Remove a Bob from the GEL list.
|-
| RemIBob()
| Immediately remove a Bob from the GEL list and the RastPort.
|-
| RemVSprite()
| Remove a VSprite from the current GEL list.
|-
| SetCollision()
| Set a pointer to a user collision routine.
|-
| SortGList()
| Sort the current GEL list, ordering its ''x,y'' coordinates.
|}

Cooperative Record Locking

2025-01-26T19:30:20Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

== Description ==

The Amiga's cooperative record locking scheme allows an application to lock regions of a file rather than locking an entire file. These regions are known as records.

The Amiga thinks of a record in terms of size and offset. The size refers to the length of the record in bytes. The offset refers to
the starting position of the record from the beginning of the file. The size and offset can vary from record to record. The only limit
on a record's size and offset are the limits the file system has on the size of the file.

== File System or DOS? ==

Starting with version 53.x of the DOS Library (dos.library), the record locking feature is handled entirely by AmigaDOS. DOS record locking is independent of the file system and is always available. Prior to this version, record locking was available only if each individual file system implemented the feature. If a file system does not record locking, the record locking functions described below will always fail.

== Record Lock Types ==

There are two basic types of record lock, exclusive and shared. An exclusive lock gives an application exclusive access to a record. While an application holds an exclusive record lock, no other process can obtain a record lock that overlaps the exclusively locked region. The file system can only grant an exclusive record lock on a region that is not part of an existing record lock.

The other type of record lock, the shared lock, gives an application shared access to a record. While an application holds a shared
record lock, other applications can also obtain a shared record lock that overlaps the original shared record lock, but no other process can obtain an exclusive record lock that overlaps the shared record lock.

== Locking and Unlocking Records ==

To lock (or unlock) a record within a file, an application needs a valid file handle on the file. Two DOS Library functions handle
individual record locks:

<syntaxhighlight lang="C" line>
BOOL LockRecord(BPTR myFH, ULONG my_offset, ULONG my_length, ULONG my_mode, ULONG my_timeout);
BOOL UnLockRecord(BPTR myFH, ULONG my_offset, ULONG my_length);
</syntaxhighlight>

In both functions, the myFH field refers to the valid file handle mentioned above, and the my_offset and my_length fields refer to the
record's offset and size.

The LockRecord() function has two additional parameters: my_mode and my_timeout. The my_mode field refers to the type of record. DOS supports four record types:

; REC_EXCLUSIVE
: Create an exclusive record lock. If the record is not immediately available, the file system will make a second record lock attempt when the timeout expires. The timeout (the my_timeout field from the RecordLock() prototype above) is in DOS ticks (1/50 of a second).

; REC_EXCLUSIVE_IMMED
: This record type is like REC_EXCLUSIVE, but the attempt to lock a record will fail if the record is not immediately available. In this case the file system ignores the timeout.

; REC_SHARED
: Create a shared record lock. If the record is not immediately available, the file system will make a second record lock attempt when the timeout expires. The timeout (the my_timeout field from the RecordLock() prototype above) is in DOS ticks (1/50th of a second).

; REC_SHARED_IMMED
: This record type is like REC_SHARED, but the attempt to lock a record will fail if the record is not immediately available. In this case the file system ignores the timeout.

The Amiga record locking scheme is cooperative--the file system does not prevent any process from accessing any part of a data
file. The record locking scheme has nothing to do with other actions of a file system. The file system will let other processes read and write a data file regardless of any existing record locks on the data file.

Also, when an application attempts to create a record lock, the file system's record locking mechanism only makes sure the record won't
conflict with any existing record locks on the same data file. The file system doesn't check the validity of the locked region. This
makes it possible to lock records in an empty data file and also to lock records that are well beyond the end of a data file. This
feature may be useful to an application that needs to lock records that don't exist yet.

When releasing a record lock, an application must provide exactly the same parameters it used when it locked the record. Attempting to
unlock a record using a different offset or length will fail. If the application does not successfully unlock a record, the record lock
will remain in effect. This means further requests to lock that record can fail, depending on the type of record lock. The record
lock will remain in effect until the data file is removed or the system restarted. As with most Amiga resources, an application
should release a record lock as quickly as possible. This helps out other applications that might be waiting to access the locked record.

== Locking Multiple Records ==

DOS Library offers a function to lock an array of record locks:

<syntaxhighlight lang="C" line>
BOOL LockRecords(struct RecordLock *recordarray, ULONG multi_timeout);
</syntaxhighlight>

LockRecords() locks a group of records using one function call. LockRecords() accepts a pointer to an array of RecordLock structures
(as defined in <dos/record.h>):

<syntaxhighlight lang="C" line>
struct RecordLock {
BPTR rec_FH; /* The file handle of the data file */
ULONG rec_Offset; /* The record offset in the data file */
ULONG rec_Length; /* The length of the record */
ULONG rec_Mode; /* The mode of the record lock */
};
</syntaxhighlight>

The fields in each RecordLock structure correspond to the parameters from the LockRecord() function. The records do not have to be in the same file. The array is terminated by a dummy RecordLock with a NULL file handle (rec_FH).

The RecordLock structure does not include a timeout. Instead, LockRecords() applies the same timeout (multi_timeout from the LockRecords() prototype above) to each RecordLock in the array. If LockRecords() fails to lock any of the records in its array, LockRecords() releases any successful record locks from the array, and return DOSFALSE.

To unlock records locked by LockRecords(), use the dos.library function UnLockRecords():

<syntaxhighlight lang="C" line>
BOOL UnLockRecords(struct RecordLock *recordarray);
</syntaxhighlight>

This function accepts the same array used to lock the records with LockRecords().

Note that it is possible to use UnLockRecord() on a record locked by LockRecords(). However, if an application uses UnLockRecord() to
unlock one record in the RecordLock array, it should use UnLockRecord() to unlock all of the records in the array.

== Locking Records Using DOS Packets ==

{{Note|title=Don't use DOS Packets|text=DOS Library now handles record locking as of version 53.?? so that file systems are no longer burdened with implementing this functionality. The information below is being provided for reference and for users of previous versions of the DOS Library.}}

To lock a record using the DOS packet interface, send an ACTION_LOCK_RECORD (2008) packet to the file system. This packet uses the following arguments:

<pre>
ARG1: BTPR The file handle of the data file in which you wish to lock a record.
ARG2: ULONG The offset (in bytes) in the file of the record.
ARG3: ULONG The length (in bytes) of the record.
ARG4: ULONG The mode with which you wish to lock record.
ARG5: ULONG Time (in ticks) you are will to wait for the record to become available.

RES1: BOOL Upon return RES1 will contain the success/failure status:
DOSTRUE if the record lock was successfully locked.
DOSFALSE if the record lock failed.
RES2: CODE Failure code if the record lock failed for a reason other than denied
access (collision for example).
</pre>

To unlock a record using the DOS packet interface, send an ACTION_FREE_RECORD (2009) packet. This packet uses the following arguments:

<pre>
ARG1: BPTR The file handle of the data file in which you locked the record.
ARG2: ULONG The offset (in bytes) in the file of the record with which you locked
the record.
ARG3: ULONG The length (in bytes) of the record with which you locked the record.

RES1: BOOL Upon return RES1 will contain the success/failure status:
DOSTRUE if the record lock was successfully unlocked.
DOSFALSE if there was no lock to unlock.
RES2: CODE Possible failure code if the record lock could not be unlocked.
</pre>

== Examples ==

=== LockRecord.c ===

<syntaxhighlight lang="C" line>
// LockRecord.c
//
// LockRecord()/UnLockRecord() example.

#include <exec/memory.h>
#include <exec/lists.h>
#include <dos/dosextens.h>
#include <dos/rdargs.h>
#include <dos/record.h>
#include <utility/tagitem.h>

#include <proto/dos.h>
#include <proto/exec.h>
#include <proto/utility.h>

void GetCommandLine(BPTR, struct RDArgs *rdargs, UBYTE *cmdbuffer);
void DoLockRecord(BPTR, struct RDArgs *rdargs);
void DoUnLockRecord(BPTR fh, struct RDArgs *rdargs);
void ListRecordLocks(void);
struct LockNode *FindRecordLock(ULONG offset, ULONG length);

/* List and node structures to keep track of record locks */
struct LockNode {
struct LockNode *ln_Succ;
struct LockNode *ln_Pred;
ULONG ln_Counter;
ULONG ln_Offset;
ULONG ln_Length;
ULONG ln_Mode;
};

struct LockList {
struct LockNode *lh_Head;
struct LockNode *lh_Tail;
struct LockNode *lh_TailPred;
ULONG lh_Counter;
};

/* Pseudo data file */
#define TESTFILE "t:locktest"

#define LOCK_TEMPLATE "OFFSET/K/N,LENGTH/K/N,EXCLUSIVE/S,IMMEDIATE/S,TIMEOUT/K/N"
#define UNLOCK_TEMPLATE "OFFSET/K/N,LENGTH/K/N"

#define OFFSET_POS 0
#define LENGTH_POS 1
#define EXCLUSIVE_POS 2
#define IMMEDIATE_POS 3
#define TIMEOUT_POS 4

struct LockList *locklist;

int main()
{
BPTR fh;
struct RDArgs *rdargs;
struct CSource *csource;
UBYTE *cmdbuffer;
struct LockNode *lnode, *nnode;
LONG error = RETURN_OK;

if (locklist = AllocVecTags(sizeof(struct LockList), AVT_ClearWithValue, 0, TAG_END))
{
IExec->NewList((struct List *)locklist);

/* Allocate RDArgs structure to parse command lines */
if (rdargs = IDOS->AllocDosObject(DOS_RDARGS, TAG_END))
{
csource = &rdargs->RDA_Source;

/* Get buffer to read command lines in */
if (csource->CS_Buffer = IExec->AllocVecTags(512, AVT_ClearWithValue, 0, TAG_END))
{
csource->CS_Length = 512;
csource->CS_CurChr = 0;

/* Buffer to isolate command keyword */
if (cmdbuffer = IExec->AllocVecTags(80, AVT_ClearWithValue, 0, TAG_END))
{
/* Open a testfile, create it if necessary */
if (fh = IDOS->Open(TESTFILE, MODE_READWRITE))
{
/* Process command lines */
GetCommandLine(fh, rdargs, cmdbuffer);

/* Try to get rid of outstanding record locks */
lnode = locklist->lh_Head;
while (nnode = lnode->ln_Succ)
{
/* Try to unlock pending locks */
if ((IDOS->UnLockRecord(fh,
lnode->ln_Offset,
lnode->ln_Length)) == DOSFALSE)
{
IDOS->Printf("Error unlocking record %ld with offset %ld length %ld\n",
lnode->ln_Counter,
lnode->ln_Offset,
lnode->ln_Length);
if (IDOS->IoErr())
IDOS->PrintFault(IDOS->IoErr(), NULL);
}
/* Remove node no matter what */
IExec->FreeVec(lnode);
lnode = nnode;
};

IDOS->Close(fh);
}
IExec->FreeVec(cmdbuffer);
} else
IDOS->SetIoErr(ERROR_NO_FREE_STORE);

IExec->FreeVec(csource->CS_Buffer);
} else
IDOS->SetIoErr(ERROR_NO_FREE_STORE);

IDOS->FreeDosObject(DOS_RDARGS, rdargs);
} else
IDOS->SetIoErr(ERROR_NO_FREE_STORE);

IExec->FreeVec(locklist);
} else
IDOS->SetIoErr(ERROR_NO_FREE_STORE);

error = IDOS->IoErr();
if (error)
{
IDOS->PrintFault(IDOS->IoErr(), NULL);
error = RETURN_FAIL;
}

return(error);
}

void GetCommandLine(BPTR fh, struct RDArgs *rdargs, UBYTE *cmdbuffer)
{
struct CSource *csource = &rdargs->RDA_Source;
UBYTE *cmdlinebuffer = csource->CS_Buffer;
LONG error;

/* Prompt for command line */
IDOS->Write(IDOS->Output(), "Cmd> ", 5);

/* Loop forever, waiting for commands */
for (;;)
{
/* Get command line */
if ((IDOS->FGets(IDOS->Input(), cmdlinebuffer, 512)) != NULL)
{
/* Use ReadItem() to isolate actual command */
error = IDOS->ReadItem(cmdbuffer, 80, csource);

/* Break on error */
if (error == ITEM_ERROR)
break;

/* Make sure I've got something */
else if (error != ITEM_NOTHING)
{
/* cmdbuffer now contains the command:
*
* KNOWN COMMANDS:
* QUIT
* LIST
* LOCKRECORD
* UNLOCKRECORD
*/
if ((IUtility->Stricmp("QUIT", cmdbuffer)) == 0)
break;
else if ((IUtility->Stricmp("HELP", cmdbuffer)) == 0)
{
IDOS->Printf("Available commands:\n");
IDOS->Printf("LOCKRECORD %s\n", LOCK_TEMPLATE);
IDOS->Printf("UNLOCKRECORD %s\n", UNLOCK_TEMPLATE);
IDOS->Printf("LIST\n");
IDOS->Printf("QUIT\n");
}
else if ((IUtility->Stricmp("LIST", cmdbuffer)) == 0)
ListRecordLocks(); /* Show all current locks */
else
{
/* Note that I've already isolated the command
* keyword, so I'm using Source->CS_CurChr to point
* after it.
*/
csource->CS_Buffer += csource->CS_CurChr;
csource->CS_CurChr = 0;

if ((IUtility->Stricmp("LOCKRECORD", cmdbuffer)) == 0)
DoLockRecord(fh, rdargs);
else if ((IUtility->Stricmp("UNLOCKRECORD", cmdbuffer)) == 0)
DoUnLockRecord(fh, rdargs);
else
IDOS->PrintFault(ERROR_NOT_IMPLEMENTED, cmdbuffer);

/* Reset CSource */
csource->CS_Buffer = cmdlinebuffer;
}

/* Output new prompt. Make sure csource is OK. */
IDOS->Write(IDOS->Output(), "Cmd> ", 5);
csource->CS_CurChr = 0;
}
} else
break;
}
}

void DoLockRecord(BPTR fh, struct RDArgs *rdargs)
{
struct RDArgs *readargs;
LONG rargs[5];
ULONG offset, length, timeout, mode;
ULONG result;
struct LockNode *lnode;

offset = length = timeout = mode = 0;
rargs[0] = rargs[1] = rargs[2] = rargs[3] = rargs[4] = 0;

if (readargs = IDOS->ReadArgs(LOCK_TEMPLATE, rargs, rdargs))
{
if (rargs[OFFSET_POS])
offset = *((LONG *)rargs[OFFSET_POS]);
if (rargs[LENGTH_POS])
length = *((LONG *)rargs[LENGTH_POS]);
if (rargs[TIMEOUT_POS])
timeout = *((LONG *)rargs[TIMEOUT_POS]);

/* Type of locking */
if (rargs[EXCLUSIVE_POS])
{
if (rargs[IMMEDIATE_POS])
mode = REC_EXCLUSIVE_IMMED;
else
mode = REC_EXCLUSIVE;
}
else
{
if (rargs[IMMEDIATE_POS])
mode = REC_SHARED_IMMED;
else
mode = REC_SHARED;
}

rargs[0] = offset;
rargs[1] = length;
switch (mode)
{
case REC_EXCLUSIVE_IMMED:
rargs[2] = (LONG)"REC_EXCLUSIVE_IMMED";
break;
case REC_EXCLUSIVE:
rargs[2] = (LONG)"REC_EXCLUSIVE";
break;
case REC_SHARED_IMMED:
rargs[2] = (LONG)"REC_SHARED_IMMED";
break;
case REC_SHARED:
rargs[2] = (LONG)"REC_SHARED";
break;
}
rargs[3] = timeout;

/* Show what I'm going to do */
IUtility->VFPrintf(Output(),
"LockRecord: Offset %ld, Length %ld, Mode %s, Timeout %ld...",
rargs);
IDOS->FFlush(IDOS->Output());

/* Lock the record. Parameters are not checked. It is f.e. possible to
* specify an offset larger than the size of the file. Possible since
* Record Locks are not related to the file itself, only the means for
* you to do arbitration.
*
* Note that the timeout value is in ticks...
*/
result = IDOS->LockRecord(fh, offset, length, mode, timeout);

if (result == DOSTRUE)
{
IDOS->Write(IDOS->Output(), "OK\n", 3);

/* Add a node to track this record lock */
if (lnode = IExec->AllocVec(sizeof(struct LockNode), AVT_ClearWithValue, 0, TAG_END))
{
lnode->ln_Counter = locklist->lh_Counter++;
lnode->ln_Offset = offset;
lnode->ln_Length = length;
lnode->ln_Mode = mode;

IExec->AddTail((struct List *)locklist, (struct Node *)lnode);
}
else
{
/* Not enough memory for node. You're on your own... */
IDOS->Write(IDOS->Output(), "Not enough memory to track record lock.\n", 40);
}
}
else
{
IDOS->Write(IDOS->Output(), "FAILED\n", 7);
if (IDOS->IoErr())
IDOS->PrintFault(IDOS->IoErr(), NULL);
}

/* Release memory associated with readargs */
IDOS->FreeArgs(readargs);
} else
IDOS->PrintFault(IDOS->IoErr(), NULL);
}

void DoUnLockRecord(BPTR fh, struct RDArgs *rdargs)
{
struct RDArgs *readargs;
LONG rargs[2];
ULONG offset, length;
ULONG result;
struct LockNode *lnode;

offset = length = 0;
rargs[0] = rargs[1] = 0;

if (readargs = IDOS->ReadArgs(LOCK_TEMPLATE, rargs, rdargs))
{
if (rargs[OFFSET_POS])
offset = *((LONG *)rargs[OFFSET_POS]);
if (rargs[LENGTH_POS])
length = *((LONG *)rargs[LENGTH_POS]);

rargs[0] = offset;
rargs[1] = length;

/* Show what I'm going to do */
IUtility->VFPrintf(Output(), "UnLockRecord: Offset %ld, Length %ld...", rargs);
IDOS->FFlush(IDOS->Output());

/* Unlock indicated record with indicated offset and length.
* If the same record (same offset/length) is locked multiple times,
* only one, the first one in the list , will be unlocked.
*/
result = IDOS->UnLockRecord(fh, offset, length);

if (result == DOSTRUE) {
IDOS->Write(IDOS->Output(), "OK\n", 3);

/* Remove node associated with this lock */
if (lnode = FindRecordLock(offset, length))
{
IExec->Remove((struct Node *)lnode);
FreeVec(lnode);
}
}
else
{
IDOS->Write(IDOS->Output(), "FAILED\n", 7); /* Keep locknode */
if (IDOS->IoErr())
IDOS->PrintFault(IDOS->IoErr(), NULL);
}
/* Release memory associated with readargs */
IDOS->FreeArgs(readargs);
} else
IDOS->PrintFault(IDOS->IoErr(), NULL);
}

void ListRecordLocks(void)
{
struct LockNode *lnode;
LONG rargs[4];

for (lnode = locklist->lh_Head; lnode->ln_Succ; lnode = lnode->ln_Succ)
{
rargs[0] = lnode->ln_Counter;
rargs[1] = lnode->ln_Offset;
rargs[2] = lnode->ln_Length;

switch (lnode->ln_Mode)
{
case REC_EXCLUSIVE_IMMED:
rargs[3] = (LONG)"REC_EXCLUSIVE_IMMED";
break;
case REC_EXCLUSIVE:
rargs[3] = (LONG)"REC_EXCLUSIVE";
break;
case REC_SHARED_IMMED:
rargs[3] = (LONG)"REC_SHARED_IMMED";
break;
case REC_SHARED:
rargs[3] = (LONG)"REC_SHARED";
break;
}

IUtility->VFPrintf(IDOS->Output(), "RecordLock #%ld: Offset %ld Length %ld Mode %s\n", rargs);
}
IDOS->FFlush(IDOS->Output());
}

struct LockNode *FindRecordLock(ULONG offset, ULONG length)
{
struct LockNode *lnode;

for (lnode = locklist->lh_Head; lnode->ln_Succ; lnode = lnode->ln_Succ)
{
if ((lnode->ln_Offset == offset) && lnode->ln_Length == length)
return(lnode);
}
return(NULL);
}
</syntaxhighlight>

=== ExRecLock1.c ===

<syntaxhighlight lang="C" line>
// ExRecLock1.c
//
// This is a simple example of using record locking to create an exclusive record
// lock on a file, and writing to that record. The example ExRecLock2 is almost
// exactly the same as this example, except ExRecLock2 uses the record lock directly
// after ExRecLock1's record. If you try to run ExRecLock1 (or ExRecLock2) while
// another instance of ExRecLock1 (or ExRecLock2) is running, the second record lock
// attempt will fail.

#include <protob/dos.h>

#define RECORDSIZE 12
#define RECORDOFFSET 0

UBYTE *string = "ExRecLock1\n"; /* This string will be the */
/* contents of the record. */
int main()
{
BPTR fh;

if (fh = IDOS->Open("t:testRLock", MODE_READWRITE)) /* Open the file, creating */
{ /* it if necessary. */
if (DOSTRUE == IDOS->LockRecord(fh, /* Lock the record as exclusive, */
RECORDOFFSET, /* and do not wait if it is not */
RECORDSIZE, /* available immediately. */
REC_EXCLUSIVE_IMMED, 0))
{
LONG error = RECORDOFFSET;

/* If the record is beyond the end of the file, */
if (IDOS->Seek(fh, 0, OFFSET_END) < RECORDOFFSET) /* lengthen the file. */
error = IDOS->SetFileSize(fh, RECORDOFFSET, OFFSET_BEGINNING);

if (error == RECORDOFFSET) /* If there was no error with the file */
{ /* file size, continue. */
if (IDOS->Seek(fh, RECORDOFFSET, OFFSET_BEGINNING) < 0)
IDOS->PrintFault(IDOS->IoErr(), "Seek() error");

if (IDOS->Write(fh, string, RECORDSIZE) < 0)
IDOS->PrintFault(IDOS->IoErr(), "Write() error");
else
IDOS->PutStr("Write successful, ");
}
IDOS->PutStr("Waiting 10 seconds...\n");
IDOS->Delay(10 * 50);
IDOS->UnLockRecord(fh, RECORDOFFSET, RECORDSIZE);
}
else IDOS->PrintFault(IDOS->IoErr(), "Record Lock Failed");
IDOS->Close(fh);
}
else IDOS->PrintFault(IDOS->IoErr(), "Open Failed");
}
</syntaxhighlight>

=== ExRecLock2.c ===

<syntaxhighlight lang="C" line>
// ExRecLock2.c
//
// This is a simple example of using record locking to create an exclusive record
// lock on a file, and writing to that record. The example ExRecLock1 is almost
// exactly the same as this example, except ExRecLock1 uses the record lock directly
// before ExRecLock2's record. If you try to run ExRecLock2 (or ExRecLock1) while
// another instance of ExRecLock2 (or ExRecLock1) is running, the second record lock
// attempt will fail.

#include <proto/dos.h>

#define RECORDSIZE 12
#define RECORDOFFSET 12

UBYTE *string = "ExRecLock2\n"; /* This string will be the */
/* contents of the record. */
int main()
{
BPTR fh;

if (fh = IDOS->Open("t:testRLock", MODE_READWRITE)) /* Open the file, creating */
{ /* it if necessary. */
if (DOSTRUE == IDOS->LockRecord(fh, /* Lock the record as exclusive, */
RECORDOFFSET, /* and do not wait if it is not */
RECORDSIZE, /* available immediately. */
REC_EXCLUSIVE_IMMED, 0))
{
LONG error = RECORDOFFSET;

/* If the record is beyond the end of the file, */
if (IDOS->Seek(fh, 0, OFFSET_END) < RECORDOFFSET) /* lengthen the file. */
error = IDOS->SetFileSize(fh, RECORDOFFSET, OFFSET_BEGINNING);

if (error == RECORDOFFSET) /* If there was no error with the file */
{ /* file size, continue. */
if (IDOS->Seek(fh, RECORDOFFSET, OFFSET_BEGINNING) < 0)
IDOS->PrintFault(IDOS->IoErr(), "Seek() error");

if (IDOS->Write(fh, string, RECORDSIZE) < 0)
IDOS->PrintFault(IDOS->IoErr(), "Write() error");
else
IDOS->PutStr("Write successful, ");
}
IDOS->PutStr("Waiting 10 seconds...\n");
IDOS->Delay(10 * 50);
IDOS->UnLockRecord(fh, RECORDOFFSET, RECORDSIZE);
}
else IDOS->PrintFault(IDOS->IoErr(), "Record Lock Failed");
IDOS->Close(fh);
}
else IDOS->PrintFault(IDOS->IoErr(), "Open Failed");
}
</syntaxhighlight>

Exec Interrupts

2025-01-26T19:30:08Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

{{NeedUpdate}}{{CodeReview}}
== Exec Interrupts ==

== Interrupts ==

Exec manages the decoding, dispatching, and sharing of all system interrupts. This includes control of hardware interrupts, software interrupts, task-relative interrupts (see the discussion of exceptions in [[Exec_Tasks|Exec Tasks]]), and interrupt disabling and enabling. In addition, Exec supports a more extended prioritization of interrupts than that provided in the CPU.

The proper operation of multitasking depends heavily on the consistent management of the interrupt system. Task activities are often driven by inter-system communication that is originated by various interrupts.

=== Sequence of Events During an Interrupt ===

Before useful interrupt handling code can be executed, a considerable amount of hardware and software activity must occur. Each interrupt must propagate through several hardware and software interfaces before application code is finally dispatched:

<ul>

<li>A hardware device decides to cause an interrupt and sends a signal to the interrupt control portions of the ''4703'' (Paula) custom chip.
</li>

<li>The ''4703'' interrupt control logic notices this new signal and performs two primary operations. First, it records that the interrupt has been requested by setting a flag bit in the INTREQ register. Second, it examines the INTENA register to determine whether the corresponding interrupt and the interrupt master are enabled. If both are enabled, the ''4703'' generates an interrupt request by placing the priority level of the request onto the three ''68000'' interrupt control input lines (IPL0, IPL1, IPL2).
</li>

<li>These three signals correspond to seven interrupt priority levels in the 68000. If the priority of the new interrupt is ''greater'' than the current processor priority, an interrupt sequence is initiated. The priority level of the new interrupt is used to index into the top seven words of the processor address space. The odd byte (a vector number) of the indexed word is fetched and then shifted left by two to create an offset into the processor's auto-vector interrupt table. The vector offsets used are in the range of $064 to $07C. These are labeled as ''interrupt autovectors'' in the ''68000'' manual. The auto-vector table appears in low memory on a ''68000'' system, but its location for other ''68000'' family processors is determined by the processor's CPU ''Vector Base Register'' (VBR). VBR can be accessed from supervisor mode with the MOVEC instruction.
</li>

<li>The processor then switches into ''supervisor'' mode (if it is not already in that mode), and saves copies of the status register and program counter (PC) onto the top of the ''system'' stack (additional information may be saved by processors other than the ''68000''). The processor priority is then raised to the level of the active interrupt.</li>

<li>From the low memory vector address (calculated in step three above), a 32-bit ''autovector'' address is fetched and loaded into the program counter. This is an entry point into Exec's interrupt dispatcher.

Exec must now further decode the interrupt by examining the INTREQ and INTENA ''4703'' chip registers. Once the active interrupt has been determined, Exec indexes into an ExecBase array to fetch the interrupt's handler entry point and handler data pointer addresses.</li>

<li>Exec now turns control over to the interrupt handler by calling it as if it were a subroutine. This handler may deal with the interrupt directly or may propagate control further by invoking interrupt server chain processing.</li>

</ul>

You can see from the above discussion that the interrupt autovectors ''should never be altered by the user''. If you wish to provide your own system interrupt handler, you must use the Exec SetIntVector() function. You should not change the contents of any autovector location.

Task multiplexing usually occurs as the result of an interrupt. When an interrupt has finished and the processor is about to return to user mode, Exec determines whether task-scheduling attention is required. If a task was signaled during interrupt processing, the task scheduler will be invoked. Because Exec uses preemptive task scheduling, it can be said that the interrupt subsystem is the heart of task multiplexing. If, for some reason, interrupts do not occur, a task might execute forever because it cannot be forced to relinquish the CPU.

[[File:LibTable26-1.png|frame|center|Interrupts by Priority]]

=== Interrupt Priorities ===

Interrupts are prioritized in hardware and software. The 68000 CPU priority at which an interrupt executes is determined strictly by hardware. In addition to this, the software imposes a finer level of ''pseudo-priorities'' on interrupts with the same CPU priority. These pseudo-priorities determine the order in which simultaneous interrupts of the same CPU priority are processed. Multiple interrupts with the same CPU priority but a different pseudo-priority will not interrupt one another. Interrupts are serviced by either an exclusive handler or by server chains to which many servers may be attached, as shown in the Type field of the next table. The table above summarizes all interrupts by priority.

The ''8520''s (also called ''CIA''s) are Amiga peripheral interface adapter chips that generate the INT2 and INT6 interrupts. For more information about them, see the ''Amiga Hardware Reference Manual''.

As described in the Motorola ''68000 Programmer's Manual'', interrupts may nest only in the direction of higher priority. Because of the time-critical nature of many interrupts on the Amiga, the CPU priority level ''must never be changed'' by user or system code. When the system is running in user mode (multitasking), the CPU priority level must remain set at zero. When an interrupt occurs, the CPU priority is raised to the level appropriate for that interrupt. Lowering the CPU priority would permit unlimited interrupt recursion on the system stack and would "short-circuit" the interrupt-priority scheme.

Because it is dangerous on the Amiga to hold off interrupts for any period of time, higher-level interrupt code must perform its business and exit promptly. If it is necessary to perform a time-consuming operation as the result of a high-priority interrupt, the operation should be deferred either by posting a ''software interrupt'' or by signalling a task. In this way, interrupt response time is kept to a minimum. Software interrupts are described in a later section.

=== Nonmaskable Interrupt ===

The ''68000'' provides a nonmaskable interrupt (NMI) of CPU priority 7. Although this interrupt cannot be generated by the Amiga hardware itself, it can be generated on the expansion bus by external hardware. Because this interrupt does not pass through the ''4703'' interrupt controller circuitry, it is capable of violating system code critical sections. In particular, it short-circuits the DISABLE mutual-exclusion mechanism. Code that uses NMI must not assume that it can access system data structures.

Interrupts are serviced on the Amiga through the use of interrupt ''handlers'' and ''servers''. An interrupt handler is a system routine that exclusively handles all processing related to a particular ''4703'' interrupt. An interrupt server is one of possibly many system routines that are invoked as the result of a single ''4703'' interrupt. Interrupt servers provide a means of interrupt sharing. This concept is useful for general-purpose interrupts such as vertical blanking.

At system start, Exec designates certain interrupts as handlers and others as server chains. The PORTS, COPER, VERTB, EXTER, and NMI interrupts are initialized as server chains. Therefore, each of these may execute multiple interrupt routines per each interrupt. All other interrupts are designated as handlers and are always used exclusively.

=== Interrupt Data Structure ===

Interrupt handlers and servers are defined by the Exec Interrupt structure. This structure specifies an interrupt routine entry point and data pointer. The C definition of this structure is as follows:

<syntaxhighlight lang="C" line>
struct Interrupt
{
struct Node is_Node;
APTR is_Data;
VOID (*is_Code)();
};
</syntaxhighlight>

Once this structure has been properly initialized, it can be used for either a handler or a server.

=== Environment ===

Interrupts execute in an environment different from that of tasks. All interrupts execute in ''supervisor mode'' and utilize the single ''system stack''. This stack is large enough to handle extreme cases of nested interrupts (of higher priorities). Interrupt processing has no effect on task stack usage.

All interrupt processing code, both handlers and servers, is invoked as assembly code subroutines. Normal assembly code register conventions dictate that the D0, D1, A0 and A1 registers be free for scratch use. In the case of an interrupt handler, some of these registers also contain data that may be useful to the handler code. See the section on handlers below.

Because interrupt processing executes outside the context of most system activities, certain data structures will not be self-consistent and must be considered off limits for all practical purposes. This happens because certain system operations are not atomic in nature and might be interrupted only after executing part of an important instruction sequence. For example, memory allocation and deallocation routines do not disable interrupts. This results in the possibility of interrupting a memory-related routine. In such a case, a memory linked list may be inconsistent during and interrupt. Therefore, interrupt routines must not use any memory allocation or deallocation functions.

In addition, interrupts may not call any system function which might allocate memory, wait, manipulate unprotected lists, or modify ExecBase->ThisTask data (for example Forbid(), Permit(), and mathieee libraries). In practice, this means that very few system calls may be used within interrupt code. The following functions may generally be used safely within interrupts:

{| class="wikitable"
| Alert()
|-
| Disable()
|-
| Enable()
|-
| Signal()
|-
| Cause()
|-
| GetMsg()
|-
| PutMsg()
|-
| ReplyMsg()
|-
| FindPort()
|-
| FindTask()
|}

and if you are manipulating your ''own'' List structures while in an interrupt:

{| class="wikitable"
| AddHead()
|-
| AddTail()
|-
| RemHead()
|-
| RemTail()
|-
| FindName()
|-
| FindIName()
|-
| GetHead()
|-
| GetTail()
|-
| GetSucc()
|-
| GetPred()
|}

In addition, certain devices (notably the timer device) specifically allow limited use of SendIO() and BeginIO() within interrupts.

=== Interrupt Handlers ===

As described above, an interrupt handler is a system routine that exclusively handles all processing related to a particular ''4703'' interrupt. There can only be one handler per ''4703'' interrupt. Every interrupt handler consists of an Interrupt structure (as defined above) and a single assembly code routine. Optionally, a data structure pointer may also be provided. This is particularly useful for ROM-resident interrupt code.

An interrupt handler is passed control as if it were a subroutine of Exec. Once the handler has finished its business, it must return to Exec by executing an RTS (return from subroutine) instruction rather than an RTE (return from exception) instruction. Interrupt handlers should be kept very short to minimize service-time overhead and thus minimize the possibilities of interrupt overruns. As described above, an interrupt handler has the normal scratch registers at its disposal. In addition, A5 and A6 are free for use. These registers are saved by Exec as part of the interrupt initiation cycle.

For the sake of efficiency, Exec passes certain register parameters to the handler (see the list below). These register values may be utilized to trim a few microseconds off the execution time of a handler. All of the following registers (D0/D1/A0/A1/A5/A6) may be used as scratch registers by an interrupt handler, and need not be restored prior to returning.

{{Note|title=Don't Make Assumptions About Registers|text=Interrupt servers have different register usage rules (see the "Interrupt Servers" section).}}

==== Interrupt Handler Register Usage ====

Here are the register conventions for interrupt handlers.

; D0
: Contains no valid information.

; D1
: Contains the ''4703'' INTENAR and INTREQR registers values '''AND''''ed together. This results in an indication of which interrupts are enabled ''and'' active.

; A0
: Points to the base address of the Amiga custom chips. This information is useful for performing indexed instruction access to the chip registers.

; A1
: Points to the data area specified by the is_Data field of the Interrupt structure. Because this pointer is always fetched (regardless of whether you use it), it is to your advantage to make some use of it.

; A5
: Is used as a vector to your interrupt code.

; A6
: Points to the Exec library base (SysBase). You may use this register to call Exec functions or set it up as a base register to access your own library or device.

Interrupt handlers are established by passing the Exec function SetIntVector(), your initialized Interrupt structure, and the ''4703'' interrupt bit number of interest. The parameters for this function are as follows:

<syntaxhighlight lang="C" line>
SetIntVector(ULONG intNumber, struct Interrupt *interrupt)
</syntaxhighlight>

The first argument is the bit number for which this interrupt server is to respond (example INTB_VERTB). The possible bits for interrupts are defined in <hardware/intbits.h>. The second argument is the address of an interrupt server node as described earlier in this article. Keep in mind that certain interrupts are established as server chains and should not be accessed as handlers.

The following example demonstrates initialization and installation of an assembler interrupt handler. See the [[Resources|Resources]] for more information on allocating resources, and [[Serial_Device|Serial Device]] for the more common method of serial communications.

<pre>
;/* rbf.c - Execute me to compile me with SAS C 5.10
LC -d0 -b1 -cfistq -v -y -j73 rbf.c
Blink FROM LIB:c.o,rbf.o,rbfhandler.o TO rbf LIBRARY LIB:LC.lib,LIB:Amiga.lib
quit

** rbf.c - serial receive buffer full interrupt handler example.
** Must be linked with assembler handler rbfhandler.o
**
** To receive characters, this example requires ASCII serial input
** at your Amiga's current serial hardware baud rate (ie. 9600 after
** reboot, else last baud rate used)
*/

#include <exec/execbase.h>
#include <exec/memory.h>
#include <exec/interrupts.h>
#include <resources/misc.h>
#include <hardware/custom.h>
#include <hardware/intbits.h>
#include <dos/dos.h>

#include <clib/exec_protos.h>
#include <clib/misc_protos.h>

#include <stdio.h>
#include <string.h>

#ifdef LATTICE
int CXBRK(void) { return(0); } /* Disable Lattice CTRL/C handling */
void chkabort(void) { return; } /* really */
#endif

#define BUFFERSIZE 256

extern void RBFHandler(); /* proto for asm interrupt handler */
void main(void);

struct MiscResource *MiscBase;
extern struct ExecBase *SysBase;
extern struct Custom far custom; /* defined in amiga.lib */

static UBYTE *allocname = "rbf-example";

struct RBFData {
struct Task *rd_Task;
ULONG rd_Signal;
ULONG rd_BufferCount;
UBYTE rd_CharBuffer[BUFFERSIZE + 2];
UBYTE rd_FlagBuffer[BUFFERSIZE + 2];
UBYTE rd_Name[32];
};

void main(void)
{
struct RBFData *rbfdata;
UBYTE *currentuser;
BYTE signr;
struct Device *serdevice;
struct Interrupt *rbfint, *priorint;
BOOL priorenable;
ULONG signal;

if (MiscBase = OpenResource("misc.resource"))
{
currentuser = AllocMiscResource(MR_SERIALPORT, allocname); /* Allocate the serial */
if (currentuser) /* port registers. */
{
printf("serial hardware allocated by %s. Trying to remove it\n",
currentuser); /* Hey! someone got it! */
Forbid();
if (serdevice = (struct Device *)FindName(&SysBase->DeviceList, currentuser))
RemDevice(serdevice);
Permit();

currentuser = AllocMiscResource(MR_SERIALPORT, allocname); /* and try again */
}
if (currentuser == NULL)
{ /* Get the serial */
currentuser = AllocMiscResource(MR_SERIALBITS, allocname); /* control bits. */
if (currentuser)
{
printf("serial control allocated by %s\n", currentuser); /* Give up. */
FreeMiscResource(MR_SERIALPORT);
}
else
{ /* Got them both. */
printf("serial hardware allocated\n");
if ((signr = AllocSignal(-1)) != -1) /* Allocate a signal bit for the */
{ /* interrupt handler to signal us. */
if (rbfint = AllocMem(sizeof(struct Interrupt), MEMF_PUBLIC|MEMF_CLEAR))
{
if (rbfdata = AllocMem(sizeof(struct RBFData), MEMF_PUBLIC|MEMF_CLEAR))
{
rbfdata->rd_Task = FindTask(NULL); /* Init rfbdata structure. */
rbfdata->rd_Signal = 1L << signr;

rbfint->is_Node.ln_Type = NT_INTERRUPT; /* Init interrupt node. */
strcpy(rbfdata->rd_Name, allocname);
rbfint->is_Node.ln_Name = rbfdata->rd_Name;
rbfint->is_Data = (APTR)rbfdata;
rbfint->is_Code = RBFHandler;
/* Save state of RBF and */
priorenable = custom.intenar & INTF_RBF ? TRUE : FALSE; /* interrupt */
custom.intena = INTF_RBF; /* disable it. */
priorint = SetIntVector(INTB_RBF, rbfint);

if (priorint) printf("replaced the %s RBF interrupt handler\n",
priorint->is_Node.ln_Name);
printf("enabling RBF interrupt\n");
custom.intena = INTF_SETCLR | INTF_RBF;

printf("waiting for buffer to fill up. Use CTRL-C to break\n");
signal = Wait(1L << signr | SIGBREAKF_CTRL_C);

if (signal & SIGBREAKF_CTRL_C) printf(">break<\n");
printf("Character buffer contains:\n%s\n", rbfdata->rd_CharBuffer);

custom.intena = INTF_RBF; /* Restore previous handler. */
SetIntVector(INTB_RBF, priorint);
/* Enable it if it was enabled */
if (priorenable) custom.intena = INTF_SETCLR|INTF_RBF; /* before. */

FreeMem(rbfdata, sizeof(struct RBFData));
}
else printf("can't allocate memory for rbf data\n");
FreeMem(rbfint, sizeof(struct Interrupt));
}
else printf("can't allocate memory for interrupt structure\n");
FreeSignal(signr);
}
else printf("can't allocate signal\n");

FreeMiscResource(MR_SERIALBITS); /* release serial hardware */
FreeMiscResource(MR_SERIALPORT);
}
}
} /* There is no 'CloseResource()' function */
}
</pre>

The assembler interrupt handler code, RBFHandler, reads the complete word of serial input data from the serial hardware and then separates the character and flag bytes into separate buffers. When the buffers are full, the handler signals the main process causing main to print the character buffer contents, remove the handler, and exit.

{{Note|text=The data structure containing the signal to use, task address pointer, and buffers is allocated and initialized in main(), and passed to the handler (shown below) via the is_Data pointer of the Interrupt structure.}}

<pre>
* rbfhandler.asm. Example interrupt handler for rbf.
*
* Assembled with Howesoft Adapt 680x0 Macro Assembler Rel. 1.0
* hx68 from: rbfhandler.asm to rbfhandler.o INCDIR include:
* blink from lib:c.o rbf.o rbfhandler.o to rbf lib lib:lc.lib lib:amiga.lib
*
INCLUDE "exec/types.i"
INCLUDE "hardware/custom.i"
INCLUDE "hardware/intbits.i"

XDEF _RBFHandler

JSRLIB MACRO
XREF _LVO\1
JSR _LVO\1(A6)
ENDM

BUFLEN EQU 256

STRUCTURE RBFDATA,0
APTR rd_task
ULONG rd_signal
UWORD rd_buffercount
STRUCT rd_charbuffer,BUFLEN+2
STRUCT rd_flagbuffer,BUFLEN+2
STRUCT rd_name,32
LABEL RBFDATA_SIZEOF

* Entered with:
* D0 == scratch
* D1 == INTENAT & INTREQR (scratch)
* A0 == custom chips (scratch)
* A1 == is_Data which is RBFDATA structure (scratch)
* A5 == vector to our code (scratch)
* A6 == pointer to ExecBase (scratch)
*
* Note - This simple handler just receives one buffer full of serial
* input data, signals main, then ignores all subsequent serial data.
*
section code

_RBFHandler: ;entry to our interrupt handler

MOVE.W serdatr(A0),D1 ;get the input word (flags and char)

MOVE.W rd_buffercount(A1),D0 ;get our buffer index
CMPI.W #BUFLEN,D0 ;no more room in our buffer ?
BEQ.S ExitHandler ;yes - just exit (ignore new char)
LEA.L rd_charbuffer(A1),A5 ;else get our character buffer address
MOVE.B D1,0(A5,D0.W) ;store character in our character buffer
LEA.L rd_flagbuffer(A1),A5 ;get our flag buffer address
LSR.W #8,d1 ;shift flags down
MOVE.B D1,0(A5,D0.W) ;store flags in flagbuffer

ADDQ.W #1,D0 ;increment our buffer index
MOVE.W D0,rd_buffercount(A1) ; and replace it
CMPI.W #BUFLEN,D0 ;did our buffer just become full ?
BNE.S ExitHandler ;no - we can exit
MOVE.L A0,-(SP) ;yes - save custom
MOVE.L rd_signal(A1),D0 ;get signal allocated in main()
MOVE.L rd_task(A1),A1 ;and pointer to main task
JSRLIB Signal ;tell main we are full
MOVE.L (SP)+,A0 ;restore custom
;Note: system call trashed D0-D1/A0-A1
ExitHandler:
MOVE.W #INTF_RBF,intreq(A0) ;clear the interrupt
RTS ;return to exec

END
</pre>

=== Interrupt Servers ===

As mentioned above, an interrupt server is one of possibly many system interrupt routines that are invoked as the result of a single ''4703'' interrupt. Interrupt servers provide an essential mechanism for interrupt sharing.

Interrupt servers must be used for PORTS, COPER, VERTB, EXTER, or NMI interrupts. For these interrupts, all servers are linked together in a chain. Every server in the chain will be called in turn as long as the previous server returned with the processor's Z (zero) flag set. If you determine that an interrupt was specifically for your server, you should return with the processor's Z flag cleared (non-zero condition) so that the remaining servers on the chain will be skipped.

{{Note|title=Use The Z Flag|text=VERTB (vertical blank) servers should ''always'' return with the Z (zero) flag set. The processor Z flag is used rather than the normal function convention of returning a result in D0 because it may be tested more quickly by Exec upon the server's return.}}

The easiest way to set the condition code register is to do an immediate move to the D0 register as follows:

<pre>
SetZflag_Calls_Next:
MOVEQ #0,D0
RTS

ClrZflag_Ends_Chain:
MOVEQ #1,D0
RTS
</pre>

The same Exec Interrupt structure used for handlers is also used for servers. Also, like interrupt handlers, servers must terminate their code with an RTS instruction.

Interrupt servers are called in priority order. The priority of a server is specified in its is_Node.ln_Pri field. Higher-priority servers are called earlier than lower-priority servers. Adding and removing interrupt servers from a particular chain is accomplished with the Exec AddIntServer() and RemIntServer() functions. These functions require you to specify both the ''4703'' interrupt number and a properly initialized Interrupt structure.

Servers have different register values passed than handlers do. A server cannot count on the D0, D1, A0, or A6 registers containing any useful information. However, the highest priority system vertical blank server currently expects to receive a pointer to the custom chips A0. Therefore, if you install a vertical blank server at priority 10 or greater, you must place custom ($DF¬†F000) in A0 before exiting. Other than that, a server is free to use D0-D1 and A0-A1/A5-A6 as scratch.

==== Interrupt Server Register Usage ====

; D0
: Scratch.

; D1
: Scratch.

; A0
: Scratch except in certain cases (see note above).

; A1
: Points to the data area specified by the is_Data field of the Interrupt structure. Because this pointer is always fetched (regardless of whether you use it), it is to your advantage to make some use of it (scratch).

; A5
: Points to your interrupt code (scratch).

; A6
: Scratch.

In a server chain, the interrupt is cleared automatically by the system. Having a server clear its interrupt is not recommended and not necessary (clearing could cause the loss of an interrupt on PORTS or EXTER).

Here is an example of a program to install and remove a low-priority vertical blank interrupt server:

<pre>
;/* vertb.c - Execute me to compile me with SAS C 5.10
LC -d0 -b1 -cfistq -v -y -j73 vertb.c
Blink FROM LIB:c.o,vertb.o,vertbserver.o TO vertb LIBRARY LIB:LC.lib,LIB:Amiga.lib
quit ; */
/* vertb.c - Vertical blank interrupt server example. Must be linked with vertbserver.o. */

#include <exec/memory.h>
#include <exec/interrupts.h>
#include <dos/dos.h>
#include <hardware/custom.h>
#include <hardware/intbits.h>
#include <clib/exec_protos.h>
#include <stdio.h>

#ifdef LATTICE
int CXBRK(void) { return(0); } /* Disable Lattice CTRL/C handling */
void chkabort(void) { return; } /* really */
#endif

extern void VertBServer(); /* proto for asm interrupt server */

void main(void)
{
struct Interrupt *vbint;
ULONG counter = 0;
ULONG endcount;
/* Allocate memory for */
if (vbint = AllocMem(sizeof(struct Interrupt), /* interrupt node. */
MEMF_PUBLIC|MEMF_CLEAR))
{
vbint->is_Node.ln_Type = NT_INTERRUPT; /* Initialize the node. */
vbint->is_Node.ln_Pri = -60;
vbint->is_Node.ln_Name = "VertB-Example";
vbint->is_Data = (APTR)&counter;
vbint->is_Code = VertBServer;

AddIntServer(INTB_VERTB, vbint); /* Kick this interrupt server to life. */

printf("VBlank server will increment a counter every frame.\n");
printf("counter started at zero, CTRL-C to remove server\n");

Wait(SIGBREAKF_CTRL_C);
endcount = counter;
printf("%ld vertical blanks occurred\nRemoving server\n", endcount);

RemIntServer(INTB_VERTB, vbint);
FreeMem(vbint, sizeof(struct Interrupt));
}
else printf("Can't allocate memory for interrupt node\n");
}
</pre>

This is the assembler VertBServer installed by the C example:

<pre>
* vertbserver.asm. Example simple interrupt server for vertical blank
*
* Assembled with Howesoft Adapt 680x0 Macro Assembler Rel. 1.0
* hx68 from: vertbserver.asm to vertbserver.o INCDIR include:
* blink from lib:c.o vertb.o vertbserver.o to vertb lib lib:lc.lib lib:amiga.lib
*
INCLUDE "exec/types.i"
INCLUDE "hardware/custom.i"
INCLUDE "hardware/intbits.i"

XDEF _VertBServer

* Entered with: A0 == scratch (execpt for highest pri vertb server)
* D0 == scratch A1 == is_Data
* D1 == scratch A5 == vector to interrupt code (scratch)
* A6 == scratch
*
section code

_VertBServer:
ADDI.L #1,(a1) ; increments counter is_Data points to
MOVEQ.L #0,d0 ; set Z flag to continue to process other vb-servers
RTS ;return to exec
END
</pre>

== Software Interrupts ==

Exec provides a means of generating ''software interrupts''. Software interrupts execute at a priority higher than that of tasks but lower than that of hardware interrupts, so they are often used to defer hardware interrupt processing to a lower priority. Software interrupts use the same Interrupt data structure as hardware interrupts. As described above, this structure contains pointers to both interrupt code and data, and should be initialized as node type NT_INTERRUPT (not NT_SOFTINT which is an internal Exec flag).

A software interrupt is usually activated with the Cause() function. If this function is called from a task, the task will be interrupted and the software interrupt will occur. If it is called from a hardware interrupt, the software interrupt will not be processed until the system exits from its last hardware interrupt. If a software interrupt occurs from within another software interrupt, it is not processed until the current one is completed. However, individual software interrupts do not nest, and will not be caused if already running as a software interrupt.

Software interrupts are prioritized. Unlike interrupt servers, software interrupts have only five allowable priority levels: -32, -16, 0, +16, and +32. The priority should be put into the ln_Pri field prior to calling Cause().

Software interrupts can also be generated by message arrival at a PA_SOFTINT message port. The applications of this technique are limited since it is not permissible, with most devices, to send IO requests from within interrupt code. However, the timer.device does allow such interactions, so a self-perpetuating PA_SOFTINT timer port can provide an application with quite consistent timing under varying multitasking loads. The following example demonstrates use of a software interrupt and a PA_SOFTINT port. See the [[Exec_Messages_and_Ports|Exec Messages and Ports]] for more information about messages and ports.

<syntaxhighlight lang="C" line>
/* timersoftint.c - Timer device software interrupt message port example. */

#include <exec/memory.h>
#include <exec/interrupts.h>
#include <devices/timer.h>
#include <dos/dos.h>
#include <proto/exec.h>
#include <proto/dos.h>

#define MICRO_DELAY 1000
#define OFF 0
#define ON 1
#define STOPPED 2

struct TSIData {
uint32 tsi_Counter;
uint32 tsi_Flag;
struct MsgPort *tsi_Port;
};

struct TSIData *tsidata;

void tsoftcode(void); /* Prototype for our software interrupt code */

int main()
{
uint32 endcount;

/* Allocate message port, data & interrupt structures. */
tsidata = IExec->AllocVecTags(sizeof(struct TSIData),
AVT_Type, MEMF_SHARED,
AVT_Lock, TRUE,
TAG_END);

/* Set up the (software)interrupt structure. Note that this task runs at */
/* priority 0. Software interrupts may only be priority -32, -16, 0, +16, */
/* +32. Also note that the correct node type for a software interrupt is */
/* NT_INTERRUPT. (NT_SOFTINT is an internal Exec flag). This is the same */
/* setup as that for a software interrupt which you Cause(). */
struct Interrupt *softint = IExec->AllocSysObjectTags(ASOT_INTERRUPT,
ASOINTR_Code, tsoftcode,
ASOINTR_Data, tsidata,
TAG_END);

struct MsgPort *port = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_AllocSig, FALSE,
ASOPORT_Action, PA_SOFTINT,
ASOPORT_Target, softint,
TAG_END);

if(tsidata != NULL && softint != NULL && port != NULL)
{
softint->is_Node.ln_Pri = 0;

/* Allocate timerequest */
struct TimeRequest *tr = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct TimeRequest),
ASOIOR_ReplyPort, port,
TAG_END);

if (tr != NULL)
{
/* Open timer.device. NULL is success. */
if (!(IExec->OpenDevice("timer.device", UNIT_MICROHZ, (struct IORequest *)tr, 0)))
{
tsidata->tsi_Flag = ON; /* Init data structure to share globally. */
tsidata->tsi_Port = port;

/* Send of the first timerequest to start. IMPORTANT: Do NOT */
/* BeginIO() to any device other than audio or timer from */
/* within a software or hardware interrupt. The BeginIO() code */
/* may allocate memory, wait or perform other functions which */
/* are illegal or dangerous during interrupts. */
IDOS->Printf("starting softint. CTRL-C to break...\n");

tr->Request.io_Command = TR_ADDREQUEST; /* Initial iorequest to start */
tr->Time.Microseconds = MICRO_DELAY; /* software interrupt. */
IExec->BeginIO((struct IORequest *)tr);

IExec->Wait(SIGBREAKF_CTRL_C);
endcount = tsidata->tsi_Counter;
IDOS->Printf("timer softint counted %lu milliseconds.\n", endcount);

IDOS->Printf("Stopping timer...\n");
tsidata->tsi_Flag = OFF;

while (tsidata->tsi_Flag != STOPPED) IDOS->Delay(10);

IExec->CloseDevice((struct IORequest *)tr);
}
else IDOS->Printf("couldn't open timer.device\n");
}
else IDOS->Printf("couldn't create timerequest\n");

IExec->FreeSysObject(ASOT_IOREQUEST, tr);
}

IExec->FreeSysObject(ASOT_INTERRUPT, softint);
IExec->FreeSysObject(ASOT_PORT, port);
IExec->FreeVec(tsidata);

return 0;
}

void tsoftcode(void)
{
/* Remove the message from the port. */
struct TimeRequest *tr = (struct TimeRequest *)IExec->GetMsg(tsidata->tsi_Port);

/* Keep on going if main() hasn't set flag to OFF. */
if ((tr) && (tsidata->tsi_Flag == ON))
{
/* increment counter and re-send timerequest--IMPORTANT: This */
/* self-perpetuating technique of calling BeginIO() during a software */
/* interrupt may only be used with the audio and timer device. */
tsidata->tsi_Counter++;
tr->Request.io_Command = TR_ADDREQUEST;
tr->Time.Microseconds = MICRO_DELAY;
IExec->BeginIO((struct IORequest *)tr);
}
/* Tell main() we're out of here. */
else tsidata->tsi_Flag = STOPPED;
}
</syntaxhighlight>

== Disabling Interrupts ==

As mentioned in [[Exec_Tasks|Exec Tasks]], it is sometimes necessary to disable interrupts when examining or modifying certain shared system data structures. However, for proper system operation, interrupts should never be disabled unless absolutely necessary, and ''never for more than 250 microseconds''. Interrupt disabling is controlled with the Disable() and Enable() functions.

In some system code, there are nested disabled sections. Such code requires that interrupts be disabled with the first Disable() and not re-enabled until the ''last'' Enable(). The system Enable() and Disable() functions are designed to permit this sort of nesting.

Disable() increments a counter to track how many levels of disable have been issued. Only 126 levels of nesting are permitted. Enable() decrements the counter, and reenables interrupts when the last disable level has been exited.

== Quick Interrupts ==

One of the features of the Zorro III bus is the Quick Interrupt, also known as the vectored interrupt. This feature allows Zorro III
hardware to supply a vector number to the system when an interrupt occurs. The system uses this vector number to go directly to an
interrupt routine.

=== Conventional Amiga Interrupts ===

The Amiga handles normal interrupts from Zorro II cards using an interrupt server chain. There are two interrupts available from the
Zorro II bus, the PORTS and EXTER interrupt server chains. If a driver for a Zorro II card needs to use an interrupt, it adds an interrupt routine to the appropriate chain. When the interrupt occurs, Exec calls each routine in the interrupt chain, which are sorted in priority order. Exec continues until it finds the routine that corresponds to the device that triggered the interrupt.

The server chain allows several routines to share a single interrupt. This means that several devices trigger the same interrupt, so each interrupt routine must do some processing to determine if its card triggered the interrupt or if some other source caused the interrupt. For example, an interrupt routine might examine a register on its card to determine that the card triggered the interrupt.

Although this scheme allows unrelated pieces of software to easily share an interrupt, it can make the interrupt overhead rather high.
These two interrupt server chains also handle interrupts from the CIA chips, which are used to trigger a variety of events. As a result, these server chains can contain a multitude of interrupt routines.

Consider what happens when a Zorro II card generates a PORTS interrupt. Exec has to perform some set up and then step through the PORTS server chain. Exec calls each interrupt routine in priority order looking for the routine that services this interrupt. If there are 20 interrupt routines of higher priority than the card's interrupt routine in the server chain, Exec has to call 20 other routines before it gets to the correct routine.

=== Zorro III Quick Interrupts ===

Quick interrupts avoid the overhead involved in Exec's interrupt server chains. Exec only helps set up the quick interrupt, which it does via the exec.library function ObtainQuickVector(). Once Exec has set up the quick interrupt routine, it does not intervene. Unlike conventional Amiga interrupt routines, which are called as subroutines from Exec's main interrupt code, the Amiga jumps directly to the quick interrupt routine using a private vector. This behavior requires quick interrupt routines to take some special precautions.

There are two important differences between a conventional Amiga interrupt routine and a quick quick interrupt routine. A quick
interrupt routine must save and restore all of the registers it changes, including D0, D1, A0, and A1. It must do this because, unlike
regular interrupt routines, Exec doesn't do it for you. Also, a quick interrupt routine ends with a RTE (return from exception) instruction.

If your quick interrupt routine is 100% self-contained and does not access any operating system structures or routines, then the work is rather simple. Just save the registers you use, perform your interrupt processing, restore the registers, and end with an RTE. If, however, the routine needs to call the OS or use an OS structure, it must check if the interrupt has been delayed. This is necessary in case the interrupt hit the CPU just after the CPU had told the hardware to hold off interrupts (see the Autodoc for ObtainQuickVector() to find out how to perform this test).

As the Amiga OS is a dynamic operating system, quick interrupts are allocated by the OS. If your hardware/software wants to use a quick
interrupt, it must allocate a vector with ObtainQuickVector(). This routine accepts a pointer to the quick interrupt code (not a pointer to an Interrupt structure). If Exec installed the vector, ObtainQuickVector() returns the vector number. When the quick
interrupt occurs, the Zorro III card sends this vector number to the CPU, which tells the CPU where the interrupt code is.

ObtainQuickVector() returns 0 if there are no more vectors. Since the number of vectors is limited, any Zorro III device that uses quick interrupts must be able to fall back to the Amiga's conventional interrupt scheme.

== Function Reference ==

The following chart gives a brief description of the Exec functions that control interrupts. See the SDK for details about each call.

{| class="wikitable"
! Interrupt Function
! Description
|-
| AddIntServer()
| Add an interrupt server to a system server chain.
|-
| Cause()
| Cause a software interrupt.
|-
| Disable()
| Disable interrupt processing.
|-
| Enable()
| Restart system interrupt processing.
|-
| RemIntServer()
| Remove an interrupt server from a system server chain.
|-
| SetIntVector()
| Set a new handler for a system interrupt vector.
|}

Intuition Special Functions

2025-01-26T19:29:48Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

== Intuition Special Functions ==

There are several Intuition topics which, while not large enough to fill articles of their own, nonetheless deserve to be discussed. The subjects covered here include locking IntuitionBase, the Intuition memory functions AllocRemember() and FreeRemember(), using sprites with Intuition, and Intuition's special internal functions.

== Locking IntuitionBase ==

It is sometimes necessary to examine the IntuitionBase structure. Items such as the address of the active screen and window, current mouse coordinates and more can be found there. It is never a good idea to simply read these fields, as they are prone to sudden change. The IntuitionBase structure must always be locked before looking at its fields.

It is necessary to inform Intuition that an application is about to examine IntuitionBase so that Intuition will not change any variables and IntuitionBase will remain static during the access. The call LockIBase() will lock the state of IntuitionBase so that it may be examined. During the time that the application has IntuitionBase locked, all Intuition input processing is frozen. Make every effort to examine IntuitionBase and release the lock as quickly as possible. The values in IntuitionBase are read-only. Applications should never write values to IntuitionBase.

<syntaxhighlight lang="C" line>
ULONG LockIBase( ULONG dontknow );
</syntaxhighlight>

LockIBase() is passed a ULONG (dontknow in the prototype above) indicating the Intuition lock desired. For all foreseeable uses of the call this value should be 0. LockIBase() returns a ULONG, that must be passed to UnlockIBase() later to allow IntuitionBase to change once again.

Every call to LockIBase() must be matched by a subsequent call to UnlockIBase():

<syntaxhighlight lang="C" line>
VOID UnlockIBase( ULONG ibLock );
</syntaxhighlight>

Set the ibLock argument to the value returned by the previous call to LockIBase().

{{Note|title=About LockIBase()|text=This function should not be called while holding any other system locks such as Layer and LayerInfo locks. Between calls to LockIBase() and UnlockIBase(), you may not call any Intuition or other high-level system functions so it is best to copy the information you need and release the lock as quickly as possible.}}

{{Note|title=About IntuitionBase|text=Never, ever, modify any of the fields in IntuitionBase directly. Also, there are fields in IntuitionBase that are considered system private that should not be accessed, even for reading. (Refer to the <intuition/intuitionbase.h> include file.) Application programs cannot depend on (and should not use) the contents of these fields; their usage is subject to change in future revisions of Intuition.}}

== Easy Memory Allocation and Deallocation ==

Intuition has a pair of routines that enable applications to make multiple memory allocations which are easily deallocated with a single call. The Intuition routines for memory management are AllocRemember() and FreeRemember(). These routines rely upon the Remember structure to track allocations.

=== Intuition Helps You Remember ===

The AllocRemember() routine calls the Exec AllocMem() function to perform the memory allocation. (Of course, the application may directly call Exec memory functions, see [[Exec_Memory_Allocation|Exec Memory Allocation]] for details.)

AllocRemember() performs two allocations each time it is called. The first allocation is the actual memory requested by the application. This memory is of the size and type specified in the call and is independent of the second block of memory. The second allocation is memory for a Remember structure which is used to save the specifics of the allocation in a linked list. When FreeRemember() is called it uses the information in this linked list to free all previous memory allocations at once. This is convenient since normally you would have to free each memory block one at a time which requires knowing the size and base address of each one.

The AllocRemember() call takes three arguments:

<syntaxhighlight lang="C" line>
APTR AllocRemember( struct Remember **rememberKey, ULONG size, ULONG flags );
</syntaxhighlight>

The rememberKey is the address of a pointer to a Remember structure. Note that this is a double indirection, not just a simple pointer. The size is the size, in bytes, of the requested allocation. The flags argument is the specification for the memory allocation. These are the same as the specifications for the Exec AllocMem() function described in [[Exec_Memory_Allocation|Exec Memory Allocation]].

If AllocRemember() succeeds, it returns the address of the allocated memory block. It returns a NULL if the allocation fails.

The FreeRemember() function gives the option of freeing memory in either of two ways. The first (and most useful) option is to free both the link nodes that AllocRemember() created and the memory blocks to which they correspond. The second option is to free only the link nodes, leaving the memory blocks for further use (and later deallocation via Exec's FreeMem() function). But, as a general rule, the application should never free only the link nodes as this can greatly fragment memory. If the link nodes are not required, use the Exec memory allocation functions.

The FreeRemember() call is as follows:

<syntaxhighlight lang="C" line>
VOID FreeRemember( struct Remember **rememberKey, LONG reallyForget );
</syntaxhighlight>

Set the rememberKey argument to the address of a pointer to a Remember structure. This is the same value that was passed to previous calls to AllocRemember(). The reallyForget argument is a boolean that should be set to TRUE. If TRUE, then both the link nodes and the memory blocks are freed. If FALSE, then only the link nodes are freed. Again, applications should avoid using the FALSE value since it can lead to highly fragmented memory.

=== How to Remember ===

To use Intuition's memory functions, first create an anchor for the memory to be allocated by declaring a variable that is a pointer to a Remember structure and initializing that pointer to NULL. This variable is called the ''remember key''.

<syntaxhighlight lang="C" line>
struct Remember *rememberKey = NULL;
</syntaxhighlight>

Call AllocRemember() with the address of the remember key, along with the memory requirements for the specific allocation. Multiple allocations may be made before a call to FreeRemember().

<syntaxhighlight lang="C" line>
memBlockA = IIntuition->AllocRemember(&rememberKey, SIZE_A, MEMF_CLEAR | MEMF_PRIVATE);
if (memBlockA == NULL)
{
/* error: allocation failed */
IDOS->Printf("Memory allocation failed.\n");
}
else
{
/* use the memory here */
IDOS->Printf("Memory allocation succeeded.\n");
}
</syntaxhighlight>

AllocRemember() actually performs two memory allocations per call, one for the memory requested and the other for a Remember structure. The Remember structure is filled in with data describing the allocation, and is linked into the list to which the ''remember key'' points.

To free memory that has been allocated, simply call FreeRemember() with the correct remember key.

<syntaxhighlight lang="C" line>
IIntuition->FreeRemember(&rememberKey, TRUE);
</syntaxhighlight>

This will free all the memory blocks previously allocated with AllocRemember() in a single call.

=== The Remember Structure ===

The Remember structure is defined in <intuition/intuition.h> as follows:

<syntaxhighlight lang="C" line>
struct Remember
{
struct Remember *NextRemember;
ULONG RememberSize;
UBYTE *Memory;
};
</syntaxhighlight>

Generally, the Remember structure is handled only by the system. Here are its fields:

; NextRemember
: The link to the next Remember structure.

; RememberSize
: The size of the memory tracked by this node.

; Memory
: A pointer to the memory tracked by this node.

=== An Example of Remembering ===

<syntaxhighlight lang="C" line>
/*
** RememberTest - Illustrates the use of AllocRemember() and FreeRemember().
*/
#define INTUI_V36_NAMES_ONLY

#include <exec/types.h>
#include <exec/memory.h>
#include <dos/dos.h>
#include <intuition/intuition.h>

#include <proto/exec.h>
#include <proto/intuition.h>

#include <stdlib.h>

/* our function prototypes */
VOID methodOne(VOID);
VOID methodTwo(VOID);

struct IntuitionIFace *IIntuition = 0;

/* random sizes to demonstrate the Remember functions. */
#define SIZE_A 100L
#define SIZE_B 200L

/*
** main() - Initialize everything.
*/
int main(int argc, char **argv)
{
LONG exitVal = RETURN_OK;

struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntutitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
if (IIntuition == NULL)
exitVal = RETURN_FAIL;
else
{
methodOne();
methodTwo();
}

IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);

return exitVal;
}

/*
** MethodOne
** Illustrates using AllocRemember() to allocate all memory and
** FreeRemember() to free it all.
*/
VOID methodOne(VOID)
{
struct Remember *rememberKey = NULL;

APTR memBlockA = IIntuition->AllocRemember(&rememberKey, SIZE_A, MEMF_CLEAR | MEMF_SHARED);
if (memBlockA)
{
/* The memBlockA allocation succeeded; try for memBlockB. */
APTR memBlockB = IIntuition->AllocRemember(&rememberKey, SIZE_B, MEMF_CLEAR | MEMF_SHARED);
if (memBlockB)
{
/* Both memory allocations succeeded.
** The program may now use this memory.
*/
}
}

/* It is not necessary to keep track of the status of each allocation.
** Intuition has kept track of all successful allocations by updating its
** linked list of Remember nodes. The following call to FreeRemember() will
** deallocate any and all of the memory that was successfully allocated.
** The memory blocks as well as the link nodes will be deallocated because
** the "ReallyForget" parameter is TRUE.
**
** It is possible to have reached the call to FreeRemember()
** in one of three states. Here they are, along with their results.
**
** 1. Both memory allocations failed.
** RememberKey is still NULL. FreeRemember() will do nothing.
** 2. The memBlockA allocation succeeded but the memBlockB allocation failed.
** FreeRemember() will free the memory block pointed to by memBlockA.
** 3. Both memory allocations were successful.
** FreeRemember() will free the memory blocks pointed to by
** memBlockA and memBlockB.
*/
IIntuition->FreeRemember(&rememberKey, TRUE);
}

/*
** MethodTwo
** Illustrates using AllocRemember() to allocate all memory,
** FreeRemember() to free the link nodes, and FreeMem() to
** free the actual memory blocks.
*/
VOID methodTwo(VOID)
{
struct Remember *rememberKey = NULL;

APTR memBlockA = IIntuition->AllocRemember(&rememberKey, SIZE_A, MEMF_CLEAR | MEMF_SHARED);
if (memBlockA)
{
/* The memBlockA allocation succeeded; try for memBlockB. */
APTR memBlockB = AllocRemember(&rememberKey, SIZE_B, MEMF_CLEAR | MEMF_SHARED);
if (memBlockB)
{
/* Both memory allocations succeeded.
** For the purpose of illustration, FreeRemember() is called at
** this point, but only to free the link nodes. The memory pointed
** to by memBlockA and memBlockB is retained.
*/
IIntuition->FreeRemember(&rememberKey, FALSE);

/* Individually free the two memory blocks. The Exec FreeMem()
** call must be used, as the link nodes are no longer available.
*/
IExec->FreeMem(memBlockA, SIZE_A);
IExec->FreeMem(memBlockB, SIZE_B);
}
}

/* It is possible to have reached the call to FreeRemember()
** in one of three states. Here they are, along with their results.
**
** 1. Both memory allocations failed.
** RememberKey is still NULL. FreeRemember() will do nothing.
** 2. The memBlockA allocation succeeded but the memBlockB allocation failed.
** FreeRemember() will free the memory block pointed to by memBlockA.
** 3. Both memory allocations were successful.
** If this is the case, the program has already freed the link nodes
** with FreeRemember() and the memory blocks with FreeMem().
** When FreeRemember() freed the link nodes, it reset RememberKey
** to NULL. This (second) call to FreeRemember() will do nothing.
*/
IIntuition->FreeRemember(&rememberKey, TRUE);
}
</syntaxhighlight>

== Current Time Values ==

The function CurrentTime() gets the current time values. To use this function, first declare the variables Seconds and Micros. Then, when the application call the function, the current time is copied into the argument pointers.

<syntaxhighlight lang="C" line>
VOID CurrentTime( ULONG *seconds, ULONG *micros );
</syntaxhighlight>

See the DOS library Autodocs for more information on functions dealing with the date and time. The DOS library includes such functions as DateToStr(), StrToDate(), SetFileDate() and CompareDates().

== Using Sprites in Intuition Windows and Screens ==

Sprite functionality has limitations under Intuition. The hardware and graphics library sprite systems manage sprites independently of the Intuition display. In particular:

* Sprites cannot be attached to any particular screen. Instead, they always appear in front of every screen.

* When a screen is moved, the sprites do not automatically move with it. The sprites move to their correct locations only when the appropriate function is called (either DrawGList() or MoveSprite()).

Hardware sprites are of limited use under the Intuition paradigm. They travel out of windows and out of screens, unlike all other Intuition mechanisms (except the Intuition pointer, which is meant to be global).

Remember that sprite data must be in Chip memory to be accessible to the custom chips on classic Amiga hardware. This may be done with a compiler specific feature, such as the __chip keyword of SAS/C. Otherwise, Chip memory can be allocated with the Exec AllocMem() function or the Intuition AllocRemember() function, setting the memory requirement flag to MEMF_CHIP. The sprite data may then be copied to Chip memory using a function like CopyMem() in the Exec library. See [[Graphics_Sprites,_Bobs_and_Animation|Graphics Sprites, Bobs and Animation]] for more information.

== Intuition and Preferences ==

The SetPrefs() function is used to configure Intuition's internal data states according to a given Preferences structure. This call relies on the Preferences system used in V34 and earlier versions of the OS. The old system has been superceded. See the [[Preferences|Preferences]] for details. This routine is called only by:

* The Preferences program itself after the user changes Preferences settings (under V34 and earlier).

* AmigaDOS when the system is being booted up. AmigaDOS opens the devs:system-configuration file and passes the information found there to the SetPrefs() routine. This way, the user can create an environment and have that environment restored every time the system is booted.

The function takes three arguments:

<pre>
struct Preferences *SetPrefs( struct Preferences *prefbuf, LONG size,
LONG realThing );
</pre>

The prefbuf argument is a pointer to a Preferences structure that will be used for Intuition's internal settings. The size is the number of bytes contained in your Preferences structure. Typically, you will use sizeof(struct Preferences) for this argument. The realThing argument is a boolean TRUE or FALSE designating whether or not this is an intermediate or final version of the Preferences. The difference is that final changes to Intuition's internal Preferences settings cause a global broadcast of NEWPREFS events to every application that is listening for this event. Intermediate changes may be used, for instance, to update the screen colors while the user is playing with the color gadgets.

{{Note|title=About SetPrefs()|text=The intended use for the SetPrefs() call is entirely to serve the user. You should never use this routine to make your programming or design job easier at the cost of yanking the rug out from beneath the user.}}

Refer to [[Preferences|Preferences]] for information about the Preferences structure and the preferred Preferences procedure calls.

== Function Reference ==

The following are brief descriptions of the Intuition functions discussed in this article. See the SDK for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| AllocRemember()
| Allocate memory and track the allocation.
|-
| FreeRemember()
| Free memory allocated with AllocRemember().
|-
| LockIBase()
| Lock IntuitionBase for reading.
|-
| UnlockIBase()
| Unlock IntuitionBase when done reading.
|-
| CurrentTime()
| Get the system time in seconds and micro-seconds.
|-
| SetPrefs()
| An Intuition internal function you should try to avoid.
|}

Virtual Sprites

2025-01-26T19:29:08Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

== Using Virtual Sprites ==

This section describes how to set up the VSprite structure so that it represents a true VSprite. True VSprites are managed by the GELs system which converts them to Simple Sprites and displays them. (Later sections describe how a VSprite structure can be set up for Bobs and AnimComps.)

Before the system is told of a VSprite's existence, space for the VSprite data structure must be allocated and initialized to "correctly" represent a VSprite. Since the system does no validity checking on the VSprite structure, the result of using a bogus structure is usually a fireworks display, followed by a system failure.

The system software provides a way to detect collisions between VSprites and other on-screen objects. There is also a method of extending the VSprite structure to incorporate user defined variables. These subjects are applicable to all GELs and are explained in [[Graphics_Sprites,_Bobs_and_Animation#Collisions_and_GEL_Structure_Extensions|Collisions and GEL Structure Extensions]].

=== Specification of VSprite Structure ===

The VSprite structure is defined in the include file <graphics/gels.h> as follows:

<syntaxhighlight lang="C" line>
/* VSprite structure definition */
struct VSprite {
struct VSprite *NextVSprite;
struct VSprite *PrevVSprite;
struct VSprite *DrawPath;
struct VSprite *ClearPath;
WORD OldY, OldX;
WORD Flags;
WORD Y, X;
WORD Height;
WORD Width;
WORD Depth;
WORD MeMask;
WORD HitMask;
WORD *ImageData;
WORD *BorderLine;
WORD *CollMask;
WORD *SprColors;
struct Bob *VSBob;
BYTE PlanePick;
BYTE PlaneOnOff;
VUserStuff VUserExt;
};
</syntaxhighlight>

There are two primary ways to allocate and fill in space for VSprite data. They can be statically declared, or a memory allocation function can be called and they can be filled in programmatically. The declaration to statically set up a VSprite structure is listed below.

<syntaxhighlight lang="C" line>
/* VSprite static data definition.
** must set the following for TRUE VSprites:
** VSPRITE flag.
** Width to 1.
** Depth to 2.
** VSBob to NULL.
*/
struct VSprite myVSprite =
{
NULL, NULL, NULL, NULL, 0, 0, VSPRITE, 0, 0, 5, 1, 2, 0, 0,
&myImage, 0, 0, &mySpriteColors, NULL, 0x3, 0, 0
};
</syntaxhighlight>

This static allocation gives the required VSprite structure, but does not allocate or set up collision masks for the VSprite. Note that the VSprite structure itself does not need to reside in Chip memory.

Refer to the makeVSprite() and freeVSprite() functions in the animtools.c listing at the end of the article for an example of dynamically allocating, initializing and freeing a VSprite structure.

=== Reserved VSprite Members ===

These VSprite structure members are reserved for system use (do not write to them):

; NextVSprite and PrevVSprite
: These are used as links in the GelsInfo list.

; DrawPath and ClearPath
: These are used for Bobs, not true VSprites.

; OldY and OldX
: Previous position holder, the system uses these for double buffered Bobs, but application programs can read them too.

The values can be set like this:

<syntaxhighlight lang="C" line>
myVSprite.NextVSprite = NULL;
myVSprite.PrevVSprite = NULL;
myVSprite.DrawPath = NULL;
myVSprite.ClearPath = NULL;
myVSprite.OldY = 0;
myVSprite.OldX = 0;
</syntaxhighlight>

=== Using VSprite Flags ===

The Flags member of the VSprite structure is both read and written by the system. Some bits are used by the application to inform the system; others are used by the system to indicate things to the application.

The only Flags bits that are used by true VSprites are:

; VSPRITE
: This may be set to indicate to the system that it should treat the structure as a true VSprite, not part of a Bob. This affects the interpretation of the data layout and the use of various system variables.

; VSOVERFLOW
: The system sets this bit in the true VSprites that it is unable to display. This happens when there are too many in the same scan line, and the system has run out of Simple Sprites to assign. It indicates that this VSprite has not been displayed. If no sprites are reserved, this means that more than eight sprites touch one scan line. This bit will not be set for Bobs and should not be changed by the application.

; GELGONE
: If the system has set GELGONE bit in the Flags member, then the GEL associated with this VSprite is not on the display at all, it is entirely outside the GEL boundaries. This area is defined by the GelsInfo members topmost, bottommost, leftmost and rightmost (see the <graphics/rastport.h> include file).

On the basis of that information, the application may decide that the object need no longer be part of the GEL list and may decide to remove it to speed up the consideration of other objects. Use RemVSprite() (or RemBob(), if it's a Bob) to do this. This bit should not be changed by the application.

The VSprite.Flags value should be initialized like this for a VSprite GEL:

<syntaxhighlight lang="C" line>
myVSprite.Flags = VSPRITE;
</syntaxhighlight>

=== VSprite Position ===

To control the position of a VSprite, the x and y variables in the VSprite structure are used. These specify where the upper left corner of the VSprite will be, relative to the upper left corner of the playfield area it appears over. So if VSprites are used under Intuition and within a screen, they will be positioned relative to the upper left-hand corner of the screen.

In a 320x200 screen, a y value of 0 puts the VSprite at the top of that display, a y value of (200 - VSprite height) puts the VSprite at the bottom. And an x value of 0 puts the VSprite at the left edge of that display, while an x value of (320 - VSprite width) puts the VSprite at the far right. Values of less than (0,0) or greater than (320, 200) may be used to move the VSprite partially or entirely off the screen, if desired.

See [[Graphics_Primitives|Graphics Primitives]] for more information on display coordinates and display size. See the "Amiga Hardware Reference Manual" for more information on hardware sprites.

{{Note|title=Position VSprites Properly|text=It is important that the starting position of true VSprites is not less than -20 in the y direction, which is the start of the active display area for sprites. Also, if they are moved too far to the left, true VSprites may not have enough DMA time to be displayed.}}

The ''x, y'' values may be set like this to put the VSprite in the upper-left:

<syntaxhighlight lang="C" line>
myVSprite.Y = 0;
myVSprite.X = 0;
</syntaxhighlight>

=== VSprite Image Size ===

A true VSprite is always one word (16 pixels) wide and may be any number of lines high. It can be made to appear thinner by making some pixels transparent. Like Simple Sprites, VSprite pixels are always the size of a pixel in low-resolution mode (320x200); regardless of the resolution the display is set to. To specify how many lines make up the VSprite image, the VSprite structure member, Height, is used.

VSprites always have a Depth of two, allowing for three colors. The values may be set like this:

<syntaxhighlight lang="C" line>
myVSprite.Width = 1; /* ALWAYS 1 for true VSprites. */
myVSprite.Height = 5; /* The example height. */
myVSprite.Depth = 2; /* ALWAYS 2 for true VSprites. */
</syntaxhighlight>

=== VSprites and Collision Detection ===

Some members of the VSprite data structure are used for special purposes such as collision detection, user extensions or for system extensions (such as Bobs and AnimComps). For most applications these fields are set to zero:

<syntaxhighlight lang="C" line>
myVSprite.HitMask = 0; /* These are all used for collision detection */
myVSprite.MeMask = 0;
myVSprite.BorderLine = 0;
myVSprite.CollMask = 0;

myVSprite.VUserExt = 0; /* Only use this for user extensions to VSprite */

myVSprite.VSBob = NULL; /* Only Bobs and AnimComps need this */
</syntaxhighlight>

The special uses of this fields are explained further in the sections that follow.

=== VSprite Image Data ===

The ImageData pointer of the VSprite structure must be initialized with the address of the first word of the image data array. The image data array must be in Chip memory. It takes two sequential 16-bit words to define each line of a VSprite. This means that the data area containing the VSprite image is always "Heightx2" (10 in the example case) words long.

A VSprite image is defined just like a real hardware sprite. The combination of bits in corresponding locations in the two data words that define each line select the color for that pixel. The first of the pair of words supplies the low-order bit of the color selector for that pixel; the second word supplies the high-order bit.

These binary values select colors as follows:

{| class="wikitable"
| 00 || selects "transparent"
|-
| 01 || selects the first of three VSprite colors
|-
| 10 || selects the second VSprite color
|-
| 11 || selects the third VSprite color
|}

In those areas where the combination of bits yields a value of 0, the VSprite is transparent. This means that the playfield, and all Bobs and AnimComps, and any VSprite whose priority is lower than this VSprite will all show through in transparent sections. For example:

<pre>
(&VSprite->ImageData) 1010 0000 0000 0000
(&VSprite->ImageData + 1) 0110 0000 0000 0000
</pre>

Reading from top to bottom, left to right, the combinations of these two sequential data words form the binary values of 01, 10, 11, and then all 00s. This VSprite's first pixel will be color 1, the next color 2, the third color 3. The rest will be transparent, making this VSprite appear to be three pixels wide. Thus, a three-color image, with some transparent areas, can be formed from a data set like the following sample:

<pre>
Address Binary Data VSprite Image Data
------- ----------- ------------------
mem 1111 1111 1111 1111 Defines top line
mem + 1 1111 1111 1111 1111 3333 3333 3333 3333

mem + 2 0011 1100 0011 1100 Defines second line
mem + 3 0011 0000 0000 1100 0033 1100 0011 3300

mem + 4 0000 1100 0011 0000 Defines third line
mem + 5 0000 1111 1111 0000 0000 3322 2233 0000

mem + 6 0000 0010 0100 0000 Defines fourth line
mem + 7 0000 0011 1100 0000 0000 0032 2300 0000

mem + 8 0000 0001 1000 0000 Defines fifth line
mem + 9 0000 0001 1000 0000 0000 0003 3000 0000
</pre>

The VSprite.Height for this sample image is 5.

=== Specifying the Colors of a VSprite ===

The system software provides a great deal of versatility in the choice of colors for Virtual Sprites. Each VSprite has "its own set" of three colors, pointed to by SprColors, which the system jams into the display's Copper list as needed.

SprColors points to the first of three 16-bit values. The first value represents the color used for the VSprite bits that select color 1, the second value is color 2, and the third value is color 3. When the system assigns a hardware sprite to carry the VSprite's image, it jams these color values into the Copper list (the intermediate Copper list, "not" the color table), so that the View's colors will be correct for this VSprite at the time the VSprite is displayed. It doesn't jam the original palette's colors back after the VSprite is done. If there is another VSprite later, that VSprite's colors will get jammed; if there is not another VSprite, the colors will remain the same until the next ViewPort's colors get loaded.

If the SprColors pointer is set to NULL, that VSprite does not generate a color-change instruction stream for the Copper. Instead, the VSprite appears drawn in whatever color set that the hardware sprite happens to have in it already.

Since the registers are initially loaded with the colors from the ViewPort's ColorMap, if all VSprites have NULL SprColors, they will appear in the ViewPort's colors.

To continue our example, a set of colors can be declared and the VSprite colors set with the following statements:

<syntaxhighlight lang="C" line>
uint16 mySpriteColors[] = { 0x0000, 0x00f0, 0x0f00 }; /* Declare colors statically */

myVSprite.SprColors = mySpriteColors; /* Assign colors to VSprite */
</syntaxhighlight>

=== Adding and Removing VSprites ===

Once a true VSprite has been set up and initialized, the obvious next step is to give it to the system by adding it to the GEL list. The VSprite may then be manipulated as needed. Before the program ends, the VSprite should be removed from the GELs list by calling RemVSprite().

A typical calling sequence could be performed like so:

<syntaxhighlight lang="C" line>
struct VSprite myVSprite = {0};
struct RastPort myRastPort = {0};

IGraphics->AddVSprite(&myVSprite, &myRastPort);

/* Manipulate the VSprite as needed here */

IGraphics->RemVSprite(&myVSprite);
</syntaxhighlight>

The &myVSprite argument is a fully initialized VSprite structure and &myRastPort is the RastPort with which this VSprite is to be associated. Note that you will probably not like the results if you try to RemVSprite() a VSprite that has not been added to the system with AddVSprite(). See the SDK for additional information on these functions.

=== Changing VSprites ===

Once the VSprite has been added to the GELs list and is in the display, some of its characteristics can be changed dynamically by:

* Changing y, x to a new VSprite position
* Changing ImageData to point to a new VSprite image
* Changing SprColors to point to a new VSprite color set

Study the next two sections to find out how to reserve hardware Sprites for use outside the VSprite system and how to assign the VSprites.

=== Getting the VSprite List in Order ===

When the system has displayed the last line of a VSprite, it is able to reassign the hardware sprite to another VSprite located at a lower position on the screen. The system allocates hardware sprites in the order in which it encounters the VSprites in the list. Therefore, the list of VSprites must be sorted before the system can assign the use of the hardware Sprites correctly.

The function SortGList() must be used to get the GELs in the correct order before the system is asked to display them. ''This sorting step is essential!'' It should be done before calling DrawGList(), whenever a GEL has changed position. This function is called as follows:

<syntaxhighlight lang="C" line>
struct RastPort myRastPort = {0};

IGraphics->SortGList(&myRastPort);
</syntaxhighlight>

The only argument is a pointer to the RastPort structure containing the GelsInfo.

=== Displaying the VSprites ===

The next few sections explain how to display the VSprites. The following system functions are used:

; DrawGList()
: Draws the VSprites into the current RastPort.

; MrgCop()
: Installs the VSprites into the display.

; LoadView()
: Asks the system to display the new View.

; WaitTOF()
: Synchronizes the functions with the display.

==== Drawing the Graphics Elements ====

The system function called DrawGList() looks through the list of GELS and prepares the necessary Copper instructions and memory areas to display the data. This function is called as follows:

<syntaxhighlight lang="C" line>
struct RastPort myRastPort = {0};
struct ViewPort myViewPort = {0};

IGraphics->DrawGList(&myRastPort, &myViewPort);
</syntaxhighlight>

The myRastPort argument specifies the RastPort containing the GelsInfo list with the VSprites that you want to display. The &myViewPort argument is a pointer to the ViewPort for which the VSprites will be created.

==== Merging VSprite Instructions ====

Once DrawGList() has prepared the necessary instructions and memory areas to display the data, the VSprites are installed into the display with MrgCop(). (DrawGList() does not actually draw the VSprites, it only prepares the Copper instructions.)

<syntaxhighlight lang="C" line>
struct View *view;

IGraphics->MrgCop(view);
</syntaxhighlight>

The view is a pointer to the View structure whose Copper instructions are to be merged.

==== Loading the New View ====

Now that the display instructions include the definition of the VSprites, the system can display this newly configured View with the LoadView() function:

<syntaxhighlight lang="C" line>
struct View *view;

IGraphics->LoadView(view);
</syntaxhighlight>

Again, view is a pointer to the View that contains the the new Copper instruction list (if you are using GELs in an Intuition Screen, do not call LoadView().)

The Copper instruction lists are double-buffered, so this instruction does not actually take effect until the next display field occurs. This avoids the possibility of some function trying to update the Copper instruction list while the Copper is trying to use it to create the display.

==== Synchronizing with the Display ====

To synchronize application functions with the display, call the system function WaitTOF().

WaitTOF() holds your task until the vertical-blanking interval (blank area at the top of the screen) has begun. At that time, the system has retrieved the current Copper instruction list and is ready to allow generation of a new list.

<syntaxhighlight lang="C" line>
WaitTOF();
</syntaxhighlight>

WaitTOF() takes no arguments and returns no values. It simply suspends your task until the video beam is at the top of field.

== Complete VSprite Example ==

The listing given here shows a complete VSprite example. This program requires the "animtools.c", "animtools.h" and "animtools_proto.h" support files in order to compile and run. These files are listed at the end of this article.

<pre>
/* vsprite.c
**
** SAS/C V5.10a
** lc -b1 -cfist -v -y vsprite.c
** blink FROM LIB:c.o vsprite.o animtools.o LIB LIB:lc.lib LIB:amiga.lib TO vsprite
*/
#include <exec/types.h>
#include <exec/memory.h>
#include <intuition/intuitionbase.h>
#include <graphics/gfx.h>
#include <graphics/gfxbase.h>
#include <graphics/gels.h>
#include <graphics/collide.h>
#include <libraries/dos.h>
#include <stdlib.h>
#include "animtools.h"

VOID borderCheck(struct VSprite *hitVSprite, LONG borderflags);
VOID process_window(struct Window *win, struct RastPort *myRPort, struct VSprite *MyVSprite);
VOID do_VSprite(struct Window *win, struct RastPort *myRPort);
VOID vspriteDrawGList(struct Window *win, struct RastPort *myRPort);

struct GfxBase *GfxBase; /* pointer to Graphics library */
struct IntuitionBase *IntuitionBase; /* pointer to Intuition library */

int return_code;
#define GEL_SIZE 4 /* number of lines in the vsprite */

/* VSprite data - there are two sets that are alternated between. */
/* note that this data is always displayed as low resolution. */
WORD chip vsprite_data1[] = { 0x7ffe, 0x80ff,
0x7c3e, 0x803f,
0x7c3e, 0x803f,
0x7ffe, 0x80ff,
0, 0 };

WORD chip vsprite_data2[] = { 0x7ffe, 0xff01,
0x7c3e, 0xfc01,
0x7c3e, 0xfc01,
0x7ffe, 0xff01,
0, 0 };

WORD mySpriteColors[] = { 0x0000, 0x00f0, 0x0f00 };
WORD mySpriteAltColors[] = { 0x000f, 0x0f00, 0x0ff0 };

NEWVSPRITE myNewVSprite = { /* information for the new VSprite */
/* Image data, sprite color array word width (must be 1 for true VSprite) */
vsprite_data1, mySpriteColors,1,
/* Line height, image depth (must be 2 for true VSprite), x, y position */
GEL_SIZE, 2, 160, 100,
/* Flags (VSPRITE == true VSprite), hit mask and me mask */
VSPRITE, 1 << BORDERHIT, 0
};

struct NewWindow myNewWindow = { /* information for the new window */
80, 20, 400, 150, -1, -1, CLOSEWINDOW | INTUITICKS,
ACTIVATE | WINDOWCLOSE | WINDOWDEPTH | RMBTRAP | WINDOWDRAG,
NULL, NULL, "VSprite", NULL, NULL, 0, 0, 0, 0, WBENCHSCREEN
};

/* Basic VSprite display subroutine */
VOID vspriteDrawGList(struct Window *win, struct RastPort *myRPort)
{
SortGList(myRPort);
DrawGList(myRPort, ViewPortAddress(win));
RethinkDisplay();
}

/* Collision routine for vsprite hitting border. Note that when the collision is VSprite to */
/* VSprite (or Bob to Bob, Bob to AnimOb, etc), then the parameters are both pointers to a VSprite. */
VOID borderCheck(struct VSprite *hitVSprite, LONG borderflags)
{
if (borderflags & RIGHTHIT)
{
hitVSprite->SprColors = mySpriteAltColors;
hitVSprite->VUserExt = -40;
}
if (borderflags & LEFTHIT)
{
hitVSprite->SprColors = mySpriteColors;
hitVSprite->VUserExt = 20;
}
}

/* Process window and dynamically change vsprite. Get messages. Go away on */
/* CLOSEWINDOW. Update and redisplay vsprite on INTUITICKS. Wait for more messages. */
VOID process_window(struct Window *win, struct RastPort *myRPort, struct VSprite *myVSprite)
{
struct IntuiMessage *msg;

FOREVER
{
Wait(1L << win->UserPort->mp_SigBit);
while (NULL != (msg = (struct IntuiMessage *)GetMsg(win->UserPort)))
{
/* Only CLOSEWINDOW and INTUITICKS are active */
if (msg->Class == CLOSEWINDOW)
{
ReplyMsg((struct Message *)msg);
return;
}
/* Must be an INTUITICKS: change x and y values on the fly. Note offset by
** window left and top edge--sprite relative to the screen, not window. Divide
** the MouseY in half to adjust for Lores movement increments on a Hires screen.
*/
myVSprite->X = win->LeftEdge + msg->MouseX + myVSprite->VUserExt;
myVSprite->Y = win->TopEdge + msg->MouseY/2 + 1;
ReplyMsg((struct Message *)msg);
}
/* Got a message, change image data on the fly */
myVSprite->ImageData = (myVSprite->ImageData == vsprite_data1) ? vsprite_data2 : vsprite_data1;
SortGList(myRPort);
DoCollision(myRPort);
vspriteDrawGList(win, myRPort);
}
}

/* Working with the VSprite. Setup the GEL system and get a new VSprite (makeVSprite()). */
/* Add VSprite to the system and display. Use the vsprite. When done, remove VSprite and */
/* update the display without the VSprite. Cleanup everything. */
VOID do_VSprite(struct Window *win, struct RastPort *myRPort)
{
struct VSprite *myVSprite;
struct GelsInfo *my_ginfo;

if (NULL == (my_ginfo = setupGelSys(myRPort, 0xfc)))
return_code = RETURN_WARN;
else
{
if (NULL == (myVSprite = makeVSprite(&myNewVSprite)))
return_code = RETURN_WARN;
else
{
AddVSprite(myVSprite, myRPort);
vspriteDrawGList(win, myRPort);
myVSprite->VUserExt = 20;
SetCollision(BORDERHIT, borderCheck, myRPort->GelsInfo);
process_window(win, myRPort, myVSprite);
RemVSprite(myVSprite);
freeVSprite(myVSprite);
}
vspriteDrawGList(win, myRPort);
cleanupGelSys(my_ginfo, myRPort);
}
}

/* Example VSprite program. First open up the libraries and a window. */
VOID main(int argc, char **argv)
{
struct Window *win;
struct RastPort myRPort = {0};

return_code = RETURN_OK;

if (NULL == (GfxBase = (struct GfxBase *)OpenLibrary(GRAPHICSNAME,37L)))
return_code = RETURN_FAIL;
else
{
if (NULL == (IntuitionBase = (struct IntuitionBase *)OpenLibrary(INTUITIONNAME,37L)))
return_code = RETURN_FAIL;
else
{
if (NULL == (win = OpenWindow(&myNewWindow)))
return_code = RETURN_WARN;
else
{
InitRastPort(&myRPort);
myRPort = win->WScreen->RastPort; /* Copy the structure. */
do_VSprite(win, &myRPort);
CloseWindow(win);
}
CloseLibrary((struct Library *)IntuitionBase);
}
CloseLibrary((struct Library *)GfxBase);
}
exit(return_code);
}
</pre>

== VSprite Advanced Topics ==

This section describes advanced topics pertaining to VSprites. It contains details about reserving hardware sprites for use outside of the GELs VSprite system, information about how VSprites are assigned, and more information about VSprite colors.

=== Reserving Hardware Sprites ===

To prevent the VSprite system from using specific hardware sprites, set the sprRsrvd member of the GelsInfo structure. The pointer to the GelsInfo structure is contained in the RastPort structure. If all of the bits of this 8-bit value are ones (0xFF), then all of the hardware sprites may be used by the VSprite system. If any of the bits is a 0, the sprite corresponding to that bit will not be utilized by VSprites.

{{Note|title=Reserving Can Cause Problems|text=Reserving sprites increases the likelihood of the system not being able to display a VSprite (VSOVERFLOW). See the next section, "How VSprites are Assigned", for further details on this topic.}}

You reserve a sprite by setting its corresponding bit in sprRsrvd. For instance, to reserve sprite zero only, set sprRsrvd to 0x01. To reserve sprite three only, set sprRsrvd to 0x08.

If a hardware sprite is reserved, the system will not consider it when it makes VSprite assignments. Remember, hardware sprite pairs share color register sets. If a hardware sprite is reserved, its mate should probably be reserved too, otherwise the reserved sprite's colors will change as the unreserved mate is assigned different VSprites. For example, it is common practice to reserve Sprites 0 and 1, so that the Intuition pointer (Sprite 0) is left alone. This could be accomplished with the following statements:

<syntaxhighlight lang="C" line>
struct RastPort myRastPort = {0}; /* the View structure is defined */

myRastPort.GelsInfo->sprRsrvd = 0x03; /* reserve 0 and 1 */
</syntaxhighlight>

The GfxBase structure may be examined to find which sprites are already in use. This may, at your option, impact what sprites you reserve. If Intuition is running, sprite 0 will already be in use as its pointer.

The reserved sprite status is accessible as

<syntaxhighlight lang="C" line>
currentreserved = GfxBase->SpriteReserved;
</syntaxhighlight>

The next section presents a few trouble-shooting techniques for VSprite assignment.

=== How VSprites Are Assigned ===

Although VSprites are managed for you by the GELs system there are some underlying limitations which could cause the system to run out of VSprites.

As the system goes through the GEL list during DrawGList(), whenever it finds a true VSprite, it goes through the following procedure. If there is a Simple Sprite available (after the reserved sprites and preceding VSprites are accounted for), Copper instructions are added that will load the sprite hardware with this VSprite's data at the right point on the screen. It may need to add a Copper instruction sequence to load the display's colors associated with the sprite as well.

There are only 8 ''real'' sprite DMA channels. The system will run out of hardware sprites if it is asked to display more than eight VSprites on one scan line. This limit goes down to four when the VSprites have different SprColor pointers. During the time that there is a conflict, the VSprites that could not be put into Simple Sprites will disappear. They will reappear when (as the VSprites are moved about the screen) circumstances permit.

These problems can be alleviated by taking some precautions:

* Minimize the number of VSprites to appear on a single horizontal line.
* If colors for some Virtual Sprites are the same, make sure that the pointer for each of the VSprite structures for these Virtual Sprites points to the same memory location, rather than to a duplicate set of colors elsewhere in memory. The system will know to map these into Sprite pairs.

If a VSprite's SprColors are set to NULL, the VSprite will appear in the ViewPort's ColorMap colors. The system will display the VSprite in any one of a set of four different possible color groupings as indicated in the Simple Sprite section above.

If SprColors points to a color set, the system will jam SprColors into the display hardware (via the Copper list), effectively overriding those ColorMap registers. The values in the ColorMap are ''not'' overwritten, but anything in the background display that used to appear in the ColorMap colors will appear in SprColors colors.

=== How VSprite and Playfield Colors Interact ===

At the start of each display, the system loads the colors from the ViewPort's color table into the display's hardware registers, so whatever is rendered into the BitMap is displayed correctly. But if the VSprite system is used, and the colors are specified (via SprColors) for each VSprite, the SprColors will be loaded by the system into the display hardware, as needed.

The system does this by generating Copper instructions that will jam the colors into the hardware at specific moments in the display cycle. Any BitMap rendering, including Bobs, which share colors with VSprites, may change colors constantly as the video display beam progresses down the screen.

This color changing can be avoided by taking one of the following precautions:

* Use a four bitplane playfield, which only allows the lower 16 colors to be rendered into the BitMap (and allows Hires display mode).
* If a 32-color playfield display is being used, avoid rendering in colors 17-19, 21-23, 25-27, and 29-32, which are the colors affected by the VSprite system.
* Specify the VSprite SprColors pointer as a value of NULL to avoid changing the contents of any of the hardware sprite color registers. This may cause the VSprites to change colors depending on their positions relative to each other, as described in the previous section.

Exec Device I/O

2025-01-26T19:28:59Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

== Exec Device I/O ==

The Amiga system devices are software engines that provide access to the Amiga hardware. Through these devices, a programmer can operate a modem, spin a disk drive motor, time an event, and blast a trumpet sound in stereo. Yet, for all that variety, the programmer uses each device in the same manner.

== What is a Device? ==

An Amiga device is a software module that accepts commands and data and performs I/O operations based on the commands it receives. In most cases, it interacts with either internal or external hardware, (the exceptions are the clipboard device and ramdrive device which simply use memory). Generally, an Amiga device runs as a separate task which is capable of processing your commands while your application attends to other things.

{| class="wikitable"
! colspan="3"|Amiga System Devices
|-
| [[Audio Device|Audio]] || audio.device || Controls the use of the audio hardware
|-
| [[Clipboard Device|Clipboard]] || clipboard.device || Manages the cutting and pasting of common data blocks
|-
| [[Console Device|Console]] || console.device || Provides the text-oriented user interface.
|-
| [[Gameport Device|Gameport]] || gameport.device || Controls the two mouse/joystick ports.
|-
| [[Input Device|Input]] || input.device || Processes input from the gameport and keyboard devices.
|-
| [[Keyboard Device|Keyboard]] || keyboard.device || Controls the keyboard.
|-
| [[Narrator Device|Narrator]] || narrator.device || Produces the Amiga synthesized speech.
|-
| [[Parallel Device|Parallel]] || parallel.device || Controls the parallel port.
|-
| [[Printer Device|Printer]] || printer.device || Converts a standard set of printer control codes to printer specific codes.
|-
| [[SCSI Device|SCSI]] || scsi.device || Controls the Small Computer Standard Interface hardware.
|-
| [[Serial Device|Serial]] || serial.device || Controls the serial port.
|-
| [[Timer Device|Timer]] || timer.device || Provides timing functions to measure time intervals and send interrupts.
|-
| [[Trackdisk Device|Trackdisk]] || trackdisk.device || Controls the Amiga floppy disk drives.
|}

The philosophy behind the devices is that I/O operations should be consistent and uniform. You print a file in the same manner as you play an audio sample, i.e., you send the device in question a WRITE command and the address of the buffer holding the data you wish to write.

The result is that the interface presented to the programmer is essentially device independent and accessible from any computer language. This greatly expands the power the Amiga brings to the programmer and, ultimately, to the user.

Devices support two types of commands: Exec standard commands like READ and WRITE, and device specific commands like the trackdisk device MOTOR command which controls the floppy drive motor, and the keyboard device READMATRIX command which returns the state of each key on the keyboard. You should keep in mind, however, that supporting standard commands does not mean that all devices execute them in ''exactly'' the same manner.

Consult the [[Devices|Amiga devices]] and the commands they support.

== Accessing a Device ==

Accessing a device requires obtaining a message port, allocating memory for a specialized message packet called an I/O request, setting a pointer to the message port in the I/O request, and finally, establishing the link to the device itself by opening it. An example of how to do this will be provided later in this section.

=== Creating a Message Port ===

When a device completes the command in a message, it will return the message to the message port specifed as the ''reply'' port in the message. A message port is obtained by calling the AllocSysObject() function with an object type of ASOT_PORT. You must delete the message port when you are finished by calling the FreeSysObject() function.

=== Creating an IO Request ===

The I/O request is used to send commands and data from your application to the device. The I/O request consists of fields used to hold the command you wish to execute and any parameters it requires. You set up the fields with the appropriate information and send it to the device by using Exec I/O functions. Different Amiga devices often require different I/O request structures. These structures all start with a simple IORequest or IOStdReq structure (see <exec/io.h>) which may be followed by various device-specific fields. Consult the Autodoc and include file for each device to determine the type and size I/O request required to access the device.

I/O request structures are commonly created and deleted with the AllocSysObject() and FreeSysObject() functions using an object type of ASOT_IOREQUEST. Any size and type of I/O request may be created with these functions.

=== Opening a Device ===

The device is opened by calling the OpenDevice() function. In addition to establishing the link to the device, OpenDevice() also initializes fields in the I/O request. OpenDevice() has this format:

<syntaxhighlight lang="C" line>
result = IExec->OpenDevice(device_name,unit_number,(struct IORequest *)IORequest,flags)
</syntaxhighlight>

; device_name
: is the name of the device.

; unit_number
: refers to one of the logical units of the device. Devices with one unit always use unit 0. Multiple unit devices like the trackdisk device and the timer device use the different units for specific purposes.

; IORequest
: is the structure discussed above. Some of the devices have their own I/O requests defined in their include files and others use standard I/O requests, (IOStdReq). Refer to [[Devices|Devices]] for more information.

; flags
: are bits set to indicate options for some of the devices. This field is set to zero for devices which don't accept options when they are opened. The flags for each device are explained in [[Devices|Devices]].

; result
: is an indication of whether the OpenDevice() was successful with zero indicating success. Never assume that a device will successfully open. Check the return value and act accordingly.

{{Note|title=''Zero Equals Success for OpenDevice().''|Unlike most Amiga system functions, OpenDevice() returns zero for success and a device-specific error value for failure.}}

=== Using A Device ===

Once a device has been opened, you use it by passing the I/O request to it. When the device processes the I/O request, it acts on the information the I/O request contains and returns a reply message, i.e., the I/O request, to the reply port specified in the I/O request when it is finished. The I/O request is passed to a device using one of three functions, '''DoIO()''', '''SendIO()''' and '''BeginIO()'''. They take only one argument: the I/O request you wish to pass to the device.

;DoIO()
:DoIO() is a synchronous function. It will not return until the device has responded to the I/O request.
:This function calls the BeginIO() entry point in the device driver with IOF_QUICK set. If the device driver leaves IOF_QUICK set, it returns to the caller immediately. The return value is the extended value of the "io_Error" field in the I/O request. If the IOF_QUICK bit is cleared, it falls through to WaitIO().

;SendIO()
:SendIO() is an asynchronous function. It can return immediately, but the I/O operation it initiates may take a short or long time. Using '''SendIO()''' requires you to monitor the message port for a return message from the device. In addition, some devices do not actually respond asynchronously even though you called '''SendIO()'''; they will return when the I/O operation is finished.
:This function calls the BeginIO() entry point in the device driver with IOF_QUICK clear. This means that the device driver should return the I/O request with ReplyMsg().

;BeginIO()
:There is one operation which DoIO() and SendIO() cannot handle, and that is sending an I/O request with the IOF_QUICK flag set, but not waiting for it to complete. That is "run this as quickly as possible but if it's going to take a while, don't wait for it". For this operation, the user must set IOF_QUICK manually, then call the device driver directly through its BeginIO() entry point.
:When the quick I/O flag (IOF_QUICK) is set in the I/O request, a device is allowed to take certain shortcuts in performing and completing a request. If the request can complete immediately, the device will not return a reply message and the quick I/O flag will remain set. If the request cannot be completed immediately, the QUICK_IO flag will be clear. '''DoIO()''' normally requests quick I/O; '''SendIO()''' does not.

'''DoIO()''' and '''SendIO()''' are most commonly used.

{{Note|title=BeginIO() Side Effects|text=BeginIO() will run on the context of the caller if quick I/O is used by the device driver. This means BeginIO() may allocate memory, wait or perform other functions which are illegal or dangerous during interrupts.}}

An I/O request typically has three fields set for every command sent to a device. You set the command itself in the '''io_Command''' field, a pointer to the data for the command in the '''io_Data''' field, and the length of the data in the '''io_Length''' field.

<syntaxhighlight lang="C" line>
SerialIO->IOSer.io_Length = sizeof(ReadBuffer);
SerialIO->IOSer.io_Data = ReadBuffer;
SerialIO->IOSer.io_Command = CMD_READ;
IExec->SendIO((struct IORequest *)SerialIO);
</syntaxhighlight>

Commands consist of two parts—a prefix and the command word separated by an underscore, all in upper case. The prefix indicates whether the command is an Exec or device specific command. All Exec commands have '''CMD''' as the prefix. They are defined in the include file exec/io.h.

=== Standard Exec Commands ===

This section lists the command and error numbers which are predefined in the Amiga system for all types of device drivers.

The following commands are reserved for all devices:
* CMD_INVALID
* CMD_RESET
* CMD_READ
* CMD_WRITE
* CMD_UPDATE
* CMD_CLEAR
* CMD_STOP
* CMD_START
* CMD_FLUSH
* CMD_NONSTD

It is seen that command number zero is invalid, and command numbers greater than 9 are custom defined.

There are 65536 command values possible with io_Command:

$0000 - $3FFF old style and 3rd party commands
$4000 - $7FFF RESERVED AREA!
$8000 - $BFFF old style and 3rd party commands
$C000 - $FFFF RESERVED AREA!

Commands in the reserved areas may only be assigned and specified by the AmigaOS Development Team. Any "custom" implementation of these commands or other commands in these reserved areas is illegal and violates the [[NSD_Standard|New Style Device (NSD) Standard]].

==== CMD_RESET ====

This resets the device to a known initial state. Pending I/O requests not processed at the time of this command should be returned with an error.

==== CMD_READ ====

This requests that "io_Length" items of data be read from location "io_Offset" on the unit, and stored at "io_Data" in the caller's memory. The actual amount of data transferred is returned in "io_Actual". The specifics depend on the device type.

==== CMD_WRITE ====

This requests that data be transferred from the caller's memory to the I/O unit. The arguments are the same as for CMD_READ.

==== CMD_UPDATE ====

This requests that all buffered, but unwritten data be forced out to the I/O unit. It might write out the track buffer in a disk device, for example.

==== CMD_CLEAR ====

This requests that all data buffered by the device for the given unit be invalidated. Thus, for example, it would throw away data waiting in a serial input buffer.

==== CMD_STOP ====

This requests that the unit stop processing commands. I/O requests not processed at the time of the CMD_STOP will wait until a CMD_START or CMD_RESET is received or they are aborted.

==== CMD_START ====

This requests that the unit clear a CMD_STOP condition and resume processing commands. Only one CMD_START is required, regardless of how many CMD_STOPs have been received.

==== CMD_FLUSH ====

This requests that the unit flush all pending commands. All I/O requests queued but not yet processed should be sent back with an error.

==== Error Numbers ====

The include file "exec/errors.h" lists the following standard error numbers.

{| class="wikitable"
! Constant !! Description
|-
| IOERR_SUCCESS || not an error (success)
|-
| IOERR_OPENFAIL || device/unit failed to open
|-
| IOERR_ABORTED || request aborted
|-
| IOERR_NOCMD || command not supported
|-
| IOERR_BADLENGTH || not a valid length
|-
| IOERR_BADADDRESS || invalid address (misaligned or bad range)
|-
| IOERR_UNITBUSY || device opens ok, but requested unit is busy
|-
| IOERR_SELFTEST || device is currently performing a self-test
|}

=== Synchronous vs. Asynchronous Requests ===

Each device maintains its own I/O request queue. When a device receives an I/O request, it either processes the request immediately or puts it in the queue because one is already being processed. After an I/O request is completely processed, the device checks its queue and if it finds another I/O request, begins to process that request.

As stated above, you can send I/O requests to a device synchronously or asynchronously. The choice of which to use is largely a function of your application.

Synchronous requests use the '''DoIO()''' function. '''DoIO()''' will not return control to your application until the I/O request has been satisfied by the device. The advantage of this is that you don’t have to monitor the message port for the device reply because '''DoIO()''' takes care of all the message handling. The disadvantage is that your application will be tied up while the I/O request is being processed, and should the request not complete for some reason, '''DoIO()''' will not return and your application will hang.

Asynchronous requests use the '''SendIO()''' and '''BeginIO()''' functions. Both return to your application almost immediately after you call them. This allows you to do other operations, including sending more I/O requests to the device. Note that any additional I/O requests you send must use separate I/O request structures. Outstanding I/O requests are not available for re-use until the device is finished with them.

{{Note|title=''Do Not Touch!''|text=When you use '''SendIO()''' or '''BeginIO()''', the I/O request you pass to the device and any associated data buffers should be considered read-only. Once you send it to the device, you must ''not'' modify it in any way until you receive the reply message from the device or abort the request (though you must still wait for a reply). Any exceptions to this rule are documented in the autodoc for the device.}}

Sending multiple asynchronous I/O requests to a device can be tricky because devices require them to be unique and initialized. This means you can't use an I/O request that's still in the queue, but you need the fields which were initialized in it when you opened the device. The solution is to copy the initialized I/O request to another I/O request(s) before sending anything to the device.

Regardless of what you do while you are waiting for an asynchronous I/O request to return, you need to have some mechanism for knowing when the request has been done. There are two basic methods for doing this.

The first involves putting your application into a wait state until the device returns the I/O request to the message port of your application. You can use the '''WaitIO()''', '''Wait()''' or '''WaitPort()''' function to wait for the return of the I/O request. It is important to note that all of the above functions and also '''DoIO()''' may '''Wait()''' on the message reply port's mp_SigBit. For this reason, the task that created the port must be the same task the waits for completion of the I/O. There are three ways to wait:

; WaitIO()
: not only waits for the return of the I/O request, it also takes care of all the message handling functions. This is very convenient, but you can pay for this convenience: your application will hang in the unlikely event that the I/O request does not return.
: If the I/O request has the IOF_QUICK flag set, it cannot possibly be in progress, so it returns immediately.

; Wait()
: waits for a signal to be sent to the message port. It will awaken your task when the signal arrives, but you are responsible for all of the message handling.

; WaitPort()
: waits for the message port to be non-empty. It returns a pointer to the message in the port, but you are responsible for all of the message handling.

The second method to detect when the request is complete involves using the '''CheckIO()''' function. '''CheckIO()''' takes an I/O request as its argument and returns an indication of whether or not it has been completed. When '''CheckIO()''' returns the completed indication, you will still have to remove the I/O request from the message port.

{{Note|text=WaitIO() and CheckIO() know about the IOF_QUICK flag and will behave accordingly.}}

=== I/O Request Completion ===

A device will set the '''io_Error''' field of the I/O request to indicate the success or failure of an operation. The indication will be either zero for success or a non-zero error code for failure. There are two types of error codes: Exec I/O and device specific. Exec I/O errors are defined in the include file <exec/errors.h>; device specific errors are defined in the include file for each device. You should always check that the operation you requested was successful.

The exact method for checking '''io_Error''' can depend on whether you use '''DoIO()''' or '''SendIO()'''. In both cases, '''io_Error''' will be set when the I/O request is returned, but in the case of '''DoIO()''', the '''DoIO()''' function itself returns the same value as '''io_Error'''. This gives you the option of checking the function return value:

<syntaxhighlight lang="C" line>
SerialIO->IOSer.io_Length = sizeof(ReadBuffer);
SerialIO->IOSer.io_Data = ReadBuffer;
SerialIO->IOSer.io_Command = CMD_READ;
if (IExec->DoIO((struct IORequest *)SerialIO)
IDOS->Printf("Read failed. Error: %ld\n", SerialIO->IOSer.io_Error);
</syntaxhighlight>

Or you can check io_Error directly:

<syntaxhighlight lang="C" line>
SerialIO->IOSer.io_Length = sizeof(ReadBuffer);
SerialIO->IOSer.io_Data = ReadBuffer;
SerialIO->IOSer.io_Command = CMD_READ;
IExec->DoIO((struct IORequest *)SerialIO);
if (SerialIO->IOSer.io_Error)
IDOS->Printf("Read failed. Error: %ld\n", SerialIO->IOSer.io_Error);
</syntaxhighlight>

Keep in mind that checking '''io_Error''' is the ''only'' way that I/O requests sent by '''SendIO()''' can be checked.

Testing for a failed I/O request is a minimum step, what you do beyond that depends on your application. In some instances, you may decide to resend the I/O request and in others, you may decide to stop your application. One thing you'll almost always want to do is to inform the user that an error has occurred.

{{Note|title=Exiting The Correct Way|text=If you decide that you must prematurely end your application, you should deallocate, release, give back and let go of everything you took to run the application. In other words, you should exit gracefully.}}

=== Ending Device Access ===

You end device access by reversing the steps you did to access it. This means you close the device, deallocate the I/O request memory and delete the message port. In that order!

Closing a device is how you tell Exec that you are finished using a device and any associated resources. This can result in housecleaning being performed by the device. However, before you close a device, you might have to do some housecleaning of your own.

A device is closed by calling the '''CloseDevice()''' function. The '''CloseDevice()''' function does not return a value. It has this format:

<syntaxhighlight lang="C" line>
IExec->CloseDevice(IORequest);
</syntaxhighlight>

where '''IORequest''' is the I/O request used to open the device.

You should not close a device while there are outstanding I/O requests, otherwise you can cause major and minor problems. Let's begin with the minor problem: memory. If an I/O request is outstanding at the time you close a device, you won't be able to reclaim the memory you allocated for it.

The major problem: the device will try to respond to the I/O request. If the device tries to respond to an I/O request, and you've deleted the message port (which is covered below), you will probably crash the system.

One solution would be to wait until all I/O requests you sent to the device return. This is not always practical if you've sent a few requests and the user wants to exit the application immediately.

In that case, the only solution is to abort and remove any outstanding I/O requests. You do this with the functions '''AbortIO()''' and '''WaitIO()'''. They must be used together for cleaning up. '''AbortIO()''' will abort an I/O request, but will not prevent a reply message from being sent to the application requesting the abort. '''WaitIO()''' will wait for an I/O request to complete and remove it from the message port. This is why they must be used together.

{{Note|title=''Be Careful With AbortIO()!''|Do not AbortIO() an I/O request which has ''not'' been sent to a device. If you do, you may crash the system.}}

Here is the checklist for gracefully exiting:

# Abort any outstanding I/O requests with '''AbortIO()'''.
# Wait for the completion of any outstanding or aborted I/O requests with '''WaitIO()'''.
# Close the device with '''CloseDevice()'''.
# Release the I/O request memory with '''FreeSysObject()''' using the '''ASOT_IOREQUEST''' object type.
# Delete the message port with '''FreeSysObject()''' using the '''ASOT_PORT''' object type.

=== Expunging a Device ===

A device can be deleted from the system using this function:

<syntaxhighlight lang="C" line>
error = IExec->RemDevice(device);
</syntaxhighlight>

The system issues this function itself if it runs out of memory and tries to reclaim space. The device is called through its Expunge() entry point.

The device should now shut down its activity, i.e. remove interrupt servers, deallocate buffers, and so on. Then it should unlink its device node from the device list, and deallocate the node, thus restoring things to the state they were in just before it was started up with InitResident(). Finally, it should return the "segList" parameter which was passed to it at initialization time. If the device came from disk, the system will use this to unload its code.

If the device is not idle when the Expunge() call arrives, it can defer the operation. To do this, it sets the LIBF_DELEXP flag in the library structure, and returns zero. This indicates that it will delete itself at the earliest opportunity.

== Devices With Functions ==

Some devices, in addition to their commands, provide library-style functions which can be directly called by applications. These functions are documented by each device.

Devices with functions behave much like Amiga libraries, i.e., you set up a base address pointer and call the functions as offsets from the pointer. See [[Exec_Libraries|Exec Libraries]] for more information.

The procedure for accessing a device's functions is as follows:

* Declare the device base address variable in the global data area. The correct name for the base address can be found in the device's proto file.

* Create a message port.

* Create an I/O request.

* Call '''OpenDevice()''', passing the I/O request. If '''OpenDevice()''' is successful (returns 0), the address of the device base may be found in the '''io_Device''' field of the I/O request structure. Consult the include file for the structure you are using to determine the full name of the '''io_Device''' field. The base address is only valid while the device is open.

* Set the device base address variable to the pointer returned in the '''io_Device''' field.

* Get the interface pointer for this device using the above device base address.

We will use the timer device to illustrate the above method. The name of the timer device base address is listed in its proto file as TimerBase.

<syntaxhighlight lang="C" line>
#include <devices/timer.h>

struct Library *TimerBase; /* device base address pointer */
struct TimerIFace *ITimer; /* interface for timer device */
struct MsgPort *TimerMP; /* message port pointer */
struct TimeRequest *TimerIO; /* I/O request pointer */

/* Create the message port. */
TimerMP = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);
if (TimerMP != NULL)
{
/* Create the I/O request. */
TimerIO = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct TimeRequest),
ASOIOR_ReplyPort, TimerMP,
TAG_END);

if ( TimerIO != NULL )
{
/* Open the timer device. */
if ( !(IExec->OpenDevice(TIMERNAME,UNIT_MICROHZ,TimerIO,0)) )
{
/* Set up pointer for timer functions. */
TimerBase = (struct Library *)TimerIO->tr_node.io_Device;

ITimer = (struct TimerIFace *)IExec->GetInterface(TimerBase, "main", 1, NULL);

/* Use timer device library-style functions such as CmpTime() through ITimer...*/

IExec->CloseDevice(TimerIO); /* Close the timer device. */
}
else
IDOS->Printf("Error: Could not open %s\n", TIMERNAME);
}
else
IDOS->Printf("Error: Could not create I/O request\n");
}
else
IDOS->Printf("Error: Could not create message port\n");
}
</syntaxhighlight>

== Using An Exec Device ==

The following short example demonstrates use of an Amiga device. The example opens the serial.device and then demonstrates both synchronous (DoIO()) and asynchronous (SendIO()) use of the serial command SDCMD_QUERY. This command is used to determine the status of the serial device lines and registers.

<syntaxhighlight lang="C" line>
/* DeviceUse.c - an example of using an Amiga device (here, serial device) */
/* */
/* If successful, use the serial command SDCMD_QUERY, then reverse our steps. */
/* If we encounter an error at any time, we will gracefully exit. */

#include <exec/types.h>
#include <exec/memory.h>
#include <exec/io.h>
#include <devices/serial.h>

#include <proto/exec.h>
#include <proto/dos.h>

int main()
{
struct IOExtSer *reply; /* for use with GetMsg */

struct MsgPort *serialMP = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);

if (serialMP != NULL)
{
/* Create the I/O request. Note that <devices/serial.h> defines the type */
/* of IORequest required by the serial device--an IOExtSer. Many devices */
/* require specialized extended IO requests which start with an embedded */
/* struct IORequest. The generic Exec and amiga.lib device IO functions */
/* are prototyped for IORequest, so some pointer casting is necessary. */

struct IOExtSer *serialIO = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOExtSer),
ASOIOR_ReplyPort, serialMP,
TAG_END);

if (serialIO != NULL)
{
/* Open the serial device (non-zero return value means failure here). */
if (IExec->OpenDevice( SERIALNAME, 0, (struct IORequest *)serialIO, 0))
IDOS->Printf("Error: %s did not open\n", SERIALNAME);
else
{
/* Device is open */ /* DoIO - demonstrates synchronous */
serialIO->IOSer.io_Command = SDCMD_QUERY; /* device use, returns error or 0. */
if (IExec->DoIO((struct IORequest *)serialIO))
IDOS->Printf("Query failed. Error - %d\n", serialIO->IOSer.io_Error);
else
/* Print serial device status - see include file for meaning */
/* Note that with DoIO, the Wait and GetMsg are done by Exec */
IDOS->Printf("Serial device status: $%x\n\n", serialIO->io_Status);

serialIO->IOSer.io_Command = SDCMD_QUERY; /* SendIO - demonstrates asynchronous */
IExec->SendIO((struct IORequest *)serialIO); /* device use (returns immediately). */

/* We could do other things here while the query is being done. */
/* And to manage our asynchronous device IO: */
/* - we can CheckIO(serialIO) to check for completion */
/* - we can AbortIO(serialIO) to abort the command */
/* - we can WaitPort(serialMP) to wait for any serial port reply */
/* OR we can WaitIO(serialIO) to wait for this specific IO request */
/* OR we can Wait(1L << serialMP_>mp_SigBit) for reply port signal */

IExec->Wait(1U << serialMP->mp_SigBit);

while(reply = (struct IOExtSer *)IExec->GetMsg(serialMP))
{ /* Since we sent out only one serialIO request the while loop is */
/* not really needed--we only expect one reply to our one query */
/* command, and the reply message pointer returned by GetMsg() */
/* will just be another pointer to our one serialIO request. */
/* With Wait() or WaitPort(), you must GetMsg() the message. */
if(reply->IOSer.io_Error)
IDOS->Printf("Query failed. Error - %d\n", reply->IOSer.io_Error);
else
IDOS->Printf("Serial device status: $%x\n\n", reply->io_Status);
}
IExec->CloseDevice((struct IORequest *)serialIO); /* Close the serial device. */
}
IExec->FreeSysObject(ASOT_IOREQUEST, serialIO); /* Delete the I/O request. */
}
else IDOS->Printf("Error: Could create I/O request\n"); /* Inform user that the I/O */
/* request could be created. */
IExec->FreeSysObject(ASOT_PORT, serialMP); /* Delete the message port. */
}
else IDOS->Printf("Error: Could not create message port\n"); /* Inform user that the message*/
/* port could not be created. */

return 0;
}
</syntaxhighlight>

== Creating An Exec Device ==

=== The BeginIO Entry Point ===

All I/O requests enter the device driver through the BeginIO() entry point. The device driver is entered in the context of the requesting task.

Normally, the device driver will now use PutMsg() to enqueue the I/O request on a message port (in a Unit structure) for processing by an internal task. Then it can return from the BeginIO() function. When Exec checks to see if the I/O request is completed yet, it checks its type field, and if it is NT_MESSAGE (as results from the PutMsg() call) it knows that it is still in progress. Eventually, the internal task receives the I/O request, operates on it, and does a ReplyMsg(). This returns the I/O request to the caller's reply port, and also sets its type to NT_REPLYMSG, signaling that it is finished.

It is clear that the device driver does not have to follow this procedure exactly. Short commands (such as checking if a disk is ready) can just be done immediately, in the caller's context. The I/O request must simply be returned with ReplyMsg() at the end, and its type field must be something other than NT_REPLYMSG if the BeginIO() function returns with
the I/O request not completed yet.

A special case of I/O processing is signaled by the IOF_QUICK flag. When it is set, it means that the requester has used the DoIO() function, and thus will be doing nothing until the I/O is complete. In this case, the device driver can run the whole I/O operation in the caller's context and return immediately. Message passing and task switch overhead is eliminated. When the BeginIO() function returns with the IOF_QUICK bit still set, it means that the I/O operation is complete.

If the device driver sees the IOF_QUICK flag set but cannot perform the I/O processing inline, it can simply clear the flag and return the I/O request with ReplyMsg() as usual.

The BeginIO() function operates on the command and parameters in the I/O request, and sets the "io_Error" field to indicate the result. Exec I/O functions return the value of this field to the caller; BeginIO() itself does not return a value. "io_Error" set to zero means that no error has occurred.

=== The AbortIO Entry Point ===

Some device driver operations, such as waiting for a timeout or input on a serial port, may need to be aborted before they complete. The AbortIO() function is provided for this. The device driver is entered through its AbortIO() entry point with the address of the I/O request to be aborted and the device node pointer. If the device driver determines that the I/O request is indeed in progress and can successfully abort it, it returns zero, otherwise it returns a non-zero error code.

A successfully aborted I/O request is returned by the normal method, i.e. ReplyMsg(). The "io_Error" field should indicate that it did not complete normally.

=== Unit Structures ===

Many device drivers manage more than one functional unit. For example, the trackdisk driver can handle up to four floppy drives. The preferred approach is to use a separate "Unit" structure for each functional unit (e.g. drive). Normally, a unit structure consists of at least the following:

<syntaxhighlight lang="C" line>
struct Unit {
struct MsgPort unit_MsgPort;
uint8 unit_flags;
/* UNITF_ACTIVE = 1
UNITF_INTASK = 2 */
uint8 unit_pad;
uint16 unit_OpenCnt;
};
</syntaxhighlight>

When the device driver is opened, it uses the unit number to select the appropriate unit structure, and stores the pointer to this structure in the I/O request. Later, it can queue up pending I/O requests on the message port for processing by the unit task.

== Function Reference ==

The following chart gives a brief description of the Exec functions that control device I/O. See the SDK for details about each call.

{| class="wikitable"
! Exec Device I/O Function
! Description
|-
| AllocSysObject(ASOT_IOREQUEST)
| Create an IORequest structure.
|-
| FreeSysObject(ASOT_IOREQUEST)
| Delete an IORequest created by AllocSysObject().
|-
| OpenDevice()
| Gain access to an Exec device.
|-
| CloseDevice()
| Close Exec device opened with OpenDevice().
|-
| DoIO()
| Perform a device I/O command and wait for completion.
|-
| SendIO()
| Initiate an I/O command. Do not wait for it to complete.
|-
| CheckIO()
| Get the status of an IORequest.
|-
| WaitIO()
| Wait for completion of an I/O request.
|-
| AbortIO()
| Attempt to abort an I/O request that is in progress.
|-
| BeginIO()
| Initiate an asynchronous device I/O request.
|}

== Credits ==

Special thanks to [http://wandel.ca Markus Wandel] for allowing us to use material from his [http://wandel.ca/homepage/execdis/devices_doc.txt Amiga Device Driver Guide].

Xena Resource

2025-01-26T19:28:52Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

== Xena Resource ==

The Xena Resource provides access to the Xena chip on the AmigaOne X1000. Two functions allow you to use the Xena chip.

'''Xena Resource Functions'''
{| class="wikitable"
| AllocResource() || Obtain exclusive access to one of the Xena resources.
|-
| FreeResource() || Returns a resource to the system.
|}

{| class="wikitable"
!colspan="2"|Xena Resource Information
|-
| Includes || resources/xena.h
|-
| AutoDocs || [[xenares.doc]]
|}

There are four separate resources that may be requested.
The application must secure as many as it requires to access the Xena system.
XR_XTAGPORT is for access to the JTAG control lines that access the Xena chip and any additional devices on the Xorro board.
XR_DATABUS is for the fast Localbus access to Core0.
XR_INTERRUPT is used for Xena to interrupt the PA6T when it needs attention. This is likely to be used with XR_DATABUS
XR_LONELYBIT is the extra unassigned pin

Example code to use the XTAG port:
<syntaxhighlight lang="C" line>
#include <proto/xena.h>
#include <resources/xena.h>
struct XenaIFace *IXena;
IXena = IExec->OpenResource("xena.resource");
if(NULL == IXena)
{
exit(-5);
}
STRPTR result = IXena->AllocResource(XR_XTAGPORT, "MyAppName");
if(NULL == result)
{
// we have exclusive access,
// code using the JTAG port goes here

//when finished, just
IXena->FreeResource(XR_XTAGPORT);
}
else
{
IDOS->Printf("We cannot access the port because %s got here first\n", result);
}
</syntaxhighlight>

AmiWest Lesson 1

2025-01-26T19:28:40Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= AmiWest Lesson 1: Coding Basics =

== Compiler and Linker ==

The [http://gcc.gnu.org/ GNU GCC toolset] is the officially supported standard compiler suite for Amiga operating system programming. An good alternative C compiler named [http://www.compilers.de/vbcc.html vbcc] is also supported and is popular with some programmers. We will focus on GCC which supports both C and C++.

Some Amiga-specific extensions to the baseline GNU GCC have been made to support the new Exec Interfaces, switching C standard libraries, shared objects and more. The source code for GNU GCC is readily available from the [http://sourceforge.net/projects/adtools/ Amiga Development Tools web site] and you are encouraged to participate if you are able.

There is a large wealth of detailed documentation and support for GNU GCC and programmers are encouraged to search around the internet. The Amiga-specific extensions are described on the [http://wiki.amigaos.net AmigaOS Documentation Wiki].

== Standard C Library ==

AmigaOS officially uses a variant of the [http://sourceware.org/newlib/ Newlib C standard library] implementation. For programmers, it is essential to know what your C standard library is and what its limits are. Functions may or may not be available. Behaviour may or may not be identical between C standard library implementations.

A popular alternative C standard library implementation is called [http://sourceforge.net/projects/clib2/ clib2] and it is included as an option with the standard Amiga SDK. The clib2 library is particular well suited for porting software from the Unix world. The complete source code for clib2 is also available which makes is possible to debug complex problems involving the C library itself.

Switching between C standard library is easy thank to an Amiga-specific extension to GCC. The -mcrt option is used for both compiling and linking:
-mcrt=newlib (default, always thread-safe)
-mcrt=clib2 (non-thread safe version)
-mcrt=clib2-ts (thread-safe version)

== AmigaOS Threading ==

AmigaOS uses lightweight processes and a shared memory model. As such, it has never been a high priority to provide an Amiga-specific threading implementation.

That said, the [http://en.wikipedia.org/wiki/POSIX_Threads POSIX threading] API (Pthreads) has been implemented and is available for programmers. This familiar API is quite popular so a lot of software has been written to use it.

AmigaOS supports a subset of the pthreads standard. It is implemented as a standard shared library with both static and dynamic link interfaces. The dynamic link interface is an Amiga shared object named libpthread.so. The static link interface is available in both newlib and clib2 flavours. These link libraries are just thin wrappers for the underlying pthreads.library which is currently private.

If your software is AmigaOS-specific then it is fine to launch and control processes using the existing API.

== Threading in C and C++ ==

It is very important to note that both C and C++ did not directly support threading until recently. This may come as a surprise to many programmers that have been developing threading applications in both C and C++ for many years.

Since there was no official standard for so long, threading has always been system dependent and several threading standards have come and gone over the years.

With C, the threading issue is relatively simple and GNU GCC supports a memory model which has always supported threading so there is little for an Amiga programmer to worry about. This is true for all platforms GCC supports.

The C++ programming language is a more complicated issue. The current GCC compiler implementation does not support threading on AmigaOS. This can be verified with the g++ -v command. The output of this command will specify what threading model is supported. On AmigaOS it currently states:

Thread model: single

This means threading is not supported. As a consequence, C++ exceptions and the RTTI feature will not function correctly in the presence of threads. Both features are optional in C++ but highly desirable. Amiga programmers may need to make some tough decisions in this case.

== Program Startup ==

There are two primary environments in which a user can start applications in AmigaOS - by Shell console or by Workbench. Each method comes with its own way of sending the application its starting arguments, data or options.

With the Workbench, the user can either double-click the application's icon, shift click the app and some other icon(s) or double-click an icon that has this application as its "default tool".

In the Shell console, the user usually enters the name of the program and ends the command line with arguments, options and/or a filename.

In either case, the application typically uses and responds to the files, options and/or arguments that were involved in starting it. A file is opened and/or the program runs as configured.

=== How did your application start? ===

Following standard ISO C, AmigaOS applications always start using the standard '''argc''' and '''argv''' parameters:

<syntaxhighlight lang="C" line>
int main(int argc, char **argv)
</syntaxhighlight>

The '''argc''' variable indicates the number of arguments received by the application. The first argument ('''argv[0]''') contains the program name. Any following command line arguments are stored in following '''argv''' array elements ('''argv[1]''', '''argv[2]''', ...).

AmigaOS provides special startup code that fills in the argc and argv parameters for you. The reason for the special startup code is twofold: to setup the standard C library and to support launching programs from Workbench or the Shell.

In AmigaOS, if ''argc''' is equal to zero that means the application was started from the Workbench. If it is non-zero then it means the application was started from the Shell console.

While the ISO C method works for applications started from the Shell, it does not directly support an application started from the Workbench. AmigaOS provides ways for handling both Workbench start-up as well as a more sophisticated way of dealing with Shell start-up and arguments.

=== Starting from the Console: the ISO C way ===

For the sake of ISO C standard conformance, an AmigaOS application can use the standard '''argv''' array variables to read the arguments passed to the app.

After determining the argument count ('''argc''') is greater than zero, then that number of arguments can be accessed and printed out as follows:

<syntaxhighlight lang="C" line>
for (int argNo=0; argNo < argc; ++argNo)
{
// print CLI arguments
printf(" argument #%d = >%s<\n", argNo, argv[argNo]);
}
</syntaxhighlight>

This method then leaves the parsing and testing of the arguments to the application and its developer. Many 3rd party libraries are available to parse the arguments such as [http://www.gnu.org/software/libc/manual/html_node/Getopt.html Getopt]. Since we are focusing on AmigaOS-specific programming they won't be discussed any further.

More information about this topic can be found in [[AmigaDOS_Programming#Running_a_Program_under_the_CLI|Running a Program under the CLI]].

=== Starting from the Console: the AmigaOS way ===

AmigaOS provides an alternate way for applications to parse arguments from a Shell command line using the '''ReadArgs''' function. In its most common use, this function will parse command line arguments according to a "template" defined by the application. If the user follows the command name with a question mark, this function will print the application's commands template and then allow the user to type in their arguments. If the user fails to provide a valid command line, then '''ReadArgs''' lets the application know and the application can then exit gracefully.

More information about this topic can be found in [[AmigaDOS_Programming#Standard_Command_Line_Parsing|Standard Command Line Parsing]].

==== Configuring ReadArgs ====

The '''ReadArgs''' function is called with the following syntax:

<syntaxhighlight lang="C" line>
struct RDArgs *result = IDOS->ReadArgs(CONST_STRPTR template, int32 *array, struct RDArgs *rdargs);
</syntaxhighlight>

The first "template" parameter is a pointer to a string that defines the application's keywords, settings and "toggles" along with the following "modifiers":

:* '''/S''' - Switch - indicates keyword string is a boolean setting
:* '''/K''' - Keyword - indicates keyword string must appear before a setting
:* '''/N''' - Number - indicates a setting must be an integer
:* '''/T''' - Toggle - indicates keyword must be followed with a boolean setting (ON, OFF, etc)
:* '''/A''' - Required - indicates keyword must be followed with a value
:* '''/F''' - Rest of line - indicates the rest of the line isn't parsed and taken as one setting
:* '''/M''' - Multiple strings - indicates following strings except for keywords are settings

Examples of such templates can be found by typing most any AmigaOS command line command with a "?". Here is an code example of how such a "template" definition could look like:

<syntaxhighlight lang="C" line>
CONST_STRPTR argTemplate = "TEST/K,NUMBER/K/N,FILE";
</syntaxhighlight>
[Note: Make sure there are no spaces in your template!]

This template allows the user to enter the following optional settings for an application:

:* the TEST keyword followed with a value.
:* the NUMBER keyword follwed with a numeric value.
:* the FILE keyword and a filename.

The second parameter in the '''ReadArgs''' function is an array of '''int32''' pointers. If the '''ReadArgs''' function finds valid arguments, the respective array elements will point to any valid user input for those parameters (in template order). To start with, those pointers can be defined and set to NULL values like this:

<syntaxhighlight lang="C" line>
int32 argArray[] =
{
0,
0,
0
};
</syntaxhighlight>

The final parameter of '''ReadArgs''' function is typically NULL unless the application wants to set some default values (see the DOS/ReadArgs autodocs for more information on this).

==== Calling ReadArgs ====

Once run, the '''ReadArgs''' function will return either a pointer to a '''RDArgs''' structure if it succesfully parsed valid arguments or NULL if inadequate input was provided by the user. If the '''ReadArgs''' function was successful, then each entry of the second parameter (the '''argArray''' defined above) will point to any valid input for that slot in the template.

It is the developer's choice how best to deal with inadequate input from the user ('''ReadArgs''' returns a NULL value). At the very lest the application should gracefully let the user know the command line arguments were not accepted.

====Using ReadArgs Results====
For example, with the above code, the first entry ('''argArray[0]''') would point to any valid input that followed the "TEST" keyword, if it was in the command line. This value could be printed as follows:

<syntaxhighlight lang="C" line>
if ((int32 *)argArray[0] != NULL)
IDOS->Printf(" TEST = %s\n", (STRPTR)argArray[0]);
</syntaxhighlight>

If the second "NUMBER" keyword was used with a numeric value, its value could be obtained from the second arguments array entry as follows:

<syntaxhighlight lang="C" line>
int32 intArg;
if ((int32 *)argArray[1] != NULL)
{
intArg = *(int32 *)argArray[1];
IDOS->Printf(" NUMBER = %ld\n", intArg);
}
</syntaxhighlight>

==== Cleaning Up After ReadArgs ====

If '''ReadArgs''' successfuly parsed input from the command line, the '''FreeArgs''' function must be called using the resulting pointer from '''ReadArgs''' ('''rdargs''' in the above example). This will release any memory used by '''ReadArgs''' to store the user's input, as follows:

<syntaxhighlight lang="C" line>
IDOS->FreeArgs(rdargs);
</syntaxhighlight>

=== Starting from the Workbench: Getting File Names ===

As discussed above, if the user starts an application from the Workbench, AmigaOS indicates this by setting the '''argc''' variable to ZERO. AmigaOS also uses the '''argv''' variable to send a pointer to a '''WBStartup''' structure that contains more information on the user's actions.

There are three ways the user could have started an application that will be reflected by the contents of the '''WBStartup''' structure;

:*'''The user double-clicked on the application's icon''' - In which case the '''WBStartup''' structure will indicate the program's name and "lock" its directory location on disk.

:*'''The user double-clicked on the "project" file's icon that had this application set as its "tool"''' - In addition to the app's information, the '''WBStartup''' structure will indicate the project file's name and "lock" the project file's directory.

:*'''The user selected one (or more) "project" files and shift-double-clicked on the application's icon''' - The '''WBStartup''' structure will have a file name and directory "lock" for each of the project files in addition to the application's information.

In all these cases, when the application starts, it must goes though a few steps to determine if any files were selected with it. If the application also wants to read any settings attached to those files - as "Tool Types" within their icons - the application has to go through a few more steps. These steps start with reading the '''WBStartup''' structure passed to the app.

More information about this topic can be found in [[Workbench_and_Icon_Library#Workbench_Environment|Workbench Environment]] and
[[Workbench_and_Icon_Library#Workbench_and_the_Startup_Code_Module|Workbench and Startup Code]].

==== Accessing the WBStartup structure ====

When started by the Workbench, an application is passed a pointer to the '''WBStartUp''' structure in the standard '''argv''' variable. After checking the '''argc''' variable is equal to zero (to see that it was started by the Workbench), the '''WBStartUp'' structure can be obtained like this:

<syntaxhighlight lang="C" line>
if (argc == 0)
{
struct WBStartup *wbs = (struct WBStartup *)argv;
}
</syntaxhighlight>

The '''WBStartup''' structure is based on the AmigaOS '''Message''' structure and it has the following format:

<syntaxhighlight lang="C" line>
struct WBStartup
{
struct Message sm_Message; /* a standard message structure */
struct MsgPort * sm_Process; /* the process descriptor for you */
BPTR sm_Segment; /* a descriptor for your code */
int32 sm_NumArgs; /* the number of elements in ArgList */
char * sm_ToolWindow; /* reserved for future use */
struct WBArg * sm_ArgList; /* the arguments themselves */
};
</syntaxhighlight>

Under typical circumstances the '''sm_NumArgs''' and '''sm_ArgList''' are the only elements of the structure that need to be accessed for program start up. The number of arguments will always be at least one, with the first entry representing the application itself. Any number of arguments above one reflects the number of "project" files or icons the user selected when the application was started.

The '''sm_ArgList''' will be an array of '''WBArg''' structures where the number of elements corresponds to the number of application & data files selected by the user (reflected by the '''sm_NumArgs''' variable above). The '''WBArg''' structure containing the arguments has the following format:

<syntaxhighlight lang="C" line>
struct WBArg
{
BPTR wa_Lock; /* a lock descriptor */
STRPTR * wa_Name; /* a string relative to that lock */
};
</syntaxhighlight>

The '''wa_Lock''' contains a pointer to an AmigaOS "lock" on the directory containing that argument's application or data file. For each of the files (the application or project files) passed to the application from the Workbench, a "lock" is applied to that directory. This prevents the directory of the application or any of the selected data files ("projects") from being disturbed or deleted while they are in use.

The '''wa_Name''' contains a string pointer to the name of the application or data file. This is a pointer to the name of the file itself and doesn't include the pathname for the directory is stored in.

The names of the application and any selected files could be printed out with the following code excerpt:

<syntaxhighlight lang="C" line>
uint8 NoArgs, argNo;
NoArgs = wbs->sm_NumArgs;
IDOS->Printf(" number of args received = %ld\n", NoArgs);
for (argNo = 0; argNo < NoArgs; ++argNo)
IDOS->Printf(" arg %ld name = >%s<\n", argNo, wbs->sm_ArgList[argNo].wa_Name);
</syntaxhighlight>

Below we will see how to obtain more information from the selected files and how to get full path names for each. When the application finishes running, AmigaOS will release the "locks" on the directories referred to by the '''WBStartUp''' entries.

=== WorkBench StartUp: Examining Icons & Tooltypes ===

Whereas options might be given to a program in the Shell console in the form of argument in command line, Workbench programs frequently keep such settings within the application's icon, which is stored in a companion '''.info''' file. Specifically, each icon has the ability to store "Tool Types" text strings within the icon's .info file. While such settings can be almost any form of text, the standard format is to have a SETTING, equals sign and a value, like these:

<pre>
TEST=verbose
NUMBER=23
</pre>

These "Tool Type" settings are usually stored within the application's icon, but such settings can be also stored in most any icon files in AmigaOS. As such, an application can also look for such information within each project's icon file.

For an application to access any information that might be stored in its icon's '''.info''' file or in those of the "Projects" passed to the application, the application needs to go through a few more steps after collecting the related file names (mentioned above).

More information about this topic can be found in [[Workbench_and_Icon_Library#The_Tool_Types_Array|Tool Types Array]].

==== Getting to Each Icon's Directory ====

The easiest way to access any of the files sent by the Workbench is to use the '''sm_ArgList''' entry provided for each. This is done by first confirming a valid directory was found and "locked" for us by the Workbench. Then we call the '''CurrentDir''' function to switch the application to that directory, like this:

<syntaxhighlight lang="C" line>
if (wbs->sm_ArgList[argNo].wa_Lock != ZERO)
{
BPTR oldDir = IDOS->CurrentDir(wbs->sm_ArgList[argNo].wa_Lock);
}
</syntaxhighlight>

As you can see, this function returns a pointer to the old directory when we switch to the new directory location. This is very important, since the Workbench also maintains a directory lock based on the application's current directory. Before an application finishes, it needs to call the '''CurrentDir''' function again and switch back to the application's original location so it can be "unlocked" when the app quits - like this:

<syntaxhighlight lang="C" line>
IDOS->CurrentDir(oldDir);
</syntaxhighlight>

==== Getting Icon Information ====

Once the application has "moved" to the directory of the icon file to be examined, we can use the '''GetDiskObjectNew''' function to get information from the icon. This function is simply called using the same '''wa_Name''' element from the '''sm_ArgList''' structure used above, as in this code excerpt:

<syntaxhighlight lang="C" line>
struct DiskObject *dobj;
dobj = IIcon->GetDiskObjectNew(wbs->sm_ArgList[argNo].wa_Name);
if(dobj != NULL)
{
IDOS->Printf(" Opened disk object.\n");
}
</syntaxhighlight>

The '''GetDiskObjectNew''' function automatically appends the ".info" necessary to open the selected file's icon. If there is no .info file for the selected file, this function will automatically use the information from the "default icon" for the selected file type. For example, if the file "test.jpg" has no "test.jpg.info" icon file, the "def_jpeg.info" will be used.

If an application needs to explore icon information for a file not in the current directory of the app, the '''GetDiskObjectNew''' function will also accept the name of a file including a full path. But as we will see below, this does involve the application going through the overhead of allocating a string sufficient to store the full file & path name.

If successful, the '''GetDiskObjectNew''' function returns a pointer to a '''DiskObject''' structure that provides the following information for that '''.info''' file and icon:

<syntaxhighlight lang="C" line>
struct DiskObject
{
UWORD do_Magic; /* magic number at start of file */
UWORD do_Version; /* so we can change structure */
struct Gadget do_Gadget; /* a copy of in core gadget */
UBYTE do_Type;
char *do_DefaultTool;
char **do_ToolTypes;
LONG do_CurrentX;
LONG do_CurrentY;
struct DrawerData *do_DrawerData;
char *do_ToolWindow; /* only applies to tools */
LONG do_StackSize; /* only applies to tools */
};
</syntaxhighlight>

As you can see, the '''DiskObject''' structure presents most of the information conveyed by an AmigaOS icon. The '''do_DefaultTool''' is the setting that is used to designate whichever application will be used when a "Project" icon is double-clicked. The '''do_ToolTypes''' element points to an array of strings containing the icon's "Tool Types".

==== Checking for Our Tooltypes ====

AmigaOS provides another function to simplify checking the Tool Types for values an application is interested in - the '''FindToolType''' function. It is simply called with the pointer to the '''do_ToolTypes''' array and the desired setting string. This function returns either a pointer to the string with that ToolType setting or NULL if the ToolType wasn't found. The following code would check for our "TEST" ToolType and print out any results found.

<syntaxhighlight lang="C" line>
STRPTR TTarg = NULL;
TTarg = IIcon->FindToolType(dobj->do_ToolTypes, "TEST");
if (TTarg)
IDOS->Printf(" TEST found set to = >%s<\n", TTarg);
</syntaxhighlight>

With all the above code, an application can check each of the elements of the '''sm_ArgList''' sent by the Workbench to check for Tool Types in the app's icon as well as any of the icons of any Project files sent to the app.

=== Workbench StartUp: Getting Path & File Names ===

So far the above code has relied on using the '''WBStartUp''' structure and '''sm_ArgList''' sub-structure to obtain the necessary information on the application and any Project files selected. This has avoided directly dealing with the full file and path names of those files. If the full file & path name is required, the application can get the full path name by examining the directory "lock" of each '''sm_ArgList''' entry. This is done by calling the DOS '''NameFromLock''' function with another multi-step process.

First we must allocate a string in which to put the full name, then call '''NameFromLock''' to get the path name from the "Lock" and finally we must free the allocated memory after we're done with it. The following code excerpt would obtain the path to the application (always the first entry in '''sm_ArgList'''):

<syntaxhighlight lang="C" line>
int32 StringLen = 2048;
// Alloc memory for pathname string
filename = (STRPTR) IExec->AllocVecTags(StringLen, TAG_END);
if (filename)
{
if (wbs->sm_ArgList[0].wa_Lock != ZERO)
if (IDOS->NameFromLock(wbs->sm_ArgList[0].wa_Lock,filename, StringLen) != 0)
IDOS->Printf(" app path name = >%s<\n", filename);
// deallocate pathname string memory
IExec->FreeVec(filename);
}
</syntaxhighlight>

As you can see, we allocate a large string size for the path name - 2048 characters - to provide room for potentially long and/or heavily nested path names. If that string is not long enough, the '''NameFromLock''' function will fail and return a NULL value. The developer must use their judgment in deciding how likely this error might be and how much effort to put into handling it - whether to have the application politely handle and notify the user of the error or whether to wrap this function in some loop that keeps allocating larger string sizes until '''NameFromLock''' succeeds.

Obviously, there are few levels of error trapping in this code: to make sure we were able to allocate our string ('''filename'''), to make sure there is a valid directory lock to use and finally to make sure the path name could be obtained from the lock. Regardless of how unlikely failure might be, within any application these tests should occur and be "wrapped" in proper and graceful error handling and feedback.

==== Getting The Full Name ====

Once we have the path name, we can combine that with the name of the file (from the '''wa_Name''' element of the '''sm_ArgList''' structure). AmigaOS provides the '''AddPart''' function which also resolves AmigaOS separator characters ("/" or ":") to create a valid and complete file pathname, like this:

<syntaxhighlight lang="C" line>
if (IDOS->AddPart(filename,wbs->sm_ArgList[argNo].wa_Name,StringLen) != 0)
IDOS->Printf(" full path = >%s<\n", filename);
</syntaxhighlight>

The resulting combined path and file name should be suitable for use by the application - to open or act upon the file selected by the user.

Bear in mind, we are still working within the fixed size of the "filename" string that must contain both the path name as well as the file name. As before, we use error trapping to check that the combined file and path names fit into the string length we've defined. Again, should there be a failure, provide feedback and gracefully manage the situation.

=== Example Program Source Code ===

The following is an example program to demonstrate the above concepts in starting an application from the Shell and the Workbench.

From the Shell, the user can enter arguments or enter the "?" to see the template prompt before entering arguments. Commented out within the code
is a working example of using the simple ANSI method of reading command line arguments.

From the Workbench, this example will print out all the above information found on all the arguments passed by the Workbench. Besides the application's information, the printed information will reflected selected icons or Projects calling this app as a default Tool.

An archive for use with CodeBench is available [[Media:ArgParser.lha|from here]].

<syntaxhighlight lang="C" line>
/*
************************************************************
**
** Created by: CodeBench 0.26 (04.01.2012)
**
** Project: PJS-OS4ex-StartUp
**
** Version: 4
**
** File: This an example program of the various AmigaOS
** ways of starting an application - from CLI or
** Workbench - and dealing with the options.
**
** Date: 25-08-2012 18:21:44
**
************************************************************
*/

#include <exec/execbase.h>
#include <workbench/startup.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/icon.h>

#include <string.h>
#include <stdio.h>

// declare & initialize empty LONG words array to be filled with pointers to CLI arguments received
int32 argArray[] =
{
0,
0,
0
};

// declare the number of possible arguments (the size of the argArray above)
uint8 noArgs = 3;

// declare CLI options template string with these modifiers:
// /S - Switch - indicates keyword string is a boolean setting
// /K - Keyword - indicates keyword string must appear before a setting
// /N - Number - indicates a setting must be an integer
// /T - Toggle - indicates keyword must be followed with a boolean setting (ON, OFF, etc)
// /A - Required - indicates keyword must be followed with a value
// /F - Rest of line - indicates the rest of the line isn't parsed and taken as one setting
// /M - Multiple strings - indicates following strings except for keywords are settings
//
CONST_STRPTR argTemplate = "TEST/K,NUMBER/K/N,FILE";

uint8 returnCode = RETURN_OK;

// Starting program
int main(int argc,char **argv)
{
uint8 argNo;

IDOS->Printf("AmigaOS StartUp Example\n");

// Check if program was started from CLI or Workbench based on value of "argc"
if (argc > 0)
{
IDOS->Printf("Started from CLI.\n");

// declare struct pointer to receive CLI options
struct RDArgs *rdargs;

// read CLI args (using AmigaOS method)
rdargs=IDOS->ReadArgs(argTemplate,argArray,NULL);

// were CLI arguments sucessfully read?
if (rdargs)
{
int32 intArg;

// loop through possible options & settings and print them
for (argNo=0; argNo<noArgs; ++argNo)
{
// print readarg arguments
IDOS->Printf(" arg %ld = %s\n", argNo, argArray[argNo]);
if ((int32 *)argArray[argNo] != NULL)
{
intArg = *(int32 *)argArray[argNo];
IDOS->Printf(" # = >%ld<\n", intArg);
}
}

// free memory used by ReadArgs and data
IDOS->FreeArgs(rdargs);
}
else
IDOS->Printf(" ERROR: Incorrect Values received by ReadArgs\n");

//read args using ISO C method
/*
for (argNo=0; argNo<argc; ++argNo)
{
// print CLI arguments
IDOS->Printf(" argument #%ld = >%s<\n", argNo, argv[argNo]);
}
*/
}
else
{
IDOS->Printf("Started from Workbench.\n");

// set pointer to WBStartUp structure using argv contents
struct WBStartup *wbs = (struct WBStartup *)argv;

// set a length for path names (to be added to file name length)
int32 MaxPathLen = 1792;
// set a length for file names (to be added to path name length)
int32 MaxFileLen = 256;

// working variable
uint8 NoArgs;
STRPTR filename = NULL;
STRPTR TTarg = NULL;
BPTR oldDir = ZERO;

// print out number of arguments (first one is this program)
NoArgs = wbs->sm_NumArgs;
IDOS->Printf(" number of args received = %ld\n", NoArgs);

// Alloc memory for pathname string
filename = (STRPTR) IExec->AllocVecTags(MaxPathLen+MaxFileLen, TAG_END);

// Alloc disk object pointer for icon information
struct DiskObject *dobj;

if (filename)
{
// loop through WB arguments getting path names
for (argNo=0; argNo<NoArgs; ++argNo)
{
IDOS->Printf(" arg %ld name = >%s<\n", argNo, wbs->sm_ArgList[argNo].wa_Name);

if (wbs->sm_ArgList[argNo].wa_Lock != ZERO)
{
IDOS->Printf(" file locked.\n");

// CD to project file's dir
oldDir = IDOS->CurrentDir(wbs->sm_ArgList[argNo].wa_Lock);

// get disk object on argument's file
dobj = IIcon->GetDiskObjectNew(wbs->sm_ArgList[argNo].wa_Name);
if(dobj)
{
IDOS->Printf(" Opened disk object.\n");

// check for "TEST" keyword
TTarg = IIcon->FindToolType(dobj->do_ToolTypes, "TEST");
if (TTarg)
IDOS->Printf(" TEST found set to = >%s<\n",TTarg);
else
IDOS->Printf(" TEST tooltype not found.\n");

// check for "NUMBER" keyword
TTarg = IIcon->FindToolType(dobj->do_ToolTypes, "NUMBER");
if (TTarg)
IDOS->Printf(" NUMBER found set to = >%s<\n",TTarg);
else
IDOS->Printf(" NUMBER tooltype not found.\n");

// free disk object structure & memory
IIcon->FreeDiskObject(dobj);
}
else
{
// print why we couldn't get icon information
int32 MYerror, MYerrLen;
MYerror = IDOS->IoErr();
IDOS->Printf(" ERROR: Unable to open disk object.\n");
IDOS->Printf(" number = >%ld<\n",MYerror);
MYerrLen = IDOS->Fault(MYerror,NULL,filename,80);
IDOS->Printf(" text = >%s<\n",filename);
returnCode = RETURN_ERROR;
}

// CD back to previous dir
IDOS->CurrentDir(oldDir);

// Indicate what type of file the WBArg is refering to
if (argNo == 0)
IDOS->Printf(" entry = application.\n");
else
{
// check item type
if (strlen(wbs->sm_ArgList[argNo].wa_Name) > 0)
IDOS->Printf(" entry = file.\n");
else
IDOS->Printf(" entry = device or directory.\n");
}

// Get the path and full path/filename of the file
if (IDOS->NameFromLock(wbs->sm_ArgList[argNo].wa_Lock,filename,MaxPathLen) != 0)
{
IDOS->Printf(" path name = >%s<\n",filename);

if (IDOS->AddPart(filename,wbs->sm_ArgList[argNo].wa_Name,MaxPathLen+MaxFileLen) != 0)
IDOS->Printf(" full path = >%s<\n",filename);
else
{
IDOS->Printf(" ERROR: full name is larger than %ld\n",(MaxPathLen+MaxFileLen));
returnCode = RETURN_WARN;
}
}
else
{
IDOS->Printf(" ERROR: path name is larger than %ld\n",MaxPathLen);
returnCode = RETURN_WARN;
}

}
else
{
IDOS->Printf(" ERROR: file handle could not be locked.\n");
returnCode = RETURN_ERROR;
}
}

// deallocate pathname string memory
IExec->FreeVec(filename);
}
else
{
IDOS->Printf(" ERROR: unable to allocate memory for string!\n");
returnCode = RETURN_ERROR;
}
}

IDOS->Printf("GOODBYE!\n");
return (returnCode);
}
</syntaxhighlight>

Intuition Requesters

2025-01-26T19:28:23Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

== Intuition Requesters ==

This article explains how to create requesters, the information exchange boxes that both the system and applications can use for confirming actions, getting command options and similar operations. These boxes are called requesters because they generally request information from the user.

== Types Of Requesters ==

There are at least three kinds of display objects in Amiga terminology called requesters: ''true requesters'', ''system requesters'' and ''ASL requesters''.

True requesters are general purpose display areas that can be thought of as temporary sub-windows. They display information to the user and allow the user to make a selection. True requesters always open within an existing window and are constrained to the boundaries of that window (often referred to as the ''parent'' window). If a requester extends beyond the edge of its parent window, either its position is adjusted or its graphics are clipped. True requesters always block input to their parent window as long as they are present.

System requesters are typically used for warnings or to confirm an action the user has just initiated. System requesters differ from true requesters in that they cannot block input to the parent window. In fact, system requesters do not open in a parent window at all, but instead open their own separate window in the screen. Since these requesters are so different from true requesters, they will be discussed separately later in the article. See the sections on [[#Easy Requesters|Easy Requesters]] and [[#System Requesters|System Requesters]] for more information.

The third type of requester, the ASL requester, is a special purpose requester. ASL requesters provide an easy, standard way to get a filename from the user for load and save operations. They can also be used to get a font selection or screen mode selection from the user. For the details about ASL file and font requesters, see [[ASL_Library|ASL Library]].

== True Requesters ==

The primary function of a requester is to display information to the user from which the user is to make a selection. Conceptually, requesters are similar to menus since both menus and requesters offer options to the user. Requesters, however, go beyond menus because they can have customized imagery, can be placed anywhere in a window, can be activated by the application and may have any type of gadget attached.

For instance, to select a color for a given operation using a menu could be awkward, especially in an application that supports a large number of colors. In that case a requester could be used instead (see figure).

[[File:LibFig7-1.png|frame|center|Requester Deluxe]]

The ability of a true requester to block input to its parent window is important in understanding how requesters are used. When input is blocked by a true requester (also known as a modal requester), the user must take some action before the program will proceed further, such as making a selection, correcting an error condition, or acknowledging a warning. These are situations where a true (modal) requester is appropriate, however, keep in mind that your application should try to be as user-responsive as possible. Putting up a requester merely because you are in a phase of the program where it would be difficult to deal with user input is bad style. Modal requesters should be used only when the program ''requires'' user interaction before proceeding.

True requesters can be created in a window in two different ways.

* An application can display a requester at any time by calling the Request() function.

* The application can declare a requester as the window's ''double menu requester'', which the user can bring up with a double-click of the menu button (this method is rarely used).

=== Creating Application Requesters ===

To create a requester, the application first allocates memory for or declares an instance of the Requester structure as defined in <intuition/intuition.h>. Once the Requester structure is set up, it is initialized with the InitRequester() function.

<syntaxhighlight lang="C" line>
VOID InitRequester( struct Requester *requester);
</syntaxhighlight>

This function simply clears the Requester structure. The application should do further initialization depending on its needs. See the section on the "Requester Structure" below for an explanation of all the Requester fields and how to set them.

A true (modal) requester is attached to its parent window and displayed with the Request() function.

<syntaxhighlight lang="C" line>
BOOL Request(struct Requester *requester, struct Window *window);
</syntaxhighlight>

This function returns TRUE if the requester opens successfully or FALSE if the requester cannot be opened. If the requester opens successfully, menu and gadget input in the parent window is blocked as long as the requester is displayed. The application should process input events from the requester, which are sent to the parent window's Window.UserPort, until the requester is satisfied.

To remove a requester from its parent window and update the display, use EndRequest().

<syntaxhighlight lang="C" line>
VOID EndRequest( struct Requester *requester, struct Window *window );
</syntaxhighlight>

This removes only the one requester specified. It is possible to set up a requester with a special gadget that, if selected, will automatically close the requester. In that case, EndRequest() need not be called. If the program needs to cancel the request early, or cancel it only after some specific manipulation of the gadgets, EndRequest() should be used.

The application should always provide a safe way for the user to back out of a requester without taking any action that affects the user's work. Providing an escape hatch is important, for instance, a requester with the message "Overwrite File?" should allow the user to cancel the operation without losing the old data.

=== Requester I/O ===

So long as a requester is active in a window, the only gadgets that can be used are those that are in the requester, plus all of the window's system gadgets except for the close gadget (i.e., the drag bar, size gadget, depth gadget, and zoom gadget). A requester also makes the menus of the parent window inaccessible. Additionally, mouse button and keyboard events will be blocked (unless the requester's NOISYREQ flag is set; see "Requester Structure" below). Mouse movement events, if enabled in the parent window (with WFLG_REPORTMOUSE), are not blocked.

Requesters do not have their own IDCMP message ports. Instead, events for a requester are sent to the IDCMP port of the requester's parent window (Window.UserPort). Since the window's menus and application gadgets are inaccessible, no IDCMP events will be sent for them.

Even though the window containing the requester is blocked for input, the user can work in another application or even in a different window of the same application without satisfying the requester. Only input to the parent window is blocked by a requester.

Output is not blocked by a requester so nothing prevents the application from writing to the window. Be aware, however, that the requester obscures part of the display and cannot be moved within the window so this may limit the usefulness of any output you send to the parent window. There are several ways to monitor the comings and goings of requesters that allow the program to know if requesters are currently displayed in a given window. See "IDCMP Requester Features" below.

The information displayed in a requester is placed in its own layer, so it does not overwrite the information in the window. Output to the window while the requester is displayed will not change the requester's display, it will go into the window's layer. The requester's layer is clipped to the window's boundaries, so the data in the requester is only visible if the window is large enough to allow for the complete display of that data.

The requester will remain in the window and input will remain blocked until the user satisfies the request or the application removes the requester. Applications can set up some or all of the gadgets in the requester to automatically terminate the requester when the gadget is selected. This allows the requester to be removed from the window by user action. The application may also remove requesters from the window based on some event internal to the program.

Multiple requesters may be nested in a single window. Such requesters must be satisfied in the reverse order in which they were posted; the last requester to be displayed must be satisfied first. Input will not be restored to a previous requester until all later requesters are satisfied.

Note that the application may not bring up a limitless number of requesters in a window. Each requester creates a new layer for rendering in its window and the system currently has a limit of ten layers per window. Normal windows use one layer for the window rendering, GimmeZeroZero windows use a second layer for the border rendering. This leaves a maximum of eight or nine simultaneous requesters open in a window at any given time.

FILE * If the requester is being brought up only to display an error message, the application may want to use a less intrusive method of bringing the error to the user's attention than a requester. Requesters interrupt the flow of the user's work, and force them to respond before continuing.

As an alternative to bringing up an error requester, the application could flash the screen instead with Intuition's DisplayBeep() function. This allows the application to notify the user of an error that is not serious enough to warrant a requester and to which the user does not really need to respond. For more information, see the description of DisplayBeep() in [[Intuition_Screens|Intuition Screens]].

=== Rendering Requesters ===

The application may choose to use Intuition's rendering facilities to display the requester, or it may define its own custom bitmap. The Requester structure is initialized differently according to the rendering method chosen.

To use Intuition's rendering facilities, you supply a list of one or more display objects with the Requester structure and submit the Requester to Intuition, allowing it to draw the objects. These objects can include independent lists of Borders, IntuiText, Images and Gadgets. Note that the ability to provide a list of Image structures requires the use of the USEREQIMAGE flag which must be set for them to be rendered. For more about Intuition rendering see [[Intuition_Images,_Line_Drawing_and_Text|Intuition Images, Line Drawing and Text]].

The gadgets in a requester also have their own borders, images and text to add to the display imagery. Intuition will allocate the buffers, construct a bitmap that lasts for the duration of the display, and render the requester into the window. This rendering is all done over a solid color, filled background specified by the BackFill pen in the Requester structure. The backfill may be disabled by setting the NOREQBACKFILL flag.

On the other hand, a custom requester may be designed with predefined, bitmap imagery for the entire object. The image bitmap is submitted to Intuition through the ImageBMap field of the Requester structure. The bitmap should be designed to reduce user confusion; gadgets should line up with their images, and the designer should attempt to use glyphs (symbols) familiar to the user.

To provide imagery for the requester, applications should always try to use data structures attached to the Requester structure as described above. Although, rendering directly into the requester layer's RastPort is tolerated, it must be done with great care.

First, a requester is allowed to have gadgets that automatically close the requester when they are selected (GACT_ENDGADGET). If such a gadget is selected, the requester, its layer, and its layer's RastPort will be deleted asynchronously to your application. If your application is trying to render directly into the requester at that time, the results are unpredictable. Therefore, do not put GACT_ENDGADGET gadgets into a requester if you plan on rendering directly into its RastPort.

Second, recall that requesters are clipped to the inside of the window (not including the borders). If the window can be sized smaller such that the requester would be entirely clipped, the requester's layer may be deleted by Intuition. If your window's minimum size and the requester size and position are such that the requester can be completely clipped, then reading Requester.ReqLayer is unsafe without additional protection. It would be correct to LockLayerInfo() the screen's Layer_Info, then check for the existence of the requester's ReqLayer, then render, then unlock.

For reasons such as these, direct rendering is discouraged.

=== Requester Refresh Type ===

A requester appears in a Layer. By default, the requester layer is of type LAYERSMART, or, in window terminology, WFLG_SMART_REFRESH; so rendering is preserved in the requester when the window is moved or revealed.

Requesters may also be simple refresh. This is the recommended type. If possible, make the requester a simple refresh layer requester by specifying the SIMPLEREQ flag.

For all refresh types, Intuition will keep the gadget, border, image and bitmap imagery properly refreshed.

=== Requester Display Position ===

The location of true requesters may be specified in one of three ways. The requester may either be a constant location, which is an offset from the top left corner of the window; a location relative to the current location of the pointer; or a location relative to the center of the window.

To display the requester as an offset from the upper left corner of the window, initialize the TopEdge and LeftEdge variables and clear the POINTREL flag. This will create a requester with a fixed position relative to the upper left corner for both normal requesters and double menu requesters.

Displaying the requester relative to the pointer can get the user's attention immediately and closely associates the requester with whatever the user was doing just before the requester was displayed in the window. However, only double menu requesters may be positioned relative to the pointer position. See below for more information on double menu requesters.

Requesters that are not double menu requesters may be positioned relative to the center of the window. This is done by setting the POINTREL flag and filling in the relative top and left of the gadget. Setting RelTop and RelLeft to zero will center the requester in the window. Positive values of RelTop and RelLeft will move the requester down and to the right, negative values will move it up and to the left.

=== Gadgets in Requesters ===

Each requester gadget must have the GTYP_REQGADGET flag set in the GadgetType field of its Gadget structure. This informs Intuition that this gadget is to be rendered in a requester rather than a window.

Requesters can have gadgets in them that ''automatically'' satisfy the request and end the requester. When one of these gadgets is selected, Intuition will remove the requester from the window. This is equivalent to the application calling EndRequest(), and, if the request is terminated by selection of such a gadget, the application should not call EndRequest() for that requester.

Set the GACT_ENDGADGET flag in the Activation field of the Gadget structure to create a gadget that automatically terminates the requester. Every time one of the requester's gadgets is selected, Intuition examines the GACT_ENDGADGET flag. If GACT_ENDGADGET is set, the requester is removed from the display and unlinked from the window's active requester list.

Requesters rendered via Intuition and those that use a custom bitmap differ in how their gadgets are rendered. For requesters rendered via Intuition, the application supplies a regular gadget list just as it would for application gadgets in a window.

In custom bitmap requesters, however, any gadget imagery is part of the bitmap supplied for the requester. Therefore the list of gadgets supplied for custom bitmap requesters should not provide gadget imagery but rather it should define only the select boxes, highlighting, and gadget types for the gadgets.

The Gadget structures used with a custom bitmap requester should have their GadgetRender, SelectRender and GadgetText fields set to NULL as these will be ignored. Other gadget information-select box dimensions, highlighting, and gadget type-is still relevant. The select box information is especially important since the select box must have a well defined correspondence with the custom bitmap imagery supplied. The basic idea is to make sure that the user understands the requester imagery and gadgets.

=== Using a Requester to Block Window Input ===

There may be times when an application needs to block user input without a visible requester. In some cases, the application needs to be busy for a while. Other times, an application wants the blocking properties of a requester, but prefers to use a window instead of a true requester. In this case, the application can create a requester with no imagery, attaching it to the parent window to block input. A new window may then be opened to act as the requester.

Some of the advantages of using a window as a requester instead of a real requester include:

* A window can be resized, and moves independently of the parent window.
* It is legal to render directly into a window.
* The window can have its own menus since only the parent window's menus are disabled (this is only occasionally useful).
* Certain code or a library you are using may not work in requesters (GadTools library is an example of this).

Of course, using a true requester instead of a window has the advantage that the requester automatically moves and depth-arranges along with the parent window.

==== A Requester Example ====

To use a window as a requester, first bring up a zero-sized requester attached to the main window (this provides the blocking feature). Then, bring up your second window, or bring up a busy pointer. The following example illustrates bringing up a busy pointer.

<syntaxhighlight lang="C" line>
/*
** blockinput.c -- program to demonstrate how to block the input from a
** window using a minimal requester, and how to put up a busy pointer.
*/
#include <exec/types.h>
#include <intuition/intuition.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>

/* our function prototypes */
BOOL beginWait(struct Window *win, struct Requester *waitRequest);
VOID endWait(struct Window *win, struct Requester *waitRequest);
VOID processIDCMP(struct Window *win);

struct IntuitionIFace *IIntuition;

/* data for a busy pointer. */
uint16 waitPointer[] =
{
0x0000, 0x0000, /* reserved, must be NULL */

0x0400, 0x07C0,
0x0000, 0x07C0,
0x0100, 0x0380,
0x0000, 0x07E0,
0x07C0, 0x1FF8,
0x1FF0, 0x3FEC,
0x3FF8, 0x7FDE,
0x3FF8, 0x7FBE,
0x7FFC, 0xFF7F,
0x7EFC, 0xFFFF,
0x7FFC, 0xFFFF,
0x3FF8, 0x7FFE,
0x3FF8, 0x7FFE,
0x1FF0, 0x3FFC,
0x07C0, 0x1FF8,
0x0000, 0x07E0,

0x0000, 0x0000, /* reserved, must be NULL */
};

/*
** main()
**
** Open a window and display a busy-pointer for a short time then wait for
** the user to hit the close gadget (in processIDCMP()). Normally, the
** application would bracket sections of code where it wishes to block window
** input with the beginWait() and endWait() functions.
*/
int main()
{
struct Window *win;

struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);

if (IIntuition != NULL)
{
if (win = IIntuition->OpenWindowTags(NULL,
WA_IDCMP, IDCMP_CLOSEWINDOW|IDCMP_INTUITICKS,
WA_Activate, TRUE,
WA_Width, 320,
WA_Height, 100,
WA_CloseGadget, TRUE,
WA_DragBar, TRUE,
WA_DepthGadget, TRUE,
WA_SizeGadget, TRUE,
WA_MaxWidth, ~0,
WA_MaxHeight, ~0,
TAG_END))
{
processIDCMP(win);
IIntuition->CloseWindow(win);
}
}

IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);

return 0;
}

/*
** beginWait()
**
** Clear the requester with InitRequester. This makes a requester of
** width = 0, height = 0, left = 0, top = 0; in fact, everything is zero.
** This requester will simply block input to the window until
** EndRequest is called.
**
** The pointer is set to a reasonable 4-color busy pointer, with proper offsets.
*/
BOOL beginWait(struct Window *win, struct Requester *waitRequest)
{
IIntuition->InitRequester(waitRequest);
if (IIntuition->Request(waitRequest, win))
{
IIntuition->SetPointer(win, waitPointer, 16, 16, -6, 0);
IIntuition->SetWindowTitles(win, "Busy - Input Blocked", (uint8 *)~0);
return(TRUE);
}
else
return(FALSE);
}

/*
** endWait()
**
** Routine to reset the pointer to the system default, and remove the
** requester installed with beginWait().
*/
VOID endWait(struct Window *win, struct Requester *waitRequest)
{
IIntuition->ClearPointer(win);
IIntuition->EndRequest(waitRequest, win);
IIntuition->SetWindowTitles(win, "Not Busy", (uint8 *)~0);
}

/*
** processIDCMP()
**
** Wait for the user to close the window.
*/
VOID processIDCMP(struct Window *win)
{
struct IntuiMessage *msg;
struct Requester myreq;
uint16 tick_count;

BOOL done = FALSE;

/* Put up a requester with no imagery (size zero). */
if (beginWait(win, &myreq))
{
/*
** Insert code here for a window to act as the requester.
*/

/* We'll count down INTUITICKS, which come about ten times
** a second. We'll keep the busy state for about three seconds.
*/
tick_count = 30;
}

while (!done)
{
IExec->Wait(1L << win->UserPort->mp_SigBit);

while (NULL != (msg = (struct IntuiMessage *)IExec->GetMsg(win->UserPort)))
{
uint32 class = msg->Class;
IExec->ReplyMsg((struct Message *)msg);

switch (class)
{
case IDCMP_CLOSEWINDOW:
done = TRUE;
break;

case IDCMP_INTUITICKS:
if (tick_count > 0)
{
if (--tick_count == 0)
endWait(win,&myreq);
}
break;
}
}
}
}
</syntaxhighlight>

=== Double Menu Requesters ===

A double menu requester is exactly like other requesters with one exception: it is displayed only when the user double clicks the mouse menu button. Double menu requesters block input in exactly the same manner as other true requesters. A double menu requester is attached to a window by calling SetDMRequest().

<pre>
BOOL SetDMRequest( struct Window *window, struct Requester *requester );
</pre>

This call does not display the requester, it simply prepares it for display. The requester will be brought up when the user double clicks the mouse menu button. The parent window will receive IDCMP_REQSET and IDCMP_REQCLEAR messages when the requester is added and removed.

To prevent the user from bringing up a double menu requester, unlink it from the window by calling ClearDMRequest(). If a double menu request is set for a window, ClearDMRequest() should be called to remove the requester before that window is closed.

<pre>
BOOL ClearDMRequest( struct Window *window );
</pre>

This function unlinks the requester from the window and disables the ability of the user to bring it up. ClearDMRequest() will fail if the double menu request is currently being displayed.

Double menu requesters can be positioned relative to the current mouse pointer position. For a mouse relative requester, specify POINTREL in the Flags field and initialize the RelLeft and RelTop variables. RelLeft and RelTop describe the offset of the upper, left corner of the requester from the pointer position at the time the requester is displayed. These values can be either negative or positive.

The values of RelLeft and RelTop are only advisory; the actual position will be restricted such that the requester is entirely contained within the borders of its parent window, if possible. The actual top and left positions are stored in the TopEdge and LeftEdge variables.

Positioning relative to the mouse pointer is possible only with double menu requesters. Setting POINTREL in a requester which is not a double menu requester will position the requester relative to the center of the window.

=== IDCMP Requester Features ===

Intuition can notify your application about user activity in the requester by sending a message to the parent window's IDCMP port (Window.UserPort). When using the IDCMP for input, the following IDCMP flags control how requester input events will be handled.

; IDCMP_REQSET
: With this flag set, the program will receive a message whenever a requester opens in its window. The application will receive one IDCMP_REQSET event for each requester opened in the window.

; IDCMP_REQCLEAR
: With this flag set, the program will receive a message whenever a requester is cleared from its window. The application will receive one IDCMP_REQCLEAR event for each requester closed in the window. By counting the number of IDCMP_REQSET and IDCMP_REQCLEAR events, the application may determine how many requesters are currently open in a window.

; IDCMP_REQVERIFY
: With this flag set, the application can ensure that it is ready to allow a requester to appear in the window before the requester is displayed.

: When the program receives an IDCMP_REQVERIFY message, it must reply to that message before the requester is added to the window. If multiple requesters are opened in the window at the same time, only the first one will cause an IDCMP_REQVERIFY event. It is assumed that once a requester is in a window others may be added without the program's consent. After the requester count drops to zero and there are no open requesters in the window, the next requester to open will cause another IDCMP_REQVERIFY event.

: IDCMP_REQVERIFY is ignored by the Request() function. Since Request() is controlled by the application, it is assumed that the program is prepared to handle the request when calling this function. Since the system does not render true requesters into an application's window (EasyRequest() and AutoRequest() come up in their own window, not in the application‚Äôs window), IDCMP_REQVERIFY will only control the timing of double menu requesters.

These flags are set when the parent window is first opened by using either the WA_IDCMP tag or NewWindow.IDCMPFlags. They can also be set after the parent window is open by using the ModifyIDCMP() call. See [[Intuition_Input_and_Output_Methods|Intuition Input and Output Methods]], for further information about these IDCMP flags. See [[Intuition_Windows|Intuition Windows]] for details on setting IDCMP flags when a window is opened.

== Requester Structure ==

Unused fields in the Requester structure should be initialized to NULL or zero before using the structure. For global data that is pre-initialized, be sure to set all unused fields to zero. For dynamically allocated structures, allocate the storage with the MEMF_CLEAR flag, or call the InitRequester() function to clear the structure.

{{Note|title=Requesters are Initialized According to Their Type|text=See "Rendering Requesters" and "Gadgets in Requesters" above for information about how the initialization of the structure differs according to how the requester is rendered.}}

The specification for a Requester structure, defined in the <intuition/intuition.h> file, is as follows.

<syntaxhighlight lang="C" line>
struct Requester
{
struct Requester *OlderRequest;
WORD LeftEdge, TopEdge;
WORD Width, Height;
WORD RelLeft, RelTop;
struct Gadget *ReqGadget;
struct Border *ReqBorder;
struct IntuiText *ReqText;
UWORD Flags;
UBYTE BackFill;
struct Layer *ReqLayer;
UBYTE ReqPad1[32];
struct BitMap *ImageBMap;
struct Window *RWindow;
struct Image *ReqImage;
UBYTE ReqPad2[32];
};
</syntaxhighlight>

Here are the meanings of the fields in the Requester structure:

; OlderRequest
: For system use, initialize to NULL.

; LeftEdge, TopEdge
: The location of the requester relative to the upper left corner of the window. These values must be set if the POINTREL flag is not set. Use RelLeft and RelTop for POINTREL requesters.

; Width, Height
: These fields describe the size of the entire requester rectangle, containing all the text and gadgets.

; RelLeft, RelTop
: These values are only used if the POINTREL flag in the requester's Flags field is set.

: If the requester is a double menu requester and POINTREL is set then these values contain the relative offset of the requester's upper left corner from the current pointer position.

: If the requester is not a double menu requester and POINTREL is set, then these values contain the relative offset of the requester's center from the center of the window that the requester is to be displayed in. For example, using POINTREL with a requester which is not a double menu requester with RelLeft and RelTop of zero will center the requester in the window. The requester is centered within the inner part of the window, that is, within the inside edge of the window's borders.

: If the requester is POINTREL and part of the containing box will appear out of the window, Intuition will adjust the requester so that the upper left corner is visible and as much of the remaining box as possible is visible. The adjustment attempts to maintain the requester within the window's borders, not within the window's bounding box.

; ReqGadget
: This field is a pointer to the first in a linked list of Gadget structures. GTYP_REQGADGET must be specified in the GadgetTypes field of all Gadget structures that are used in a requester. Take care not to specify gadgets that extend beyond the Requester rectangle specified by the Width and Height fields, as Intuition does no boundary checking.

: For requesters with custom imagery, where PREDRAWN is set, ReqGadget points to a valid list of gadgets, which are real gadgets in every way except that the gadget text and imagery information are ignored (and can be NULL). The select box, highlighting, and gadget type data are still used. Try to maintain a close correspondence between the gadgets' select boxes and the supplied imagery.

{{Note|title=String Gadgets and Pre-drawn Requesters|text=Intuition will not render string gadget text in a predrawn requester. The application must use other rendering means than the predrawn bitmap if it wishes to use string gadgets with a requester.}}

; ReqBorder
: This field is a pointer to an optional linked list of Border structures for drawing lines around and within the requester. The lines specified in the border may go anywhere in the requester; they are not confined to the perimeter of the requester.

: For requesters with custom imagery, where PREDRAWN is set, this variable is ignored and may be set to NULL.

; ReqText
: This field is a pointer to an optional linked list of IntuiText structures containing text for the requester. This is for general text in the requester.

: For requesters with custom imagery, where PREDRAWN is set, this variable is ignored and can be set to NULL.

; Flags
: The following flags may be specified for the Requester:

:{| class="wikitable"
| POINTREL
| Specify POINTREL to indicate that the requester is to appear in a relative rather than a fixed position.
 
For double menu requesters, the position is relative to the pointer. Otherwise, the position of POINTREL requesters is relative to the center of the window.
 
See the discussion of RelLeft and RelTop, above.
|-
| PREDRAWN
| Specify PREDRAWN if a custom BitMap structure is supplied for the requester and ImageBMap points to the structure.
|-
| NOISYREQ
| Normally, when a requester is active, any gadget, menu, mouse and keyboard events within the parent window are blocked. Specify the NOISYREQ requester flag to allow keyboard and mouse button IDCMP events to be posted, even though the requester is active in the parent window. 
If the NOISYREQ requester flag is set, the application will receive IDCMP_RAWKEY, IDCMP_VANILLAKEY and IDCMP_MOUSEBUTTONS events. Note that with NOISYREQ set, IDCMP_MOUSEBUTTON events will also be sent when the user clicks on any of the blocked gadgets in the parent window. 
Although the reporting of mouse button events depends on NOISYREQ, mouse movement events do not. IDCMP_MOUSEMOVE events are reported if the window flag WFLG_REPORTMOUSE is set in the parent window, or if one of the requester gadgets is down and has the GACT_FOLLOWMOUSE flag set. This is true even if the requester is a double-menu requester.
|-
| USEREQIMAGE
| Render the linked list of images pointed to by ReqImage after rendering the BackFill color but before gadgets and text.
|-
| NOREQBACKFILL
| Do not backfill the requester with the BackFill pen.
|}

: In addition, Intuition uses these flags in the Requester:

:{| class="wikitable"
| REQOFFWINDOW
| Set by Intuition if the requester is currently active but is positioned off window.
|-
| REQACTIVE
| This flag is set or cleared by Intuition as the requester is posted and removed. The active requester is indicated by the value of Window.FirstRequest.
|-
| SYSREQUEST
| This flag is set by Intuition if this is a system generated requester. Since the system will never create a true requester in an application window, the application should not be concerned with this flag.
|}

; BackFill
: BackFill is the pen number to be used to fill the rectangle of the requester before any drawing takes place. For requesters with custom imagery, where PREDRAWN is set, or for requesters with NOREQBACKFILL set, this variable is ignored.

; ReqLayer
: While the requester is active, this contains the address of the Layer structure used in rendering the requester.

; ImageBMap
: A pointer to the custom bitmap for this requester. If this requester is not PREDRAWN, Intuition ignores this variable.
: When a custom bitmap is supplied, the PREDRAWN flag in the requester's Flags field must be set.

; RWindow
: Reserved for system use.

; ReqImage
: A pointer to a list of Image structures used to create imagery within the requester. Intuition ignores this field if the flag USEREQIMAGE is not set. This imagery is automatically redrawn by Intuition each time the requester needs refreshing. The images are drawn after filling with the BackFill pen, but before the gadgets and text.

; ReqPad1, ReqPad2
: Reserved for system use.

== Easy Requesters ==

EasyRequest() provides a simple way to make a requester that allows the user to select one of a limited number of choices. (A similar function, AutoRequest(), is also available but is not as flexible or as powerful. See the SDK for more information.)

[[File:LibFig7-2.png|frame|center|A Simple Requester Made with EasyRequest()]]

The program supplies the text for the body of the requester, text for each of the possible options, an optional title for the window, and other arguments. The body text can consist of one or more lines with lines separated by the linefeed character.

Each option for an easy requester is displayed as a simple button gadget positioned beneath the body text you specify. The layout of the requester, its text and buttons, is done automatically and is font sensitive. The screen font (Screen.Font) is used for all text in the requester.

Typically, easy requesters have one selection indicating a positive action and one selection indicating a negative action. The text used for the positive action might be "OK", "Yes," "True," "Retry," or similar responses. Likewise, the text used for the negative action might be "No," "False," "Cancel" and so on. The negative choice should always be the rightmost or final choice and will return a zero if selected.

When EasyRequest() is called, Intuition will build the requester, display it, and wait for user response.

<pre>
LONG EasyRequest( struct Window *window, struct EasyStruct *easyStruct,
ULONG *idcmpPtr, APTR arg1, ... );

LONG EasyRequestArgs( struct Window *window, struct EasyStruct *easyStruct,
ULONG *idcmpPtr, APTR args );
</pre>

The window argument is a pointer to the reference window. The requester will be displayed on the same screen that the reference window is on and also takes its title from the reference window, if not otherwise specified. This argument can be NULL, which means the requester is to appear on the Workbench screen, or the default public screen, if defined.

The easyStruct argument is a pointer to an EasyStruct structure which defines the setup and the text of this easy requester (described below).

The idcmpPtr argument is a pointer to a ULONG containing the IDCMP flags for the event that you want to terminate this requester. If such an event occurs the requester is terminated (with a result of -1) and the ULONG that idcmpPtr points to will contain the actual class of the event message. This feature allows external events to satisfy the request, such as the user inserting a disk in the disk drive. This argument can be set to NULL for no automatic termination.

The gadget and body text for an easy requester is specified in an EasyStruct structure (see below). Body text can be specified using a printf()-style format string that also accepts variables as part of the text. If variables are specified in the requester text, their value is taken from the args (or arg1,...) parameters shown in the prototypes above. EasyRequestArgs() takes a pointer to an array of pointers to arguments, while EasyRequest() has a ''varargs'' interface and takes individual arguments as part of the function call. The types of these arguments are specified in the format strings of the EasyStruct structure. Arguments for es_GadgetFormat follow arguments for es_TextFormat.

The EasyRequest() functions return an integer from 0 to ''n - 1'', where ''n'' is the number of choices specified for the requester. The numbering from left-to-right is: 1, 2, ..., ''n - 1'', 0. This is for compatibility with AutoRequest() which returns FALSE for the rightmost gadget.

The function will return -1 if it receives an IDCMP event that matches one of the termination events specified in the idcmpPtr argument.

{{Note|title=Turn Off the Verify Messages|text=Use ModifyIDCMP() to turn off all verify messages (such as MENUVERIFY) before calling EasyRequest() or AutoRequest(). Neglecting to do so can cause situations where Intuition is waiting for the return of a message that the application program cannot receive because its input is shut off while the requester is up. If Intuition finds itself in a deadlock state, the verify function will timeout and will be automatically replied.}}

=== The EasyStruct Structure ===

The text and setup of an easy requester is specified in an EasyStruct structure, defined in <intuition/intuition.h>.

<syntaxhighlight lang="C" line>
struct EasyStruct
{
ULONG es_StructSize;
ULONG es_Flags;
UBYTE *es_Title;
UBYTE *es_TextFormat;
UBYTE *es_GadgetFormat;
};
</syntaxhighlight>

; es_StructSize
: Contains the size of the EasyStruct structure, sizeof(struct EasyStruct).

; es_Flags
: Set to zero.

; es_Title
: Title of easy requester window. If this is NULL, the title will be taken to be the same as the title of the reference window, if one is specified in the EasyRequest() call, else the title will be "System Request".

; es_TextFormat
: Format string for the text in the requester body, with printf()-style variable substitution as described in the Exec library function RawDoFmt(). Multiple lines are separated by the linefeed character (hex 0x0A or \n in C). Formatting "%" functions are supported exactly as in RawDoFmt(). The variables that get substituted in the format string come from the last argument passed to EasyRequest() (see prototype above).

; es_GadgetFormat
: Format string for gadgets, where the text for separate gadgets is separated by "|" (vertical bar). As with the body text, printf()-style formatting with variable substitution is supported, but multi-line text in the gadgets is not supported. At least one gadget ''must'' be specified.

Requesters generated with EasyRequest() and BuildEasyRequest() (including system requesters, which use SysReqHandler() to handle input) can be satisfied by the user via the keyboard. The key strokes left Amiga V and left Amiga B correspond to selecting the requester's leftmost or rightmost gadgets with the mouse, respectively.

An easy request must have at least one choice. Multiple choices are specified through the "|" (vertical bar) separator character in the es_GadgetFormat string. The buttons are displayed evenly spaced, from left-to-right in the order in which they appear in the string.

The requesters generated by EasyRequest() appear in the visible portion of the specified screen. They do not cause the screen to scroll. Under the current implementation, the window for an easy requester will appear in the upper left corner of the display clip for the specified screen.

When a request is posted using EasyRequest() or BuildEasyRequest(), it will move the screen it appears on to the front, if that screen is not already the front-most. This brings the request to the attention of the user. The request also comes up as the active window and could potentially steal the input focus from the current window.

When the request is satisfied the screen will be moved to back if the request caused the screen to move to the front when it was displayed. Note that the final screen position may not be the same as the original screen position.

==== Example Using EasyRequest() ====

<syntaxhighlight lang="C" line>
/*
** easyrequest.c - show the use of an easy requester.
*/
#include <exec/types.h>
#include <intuition/intuition.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>

/* declare the easy request structure.
** this uses many features of EasyRequest(), including:
** multiple lines of body text separated by '\n'.
** variable substitution of a string (%s) in the body text.
** multiple button gadgets separated by '|'.
** variable substitution in a gadget (long decimal '%ld').
*/
struct EasyStruct myES =
{
sizeof(struct EasyStruct),
0,
"Request Window Name",
"Text for the request\nSecond line of %s text\nThird line of text for the request",
"Yes|%ld|No",
};

struct IntuitionIFace *IIntuition;

/*
** Main routine to show the use of EasyRequest()
*/
int main ()
{
struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*) IExec->GetInterface(IntuitionBase, "main", 1, NULL);

if (IIntuitionBase != NULL)
{
int32 number = 3125794; /* for use in the middle button */

/* note in the variable substitution:
** the string goes in the first open variable (in body text).
** the number goes in the second open (gadget text).
*/
int32 answer = IIntuition->EasyRequest(NULL, &myES, NULL, "(Variable)", number);

/* Process the answer. Note that the buttons are numbered in
** a strange order. This is because the rightmost button is
** always a negative reply. The code can use this if it chooses,
** with a construct like:
**
** if (EasyRequest())
** positive_response();
*/
switch (answer)
{
case 1:
IDOS->Printf("selected 'Yes'\n");
break;
case 2:
IDOS->Printf("selected '%ld'\n", number);
break;
case 0:
IDOS->Printf("selected 'No'\n");
break;
}
}

IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);

return 0;
}
</syntaxhighlight>

=== Low Level Access to Easy Requesters ===

The EasyRequest() function calls a lower level Intuition function named BuildEasyRequest() to construct the requester. An application can call BuildEasyRequest() directly if it needs to use an easy requester but requires custom handling of the events sent to the requester. Handling of the events should be done using the SysReqHandler() function as described below.

The BuildEasyRequest() functions take the same arguments as EasyRequest():

<syntaxhighlight lang="C" line>
struct Window *BuildEasyRequestArgs( struct Window *window,
struct EasyStruct *easyStruct,
ULONG idcmp, APTR args );

struct Window *BuildEasyRequest( struct Window *window,
struct EasyStruct *easyStruct,
ULONG idcmp, APTR arg1, ... );
</syntaxhighlight>

To process input event information directly while an easy requester is displayed, first call BuildEasyRequest() then call SysReqHandler() periodically to process user input.

<syntaxhighlight lang="C" line>
LONG SysReqHandler( struct Window *window, ULONG *idcmpPtr, LONG waitInput );
</syntaxhighlight>

This will provide standard handling of events but allow the application to control the timing of checking the events. This handling includes checks for left Amiga keys.

The FreeSysRequest() function must be called after an application has finished with a requester (if it was created with BuildEasyRequest() call).

<syntaxhighlight lang="C" line>
VOID FreeSysRequest( struct Window *window );
</syntaxhighlight>

This function ends the requester and frees any resources allocated with the BuildEasyRequest() call.

== System Requesters ==

System requesters, such as DOS requests to "Insert volume foo in any drive", are created by the system using EasyRequest(). Unless otherwise specified, these requests appear on the default public screen.

System requests may appear at any time the system requires a resource that is not available. The user may be in the middle of an action, the program may be in any state.

Use the function ModifyIDCMP() to turn off all verify messages before calling any function that might generate a system requester. Neglecting to do so can cause situations where Intuition is waiting for the return of a message which the application program is unable to receive because its input is shut off while the requester is up. If Intuition finds itself in a deadlock state, the verify function will timeout and be automatically replied.

=== Redirecting System Requesters ===

A process can force the system requests which are caused by its actions to appear on a custom screen by changing the pr_WindowPtr field of its Process structure. This field may be set to three values: zero, negative one or a valid pointer to the Window structure of an open window. If pr_WindowPtr is set to zero, the request will appear on the default public screen. If pr_WindowPtr is set to negative one, the system request will never appear and the return code will be as if the user had selected the rightmost button (negative response). If pr_WindowPtr is set to a valid window pointer, then the request will appear on the same screen as the window.

The original value of pr_WindowPtr ''must'' be cached and restored before the window is closed.

=== Function Reference ===

The following are brief descriptions of the Intuition functions that relate to the use of Intuition requesters. See the SDK for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| Request()
| Open a requester in an open window.
|-
| EndRequest()
| Close an open requester in a window.
|-
| InitRequester()
| Clear a requester structure before use.
|-
| EasyRequestArgs()
| Open a system requester.
|-
| EasyRequest()
| Alternate calling sequence for EasyRequestArgs().
|-
| BuildEasyRequestArgs()
| Low level function to open EasyRequestArgs().
|-
| BuildEasyRequest()
| Low level function to close EasyRequestArgs().
|-
| SysReqHandler()
| Event handler function for EasyRequestArgs().
|-
| AutoRequest()
| Open a pre-V36 system requester.
|-
| BuildSysRequest()
| Low level function to open an AutoRequest().
|-
| FreeSysRequest()
| Low level function to close an AutoRequest().
|-
| SetDMRequest()
| Set a double menu requester for an open window.
|-
| ClearDMRequest()
| Clear a double menu requester from an open window.
|}

Trackdisk Device

2025-01-26T19:27:56Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

== Trackdisk Device ==

The Amiga trackdisk device directly drives the disk, controls the disk motors, reads raw data from the tracks, and writes raw data to the tracks. Normally, you use the AmigaDOS functions to write or read data from the disk. The trackdisk device is the lowest-level software access to the disk data and is used by AmigaDOS to access the disks. The trackdisk device supports the usual commands such as CMD_WRITE and CMD_READ. In addition, it supports an extended form of these commands to allow additional control over the trackdisk device.

== Trackdisk Device Commands and Functions ==

{| class="wikitable"
! Command
! Command Operation
|-
| CMD_CLEAR || Mark track buffer as invalid. Forces the track to be re-read.
|-
| ETD_CLEAR || ETD_CLEAR also checks for a diskchange.
|-
| CMD_READ || Read one or more sectors from a disk.
|-
| ETD_READ || ETD_READ also reads the sector label area and checks for a diskchange.
|-
| CMD_UPDATE || Write out track buffer if it has been changed.
|-
| ETD_UPDATE || ETD_UPDATE also checks for a diskchange.
|-
| CMD_WRITE || Write one or more sectors to a disk.
|-
| ETD_WRITE || ETD_WRITE also writes the sector label area and checks for a diskchange.
|-
| TD_ADDCHANGEINT || Add an interrupt handler to be activated on a diskchange.
|-
| TD_CHANGENUM || Return the current value of the diskchange counter used by the ETD commands to determine if a diskchange has occurred.
|-
| TD_CHANGESTATE || Return the disk present/not-present status of a drive.
|-
| TD_EJECT || Eject a disk from a drive. This command will only work on drives that support an eject command.
|-
| TD_FORMAT || Initialize one or more tracks with a data buffer.
|-
| ETD_FORMAT || ETD_FORMAT also initializes the sector label area.
|-
| TD_GETDRIVETYPE || Return the type of disk drive in use by the unit.
|-
| TD_GETGEOMETRY || Return the disk geometry table.
|-
| TD_GETNUMTRACKS || Return the number of tracks usable with the unit.
|-
| TD_MOTOR || Turn the motor on or off.
|-
| ETD_MOTOR || ETD_MOTOR also checks for a diskchange.
|-
| TD_PROTSTATUS || Return the write-protect status of a disk.
|-
| TD_RAWREAD || Read RAW sector data from disk (unencoded MFM).
|-
| ETD_RAWREAD || ETD_RAWREAD also checks for a diskchange.
|-
| TD_RAWWRITE || Write RAW sector data to disk.
|-
| ETD_RAWWRITE || ETD_RAWWRITE also checks for a diskchange.
|-
| TD_REMCHANGEINT || Remove a diskchange interrupt handler.
|-
| TD_SEEK || Move the head to a specific track.
|-
| ETD_SEEK || ETD_SEEK also checks for a diskchange.
|}

== Device Interface ==

The trackdisk device operates like other Amiga devices. To use it, you must first open the device, then send I/O requests to it, and then close it when finished. See [[Exec_Device_I/O|Exec Device I/O]] for general information on device usage.

The trackdisk device uses two different types of I/O request blocks, IOStdReq and IOExtTD and two types of commands, standard and extended. An IOExtTD is required for the extended trackdisk commands (those beginning with “ETD_”), but can be used for both types of commands. Thus, the IOExtTD is the type of I/O request that will be used in this article.

<syntaxhighlight lang="C" line>
struct IOExtTD
{
struct IOStdReq iotd_Req;
ULONG iotd_Count; /* Diskchange counter */
ULONG iotd_SecLabel; /* Sector label data */
};
</syntaxhighlight>

See the include file devices/trackdisk.h for the complete structure definition.

The enhanced commands listed above—those beginning with “ETD_”— are similar to their standard counterparts but have additional features: they allow you to control whether a command will be executed if the disk has been changed and they allow you to read or write to the sector label portion of a sector.

Enhanced commands require a larger I/O request, IOExtTD, than the IOStdReq request used by the standard commands. IOExtTD contains extra information needed by the enhanced command; since the standard form of a command ignores the extra fields, IOExtTD requests can be used for both types. The extra information takes the form of two extra longwords at the end of the data structure. These commands are performed only if the change count is less than or equal to the value in the iotd_Count field of the command’s request block.

The iotd_Count field keeps old I/O requests from being performed when the disk is changed. Any request found with an iotd_Count less than the current change counter value will be returned with a characteristic error (TDERR_DiskChange) in the io_Error field. This allows stale I/O requests to be returned to the user after a disk has been changed. The current disk-change counter value can be obtained by TD_CHANGENUM. If the user wants enhanced disk I/O but does not care about disk removal, then iotd_Count may be set to the maximum unsigned long integer value (0xFFFFFFFF).

The iotd_SecLabel field allows access to the sector identification section of the sector header. Each sector has 16 bytes of descriptive data space available to it; the trackdisk device does not interpret this data. If iotd_SecLabel is NULL, then this descriptive data is ignored. If it is not NULL, then iotd_SecLabel should point to a series of contiguous 16-byte chunks (one for each sector that is to be read or written). These chunks will be written out to the sector’s label region on a write or filled with the sector’s label area on a read. If a CMD_WRITE (the standard write call) is done, then the sector label area is left unchanged.

=== About Amiga Floppy Disks ===

The standard 3.5 inch Amiga floppy disk consists of a number of tracks that are NUMSECS (11) sectors of TD_SECTOR (512) usable data bytes plus TD_LABELSIZE (16) bytes of label area. There are usually 2 tracks per cylinder (2 heads) and 80 cylinders per disk. The number of tracks can be found using the TD_GETNUMTRACKS command.

The NUMSECS in some drives may be variable and may change when a disk is inserted. Use TD_GETGEOMETRY to determine the current number of sectors.

{{Note|title=Think Tracks not Cylinders|text=The result is given in tracks and not cylinders. On a standard 3.5" drive, this gives useful space of 880K bytes plus 28K bytes of sector label area per floppy disk.}}

Although the disk is logically divided up into sectors, all I/O to the disk is done a track at a time. This allows access to the drive with no interleaving and increases the useful storage capacity by about 20 percent. Each disk drive on the system has its own buffer which holds the track data going to and from the drive.

Normally, a read of a sector will only have to copy the data from the track buffer. If the track buffer contains another track’s data, then the buffer will first be written back to the disk (if it is “dirty”) and the new track will be read in. All track boundaries are transparent to the programmer (except for FORMAT, SEEK, and RAWREAD/RAWWRITE commands) because you give the device an offset into the disk in the number of bytes from the start of the disk. The device ensures that the correct track is brought into memory.

The performance of the disk is greatly enhanced if you make effective use of the track buffer. The performance of sequential reads will be up to an order of magnitude greater than reads scattered across the disk. In addition, only full-sector writes on sector boundaries are supported.

The trackdisk device is based upon a standard device structure. It has the following restrictions:

* All reads and writes must use an io_Length that is an integer multiple of TD_SECTOR bytes (the sector size in bytes).
* The offset field must be an integer multiple of TD_SECTOR.
* The data buffer must be word-aligned.

=== Opening the Trackdisk Device ===

Three primary steps are required to open the trackdisk device:

* Create a message port by calling CreatePort(). Reply messages from the device must be directed to a message port.
* Create an extended I/O request structure of type IOExtTD. The IOExtTD structure is created by the CreateExtIO() function.
* Open the trackdisk device. Call OpenDevice(), passing it the extended I/O request.

For the trackdisk device, the flags parameter of the OpenDevice() function specifies whether you are opening a 3.5’’ drive (flags=0) or a 5.25’’ drive (flags=1). With flags set to 0 trackdisk will only open a 3.5’’ drive. To tell the device to open any drive it understands, set the flags parameter to TDF_ALLOW_NON_3_5. (See the include file devices/trackdisk.h for more information.)

<syntaxhighlight lang="C" line>
#include <devices/trackdisk.h>

struct MsgPort *TrackMP; /* Pointer for message port */
struct IOExtTD *TrackIO; /* Pointer for IORequest */

if (TrackMP = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END))
{
if (TrackIO = (struct IOExtTD *)
IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_ReplyPort, TrackMP,
ASOIOR_Size, sizeof(struct IOExtTD),
TAG_END))
{
if (IExec->OpenDevice(TD_NAME,0L,(struct IORequest *)TrackIO,Flags))
{
IDOS->Printf("%s did not open\n", TD_NAME);
</syntaxhighlight>

{{Note|title=Disk Drive Unit Numbers|text=The unit number—second parameter of the OpenDevice() call—can be any value from 0 to 3. Unit 0 is the built-in 3.5’’ disk drive. Units 1 through 3 represent additional disk drives that may be connected to an Amiga system.}}

=== Reading from the Trackdisk Device ===

You read from the trackdisk device by passing an IOExtTD to the device with CMD_READ set in io_Command, the number of bytes to be read set in io_Length, the address of the read buffer set in io_Data and the track you want to read—specified as a byte offset from the start of the disk—set in io_Offset.

The byte offset of a particular track is calculated by multiplying the number of the track you want to read by the number of bytes in a track. The number of bytes in a track is obtained by multiplying the number of sectors (NUMSECS) by the number of bytes per sector (TD_SECTOR). Thus you would multiply 11 by 512 to get 5632 bytes per track. To read track 15, you would multiply 15 by 5632 giving 84,480 bytes offset from the beginning of the disk.

<syntaxhighlight lang="C" line>
#define TRACK_SIZE ((int32) (NUMSECS * TD_SECTOR))
uint8 *Readbuffer;

if (Readbuffer = IExec->AllocVecTags(TRACK_SIZE, AVT_ClearWithValue, 0, TAG_END))
{
DiskIO->iotd_Req.io_Length = TRACK_SIZE;
DiskIO->iotd_Req.io_Data = (APTR)Readbuffer;
DiskIO->iotd_Req.io_Offset = (uint32)(TRACK_SIZE * track);
DiskIO->iotd_Req.io_Command = CMD_READ;
IExec->DoIO((struct IORequest *)DiskIO);
}
</syntaxhighlight>

For reads using the enhanced read command ETD_READ, the IOExtTD is set the same as above with the addition of setting iotd_Count to the current diskchange number. The diskchange number is returned by the TD_CHANGENUM command (see below). If you wish to also read the sector label area, you must set iotd_SecLabel to a non-NULL value.

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Length = TRACK_SIZE;
DiskIO->iotd_Req.io_Data = (APTR)Readbuffer;
DiskIO->iotd_Req.io_Offset = (uint32)(TRACK_SIZE * track);
DiskIO->iotd_Count = change_count;
DiskIO->iotd_Req.io_Command = ETD_READ;
IExec->DoIO((struct IORequest *)DiskIO);
</syntaxhighlight>

ETD_READ and CMD_READ obey all of the trackdisk device restrictions noted above. They transfer data from the track buffer to the user’s buffer. If the desired sector is already in the track buffer, no disk activity is initiated. If the desired sector is not in the buffer, the track containing that sector is automatically read in. If the data in the current track buffer has been modified, it is written out to the disk before a new track is read.

=== Writing to the Trackdisk Device ===

You write to the trackdisk device by passing an IOExtTD to the device with CMD_WRITE set in io_Command, the number of bytes to be written set in io_Length, the address of the write buffer set in io_Data and the track you want to write—specified as a byte offset from the start of the disk—set in io_Offset.

<syntaxhighlight lang="C" line>
#define TRACK_SIZE ((int32) (NUMSECS * TD_SECTOR))
uint8 *Writebuffer;

if (Writebuffer = IExec->AllocVecTags(TRACK_SIZE, AVT_ClearWithValue, 0, TAG_END))
{
DiskIO->iotd_Req.io_Length = TRACK_SIZE;
DiskIO->iotd_Req.io_Data = (APTR)Writebuffer;
DiskIO->iotd_Req.io_Offset = (uint32)(TRACK_SIZE * tracknum);
DiskIO->iotd_Req.io_Command = CMD_WRITE;
IExec->DoIO((struct IORequest *)DiskIO);
}
</syntaxhighlight>

For writes using the enhanced write command ETD_WRITE, the IOExtTD is set the same as above with the addition of setting iotd_Count to the current diskchange number. The diskchange number is returned by the TD_CHANGENUM command (see below). If you wish to also write the sector label area, you must set iotd_SecLabel to a non-NULL value.

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Length = TRACK_SIZE;
DiskIO->iotd_Req.io_Data = (APTR)Writebuffer;
DiskIO->iotd_Req.io_Offset = (uint32)(TRACK_SIZE * tracknum);
DiskIO->iotd_Count = change_count;
DiskIO->iotd_Req.io_Command = ETD_WRITE;
IExec->DoIO((struct IORequest *)DiskIO);
</syntaxhighlight>

ETD_WRITE and CMD_WRITE obey all of the trackdisk device restrictions noted above. They transfer data from the user’s buffer to the track buffer. If the track that contains this sector is already in the track buffer, no disk activity is initiated. If the desired sector is not in the buffer, the track containing that sector is automatically read in. If the data in the current track buffer has been modified, it is written out to the disk before a new track is read in for modification.

=== Closing the Trackdisk Device ===

As with all devices, you ''must'' close the trackdisk device when you have finished using it. To release the device, a CloseDevice() call is executed with the same IOExtTD used when the device was opened. This only closes the device and makes it available to the rest of the system. It does '''not''' deallocate the IOExtTD structure.

<syntaxhighlight lang="C" line>
IExec->CloseDevice((struct IORequest *)DiskIO);
</syntaxhighlight>

== Advanced Commands ==

=== Determining the Drive Geometry Table ===

The layout geometry of a disk drive can be determined by using the TD_GETGEOMETRY command. The layout can be defined three ways:

* TotalSectors
* Cylinders and CylSectors
* Cylinders, Heads, and TrackSectors

Of the three, TotalSectors is the most accurate, Cylinders and CylSectors is less so, and Cylinders, Heads and TrackSectors is the least accurate. All are usable, though the last two may waste some portion of the available space on some drives.

The TD_GETGEOMETRY commands returns the disk layout geometry in a DriveGeometry structure:

<syntaxhighlight lang="C" line>
struct DriveGeometry
{
ULONG dg_SectorSize; /* in bytes */
ULONG dg_TotalSectors; /* total # of sectors on drive */
ULONG dg_Cylinders; /* number of cylinders */
ULONG dg_CylSectors; /* number of sectors/cylinder */
ULONG dg_Heads; /* number of surfaces */
ULONG dg_TrackSectors; /* number of sectors/track */
ULONG dg_BufMemType; /* preferred buffer memory type */
/* (usually MEMF_PUBLIC) */
UBYTE dg_DeviceType; /* codes as defined in the SCSI-2 spec*/
UBYTE dg_Flags; /* flags, including removable */
UWORD dg_Reserved;
};
</syntaxhighlight>

See the include file devices/trackdisk.h for the complete structure definition and values for the dg_DeviceType and dg_Flags fields.

You determine the drive layout geometry by passing an IOExtTD with TD_GETGEOMETRY set in io_Command and a pointer to a DriveGeometry structure set in io_Data.

<syntaxhighlight lang="C" line>
struct DriveGeometry *Euclid =
IExec->AllocVecTags(sizeof(struct DriveGeometry),
AVT_Type, MEMF_SHARED,
AVT_ClearWithValue, 0,
TAG_END);

DiskIO->iotd_Req.io_Data = Euclid; /* put layout geometry here */
DiskIO->iotd_Req.io_Command = TD_GETGEOMETRY;
IExec->DoIO((struct IORequest *)DiskIO);
</syntaxhighlight>

TD_GETGEOMETRY is preferred over TD_GETNUMTRACKS for determining the number of tracks on a disk. This is because new drive types may have more sectors or different sector sizes, etc., than standard Amiga drives.

=== Clearing the Track Buffer ===

ETD_CLEAR and CMD_CLEAR mark the track buffer as invalid, forcing a reread of the disk on the next operation. ETD_UPDATE or CMD_UPDATE would be used to force data out to the disk before turning the motor off. ETD_CLEAR or CMD_CLEAR is usually used after having locked out the trackdisk device via the use of the disk resource, when you wish to prevent the track from being updated, or when you wish to force the track to be re-read. ETD_CLEAR or CMD_CLEAR will not do an update, nor will an update command do a clear.

You clear the track buffer by passing an IOExtTD to the device with CMD_CLEAR or ETD_CLEAR set in io_Command. For ETD_CLEAR, you must also set iotd_Count to the current diskchange number.

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Command = TD_CLEAR;
IExec->DoIO((struct IORequest *)DiskIO);
</syntaxhighlight>

=== Controlling the Drive Motor ===

ETD_MOTOR and TD_MOTOR give you control of the motor. When the trackdisk device executes this command, the old state of the motor is returned in io_Actual. If io_Actual is zero, then the motor was off. Any other value implies that the motor was on. If the motor is just being turned on, the device will delay the proper amount of time to allow the drive to come up to speed. Normally, turning the drive on is not necessary—the device does this automatically if it receives a request when the motor is off.

However, turning the motor off ''is'' the programmer’s responsibility. In addition, the standard instructions to the user are that it is safe to remove a disk if, and only if, the motor is off (that is, if the disk light is off).

You control the drive motor by passing an IOExtTD to the device with CMD_MOTOR or ETD_MOTOR set in io_Command and the state you want to put the motor in set in io_Length. If io_Length is set to 1, the trackdisk device will turn on the motor; a 0 will turn it off. For ETD_MOTOR, you must also set iotd_Count to the current diskchange number.

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Length = 1; /* Turn on the drive motor */
DiskIO->iotd_Req.io_Command = TD_MOTOR;
IExec->DoIO((struct IORequest *)DiskIO);
</syntaxhighlight>

=== Updating a Track Sector ===

The Amiga trackdisk device does not write data sectors unless it is necessary (you request that a different track be used) or until the user requests that an update be performed. This improves system speed by caching disk operations. The update commands ensure that any buffered data is flushed out to the disk. If the track buffer has not been changed since the track was read in, the update commands do nothing.

You update a data sector by passing an IOExtTD to the device with CMD_UPDATE or ETD_UPDATE set in io_Command. For ETD_UPDATE, you must also set iotd_Count to the current diskchange number.

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Command = TD_UPDATE;
IExec->DoIO((struct IORequest *)DiskIO);
</syntaxhighlight>

=== Formatting a Track ===

ETD_FORMAT and TD_FORMAT are used to write data to a track that either has not yet been formatted or has had a hard error on a standard write command. TD_FORMAT completely ignores all data currently on a track and does not check for disk change before performing the command. The device will format the requested tracks, filling each sector with the contents of the buffer pointed to by io_Data field. You should do a read pass to verify the data.

If you have a hard write error during a normal write, you may find it possible to use the TD_FORMAT command to reformat the track as part of your error recovery process. ETD_FORMAT will write the sector label area if the iotd_SecLabel is non-NULL.

You format a track by passing an IOExtTD to the device with CMD_FORMAT or ETD_FORMAT set in io_Command, io_Data set to at least track worth of data, io_Offset field set to the byte offset of the track you want to write and the io_Length set to the length of a track. For ETD_FORMAT, you must also set iotd_Count to the current diskchange number.

<syntaxhighlight lang="C" line>
#define TRACK_SIZE (NUMSECS * TD_SECTOR)
uint8 *Writebuffer;

if (WriteBuffer = AllocVecTags(TRACK_SIZE, AVT_Type, MEMF_SHARED, AVT_ClearWithValue, 0, TAG_END))
{
DiskIO->iotd_Req.io_Length = TRACK_SIZE;
DiskIO->iotd_Req.io_Data =(APTR)Writebuffer;
DiskIO->iotd_Req.io_Offset =(uint32)(TRACK_SIZE * track);
DiskIO->iotd_Req.io_Command = TD_FORMAT;
IExec->DoIO((struct IORequest *)DiskIO);
}
</syntaxhighlight>

=== Ejecting a Disk ===

Certain disk drive manufacturers allow software control of disk ejection. The trackdisk device provides the TD_EJECT command to tell such drives to eject a disk.

You eject a disk by passing an IOExtTD to the device with TD_EJECT set in io_Command.

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Command = TD_EJECT;
IExec->DoIO((struct IORequest *)DiskIO);
</syntaxhighlight>

{{Note|title=Read the Instruction Manual|text=The 3.5’’ drives for the Amiga and most other Amiga drive manufacturers do not support software disk ejects. Attempting this command on those drives will result in an error condition. Consult the instruction manual for your disk drive to determine whether this is supported.}}

== Disk Status Commands ==

Disk status commands return status on the current disk in the opened unit. These commands may be done with quick I/O and thus may be called within interrupt handlers (such as the trackdisk disk change handler). See [[Exec_Device_I/O|Exec Device I/O]] for more detailed information on quick I/O.

=== Determining the Presence of a Disk ===

You determine the presence of a disk in a drive by passing an IOExtTD to the device with TD_CHANGESTATE set in io_Command. For quick I/O, you must set io_Flags to IOF_QUICK.

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Flags = IOF_QUICK;
DiskIO->iotd_Req.io_Command = TD_CHANGESTATE;
IExec->BeginIO((struct IORequest *)DiskIO);
</syntaxhighlight>

TD_CHANGESTATE returns the presence indicator of a disk in io_Actual. The value returned will be zero if a disk is currently in the drive and nonzero if the drive has no disk.

=== Determining the Write-Protect Status of a Disk ===

You determine the write-protect status of a disk by passing an IOExtTD to the device with TD_PROTSTATUS set in io_Command. For quick I/O, you must set io_Flags to IOF_QUICK.

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Flags = IOF_QUICK;
DiskIO->iotd_Req.io_Command = TD_PROTSTATUS;
IExec->BeginIO((struct IORequest *)DiskIO);
</syntaxhighlight>

TD_PROTSTATUS returns the write-protect status in io_Actual. The value will be zero if the disk is not write-protected and nonzero if the disk is write-protected.

=== Determining the Drive Type ===

You determine the drive type of a unit by passing an IOExtTD to the device with TD_GETDRIVETYPE set in io_Command. For quick I/O, you must set io_Flags to IOF_QUICK.

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Flags = IOF_QUICK;
DiskIO->iotd_Req.io_Command = TD_GETDRIVETYPE;
IExec->BeginIO((struct IORequest *)DiskIO);
</syntaxhighlight>

TD_GETDRIVETYPE returns the drive type for the unit that was opened in io_Actual. The value will be DRIVE3_5 for 3.5’’ drives and DRIVE5_25 for 5.25’’ drives. The unit can be opened only if the device understands the drive type it is connected to.

=== Determining the Number of Tracks of a Drive ===

You determine the number of a tracks of a drive by passing an IOExtTD to the device with TD_GETNUMTRACKS set in io_Command. For quick I/O, you must set io_Flags to IOF_QUICK.

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Flags = IOF_QUICK;
DiskIO->iotd_Req.io_Command = TD_GETNUMTRACKS;
IExec->BeginIO((struct IORequest *)DiskIO);
</syntaxhighlight>

TD_GETNUMTRACKS returns the number of tracks on that device in io_Actual. This is the number of tracks of TD_SECTOR * NUMSECS size. It is not the number of cylinders. With two heads, the number of cylinders is half of the number of tracks. The number of cylinders is equal to the number of tracks divided by the number of heads (surfaces). The standard 3.5’’ Amiga drive has two heads

TD_GETGEOMETRY is the preferred over TD_GETNUMTRACKS especially since new drive types may have more sectors or different sector sizes, etc., than standard Amiga drives.

=== Determining the Current Diskchange Number ===

You determine the current diskchange number of a disk by passing an IOExtTD to the device with TD_CHANGENUM set in io_Command. For quick I/O, you must set io_Flags to IOF_QUICK.

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Flags = IOF_QUICK;
DiskIO->iotd_Req.io_Command = TD_CHANGENUM;
IExec->BeginIO((struct IORequest *)DiskIO);
</syntaxhighlight>

TD_CHANGENUM returns the current value of the diskchange counter (as used by the enhanced commands) in io_Actual. The disk change counter is incremented each time the disk is inserted or removed.

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Flags = IOF_QUICK;
DiskIO->iotd_Req.io_Command = TD_CHANGENUM;
IExec->BeginIO((struct IORequest *)DiskIO);
uint32 change_count = DiskIO->iotd_Req.io_Actual; /* store current diskchange value */

DiskIO->iotd_Req.io_Length = 1; /* Turn on the drive motor */
DiskIO->iotd_Count = change_count;
DiskIO->iotd_Req.io_Command = ETD_MOTOR;
IExec->DoIO((struct IORequest *)DiskIO);
</syntaxhighlight>

== Commands for Diagnostics and Repair ==

The trackdisk device provides commands to move the drive heads to a specific track. These commands are provided for internal diagnostics, disk repair, and head cleaning only.

=== Moving the Drive Head to a Specific Track ===

You move the drive head to a specific track by passing an IOExtTD to the device with TD_SEEK or ETD_SEEK set in io_Command, and io_Offset set to the byte offset of the track to which the seek is to occur.

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Offset = (uint32)(TRACK_SIZE * track);
DiskIO->iotd_Req.io_Command = TD_SEEK;
IExec->DoIO((struct IORequest *)DiskIO);
</syntaxhighlight>

{{Note|title=Seeking is not Reading|text=TD_SEEK and ETD_SEEK do not verify their position until the next read. That is, they only move the heads; they do not actually read any data.}}

== Notification of Disk Changes ==

Many programs will wish to be notified if the user has changed the disk in the active drive. While this can be done via the Intuition DISKREMOVED and DISKINSERTED messages, sometimes more tightly controlled testing is required. The trackdisk device provides commands to initiate interrupt processing when disks change.

Those implementing their own disk change notification support in a file system or device driver should review [[Supporting_Disk_Change_Events|Supporting Disk Change Events]].

=== Adding a Diskchange Software Interrupt Handler ===

The trackdisk device lets you add a software interrupt handler that will be Cause()’ed when a disk insert or remove occurs. Within the handler, you may only call the status commands that can use IOF_QUICK.

You add a software interrupt handler by passing an IOExtTD to the device with a pointer to an Interrupt structure set in io_Data, the length of the structure set in io_Length and TD_ADDCHANGEINT set in io_Command.

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Length = sizeof(struct Interrupt)
DiskIO->iotd_Req.io_Data = (APTR)Disk_Interrupt;
DiskIO->iotd_Req.io_Command = TD_ADDCHANGEINT;
IExec->SendIO((struct IORequest *)DiskIO);
</syntaxhighlight>

{{Note|title=Going, going, gone|text=This command does ''not'' return when executed. It holds onto the IORequest until the TD_REMCHANGEINT command is executed with that same IORequest. Hence, you must use SendIO() with this command.}}

=== Removing a Diskchange Software Interrupt Handler ===

You remove a software interrupt handler by passing the same IOExtTD to the device you used with TD_ADDCHANGEINT but with the io_Command set to TD_REMCHANGEINT. You ''must'' pass it the same Interrupt structure used to add the handler.

For maximum compatibility, when you remove the change interrupt handler with the TD_REMCHANGEINT command you must make sure that the TD_ADDCHANGEINT command was successful, and if not, then you will have to remove the IOExtTD as shown below:

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Command = TD_REMCHANGEINT;
IExec->DoIO((struct IORequest *)DiskIO);

/* Was the TD_ADDCHANGEINT command successful? */
if (IExec->CheckIO((struct IORequest *)DiskIO) == NULL)
{
DiskIO->io_Command = TD_REMCHANGEINT;
IExec->DoIO((struct IORequest *)DiskIO);
}
else
{
/* The TD_ADDCHANGEINT command was not successful and has been rejected. */
IExec->WaitIO((struct IORequest *)DiskIO);
}
</syntaxhighlight>

== Commands for Low-Level Access ==

The trackdisk device provides commands to read and write raw flux changes on the disk. The data returned from a low-level read or sent via a low-level write should be encoded into some form of legal flux patterns. See the ''Amiga Hardware Reference Manual'' and books on magnetic media recording and reading.

=== Reading Raw Data from a Disk ===

ETD_RAWREAD and TD_RAWREAD perform a raw read from a track on the disk. They seek to the specified track and read it into the user’s buffer.

''No processing of the track is done.''

It will appear exactly as the bits come off the disk – typically in some legal flux format (such as MFM, FM, GCR, etc; if you don’t know what these are, you shouldn’t be using this call). Caveat programmer.

This interface is intended for sophisticated programming only. You must fully understand digital magnetic recording to be able to utilize this call. It is also important that you understand that the MFM encoding scheme used by the higher level trackdisk routines may change without notice. Thus, this routine is only really useful for reading and decoding other disks such as MS-DOS formatted disks.

You read raw data from a disk by passing an IOExtTD to the device with TD_RAWREAD or ETD_RAWREAD set in io_Command, the number of bytes to be read set in io_Length (maximum 32K), a pointer to the read buffer set in io_Data, and io_Offset set to the byte offset of the track where you want to the read to begin. For ETD_RAWREAD, you must also set iotd_Count to the current diskchange number.

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Length = 1024; /* number of bytes to read */
DiskIO->iotd_Req.io_Data = (APTR)Readbuffer; /* pointer to buffer */
DiskIO->iotd_Req.io_Offset = (uint32)(TRACK_SIZE * track); /* track number */
DiskIO->iotd_Req.io_Flags = IOTDF_INDEX /* Set for index sync */
DiskIO->iotd_Count = change_count; /* diskchange number */
DiskIO->iotd_Req.io_Command = ETD_RAWREAD;
IExec->DoIO((struct IORequest *)DiskIO);
</syntaxhighlight>

A raw read may be synched with the index pulse by setting the IOTDF_INDEXSYNC flag or synched with a $4489 sync pattern by setting the IOTDF_WORDSYNC flag. See the [http://wiki.amigaos.net/amiga/autodocs/trackdisk.doc.txt trackdisk.doc] in the SDK for more information about these flags.

{{Note|title=Forewarned is Forearmed|text=The AmigaOS development team may make enhancements to the disk format in the future. The AmigaOS development team intends to provide compatibility within the trackdisk device. Anyone who uses these raw routines is bypassing this upward-compatibility and does so at her own risk.}}

=== Writing Raw Data to a Disk ===

ETD_RAWWRITE and TD_RAWWRITE perform a raw write to a track on the disk. They seek to the specified track and write it from the user’s buffer.

''No processing of the track is done.''

It will be written exactly as the bits come out of the buffer – typically in some legal flux format (such as MFM, FM, GCR; if you don’t know what these are, you shouldn’t be using this call). Caveat Programmer.

This interface is intended for sophisticated programming only. You must fully understand digital magnetic recording to be able to utilize this call. It is also important that you understand that the MFM encoding scheme used by the higher level trackdisk routines may change without notice. Thus, this routine is only really useful for encoding and writing other disk formats such as MS-DOS disks.

You write raw data to a disk by passing an IOExtTD to the device with TD_RAWRITE or ETD_RAWRITE set in io_Command, the number of bytes to be written set in io_Length (maximum 32K), a pointer to the write buffer set in io_Data, and io_Offset set to the byte offset of the track where you want to the write to begin. For ETD_RAWWRITE, you must also set iotd_Count to the current diskchange number.

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Length = 1024; /* number of bytes to write */
DiskIO->iotd_Req.io_Data = (APTR)Writebuffer; /* pointer to buffer */
DiskIO->iotd_Req.io_Offset = (uint32)(TRACK_SIZE * track); /* track number */
DiskIO->iotd_Req.io_Flags = IOTDF_INDEX /* Set for index sync */
DiskIO->iotd_Count = change_count; /* diskchange number */
DiskIO->iotd_Req.io_Command = ETD_RAWWRITE;
IExec->DoIO((struct IORequest *)DiskIO);
</syntaxhighlight>

A raw write may be synched with the index pulse by setting the IOTDF_INDEXSYNC flag or synched with a $4489 sync pattern by setting the IOTDF_WORDSYNC flag. See the [http://wiki.amigaos.net/amiga/autodocs/trackdisk.doc.txt trackdisk.doc] in the SDK for more information about these flags.

{{Note|title=Beware The Synch On Write|text=Synch on write will most likely destroy some of the bits following the synch before reliable writing begins. This is due to how the ''Paula'' chip implements this feature. Use synch on write very carefully if at all.}}

=== Limitations for Sync’ed Reads and Writes ===

There is a delay between the index pulse and the start of bits coming in from the drive (e.g. DMA started). It is in the range of 135-200 microseconds. This delay breaks down as follows: 55 microseconds for software interrupt overhead (this is the time from interrupt to the write of the DSKLEN register); 66 microseconds for one horizontal line delay (remember that disk I/O is synchronized with ''Agnus''’ display fetches). The last variable (0-65 microseconds) is an additional scan line since DSKLEN is poked anywhere in the horizontal line. This leaves 15 microseconds unaccounted for. In short, you will almost never get bits within the first 135 microseconds of the index pulse, and may not get it until 200 microseconds. At 4 microsecs/bit, this works out to be between 4 and 7 bytes of user data delay.

{{Note|title=Forewarned is Forearmed|text=The AmigaOS development team may make enhancements to the disk format in the future. The AmigaOS development team intends to provide compatibility within the trackdisk device. Anyone who uses these raw routines is bypassing this upward-compatibility and does so at her own risk.}}

== Trackdisk Device Errors ==

The trackdisk device returns error codes whenever an operation is attempted.

<syntaxhighlight lang="C" line>
DiskIO->iotd_Req.io_Length = TRACK_SIZE;
DiskIO->iotd_Req.io_Data = (APTR)Writebuffer;
DiskIO->iotd_Req.io_Offset = (uint32)(TRACK_SIZE * tracknum);
DiskIO->iotd_Count = change_count;
DiskIO->iotd_Req.io_Command = ETD_WRITE;
if (IExec->DoIO((struct IORequest *)DiskIO))
IDOS->Printf("ETD_WRITE failed. Error: %ld\n", DiskIO-iotd.io_Error);
</syntaxhighlight>

When an error occurs, these error numbers will be returned in the io_Error field of your IOExtTD block.

{| class="wikitable"
|+Trackdisk Device Error Codes
|-
! Error
! Value
! Explanation
|-
| TDERR_NotSpecified || 20 || Error could not be determined
|-
| TDERR_NoSecHdr || 21 || Could not find sector header
|-
| TDERR_BadSecPreamble || 22 || Error in sector preamble
|-
| TDERR_BadSecID || 23 || Error in sector identifier
|-
| TDERR_BadHdrSum || 24 || Header field has bad checksum
|-
| TDERR_BadSecSum || 25 || Sector data field has bad checksum
|-
| TDERR_TooFewSecs || 26 || Incorrect number of sectors on track
|-
| TDERR_BadSecHdr || 27 || Unable to read sector header
|-
| TDERR_WriteProt || 28 || Disk is write-protected
|-
| TDERR_DiskChanged || 29 || Disk has been changed or is not currently present
|-
| TDERR_SeekError || 30 || While verifying seek position, found seek error
|-
| TDERR_NoMem || 31 || Not enough memory to do this operation
|-
| TDERR_BadUnitNum || 32 || Bad unit number (unit # not attached)
|-
| TDERR_BadDriveType || 33 || Bad drive type (not an Amiga 3.5’’ disk)
|-
| TDERR_DriveInUse || 34 || Drive already in use (only one task exclusive)
|-
| TDERR_PostReset || 35 || User hit reset; awaiting doom
|}

== Example Trackdisk Program ==

<syntaxhighlight lang="C" line>
/*
* Track_Copy.c
*
* This program does a track by track copy from one drive to another
*
* This program will only run from the CLI. If started from
* the workbench, it will just exit...
*
* Usage: trackcopy dfx dfy
*/

#include <exec/types.h>
#include <exec/memory.h>
#include <devices/trackdisk.h>
#include <dos/dosextens.h>

#include <proto/exec.h>
#include <proto/dos.h>

#include <stdio.h>
#include <string.h>

#define TRACK_SIZE ((int32)(NUMSECS * TD_SECTOR))

/*
* Turn the BUSY flag off/on for the drive
* If onflag is TRUE, the disk will be marked as busy...
*
* This is to stop the validator from executing while
* we are playing with the disks.
*/
VOID disk_busy(CONST_STRPTR drive, int32 onflag)
{
IDOS->Inhibit(drive, onflag);
}

/*
* This turns the motor off
*/
VOID Motor_Off(struct IOExtTD *disk)
{
disk->iotd_Req.io_Length=0;
disk->iotd_Req.io_Command=TD_MOTOR;
IExec->DoIO((struct IORequest *)disk);
}

/*
* This turns the motor on
*/
VOID Motor_On(struct IOExtTD *disk)
{
disk->iotd_Req.io_Length=1;
disk->iotd_Req.io_Command=TD_MOTOR;
IExec->DoIO((struct IORequest *)disk);
}

/*
* This reads a track, reporting any errors...
*/

int16 Read_Track(struct IOExtTD *disk,UBYTE *buffer, int16 track)
{
int16 All_OK=TRUE;

disk->iotd_Req.io_Length=TRACK_SIZE;
disk->iotd_Req.io_Data=(APTR)buffer;
disk->iotd_Req.io_Command=CMD_READ;
disk->iotd_Req.io_Offset=(uint32)(TRACK_SIZE * track);
IExec->DoIO((struct IORequest *)disk);
if (disk->iotd_Req.io_Error)
{
All_OK=FALSE;
IDOS->Printf("Error %lu when reading track %ld",disk->iotd_Req.io_Error,track);
}
return(All_OK);
}

/*
* This writes a track, reporting any errors...
*/

int16 Write_Track(struct IOExtTD *disk,UBYTE *buffer,int16 track)
{
int16 All_OK=TRUE;

disk->iotd_Req.io_Length=TRACK_SIZE;
disk->iotd_Req.io_Data=(APTR)buffer;
disk->iotd_Req.io_Command=TD_FORMAT;
disk->iotd_Req.io_Offset=(uint32)(TRACK_SIZE * track);
IExec->DoIO((struct IORequest *)disk);
if (disk->iotd_Req.io_Error)
{
All_OK=FALSE;
IDOS->Printf("Error %ld when writing track %ld",disk->iotd_Req.io_Error,track);
}
return(All_OK);
}

/*
* This function finds the number of TRACKS on the device.
* NOTE That this is TRACKS and not cylinders. On a Two-Head
* drive (such as the standard 3.5" drives) the number of tracks
* is 160, 80 cylinders, 2-heads.
*/

int16 FindNumTracks(struct IOExtTD *disk)
{
disk->iotd_Req.io_Command=TD_GETNUMTRACKS;
IExec->DoIO((struct IORequest *)disk);
return((int16)disk->iotd_Req.io_Actual);
}

/*
* This routine allocates the memory for one track and does
* the copy loop.
*/

VOID Do_Copy(struct IOExtTD *diskreq0,struct IOExtTD *diskreq1)
{
UBYTE *buffer;
int16 track;
int16 All_OK;
int16 NumTracks;

if (buffer=IExe->AllocVecTags(TRACK_SIZE, AVT_Type, MEMF_SHARED, TAG_END))
{
IDOS->Printf(" Starting Motors\r");
Motor_On(diskreq0);
Motor_On(diskreq1);
All_OK=TRUE;

NumTracks=FindNumTracks(diskreq0);

for (track=0;(track<NumTracks) && All_OK;track++)
{
IDOS->Printf(" Reading track %ld\r",track);

if (All_OK=Read_Track(diskreq0,buffer,track))
{
IDOS->Printf(" Writing track %ld\r",track);

All_OK=Write_Track(diskreq1,buffer,track);
}
}
if (All_OK) IDOS->Printf(" * Copy complete *");
IDOS->Printf("\n");
Motor_Off(diskreq0);
Motor_Off(diskreq1);
IExec->FreeVec(buffer);
}
else IDOS->Printf("No memory for track buffer...\n");
}

/*
* Prompts the user to remove one of the disks.
* Since this program makes an EXACT copy of the disks
* AmigaDOS would get confused by them so one must be removed
* before the validator is let loose. Also, note that the
* disks may NEVER be in drives on the SAME computer at the
* SAME time unless one of the disks is renamed. This is due
* to a bug in the system. It would normally be prevented
* by a diskcopy program that knew the disk format and modified
* the creation date by one clock-tick such that the disks would
* be different.
*/

VOID Remove_Disks(VOID)
{
IDOS->Printf("\nYou *MUST* remove at least one of the disks now.\n");
IDOS->Printf("\nPress RETURN when ready\n");
while(getchar()!='\n');
}

/*
* Prompts the user to insert the disks.
*/

VOID Insert_Disks(char drive1[], char drive2[])
{
IDOS->Printf("\nPlease insert source disk in %s\n",drive1);
IDOS->Printf("\n and destination in %s\n",drive2);
IDOS->Printf("\nPress RETURN when ready\n");
while(getchar()!='\n');
}

/*
* Open the devices and mark them as busy
*/
VOID Do_OpenDevice(struct IOExtTD *diskreq0,struct IOExtTD *diskreq1, int32 unit[])
{
char drive1[] = "DFx:"; /* String for source drive */
char drive2[] = "DFx:"; /* String for destination drive */

drive1[2] = unit[0]+ '0'; /* Set drive number for source */

if (!IExec->OpenDevice(TD_NAME,unit[0],(struct IORequest *)diskreq0,0L))
{
disk_busy(drive1,TRUE);
drive2[2] = unit[1]+ '0'; /* Set drive number for destination */

if (!IExec->OpenDevice(TD_NAME,unit[1],(struct IORequest *)diskreq1,0L))
{
disk_busy(drive2,TRUE);

Insert_Disks(drive1,drive2);
Do_Copy(diskreq0,diskreq1);
Remove_Disks();

disk_busy(drive2,FALSE);
IExec->CloseDevice((struct IORequest *)diskreq1);
}
else IDOS->Printf("Could not open %s\n",drive2);

disk_busy(drive1,FALSE);
IExec->CloseDevice((struct IORequest *)diskreq0);
}
else IDOS->Printf("Could not open %s\n",drive1);
}

int16 ParseArgs(int argc, char **argv, int32 Unit[])
#define OKAY 1
{
int j=1, params = OKAY;
char *position[]={"First","Second"};

if (argc != 3)
{
IDOS->Printf("\nYou must specify a source and destination disk\n");
return(!OKAY);
}
else if (strcmp(argv[1],argv[2]) == 0)
{
IDOS->Printf("\nYou must specify different disks for source and destination\n");
return(!OKAY);
}
else while (params == OKAY && j<3)
{
if (strnicmp(argv[j],"df",2)==0)
{
if (argv[j][2] >= '0' && argv[j][2] <= '3' && argv[j][3] == '\0')
{
Unit[j-1] = argv[j][2] - 0x30;
}
else
{
IDOS->Printf("\n%s parameter is wrong, unit number must be 0-3\n",position[j-1]);
params = !OKAY;
return(!OKAY);
}
}
else
{
IDOS->Printf("\n%s parameter is wrong, you must specify a floppy device df0 - df3\n",
position[j-1]);
params=!OKAY;
return(!OKAY);
}
j++;
}
return(OKAY);
}

int main(int argc, char **argv)
{
int32 unit[2];

if (ParseArgs(argc, argv, unit)) /* Check inputs */
{
struct MsgPort *diskPort = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);
if (diskPort != NULL)
{
struct IOExtTD *diskreq0 = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOExtTD),
ASOIOR_ReplyPort, diskPort,
TAG_END);

if (diskreq0 != NULL)
{
struct IOExtTD *diskreq1 = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOExtTD),
ASOIOR_ReplyPort, diskPort,
TAG_END);

if (diskreq1 != NULL)
{
Do_OpenDevice(diskreq0,diskreq1, unit);
IExec->FreeSysObject(ASOT_IOREQUEST, diskreq1);
}
else IDOS->Printf("Out of memory\n");
IExec->FreeSysObject(ASOT_IOREQUEST, diskreq0);
}
else IDOS->Printf("Out of memory\n");
IExec->FreeSysObject(ASOT_PORT, diskPort);
}
else IDOS->Printf("Could not create diskReq port\n");
}

return 0;
}
</syntaxhighlight>

{{Note|title=Only one per customer|text=Since this example program makes an exact track-for-track duplicate, AmigaDOS will get confused if both disks are in drives on the system at the same time. While the disks are inhibited, this does not cause a problem, but during normal operation, this will cause a system hang. To prevent this, you can relabel one of the disks. A commercial diskcopy program would have to understand the disk format and either relabel the disk or modify the volume creation date/time by a bit in order to make the disks look different to the system.}}

== Additional Information on the Trackdisk Device ==

Additional programming information on the trackdisk device can be found in the include files and the autodocs for the trackdisk device. Both are contained in the [[Autodocs:Main|Autodocs]].

{| class="wikitable"
!colspan=2|Trackdisk Device Information
|-
|rowspan="2"|Includes||devices/trackdisk.h
|-
|devices/trackdisk.i
|-
|[[Autodocs:Main|Autodocs]]||[http://wiki.amigaos.net/amiga/autodocs/trackdisk.doc.txt trackdisk.doc]
|}

Revision 4

2025-01-26T19:27:39Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= SANA-II Revision 4 =

Extending the SANA-II network driver specification 
by Olaf Barthel

(Last updated 02-Mar-2003)

== Introduction ==

The years have gone by without any substantial changes to the SANA-II standard being made. With good reason, since there was no apparent need to push the envelope and extend the driver specification. The last proposed change came 1997 from Holger Kruse, who suggested that commands should be added to control multicast packet reception for ranges of addresses rather than individual addresses.

I've been working on a TCP/IP stack and PPP drivers to go with them for a while and found that there were some things that SANA-II did specifically not address, and which ought to be covered by it. In other areas clarification was needed. Also, discussions I had with Harald Frank suggested that the extensions made by Heinz Wrobel and Stefan Sticht in the SANA-IIR3 specification could need extending.

The following text tries to tie all issues together and will conclude by listing problems which I think still need attention (or in other words, I didn't find a solution myself). Wherever possible, I have tried to provide a rationale for the changes I propose.

Please feel free to comment; you can contact me through the [http://www.amigaos.net/contact AmigaOS contact form]. Note that the issues discussed in this document are just a list of proposed changes. No such features are part of any SANA-II specifications, although I'd like to claim that I have tried to implement the majority of the changes listed below in my own software.

This is a revised version of the original document I put together around October 14, 2001. For a list of changes that have been made since, please see [[#10_changes|section 10]] ('Changes'). This document has been updated and enhanced several times, in response to discussions with Heinz Wrobel.

== New commands ==

=== S2_GETPEERADDRESS ===

As part of the negotiation process, the PPP protocol can return the addresses used by the peer (the other side of the point-to-point connection PPP establishes; typically a dial-in server) and assigned to the client establishing the connection. The SANA-II standard does not provide for a mechanism to return such information. Existing drivers therefore had to resort to other means, such as by setting global environment variables containing this information.

I propose a command with the following semantics:

<pre>
NAME
S2_GETPEERADDRESS -- Obtain the addresses used by the peer
(server) and the client of a point-to-point connection.

FUNCTION
Obtain the address used by the peer of a point-to-point connection and
the address assigned to the local driver.

IO REQUEST
ios2_Command - S2_GETPEERADDRESS
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number
ios2_SrcAddr - Address assigned to the local driver
ios2_DstAddr - Address used by the peer

NOTES
The size of the address returned by S2_GETPEERADDRESS must not be
different from the size returned by the S2_DEVICEQUERY command. For
example, if a 32 bit IPv4 address was advertized, the driver must not
return a 128 bit IPv6 address instead.

If the driver is unable to return the local driver address
(ios2_SrcAddr) or the peer's address (ios2_DstAddr) it must fill the
respective address fields with zeroes. It is legal for a driver to
respond to the S2_GETPEERADDRESS command with two zero addresses (both
ios2_SrcAddr and ios2_DstAddr filled with zeroes).
</pre>

I propose that the following command number should be assigned:
<tt>#define S2_GETPEERADDRESS 0xC002</tt>

This command may be useful beyond the typical application (PPP) described above.

=== S2_GETDNSADDRESS ===

The PPP negotiation process may produce information on which domain name and NetBIOS name servers are available to the client. I think that it is doubtful that the availability of NetBIOS name servers will be useful for Amiga software (let alone whether NetBIOS name resolution has a future), which is why I suggest that a SANA-II command for returning only the domain name servers is introduced.

I propose a command with the following semantics:

<pre>
NAME
S2_GETDNSADDRESS -- Obtain the addresses of the primary
and secondary domain name servers.

FUNCTION
Obtain the addresses of the domain name servers available to the
client using this driver's address.

IO REQUEST
ios2_Command - S2_GETDNSADDRESS
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number
ios2_SrcAddr - Address of primary domain name server
ios2_DstAddr - Address of secondary domain name server

NOTES
The size of the address returned by S2_GETPEERADDRESS must not be
different from the size as returned by the S2_DEVICEQUERY command. For
example, if a 32 bit IPv4 address was advertized, the driver must not
return a 128 bit IPv6 address instead.

If the driver is unable to return the primary domain name server
address (ios2_SrcAddr) or the secondary domain name server address
(ios2_DstAddr) it must fill the respective address fields with zeroes.
It is legal for a driver to respond to the S2_GETDNSADDRESS command
with two zero addresses (both ios2_SrcAddr and ios2_DstAddr filled
with zeroes).
</pre>

I propose that the following command number should be assigned:
<tt>#define S2_GETDNSADDRESS 0xC003</tt>

This command may be useful beyond the typical application (PPP) described above.

=== S2_GETEXTENDEDGLOBALSTATS ===

There already exists a SANA-II command for querying global device statistics (<tt>S2_GETGLOBALSTATS</tt>) which should be common to all kinds of networking devices. Statistics that are particular to a certain device type are intended to be returned through the <tt>S2_GETSPECIALSTATS</tt> command. I feel that these mechanisms both fail to cater well enough for dial-up or session-oriented networking applications such as PPP or PPPoE. Since the data structure used by <tt>S2_GETGLOBALSTATS</tt> is of a fixed size and not intended to accomodate for new fields, I propose to introduce a new command which uses a different data structure, as follows:

<syntaxhighlight lang="C" line>
struct Sana2ExtDeviceStats
{
ULONG s2xds_Length;
ULONG s2xds_Actual;

S2QUAD s2xds_PacketsReceived;
S2QUAD s2xds_PacketsSent;
S2QUAD s2xds_BadData;
S2QUAD s2xds_Overruns;
S2QUAD s2xds_UnknownTypesReceived;
S2QUAD s2xds_Reconfigurations;
struct timeval s2xds_LastStart;

struct timeval s2xds_LastConnected;
struct timeval s2xds_LastDisconnected;
struct timeval s2xds_TimeConnected;
};
</syntaxhighlight>

Before I proceed to explain what purposes the individual members serve, a few words on the <tt>S2QUAD</tt> type, which is defined as follows:
<tt>typedef struct { ULONG s2q_High; ULONG s2q_Low; } S2QUAD;</tt>

In other words, the <tt>S2QUAD</tt> type stands for an unsigned 64 bit big endian integer, as expressed in ISO 'C' terms.

The structure members have the following purposes:

<tt>s2xds_Length</tt>

This is the size of the data structure to be filled in and should be initialized by the caller to <tt>sizeof(struct Sana2ExtDeviceStats)</tt>. Smaller values are permitted, but these '''must not''' be smaller than 8 (which covers the <tt>s2xds_Length</tt> and <tt>s2xds_Actual</tt> members). A driver which finds an <tt>s2xds_Length</tt> < 8 '''must''' treat this as an error and reject the command with <tt>ios2_Req.io_Error</tt>=<tt>IOERR_BADLENGTH</tt>.

<tt>s2xds_Actual</tt>

The size of the data structure filled with information. This member is initialized by the driver and '''must''' be <= <tt>s2xds_Length</tt>.

<tt>s2xds_PacketsReceived</tt>

Number of packets that this unit has received. This is a 64 bit integer.

<tt>s2xds_PacketsSent</tt>

Number of packets that this unit has sent. This is a 64 bit integer.

<tt>s2xds_BadData</tt>

Number of bad packets received (i.e., hardware CRC failed). This is a 64 bit integer.

<tt>s2xds_Overruns</tt>

Number of packets dropped due to insufficient resources available in the network interface. This is a 64 bit integer.

<tt>s2xds_UnknownTypesReceived</tt>

Number of packets received that had no pending read command with the appropriate packet type. This is a 64 bit integer.

<tt>s2xds_Reconfigurations</tt>

Number of network reconfigurations since this unit was last configured. This is a 64 bit integer.

<tt>s2xds_LastStart</tt>

The time when this unit last went on-line.

<tt>s2xds_LastConnected</tt>

The time when this unit last established a connection. For dial-up connections, this should be the time when the underlying serial line started to accumulate costs. <tt>s2xds_LastConnected</tt> '''must''' be set to zero if the unit never managed to make a connection.

<tt>s2xds_LastDisconnected</tt>

The time when this unit last shut down a connection. For dial-up connections, this should be the time when the underlying serial line stopped accumulating costs, e.g. when the modem's carrier signal was lost. <tt>s2xds_LastDisconnected</tt> '''must''' be set to zero if the unit never disconnected.

<tt>s2xds_TimeConnected</tt>

The time this unit has been connected. For dial-up connections this should be the time between now and when the underlying serial line started accumulating costs.

If this unit is not currently connected, then <tt>s2xds_TimeConnected</tt> '''must''' be set to zero. This means in particular that when the connection is lost, <tt>s2xds_TimeConnected</tt> '''must''' be immediately set to zero and <tt>s2xds_LastDisconnected</tt> '''must''' be filled in so that client software can query how long the unit was connected by subtracting <tt>s2xds_LastConnected</tt> from <tt>s2xds_LastDisconnected</tt>.

If this unit is currently connected, <tt>s2xds_TimeConnected</tt> '''must never''' be zero; if necessary, set <tt>s2xds_TimeConnected.tv_secs=0</tt> and <tt>s2xds_TimeConnected.tv_micros=1</tt>.

If <tt>s2xds_TimeConnected</tt> is zero, check <tt>s2xds_LastConnected</tt> and <tt>s2xds_LastDisconnected</tt>; if the latter two are not zero, you can calculate the previous connection time by subtracting <tt>s2xds_LastConnected</tt> from <tt>s2xds_LastDisconnected</tt>.

The layout and semantics used by the <tt>Sana2ExtDeviceStats</tt> data structure suggest that there is a difference between the underlying networking media (the link layer) and the state of the protocol that is running on top of it. With drivers for networking hardware such as Ethernet there was no difference between these two, but for protocols like SLIP, PPP or PPPoE there is a difference. The difference is in that a session or connection may exist for a certain time whereas the protocol running inside that session may be switched 'online' later. The primary purpose of the <tt>s2xds_LastConnected</tt>, <tt>s2xds_LastDisconnected</tt> and <tt>s2xds_TimeConnected</tt> fields is to allow for cost accounting and traffic monitoring (so that, for example, a driver may be disconnected after it has been idle for a while) to be written.

I propose a command with the following semantics:

<pre>
NAME
S2_GETEXTENDEDGLOBALSTATS -- Get interface accumulated statistics;
updated version.

FUNCTION
This command causes the device driver to retrieve various global
runtime statistics for this network interface. The format of the data
returned is as follows:

struct Sana2ExtDeviceStats
{
ULONG s2xds_Length;
ULONG s2xds_Actual;

S2QUAD s2xds_PacketsReceived;
S2QUAD s2xds_PacketsSent;
S2QUAD s2xds_BadData;
S2QUAD s2xds_Overruns;
S2QUAD s2xds_UnknownTypesReceived;
S2QUAD s2xds_Reconfigurations;
struct timeval s2xds_LastStart;

struct timeval s2xds_LastConnected;
struct timeval s2xds_LastDisconnected;
struct timeval s2xds_TimeConnected;
};

IO REQUEST
ios2_Command - S2_GETEXTENDEDGLOBALSTATS
ios2_StatData - Pointer to Sana2ExtDeviceStats structure
to fill in
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number
</pre>

I propose that the following command number should be assigned:
<tt>#define S2_GETEXTENDEDGLOBALSTATS 0xC004</tt>

=== S2_CONNECT ===

The driver model specified by the SANA-II standard really only covers networking hardware well. Software-only drivers, such as for dial-up networking, are, well, somehow mentioned in the standard, but they don't receive much attention. In particular, this means that a networking driver is assumed to be practically always attached to its link layer and no provisions exist to specify what kind of link layer that might be and how it might be accessed. This small oversight can probably be explained by the fact that at the time the SANA-II standard was adopted, dial-up networking had not yet gained the prominence it has today.

To bridge this gap, I propose a new command which will make a driver connect to its link layer and go online, which uses the following data structure:

<syntaxhighlight lang="C" line>
struct Sana2Connection
{
ULONG s2c_Size;
struct MinList s2c_Options;
struct Hook s2c_ErrorHook;
struct Hook s2c_ConnectHook;
struct Hook s2c_DisconnectHook;
STRPTR s2c_Login;
STRPTR s2c_Password;
};
</syntaxhighlight>

The individual structure members have the following purposes:

<tt>s2c_Size</tt>

The size of the entire data structure is stored here. This value '''must''' be >= 84. Smaller values '''must''' be rejected with <tt>ios2_Req.io_Error</tt>=<tt>IOERR_BADLENGTH</tt>. The purpose of <tt>s2c_Size</tt> is to allow for future expansion during which the structure may grow in size.

<tt>s2c_Options</tt>

This list contains options, to be used during the connection process. Each node has the following format:

<syntaxhighlight lang="C" line>
struct Sana2ConnectionOption
{
struct MinNode s2co_MinNode;
STRPTR s2co_Name;
STRPTR s2co_Value;
};
</syntaxhighlight>

The <tt>s2co_Name</tt> and <tt>s2co_Value</tt> entries point to <tt>NUL</tt>-terminated strings, which contain the name and the value of a parameter. ''Note that for numeric values, the respective number will be encoded in a text string.'' A number of parameters are reserved, which are [[#s2c_options|listed later]] in this text.

<tt>s2c_ErrorHook</tt>

This hook is called whenever an error message is to be reported during the connection/disconnection process. The hook function is invoked using the following parameters:

<pre>error_hook_func(hook,reserved,message);

VOID error_hook_func(struct Hook *hook,APTR reserved,
STRPTR message);</pre>
The <tt>reserved</tt> parameter '''must''' be <tt>NULL</tt>. The <tt>message</tt> parameter points to a <tt>NUL</tt>-terminated string. It '''must not''' be <tt>NULL</tt>.

Because the hook function may have to allocate memory, it '''must not''' be called from interrupt code.

<tt>s2c_ConnectHook</tt>

This hook is called when the link level device has been set up, but further initializations are necessary, such as telling a modem to dial out. The hook function is invoked with the following parameters:

<pre>
success = connect_hook_func(hook,reserved,s2cm);

BOOL connect_hook_func(struct Hook *hook,APTR reserved,
struct Sana2ConnectionMessage *s2cm);
</pre>

The <tt>reserved</tt> parameter '''must''' be <tt>NULL</tt>. The <tt>s2cm</tt> parameter points to a data structure, as follows:

<syntaxhighlight lang="C" line>
struct Sana2ConnectionMessage
{
ULONG s2cm_Size;
struct Sana2Connection * s2cm_Connection;
struct IORequest * s2cm_Request[2];
LONG s2cm_RequestType;
};
</syntaxhighlight>

In this structure, the members have the following purposes:

<tt>s2cm_Size</tt>

The size of this data structure; it '''must''' be at least 20 bytes in size. The purpose of <tt>s2cm_Size</tt> is to allow for future expansion, which may cause the size of this structure to grow.

<tt>s2cm_Connection</tt>

This points back to the <tt>Sana2Connection</tt> structure which the hook that was invoked with the <tt>Sana2ConnectionMessage</tt> is embedded in.

<tt>s2cm_Request</tt>

Here you will find two I/O requests which can be used for reading and writing data to the link layer. These pointers '''must not''' be <tt>NULL</tt> and they '''must''' refer to different I/O requests, it is not permitted to pass the same request twice.

The dialer can use these requests for communicating with the modem, but it is also permitted to clone these requests by creating new I/O requests of the same size, copying the original contents and filling in different reply ports.

There is a danger in that the hook code may not receive the right kind of I/O request, which is why the <tt>s2cm_RequestType</tt> field identifies the kind of device the requests were created for.

When the hook function returns, it '''must''' make sure that none of the I/O requests are still pending, i.e. asynchronous I/O '''must''' have been stopped.

<tt>s2cm_RequestType</tt>

This identifies the type of device the I/O requests passed in <tt>s2cm_Request</tt> were created for. Possible values for this entry come from the New Style Device specification, e.g. <tt>NSDEVTYPE_SERIAL</tt> for a <tt>serial.device</tt>-like device or <tt>NSDEVTYPE_SANA2</tt> for a networking driver.

The hook function '''must''' return <tt>TRUE</tt> if the connection could be established, and <tt>FALSE</tt> otherwise. Note that it is ''not'' sufficient to just return <tt>FALSE</tt> in case of failure. Your code '''must''' have called the <tt>s2c_ErrorHook</tt> with an explanation why things went wrong first.

<tt>s2c_DisconnectHook</tt>

This hook is called by <tt>S2_CONNECT</tt> when the connection could not be established (the <tt>s2c_ConnectHook</tt> returned <tt>FALSE</tt>), or by <tt>S2_DISCONNECT</tt>, shortly before the link level device is to be closed. The hook function is invoked with the following parameters:

<pre>
disconnect_hook_func(hook,reserved,s2cm);

VOID disconnect_hook_func(struct Hook *hook,APTR reserved,
struct Sana2ConnectionMessage *s2cm);
</pre>

The <tt>reserved</tt> parameter '''must''' be <tt>NULL</tt>. The <tt>s2cm</tt> parameter points to a data structure, as was described for the <tt>s2c_ConnectHook</tt>.

<tt>s2c_Login</tt>

<tt>s2c_Password</tt>

The purpose of these entries is to transport the authentication information the protocol may require. These entries are either <tt>NULL</tt> or contain pointers to <tt>NUL</tt>-terminated strings. If <tt>s2c_Login</tt> is <tt>NULL</tt>, then both login and password '''must''' be assumed to be empty. If <tt>s2c_Login</tt> is not <tt>NULL</tt> and <tt>s2c_Password</tt> is <tt>NULL</tt>, then the password '''must''' be assumed to be empty.

The list of options in <tt>s2c_Options</tt> supplies the necessary information on how the driver is to connect to the link layer. Each node contains an option, which bears a name and contains a value. This pair is what I call a ''parameter''. A number of parameter names are reserved, as will be listed below:

<tt>ppp</tt>.async.device

Name of device driver to use for asynchronous PPP.

Example: <tt>serial.device</tt>

<tt>ppp</tt>.async.unit

Device unit number to use for asynchronous PPP.

Example: <tt>0</tt>

<tt>ppp</tt>.async.speed

Transmission speed to use for asynchronous PPP in bits per second.

Example: <tt>115200</tt>

<tt>ppp.async.buffersize</tt>

Receive buffer size for asynchronous PPP.

Example: <tt>50000</tt>

<tt>ppp.async.checkcarrier</tt>

Whether the carrier signal of the link layer should be tested or not. This can be either 0 (do not test) or 1 (test the carrier signal).

Example: <tt>1</tt>

<tt>ppp.async.rtscts</tt>

Whether or not hardware handshaking should be used by the link layer. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.shared</tt>

Whether or not the link layer device should be opened in shared mode. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.nullmodem</tt>

Whether or not the link layer is a direct connection, such as a nullmodem. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.eof</tt>

Whether or not the underlying serial device driver's 'EOF mode' should be enabled. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.readrequests</tt>

Number of read requests to be used for asynchronous PPP.

Example: <tt>16</tt>

<tt>ppp.async.writerequests</tt>

Number of write requests to be used for asynchronous PPP.

Example: <tt>16</tt>

<tt>ppp.async.accm</tt>

Asynchronous control character map, expressed as a hexadecimal value.

Example: <tt>$000A0000</tt>

<tt>ppp.async.pfc</tt>

Whether or not protocol field compression should be used. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.aacfc</tt>

Whether or not address and control field compression should be used. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.vjhc</tt>

Whether or not Van Jacobson header compression should be used. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.ignorefcs</tt>

Whether or not frame check sequences should be ignored upon reception. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.initialize</tt>

The modem initialization command, with embedded control sequences, if possible.

Example: <tt>AT\r</tt>

<tt>ppp.async.dial</tt>

The modem dial command, with embedded control sequences, if possible.

Example: <tt>ATD12345\r</tt>

<tt>ppp.async.dialtimeout</tt>

The dial timeout, i.e. the number of seconds to wait after the dial command has been sent for the modem to establish a connection.

Example: <tt>60</tt>

<tt>ppp.async.hangup</tt>

The modem hangup command, with embedded control sequences, if possible.

Example: <tt>ATH0\r</tt>

<tt>ppp.idletimeout</tt>

Number of seconds the local host may remain idle, i.e. send no data to the peer, before a watchdog timeout elapses and proceeds to verify that the line is still operational.

Example: <tt>30</tt>

<tt>ppp.localaddress</tt>

The IP address to assign to the local host, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.remoteaddress</tt>

The IP address to assume for the peer, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.dns1address</tt>

The IP address to be used by the primary domain name server, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.dns2address</tt>

The IP address to be used by the secondary domain name server, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.maxfail</tt>

The maximum number of negative configuration acknowledgements to be sent before the PPP negotiation process switches to reject those options.

Example: <tt>5</tt>

<tt>ppp.maxterm</tt>

The maximum number of termination requests to be sent before the respective PPP network or link protocol gives up.

Example: <tt>2</tt>

<tt>ppp.maxconfig</tt>

The maximum number of configuration requests to be sent before the respective PPP network or link protocol gives up.

Example: <tt>10</tt>

<tt>ppp.timeout</tt>

The number of seconds that have to pass before the respective PPP network or link protocol will retry to do whatever didn't work during the last attempt.

Example: <tt>3</tt>

<tt>ppp.mtu</tt>

The maximum transmission unit to use.

Example: <tt>1500</tt>

<tt>ppp.peeridletimeout</tt>

Number of seconds the peer may remain idle, i.e. send no data to the local host, before a watchdog timeout elapses and proceeds to verify that the line is still operational.

Example: <tt>30</tt>

<tt>ppp.rejectpap</tt>

Whether or not the Password Authentication Protocol should be accepted, if offered by the peer. This can be either <tt>0</tt> (accept) or <tt>1</tt> (reject).

Example: <tt>0</tt>

<tt>ppp.sendid</tt>

A flag which controls whether the local host should send LCP identification packets or not. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.pap.timeout</tt>

The Password Authentication Protocol requires that the server answers to the client's request to log in. The server may be unable to respond immediately, which means that the client will have to repeat its request. A short delay should separate each request sent, such as three seconds.

Example: <tt>3</tt>

<tt>ppp.pap.retry</tt>

If the client does not manage to authenticate with the server immediately, it may resend the authentication request several times. But the attempts have to stop eventually, such as after having resent the message ten times.

Example: <tt>10</tt>

<tt>ppp.dummyremoteaddress</tt>

Whether or not the PPP driver should make up an IP address if the peer refuses to state its own IP address.

Example: <tt>1</tt>

<tt>logfile</tt>

The name of a log file to create. If the file already exists, then new data should be appended to it.

Example: <tt>t:logfile</tt>

<tt>logoptions</tt>

A list of options which control what exactly should be logged.

<tt>ppp.ethernet.device</tt>

Name of device driver to use for PPPoE (PPP over Ethernet).

Example: <tt>a2065.device</tt>

<tt>ppp.ethernet.unit</tt>

Device unit number to use for PPPoE.

Example: <tt>0</tt>

<tt>ppp.ethernet.raw</tt>

Whether or not raw link layer frames should be constructed for transmission or not. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.ethernet.bypass</tt>

Whether or not the IP packet transmission and reception should bypass several copying steps. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.ethernet.readpackets</tt>

The number of read requests to queue for the link layer.

Example: <tt>16</tt>

<tt>ppp.ethernet.writepackets</tt>

The number of write requests to queue for the link layer.

Example: <tt>16</tt>

<tt>ppp.ethernet.service</tt>

The name of the PPPoE service to request.

Example: <tt>?</tt>

<tt>ppp.ethernet.ac</tt>

The name of the PPPoE access concentrator to request.

Example: <tt>?</tt>

<tt>ppp.ethernet.connecttimeout</tt>

The number of seconds to wait for the PPPoE server to allow a session to be opened.

Example: <tt>3</tt>

While this list of parameters may suggest that the command described above can be used solely with the PPP protocol, do not let that put you off. This list is merely the starting point, but it is not set in stone that it cannot be extended.

The names of the parameters are not case sensitive. As the names suggest, the name space itself is hierarchic in construction, i.e. everything related to the PPP protocol bears a name starting with the letters 'ppp' with the dot '.' separating the individual items. By this rule, ppp.async refers to options that concern asynchronous PPP and ppp.ethernet to options that concern PPP over Ethernet wire.

To add your own parameter, register it with the maintainer of the SANA-II standard or prefix its name with the letters 'x-'. For example, to use your own kind of 'ppp.ethernet.connecttimeout' parameter, change the name of the last component like this: ppp.ethernet.x-connecttimeout. No officially-registered parameter will ever begin with the prefix 'x-'.

The command should work as follows:

# The client must set up the <tt>Sana2Connection</tt> data structure, initialize the <tt>s2c_Size</tt>, <tt>s2c_Options</tt>, <tt>s2c_ErrorHook</tt>, <tt>s2c_ConnectHook</tt>, <tt>s2c_DisconnectHook</tt>, <tt>s2c_Login</tt> and <tt>s2c_Password</tt> fields.
# The connection options must be filled in, which means that nodes containing the respective information must be stored in the <tt>s2c_Options</tt> list. The client must make sure that the syntax of the parameters conforms to the specifications described above.
# A pointer to the <tt>Sana2Connection</tt> data structure is placed in the <tt>ios2_Data</tt> member of an <tt>IOSana2Req</tt>, the command is set to <tt>S2_CONNECT</tt> and the request is sent via <tt>DoIO()</tt> or <tt>SendIO()</tt>.
# The driver receives the request and begins to examine the contents of the <tt>s2c_Options</tt> list, as provided in the data structure pointed to by the <tt>ios2_Data</tt> member of the request. Unknown options are ignored, options whose values do not conform to the syntax specification are rejected; this is done by calling the <tt>s2c_ErrorHook</tt> with an error message referring to the option in question and by returning the <tt>IOSana2Req</tt> with an error code of <tt>S2ERR_BAD_ARGUMENT</tt> and wire error code of <tt>S2WERR_INVALID_OPTION</tt>.
# If the options are all in good order, the driver proceeds to verify that all mandatory options are provided. If this is not the case, the <tt>s2c_ErrorHook</tt> is called with an error message referring to the option in question and the <tt>IOSana2Req</tt> is returned with an error code of <tt>S2ERR_BAD_ARGUMENT</tt> and wire error code of <tt>S2WERR_MISSING_OPTION</tt>.
# The driver proceeds to do its local initialization, which involves opening the link layer device, etc. If this initialization fails, the <tt>s2c_ErrorHook</tt> is called with an error message referring to the problem and the <tt>IOSana2Req</tt> is returned with an appropriate error code.
# When the initialization has finished, the driver may invoke the <tt>s2c_ConnectHook</tt> callback. Some drivers may require this, such as asynchronous PPP, some may not, such as PPPoE. The purpose of the hook function is to give the client a chance to perform modem initializations and connect to the peer. If the <tt>s2c_ConnectHook</tt> cannot perform its duties, it has to invoke the <tt>s2c_ErrorHook</tt> with an error message and eventually return <tt>FALSE</tt>. If <tt>FALSE</tt> is returned, the driver must invoke the <tt>s2c_DisconnectHook</tt>, reverse any initializations it had made and eventually returned the <tt>IOSana2Req</tt> with an appropriate error code. If the <tt>s2c_ConnectHook</tt> returned <tt>TRUE</tt>, then the driver must proceed with the actions that require that the link layer is operational. A protocol negotiation may follow, which, if successful, will make the driver return the <tt>IOSana2Req</tt> with an error code of zero, indicating success. If successful, the SANA-II events <tt>S2EVENT_CONNECT</tt> and <tt>S2EVENT_ONLINE</tt> must be sent.
# The command will eventually return, but the client '''must not''' release the memory allocated for the <tt>Sana2Connection</tt> structure and the option nodes in the <tt>s2c_Options</tt> list. This is because the driver may have to invoke the <tt>s2c_DisconnectHook</tt> hook due to the connection shutting down on its own accord.

The connect and disconnect hook functions '''must not''' be called from interrupt code. For each hook only a <tt>Task</tt> calling context of unknown priority must be assumed. Also, stack space is provided only to call <tt>exec.library</tt> and <tt>utility.library</tt> functions. The callback shall not place excessive data on the stack. Stack space should be considered limited.

I propose a command with the following semantics:

<pre>
NAME
S2_CONNECT -- Establish a link layer connection and go
online.

FUNCTION
This command is for use by networking devices which require
a special link layer device to transmit their data, such as
an asynchronous serial line and need to know about the
configuration parameters necessary to open the connection.

IO REQUEST
ios2_Command - S2_CONNECT
ios2_Data - Pointer to Sana2Connection structure
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number

NOTES
If successful, this command implies S2_ONLINE, i.e. the
link layer is allocated and used by the driver.

The contents of the Sana2Connection structure must be valid
until the connection is eventually shut down. The driver will
need to cache it, so it must not be deallocated or otherwise
modified.

Note that S2_ONLINE does not necessarily imply S2_CONNECT, if
the S2_CONNECT command is listed as supported by the driver via
NSCMD_DEVICEQUERY. If S2_CONNECT is not listed as supported,
S2_ONLINE obviously implies connect functionality.

S2_CONNECT/S2_DISCONNECT do not nest.

SEE ALSO
S2_DISCONNECT</pre>
I propose that the following command number should be assigned:

<tt>#define S2_CONNECT 0xC005</tt>

=== S2_DISCONNECT ===

This command complements <tt>S2_CONNECT</tt> in that it tears down a connection. It uses the same <tt>Sana2Connection</tt> structure and hooks, but most of these members are ignored.

The command should work as follows:

# The client must set up the <tt>Sana2Connection</tt> data structure, initialize the <tt>s2c_Size</tt>, <tt>s2c_Options</tt>, <tt>s2c_ErrorHook</tt>, <tt>s2c_ConnectHook</tt>, <tt>s2c_DisconnectHook</tt>, <tt>s2c_Login</tt> and <tt>s2c_Password</tt> fields. The <tt>s2c_Options</tt>, <tt>s2c_ConnectHook</tt>, <tt>s2c_Login</tt> and <tt>s2c_Password</tt> fields will be ignored, but the client should play things safe.
# A pointer to the <tt>Sana2Connection</tt> data structure is placed in the <tt>ios2_Data</tt> member of an <tt>IOSana2Req</tt>, the command is set to <tt>S2_DISCONNECT</tt> and the request is sent via <tt>DoIO()</tt> or <tt>SendIO()</tt>.
# The driver receives the request and proceeds to reverse the steps that previously allowed it to establish a connection. This includes telling the peer to shut down the link, but it does not include cleaning up the link layer device access, i.e. no I/O requests used for accessing a modem may be shut down yet.
# The <tt>s2c_DisconnectHook</tt> may be invoked with the proper parameters. Some drivers, such as for asynchronous PPP, will need the hook to tell the modem to hang up the line. Some drivers, such as for PPPoE, may not need this hook and thus ignore it.
# The initialization is reversed completely, all resources allocated when the connection was previously opened are released. The <tt>IOSana2Req</tt> is returned with an error code of zero, indicating success. The SANA-II event <tt>S2EVENT_DISCONNECT</tt> must be sent, and, if necessary, <tt>S2EVENT_OFFLINE</tt>.

The connect and disconnect hook functions must not be called from interrupt code. For each hook only a <tt>Task</tt> calling context of unknown priority must be assumed. Also, stack space is provided only to call <tt>exec.library</tt> and <tt>utility.library</tt> functions. The callback shall not place excessive data on the stack. Stack space should be considered limited.

I propose a command with the following semantics:

<pre>
NAME
S2_DISCONNECT -- Go offline and close a link layer connection
previously established with S2_CONNECT.

FUNCTION
This command complements the S2_CONNECT command in that it
reverses the steps taken to establish a link layer connection.

IO REQUEST
ios2_Command - S2_DISCONNECT
ios2_Data - Pointer to Sana2Connection structure
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number

NOTES
If successful, this command implies S2_OFFLINE, i.e. the
link layer is deallocated.

The driver must ignore the S2_DISCONNECT command and
recover gracefully if the S2_CONNECT was never sent or
returned with an error.

The contents of the Sana2Connection structure are valid only
until the device driver has processed the command and returned
the IOSana2Req. Any data the driver may need to retain beyond
that point of time must be copied.

Once the S2_DISCONNECT command has returned, it is safe to dispose
of the Sana2Connection structure provided at S2_CONNECT time.

Note that S2_OFFLINE does not necessarily imply S2_DISCONNECT, if
the S2_DISCONNECT command is listed as supported by the driver via
NSCMD_DEVICEQUERY. If S2_DISCONNECT is not listed as supported,
S2_OFFLINE obviously implies disconnect functionality.

S2_CONNECT/S2_DISCONNECT do not nest.

SEE ALSO
S2_CONNECT
</pre>

I propose that the following command number should be assigned:

<tt>#define S2_DISCONNECT 0xC006</tt>

=== S2_SAMPLE_THROUGHPUT ===

The SANA-II standard already allows for statistics to be returned on the amount of data that has passed through a driver. Unfortunately, that information is not very accurate in that no information is provided on the time span in which the data was accumulated. Such information would be helpful in trying to determine as accurately as possible how large the data throughput actually is. I therefore propose a new command which can be used to obtain that information, which uses the following data structure:

<syntaxhighlight lang="C" line>
struct Sana2ThroughputStats
{
ULONG s2ts_Length;
ULONG s2ts_Actual;

struct Task * s2ts_NotifyTask;
ULONG s2ts_NotifyMask;

struct timeval s2ts_StartTime;
struct timeval s2ts_EndTime;
S2QUAD s2ts_BytesSent;
S2QUAD s2ts_BytesReceived;
S2QUAD s2ts_Updates;
};
</syntaxhighlight>

Before I proceed to explain what purposes the individual members serve, a few words on the <tt>S2QUAD</tt> type, which is defined as follows:

<tt>typedef struct { ULONG s2q_High; ULONG s2q_Low; } S2QUAD;</tt>

In other words, the <tt>S2QUAD</tt> type stands for an unsigned 64 bit big endian integer, as expressed in ISO 'C' terms.

The structure members have the following purposes:

<tt>s2ts_Length</tt>

This is the size of the data structure to be filled in and should be initialized by the caller to <tt>sizeof(struct Sana2ThroughputStats)</tt>. Smaller values are permitted, but these must not be smaller than 8 (which covers the <tt>s2ts_Length</tt> and <tt>s2ts_Actual</tt> members). A driver which finds an <tt>s2ts_Length</tt> < 8 must treat this as an error and reject the command with <tt>ios2_Req.io_Error</tt>=<tt>IOERR_BADLENGTH</tt>.

<tt>s2ts_Actual</tt>

The size of the data structure filled with information. This member is initialized by the driver and must be <= <tt>s2ts_Length</tt>.

<tt>s2ts_NotifyTask</tt>

The <tt>Task</tt> to notify whenever the contents of this data structure change. This must be <tt>NULL</tt> if no notification is desired.

'''Note:''' This feature should be used carefully, as so much data may arrive that the driver will almost be constantly signalling this <tt>Task</tt> that a change has taken place.

It is recommend that periodic polling be used, such as to update displays of a link monitoring program.

<tt>s2ts_NotifyMask</tt>

The signal mask to use for notifying the <tt>Task</tt> whose address is found in <tt>s2ts_NotifyTask</tt> (via <tt>Signal(s2ts->s2ts_NotifyTask,s2ts->s2ts_NotifyMask);</tt>). This must be zero if no notification is desired.

<tt>s2ts_StartTime</tt>

The time when the driver started to fill in this data structure.

<tt>s2ts_EndTime</tt>

The time when the driver last updated the contents of this data structure.

<tt>s2ts_BytesSent</tt>

Total number of bytes sent since the driver started to fill in this data structure. This is a 64 bit integer.

<tt>s2ts_BytesReceived</tt>

Total number of bytes received since the driver started to fill in this data structure. This is a 64 bit integer.

<tt>s2ts_Updates</tt>

Number of times the driver has updated this data structure. This value will increase with every change. This is a 64 bit integer.

A driver implementing this command should take care to update the members <tt>s2ts_EndTime</tt>, <tt>s2ts_BytesSent</tt>, <tt>s2ts_BytesReceived</tt> and <tt>s2ts_Updates</tt> atomically each time changes are made.

I propose a command with the following semantics:

<pre>
NAME
S2_SAMPLE_THROUGHPUT -- Obtain accurate information on
driver data throughput.

FUNCTION
This command installs a data structure which is updated every time
data is sent or received by the driver.

This command must be sent via SendIO() or BeginIO(); until
the associated I/O request is recalled using AbortIO(), the
device unit will continue to update the Sana2ThroughputStats
structure in real time.

IO REQUEST
ios2_Command - S2_SAMPLE_THROUGHPUT
ios2_StatData - Pointer to Sana2ThroughputStats structure
to fill in
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise

NOTES
If this device driver does not understand this command,
it will immediately return the IOSana2Req with
ios2_Req.io_Error set to IOERR_NOCMD. Otherwise, the request will
remain queued until it is removed with AbortIO() later.
</pre>

I propose that the following command number should be assigned:

<tt>#define S2_SAMPLE_THROUGHPUT 0xC007</tt>

== Annotations for existing commands ==

=== S2_ONLINE and S2_OFFLINE ===

This proposal introduces two new commands (<tt>S2_CONNECT</tt> and <tt>S2_DISCONNECT</tt>) which are somewhat related to the <tt>S2_ONLINE</tt> and <tt>S2_OFFLINE</tt> commands. How this relation works out shall be explained below. Note that the following text assumes that both the <tt>S2_CONNECT</tt>/<tt>S2_DISCONNECT</tt> and <tt>S2_ONLINE</tt>/<tt>S2_OFFLINE</tt> command pairs are implemented.

<tt>S2_CONNECT</tt> implies <tt>S2_ONLINE</tt> and, if successful, may report <tt>S2EVENT_ONLINE</tt> and <tt>S2EVENT_CONNECT</tt> events. If the unit is currently disconnected, but still online, only the <tt>S2EVENT_CONNECT</tt> event shall be sent. Invoking the <tt>S2_CONNECT</tt> command on a driver which is already connected must be rejected with <tt>ios2_Req.io_Error=S2ERR_BAD_STATE</tt> and <tt>ios2_WireError=S2WERR_UNIT_CONNECTED</tt>.

<tt>S2_DISCONNECT</tt> implies <tt>S2_OFFLINE</tt> and, if successful, may report <tt>S2EVENT_OFFLINE</tt> and <tt>S2EVENT_DISCONNECT</tt> events. If the unit is curently connected and offline, then only the <tt>S2EVENT_DISCONNECT</tt> event shall be sent. Invoking the <tt>S2_DISCONNECT</tt> command on a driver which is already disconnected must be rejected with <tt>ios2_Req.io_Error=S2ERR_BAD_STATE</tt> and <tt>ios2_WireError=S2WERR_UNIT_DISCONNECTED</tt>.

<tt>S2_OFFLINE</tt> may be used after the <tt>S2_CONNECT</tt> has successfully connected the unit. In this case the driver will release control over the link layer and report the <tt>S2EVENT_OFFLINE</tt> event. The connection established using the <tt>S2_CONNECT</tt> will, however, persist.

<tt>S2_ONLINE</tt> may be used after <tt>S2_CONNECT</tt> has successfully connected the unit and the <tt>S2_OFFLINE</tt> was used. In this case the driver will again try to obtain control over the link layer and report the <tt>S2EVENT_ONLINE</tt> event if successful.

If the <tt>S2_CONNECT</tt> command was never successfully executed, then the commands <tt>S2_ONLINE</tt> and <tt>S2_OFFLINE</tt> must be rejected with <tt>ios2_Req.io_Error=S2ERR_BAD_STATE</tt> and <tt>ios2_WireError=S2WERR_UNIT_DISCONNECTED</tt>.

== Extensions for existing commands ==

=== S2_DEVICEQUERY ===

The <tt>Sana2DeviceQuery</tt> structure filled in by the <tt>S2_DEVICEQUERY</tt> command provides for information on the device's properties, including the maximum transmission unit (MTU) that may be used. What is not specifically covered is the 'raw' MTU a device may offer. In this context 'raw' means the number of bytes that are available for reading and writing when using the <tt>SANA2IOB_RAW</tt> flag with a <tt>CMD_READ</tt>/<tt>CMD_WRITE</tt> request on a device that supports these access methods. Currently, software developers can only make assumptions on how many bytes might comprise the 'raw' MTU by checking the <tt>Sana2DeviceQuery.HardwareType</tt> member and hoping that the driver supports raw <tt>CMD_READ</tt>/<tt>CMD_WRITE</tt> access.

I propose that the <tt>S2_DEVICEQUERY</tt> command and the associated <tt>Sana2DeviceQuery</tt> structure are extended to allow for the raw MTU to be queried. The new <tt>Sana2DeviceQuery</tt> structure would look like this:

<syntaxhighlight lang="C" line>
struct Sana2DeviceQuery
{
/*
** Standard information
*/
ULONG SizeAvailable; /* bytes available */
ULONG SizeSupplied; /* bytes supplied */
LONG DevQueryFormat; /* this is type 0 */
LONG DeviceLevel; /* this document is level 0 */

/*
** Common information
*/
UWORD AddrFieldSize; /* address size in bits */
ULONG MTU; /* maximum packet data size */
LONG bps; /* line rate (bits/sec) */
LONG HardwareType; /* what the wire is */
ULONG RawMTU; /* maximum raw packet data size */

/*
** Format specific information
*/
};
</syntaxhighlight>

The <tt>RawMTU</tt> member is new. Devices which do not know and support this structure member may fill in the <tt>Sana2DeviceQuery</tt> structure only up to and including the <tt>HardwareType</tt> member.

Devices which know and support the <tt>RawMTU</tt> member must fill it with a well-defined value. For Amiga Ethernet drivers, that value would be 1514, which is the standard MTU value of 1500 bytes plus the size of the Ethernet frame header, as per RFC894 (six bytes for the destination address, six bytes for the source address and two bytes for the frame type; the eight byte preamble and the terminating four byte CRC value are typically not under the control of the driver). Drivers which do not support raw read or write access must set the <tt>RawMTU</tt> member to zero.

If the <tt>RawMTU</tt> member is not provided, all bets are off and the application software must fall back to making estimates based upon the hardware type and the raw frame types it wishes to read and write. Ultimatively, the driver itself must decide whether it can accept raw read and write commands (or has to reject them with <tt>S2ERR_NOT_SUPPORTED</tt>) and whether the raw packet size is still covered by the underlying hardware MTU (or must be rejected with <tt>S2ERR_MTU_EXCEEDED</tt>).

A word of warning: a little testing with various Ethernet hardware drivers has revealed that the A2065 driver <tt>a2065.device</tt> does not handle the <tt>S2_DEVICEQUERY</tt> command properly if the <tt>Sana2DeviceQuery</tt> structure provided is larger than 30 bytes. In other words, the command will fail if the proposed <tt>RawMTU</tt> member is present in the query data structure to be filled in.

== New events ==

=== S2EVENT_CONFIGCHANGED ===

The SANA-II standard does not cover protocols or devices which can change their properties during operation, such as the hardware address of the underlying driver. For drivers such as those which implement the proposed <tt>S2_GETPEERADDRESS</tt> and <tt>S2_GETDNSADDRESS</tt> commands it is vital that such changes can take place and be noticed by the client software. For this purpose I propose that a new event type is introduced, to be used with the SANA-II <tt>S2_ONEVENT</tt> command, using the following definition:

<tt>#define S2EVENT_CONFIGCHANGED (1L<<8)</tt>

This event should be triggered whenever client-visible configuration information changes, as can be queried via the <tt>S2_DEVICEQUERY</tt>, <tt>S2_GETSTATIONADDRESS</tt>, <tt>S2_GETSPECIALSTATS</tt>, <tt>S2_GETGLOBALSTATS</tt>, <tt>S2_GETPEERADDRESS</tt> and <tt>S2_GETDNSADDRESS</tt> commands. Here is a short list of what could change:

<tt>S2_DEVICEQUERY</tt>

<tt>AddrFieldSize</tt>, <tt>MTU</tt>, <tt>BPS</tt>

<tt>S2_GETSTATIONADDRESS</tt>

<tt>ios2_SrcAddr</tt>

<tt>S2_GETGLOBALSTATS</tt>

<tt>Reconfigurations</tt>, <tt>LastStart</tt>

<tt>S2_GETPEERADDRESS</tt>

<tt>ios2_SrcAddr</tt>, <tt>ios2_DstAddr</tt>

<tt>S2_GETDNSADDRESS</tt>

<tt>ios2_SrcAddr</tt>, <tt>ios2_DstAddr</tt>

The purpose of this event '''is not''' to post a notification whenever another byte or event counter has changed so that a monitoring program may update its display. The purpose '''is''' to convey to the client software that an important device configuration option has changed and that it is supposed to react and adapt to it. For example, a TCP/IP stack may, upon learning that a device's IP address has changed, rebuild its routing table.

Since the <tt>S2EVENT_CONFIGCHANGED</tt> event may arrive at any time and does not indicate what exactly has changed, application software should query the information it expects to change during its life time, and keep a copy of it around for later reference. When the <tt>S2EVENT_CONFIGCHANGED</tt> event arrives, it can compare the contents of the copy against the current state of affairs and act according to the differences it finds.

=== S2EVENT_CONNECT ===

This event is a counterpart to <tt>S2EVENT_ONLINE</tt>, and is associated with the <tt>S2_CONNECT</tt> command. I propose the following semantics:

<tt>#define S2EVENT_CONNECT (1L<<9) /* Driver has opened session */</tt>

The event is to be sent when the driver has successfully established a link layer connection.

=== S2EVENT_DISCONNECT ===

This event is a counterpart to <tt>S2EVENT_OFFLINE</tt>, and is associated with the <tt>S2_DISCONNECT</tt> command. I propose the following semantics:

<tt>#define S2EVENT_DISCONNECT (1L<<10) /* Driver has closed session */</tt>

The event is to be sent when the driver has closed the link layer connection previously established by the <tt>S2_CONNECT</tt> command.

== New wire error codes ==

=== S2WERR_UNIT_DISCONNECTED ===

This error code is a counterpart to <tt>S2WERR_UNIT_OFFLINE</tt>. It indicates that the associated command could not be executed because the link layer is not connected.

I propose the following semantics:

<tt>#define S2WERR_UNIT_DISCONNECTED 19 /* unit is currently not connected */</tt>

=== S2WERR_UNIT_CONNECTED ===

This error code is a counterpart to <tt>S2WERR_UNIT_ONLINE</tt>. It indicates that the associated command could not be executed because the link layer is already connected.

I propose the following semantics:

<tt>#define S2WERR_UNIT_CONNECTED 20 /* unit is currently connected */</tt>

=== S2WERR_INVALID_OPTION ===

This error code indicates that an option, such as passed by the <tt>S2_CONNECT</tt> command, is not acceptable. The option's value may be out of range or may not match the syntax specifications. To indicate which option that may be, a different mechanism '''must''' be used; a simple indication that something was wrong is '''not sufficient'''.

I propose the following semantics:

<tt>#define S2WERR_INVALID_OPTION 21 /* invalid option rejected */</tt>

=== S2WERR_MISSING_OPTION ===

This error code indicates that a mandatory option, such as passed by the <tt>S2_CONNECT</tt> command, is not present. To indicate which option that may be, a different mechanism '''must''' be used; a simple indication that something was wrong is '''not sufficient'''.

I propose the following semantics:

<tt>#define S2WERR_MISSING_OPTION 22 /* a mandatory option is missing */</tt>

=== S2WERR_AUTHENTICATION_FAILED ===

Some drivers run protocols that require them to authenticate to a server. That process may fail. This wire error code is to indicate this fact.

I propose the following semantics:

<tt>#define S2WERR_AUTHENTICATION_FAILED 23 /* could not log in */</tt>

== Callbacks ==

=== S2_DMACopyToBuff64 and S2_DMACopyFromBuff64 ===

These two callbacks are identical in operation to the <tt>S2_DMACopyToBuff32</tt> and <tt>S2_DMACopyFromBuff32</tt> callbacks, as specified in the SANA-IIR3 standard. The difference is in that the memory region DMA is to take place in must be aligned to a 64 bit boundary and must be large enough to hold data that is a multiple of 64 bits in size. The purpose of these hooks is to allow for 64 bit aligned PCI DMA accesses to take place.

I propose that the following numbers should be assigned:

<tt>#define S2_DMACopyToBuff64 (S2_Dummy + 10)</tt>

#define S2_DMACopyFromBuff64 (S2_Dummy + 11)

=== S2_Log ===

A driver may want to report an important event for the user to see. Adding a log message to a file or opening a window to display a message in may not be the optimum approach as the user may be unaware of the context into which the message belongs. It may be advisable for the driver to use the message reporting and logging facilities used by the client software that uses its services, such as a TCP/IP stack. The <tt>S2_Log</tt> callback hook is intended to provide for such a link. If present, the driver must use this callback hook rather than whatever logging methods it implements itself. Note that unlike the other SANA-II callbacks, this is a regular hook, as to be invoked using <tt>utility.library</tt>/<tt>CallHookPkt()</tt>. The hook function is invoked using the following parameters:

<pre>
log_hook_function(hook,reserved,message)

void log_hook_function(struct hook * hook,APTR reserved,
struct S2LogMessage * message);
</pre>

The <tt>reserved</tt> parameter '''must''' be set to <tt>NULL</tt>. The <tt>S2LogMessage</tt> structure passed as the third parameter looks like this:

<syntaxhighlight lang="C" line>
struct S2LogMessage
{
LONG s2lm_Size;
ULONG s2lm_Priority;
STRPTR s2lm_Name;
STRPTR s2lm_Message;
};
</syntaxhighlight>

The individual structure members serve the following functions:

<tt>s2lm_Size</tt>

Size of the <tt>S2LogMessage</tt> structure, in bytes. The idea is to extend this data structure in the future, and the size stored in here tells you how long the structure is. The size '''must''' always be >= 16.

<tt>s2lm_Priority</tt>

The smaller this value, the more important the message to be logged or displayed. The following priority levels are defined (similar to the Unix <tt>syslog()</tt> mechanism):

<tt>#define S2LOG_Emergency 0</tt>

A panic condition.

<tt>#define S2LOG_Alert 1</tt>

A condition that should be corrected immediately.

<tt>#define S2LOG_Critical 2</tt>

Critical conditions.

<tt>#define S2LOG_Error 3</tt>

A plain error.

<tt>#define S2LOG_Warning 4</tt>

A warning message.

<tt>#define S2LOG_Notice 5</tt>

Conditions that are not error conditions, but should possibly be handled specially.

<tt>#define S2LOG_Information 6</tt>

An informational message.

<tt>#define S2LOG_Debug 7</tt>

Messages that contain information normally of use only when debugging.

<tt>s2lm_Name</tt>

Pointer to a <tt>NUL</tt>-terminated string which identifies the source of this message. This can be <tt>NULL</tt> in which case the name is treated as being unknown.

<tt>s2lm_Message</tt>

Pointer to a <tt>NUL</tt>-terminated string which contains the log message. The text should not contain any formatting characters such as line feeds or carriage returns. The <tt>s2lm_Message</tt> member '''must never''' be <tt>NULL</tt>.

All error messages issued by the device driver should use the current system locale wherever this is possible. The purpose of an error message is, after all, to assist the user in recovering from the error. Which may be difficult if the user does not even know the language in which the message is written.

The log message string is valid until the log hook function returns. If the driver needs to retain the message any longer, it must make a copy of it.

Since the client software into which the log hook calls may have to allocate memory to hold and display the log message, the log hook '''must not''' be called from interrupt code. The log hook shall not <tt>Wait()</tt> and it shall assume only a <tt>Task</tt> calling context of unknown priority. <tt>dos.library</tt> functions may not be called. Also, stack space is provided only to call <tt>exec.library</tt> and <tt>utility.library</tt> functions. The callback shall not place excessive data on the stack. Stack space should be considered limited and the callback should be designed to be fast and short.

This hook is installed at <tt>OpenDevice()</tt> time, which means that the hook is used for the unit that was opened, and not just for the I/O request it was opened with. The hook must remain installed until the I/O request that installed it is eventually used to close the device. When this happens, the device should fall back to use no log hook at all. No nesting is permitted or required.

I propose that the following number should be assigned:

<tt>#define S2_Log (S2_Dummy + 12)</tt>

== Proposed driver requirements ==

This is an attempt to clarify part of the specification and to lay down a few rules that every SANA-II driver should follow in addition to the requirements described in the existing specifications. Here is what I propose:

<ul>
<li>A driver that does not use a broadcast medium, such as Ethernet, must not implement the <tt>S2_BROADCAST</tt> command. Likewise, if no multicast mechanism is supported, the <tt>S2_MULTICAST</tt> must not be implemented either.</li>
<li>SANA-II standard commands which the driver does not implement must be rejected with the <tt>IOERR_NOCMD</tt> error code. Commands that are implemented, but which cannot perform the requested services, must be rejected with the <tt>S2ERR_NOT_SUPPORTED</tt> error code. The difference between the two cases is in when the decision is made whether a command can be handled or not. Which commands should return <tt>IOERR_NOCMD</tt> is decided upon at the time the driver is designed and implemented. At this stage the implementor knows for sure which capabilities the driver will have and which it will not have. Commands which the driver will never be able to execute will be made to return the <tt>IOERR_NOCMD</tt> error code. If the decision whether a command can be executed is made only at run time, by evaluating the conditions under which a command can be executed, then the error code <tt>S2ERR_NOT_SUPPORTED</tt> should be returned in case of failure.</li>
<li>It must be possible to open the driver with a plain <tt>struct IOStdReq</tt>. This is necessary for the NewStyleDevices query command to work. In the command dispatcher, the driver must verify that all SANA-II commands are invoked with a proper size <tt>struct IOSana2Req</tt> I/O request. If the I/O request is shorter (as can be verified by looking at the embedded Message's <tt>mn_Length</tt> member), the command must be rejected with <tt>ios2_Req.io_Error=IOERR_BADLENGTH</tt>.</li>
<li>A driver must implement the NewStyleDevices <tt>NSCMD_DEVICEQUERY</tt> command, in conformance with the NSD specification 1.6 or newer. The motivation for this is to have a mechanism available for probing the capabilities of the driver, and the supported command set can provide for vital clues. In this context, the absence of the <tt>S2_BROADCAST</tt> command would suggest that the driver cannot send or receive broadcast messages.</li>
<li>A driver that does not allow its station address to be set with the <tt>S2_CONFIGINTERFACE</tt> command may silently ignore the command (returning it without setting an error condition) and even pretend that it can be configured more than once.</li>
<li>In response to the <tt>S2_DEVICEQUERY</tt>, <tt>S2_GETSPECIALSTATS</tt> and <tt>S2_GETGLOBALSTATS</tt> commands a driver may return information that is not entirely correct if it has to go online before it can provide for the correct data. For example, the maximum transmission unit for PPP is a number in the range of [1..1500] which is negotiated during the protocol configuration process. It is unlikely that numbers greater than 1500 will be used, yet it is still not impossible. Since the actual number will be known only after the driver has configured the protocol, the MTU value returned before the session was opened can differ from the MTU value valid after it has been opened. A driver should therefore attempt to return 'safe' defaults in place of information that is unavailable at the time it is queried. The 'safe' values shall be set up to allow the driver to work even if the protocol stack is not aware of later changes to those values. Beware of zero-length buffer sizes or time intervals that may cause client software to perform zero-length memory allocations or divisions by zero.</li>
<li>SANA-II assigns packet type numbers according to the underlying transport media. For example, Ethernet uses packet type 2048 for IP frames. No such packet type definition exists for PPP yet, which is why I propose to assign packet type 31 for IP packets transmitted via PPP.
To simplify client software configuration, drivers may treat packet type 2048 as equivalent to the packet number associated with IP frames. This association is permitted only if it does not introduce ambiguity. For example, this association would not be permitted if the driver would receive and transmit IP packets in two different frame types or if the driver already associates packet type 2048 with non-IP packets.</li></ul>

== Unsolved problems ==

* Protocols like PPP can provide both for IPv4 and IPv6 addresses that should be used by the local client, the peer or any of the domain name servers. While the two addressing families are interoperable, there is a problem in how the driver should report them. Can you assume 128 bit addresses and encapsulate 32 bit addresses in them? If so, how do you make sure that the address format is unambiguous?
* Currently, only the device's hardware type provides a clue as to what packet type responds to which protocol transported via the link. For Ethernet, IP packets are encapsulated in type 2048 frames, PPP encapsulates IP packets in type 31 frames, Arcnet can use type 240 or 212. Matching a protocol with a frame type is not an easy process which could be handled more elegantly.
* How to extend the <tt>Sana2DeviceQuery</tt> structure in the future? The current layout separates standard, common and format specific information, but there is no hint as to where which each section starts and where the next begins. Now that there is a proposal to add a new field to the common section, how would you add fields to the format specific section?

== Changes ==

Changes since 02-May-2012:

* Converted to MediaWiki format.

Changes since 24-Dec-2002:

* The <tt>Sana2Connection</tt> data structure used by the <tt>S2_CONNECT</tt> command now must remain valid until the <tt>S2_DISCONNECT</tt> command is sent (see [[#2.4|section 2.4]]).

Changes since 01-May-2002:

* Added the <tt>ppp.async.readrequests</tt> and <tt>ppp.async.eof</tt> configuration keywords.

Changes since 04-Jan-2002:

* Added the <tt>ppp.dummyremoteaddress</tt> and <tt>ppp.ethernet.ac</tt> configuration keywords.

Changes since 10-Dec-2001:

* Converted to HTML format.
* Added the <tt><devices/sana2.h></tt> header file to the appendix.
* The memory alignment for the <tt>S2_DMACopyToBuff64</tt> and <tt>S2_DMACopyFromBuff64</tt> hooks refers to bits and not to bytes.

Changes since 19-Nov-2001:

* Added to the list of reserved configuration keywords (<tt>ppp.idletimeout</tt>, <tt>ppp.peeridletimeout</tt>, <tt>ppp.sendid</tt>).
* Renamed the fields of the <tt>Sana2ExtDeviceStats</tt> structure.
* Clarified that the <tt>S2QUAD</tt> type is a big endian integer.
* More clarifications for the <tt>S2_CONNECT</tt>/<tt>S2_DISCONNECT</tt> and <tt>S2_ONLINE</tt>/<tt>S2_OFFLINE</tt> commands.
* Updated the discussion of the <tt>Sana2DeviceQuery.RawMTU</tt> field, clarifying what is included in the the Ethernet <tt>RawMTU</tt>.
* Updated the <tt><devices/sana2.h></tt> header file. Note that there is no equivalent <tt>"devices/sana2.i"</tt> header file yet.

Changes since 12-Nov-2001:

* Changed the command numbers of <tt>S2_GETPEERADDRESS</tt>, <tt>S2_GETDNSADDRESS</tt>, <tt>S2_GETEXTENDEDGLOBALSTATS</tt>, <tt>S2_CONNECT</tt>, <tt>S2_DISCONNECT</tt> and <tt>S2_SAMPLE_THROUGHPUT</tt> to be NSD-compliant. Also assigned a new number to the <tt>S2_SAMPLE_THROUGHPUT </tt> command.
* Added section 4 ("Extensions for existing commands").
* Added the last paragraph to section 9, relating to the future extension of the <tt>Sana2DeviceQuery</tt> structure.

Changes since 03-Nov-2001:

* Renamed <tt>S2_GETNEWGLOBALSTATS</tt> to <tt>S2_GETEXTENDEDGLOBALSTATS</tt> (see [[#2.3|section 2.3]]).
* The <tt>S2_GETEXTENDEDGLOBALSTATS</tt> now uses 64 bit quantities for the <tt>s2xds_PacketsReceived</tt>, <tt>s2xds_PacketsSent</tt>, <tt>s2xds_BadData</tt>, <tt>s2xds_Overruns</tt>, <tt>s2xds_UnknownTypesReceived</tt> and <tt>s2xds_Reconfigurations</tt> counters.
* In section 2.6 the <tt>S2_SAMPLE_THROUGHPUT</tt> command was modified to use 64 bit integers for all members of the <tt>Sana2ThroughputStats</tt> structure.
* All proposed commands are now listed with their numeric IDs.
* The command autodocs specifically mention the <tt>ios2_BufferManagement</tt> field.
* All references to <tt>ios2_Error</tt> have been replaced with <tt>ios2_Req.io_Error</tt>.
* In section 7 the use of the <tt>IOERR_NOCMD</tt>/<tt>S2ERR_NOT_SUPPORTED</tt> error codes is clarified.
* Section 7 takes a more detailed look at safe default values returned by the query commands.
* Inserted section 3 ("Annotations for existing commands").
* The <tt>S2_CONNECT</tt> and <tt>S2_DISCONNECT</tt> commands now specifically mention the life time of the data they have to deal with.

Changes since 14-Oct-2001:

* Added <tt>S2_CONNECT</tt> and <tt>S2_DISCONNECT</tt> commands.
* Added <tt>S2EVENT_CONNECT</tt> and <tt>S2EVENT_DISCONNECT</tt> events.
* Added section 4 ("New wire error codes").
* In section 5.2 the originally proposed log callback function has been wrapped into a standard Hook structure.
* Removed item on <tt>S2_CONNECT</tt>/<tt>S2_DISCONNECT</tt> from section 7 ("Unsolved problems").
* Added section 8 ("Changes").

Classic Graphics Primitives

2025-01-26T19:27:24Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

== Graphics Primitives ==

This section defines the display routines for use on Classic Amiga hardware. These routines show you how to form and manipulate a display, including the following aspects of display use:

* How to query the graphics system to find out what type of video monitor is attached and which graphics modes can be displayed on it.
* How to identify the memory area that you wish to have displayed.
* How to position the display area window to show only a certain portion of a larger drawing area.
* How to split the screen into as many vertically stacked slices as you wish.
* How to determine which horizontal and vertical resolution modes to use.
* How to determine the current correct number of pixels across and lines down for a particular section of the display.
* How to specify how many color choices per pixel are to be available in a specific section of the display.

== Components of a Display ==

In producing a display, you are concerned with two primary components: sprites and the playfield. Sprites are the easily movable parts of the display. The playfield is the static part of the display and forms a backdrop against which the sprites can move and with which the sprites can interact.

This article covers the creation of the background. Sprites are described in [[Graphics Sprites, Bobs and Animation]].

=== Introduction to Raster Displays ===

There are three major television standards in common use around the world: NTSC, PAL, and SECAM. NTSC is used primarily in the United States and Japan; PAL and SECAM are used primarily in Europe. The Amiga currently supports both NTSC and PAL. The major differences between the two systems are refresh frequency and the number of scan lines produced. Where necessary, the differences will be described and any special considerations will be mentioned.

The Amiga produces its video displays on standard television or video monitors by using raster display techniques. The picture you see on the video display screen is made up of a series of horizontal video lines stacked one on top of another, as illustrated in the following figure. Each line represents one sweep of an electronic video beam, which “paints” the picture as it moves along. The beam sweeps from left to right, producing the full screen one line at a time. After producing the full screen, the beam returns to the top of the display screen.

[[File:LibFig27-1.png|frame|center|How the Video Display Picture Is Produced]]

The diagonal lines in the figure show how the video beam returns to the start of each horizontal line.

==== Effect of Display Overscan on the Viewing Area ====

To assure that the picture entirely fills the monitor (or television) screen, the manufacturer of the video display device usually creates a deliberate ''overscan''. That is, the video beam is swept across an area that is larger than the viewable region of the monitor.

The video beam actually covers 262 vertical lines (312 for PAL). The user, however, sees only the portion of the picture that is within the center region of the display, typically surrounded by a border as illustrated in the figure below. The center region is nominally about 200 lines high on an NTSC machine (256 lines for PAL). Overscan also limits the amount of video data that can appear on each display line. The width of the center region is nominally, about 320 pixels for both PAL and NTSC.

[[File:LibFig27-2.png|frame|center|Display Overscan Restricts Usable Picture Area]]

The flexibility of the Amiga graphics subsystem allows the overscan region, which normally forms the border of the display, to be used for application graphics instead. So the nominal dimensions given above can be enlarged.

The time during which the video beam is below the bottom line of the viewable region and above the first line is called the ''vertical blanking interval''. The recommended minimum to allow for this interval is 21 lines for NTSC (29 lines for PAL). So, for applications that take full advantage of the overscan area, a maximum of 241 usable lines in NTSC (283 in PAL) can be achieved. The display resolution can also be changed by changing the Amiga display mode as discussed in the sections below.

==== Color Information for the Video Lines ====

The hardware reads the system display memory to obtain the color information for each line. As the video display beam sweeps across the screen producing the display line, it changes color, producing the images you have defined. On the current generation of Amiga hardware, there are 4,096 possible colors.

=== Interlaced and Non-Interlaced Modes ===

In producing the complete display (262 lines in NTSC, 312 in PAL), the video display device produces the top line, then the next lower line, then the next, until it reaches the bottom of the screen. When it reaches the bottom, it returns to the top to start a new scan of the screen. Each complete set of lines is called a ''display field''. It takes about 1/60th of a second to produce a complete NTSC display field (1/50th of a second for PAL).

The Amiga has two vertical display modes: ''interlaced'' and ''non-interlaced''. In non-interlaced mode, the video display produces the same picture for each successive display field. A non-interlaced NTSC display normally has about 200 lines in the viewable area (up to a maximum of 241 lines with overscan) while a PAL display will normally show 256 lines (up to a maximum of 283 with overscan).

With interlaced mode, the amount of information in the viewable area can be doubled. On an NTSC display this amounts to 400 lines (482 with overscan), while on a PAL display it amounts to 512 lines (566 with overscan).

For interlaced mode, the video beam scans the screen at the same rate (1/60th of a second per complete NTSC video display field); however, it takes two display fields to form a complete video display picture and twice as much display memory to store line data. During the first of each pair of display fields, the system hardware shows the odd-numbered lines of an interlaced display (1, 3, 5, and so on). During the second display field, it shows the even-numbered lines (2, 4, 6 and so on). The second field is positioned slightly lower so that the lines in the second field are “interlaced” with those of the first field, giving the higher vertical resolution of this mode.

Interlaced Mode – Display Fields and Data in Memory

<table>
<tr class="odd">
<td align="left">'''Data as Displayed'''</td>
<td align="left">'''Data In Memory'''</td>
</tr>
<tr class="even">
<td align="left">Odd field - Line 1</td>
<td align="left">Line 1</td>
</tr>
<tr class="odd">
<td align="left">Even field - Line 1</td>
<td align="left">Line 2</td>
</tr>
<tr class="even">
<td align="left">Odd field - Line 2</td>
<td align="left">Line 3</td>
</tr>
<tr class="odd">
<td align="left">Even field - Line 2</td>
<td align="left">Line 4</td>
</tr>
<tr class="even">
<td align="left">. . .</td>
<td align="left">. . .</td>
</tr>
<tr class="odd">
<td align="left">Odd field - Line 200</td>
<td align="left">Line 399</td>
</tr>
<tr class="even">
<td align="left">Even field - Line 200</td>
<td align="left">Line 400</td>
</tr>
</table>

The following figure shows a display formed as display lines 1, 2, 3, 4, ... 400. The 400-line interlaced display uses the same physical display area as a 200-line non-interlaced display.

[[File:LibFig27-4.png|frame|center|Interlaced Mode Doubles Vertical Resolution]]

During an interlaced display, it appears that both display fields are present on the screen at the same time and form one complete picture. However, interlaced displays will appear to flicker if adjacent (odd and even) scan lines have contrasting brightness. Choosing appropriate colors for your display will reduce this flicker considerably. This phenomenon can also be reduced by using a long-persistence monitor, or alleviated completely with a hardware de-interlacer.

=== Low, High and Super-High Resolution Modes ===

The Amiga also has three horizontal display modes: low-resolution (or ''Lores''), high-resolution (''Hires'') and super-high-resolution (''SuperHires'').

Normally, these three horizontal display modes have a width of 320 for Lores, 640 for Hires or 1,280 for SuperHires on both PAL and NTSC machines. However, by taking full advantage of the overscan region, it is possible to create dispays up to 362 pixels wide in Lores mode, 724 pixels wide in Hires or 1,448 pixels wide in SuperHires. Usually, however, you should use the standard values (320, 640 or 1,280) for most applications.

In general, the number of colors available in each display mode decreases as the resolution increases. The Amiga has two special display modes that can be used to increase the number of colors available. HAM is ''Hold-And-Modify'' mode, EHB is ''Extra-Half-Brite'' mode.

Hold-And-Modify (HAM) allows you to display the entire palette of 4,096 colors on-screen at once with certain restrictions, explained later.

Extra-Half-Brite allows for 64 colors on-screen at once; 32 colors plus 32 additional colors that are half the intensity of the first 32. For example, if color 1 is defined as 0xFFF (white), then color 33 is 0x777 (grey).

==== Display Modes, Colors, and Requirements ====

The following chart lists all of the display modes that are available.

{| class="wikitable"
! 15 kHz Amiga Display Modes
! NTSC
! PAL
! Maximum Colors
! Supports HAM/EHB
|-
| Lores || 320x200 || 320x256 || 32 of 4,096 || Yes
|-
| Lores-Interlaced || 320x400 || 320x512 || 32 of 4,096 || Yes
|-
| Hires || 640x200 || 640x256 || 16 of 4,096 || No
|-
| Hires-Interlaced || 640x400 || 640x512 || 16 of 4,096 || No
|-
| SuperHires* || 1,280x200 || 1,280x256 || 4 out of 64 || No
|-
| SuperHires-Interlaced* || 1,280x400 || 1,280x512 || 4 out of 4,096 || No
|}

<nowiki>*</nowiki> Requires ECS

{| class="wikitable"
! 31 kHz Amiga Display Modes*
! Default Resolution
! Maximum Colors
! Supports HAM/EHB
|-
| VGA-ExtraLores
| 160x480
| 32 out of 4,096
| Yes
|-
| VGA-ExtraLores-Interlace
| 160x960
| 32 out of 4,096
| Yes
|-
| VGA-Lores
| 320x480
| 16 out of 4,096
| No
|-
| VGA-Lores-Interlace
| 320x960
| 16 out of 4,096
| No
|-
| Productivity
| 640x480
| 4 out of 64
| No
|-
| Productivity-Interlace
| 640x960
| 4 out of 64
| No
|}

<nowiki>*</nowiki> 31 kHz modes require ECS and either a bi-scan or multi-scan monitor

{| class="wikitable"
! A2024* Display Modes
! NTSC
! PAL
! Maximum Colors
|-
| A2024-10Hz || 1,008x800 || 1,008x1,024 || 4 out of 4 grey levels
|-
| A2024-15Hz || 1,008x800 || 1,008x1,024 || 4 out of 4 grey levels
|}

<nowiki>*</nowiki> A2024 modes require special hardware

=== About ECS ===

ECS stands for ''Enhanced Chip Set'', the latest version of the Amiga’s custom chips that provides for improved graphics capabilities. Some of the special features of the Amiga’s graphics sub-system such as the VGA, Productivity and SuperHires display modes require the ECS.

==== SuperHires (35 nanosecond) Pixel Resolutions ====

The enhanced version of the Denise chip can generate SuperHires pixels that are twice as fine as Hires pixels. It is convenient to refer to pixels here by their speed, rather than width, for reasons that will be explained below. They are approximately 35nS long, while Hires are 70nS, and Lores 140nS. In the absence of any other features, this can bring a new mode with nominal dimensions of 1,280x200 (NTSC) or 1,280x256 (PAL). This mode requires the ECS Agnus chip as well.

When Denise is generating these new fast pixels, simple bandwidth arithmetic indicates that at most two bitplanes can be supported. Also note that with two bitplanes, DMA bandwidth is saturated. The palette for SuperHires pixels is also restricted to 64 colors.

==== Productivity Mode ====

The enhanced version of the Denise chip can support monitor horizontal scan frequencies of 31kHz, twice the old 15.75kHz rate. This provides over 400 non-interlaced horizontal lines in a frame, but requires the use of a multiple scan rate, or multi-sync monitor.

This effect speeds up the video beam roughly by a factor of two, which has the side effect of doubling the width of a pixel emitted at a given speed. Thus, for a given Denise mode, pixels are twice as fat, and there are half as many on a given line.

The increased scan rate interacts with all of the Denise modes. So with both SuperHires (35nS) pixels and the double scan rate the display generated would be 640 pixels wide by more than 400 rows, non-interlaced, with up to four colors from a palette of 64. This combination is termed Productivity mode, and the default international height is 480 rows.

This conforms, in a general way, to the VGA Mode 3 Standard ''8514/A''.

The support in Agnus is actually more flexible, and gives the ability to conform to special-purpose modes, such as displays synchronized to motion picture cameras.

==== Selectable PAL/NTSC ====

The Enhanced Chip Set can be set to NTSC or PAL modes under software control. Its initial default behavior is determined by a jumper or trace on the system motherboard. This has no bearing on Productivity mode and other programmable scan operations, but the new system software can support displays in either mode.

==== Determining Chip Versions ====

It is possible to ascertain whether the ECS chips are in the machine at run time by looking in the ChipRevBits0 field of the GfxBase structure. If this field contains the flag for the chip you are interested in (as defined in the <gfxbase.h> include file), then that chip is present.

For example, if the C statement (GfxBase->ChipRevBits0 & GFXF_HR_AGNUS) evaluates to non-zero, then the machine contains the ECS version of the Agnus chip and has advanced features such as the ability to handle larger rasters. Older Agnus chips were capable of handling rasters up to 1,024 by 1,024 pixels. The ECS Agnus can handle rasters up to 16,384 by 16,384 pixels.

If (GfxBase->ChipRevBits0 & GFXF_HR_DENISE) is non-zero, then the ECS version of the Denise chip is present. Having both the ECS Agnus and ECS Denise present allows for the special SuperHires, VGA and Productivity display modes. For more information on ECS and the custom chips, refer to the ''Amiga Hardware Reference Manual''.

=== Forming an Image ===

To create an image, you write data (that is, you “draw”) into a memory area in the computer. From this memory area, the system can retrieve the image for display. You tell the system exactly how the memory area is organized, so that the display is correctly produced. You use a block of memory words at sequentially increasing addresses to represent a rectangular region of data bits. The following figure shows the contents of three example memory words: 0 bits are shown as blank rectangles, and 1 bits as filled-in rectangles.

[[File:LibFig27-5.png|frame|center|Sample Memory Words]]

The system software lets you define linear memory as rectangular regions, called ''bitplanes''. The figure below shows how the system would organize three sequential words in memory into a rectangular bitplane with dimensions of 16x3 pixels.

[[File:LibFig27-6.png|frame|center|A Rectangular Bitplane Made from 3 Memory Words]]

The following figure shows how 4,000 words (8,000 bytes) of memory can be organized to provide enough bits to define a single bitplane of a full-screen, low-resolution video display (320x200).

[[File:LibFig27-7.png|frame|center|Bitplane for a Full-screen, Low-resolution Display]]

Each memory data word contains 16 data bits. The color of each pixel on a video display line is directly related to the value of one or more data bits in memory, as follows:

* If you create a display in which each pixel is related to only one data bit, you can select from only two possible colors, because each bit can have a value of only 0 or 1.
* If you use two bits per pixel, there is a choice of four different colors because there are four possible combinations of the values of 0 and 1 from each of the two bits.
* If you specify three, four, or five bits per pixel, you will have eight, sixteen, or thirty-two possible choices of a color for a pixel.
* If you use six bits per pixel, then depending on the video mode (EHB or HAM), you will have sixty-four or 4,096 possible choices for a pixel.

To create multicolored images, you must tell the system how many bits are to be used per pixel. The number of bits per pixel is the same as the ''number of bitplanes'' used to define the image.

As the video beam sweeps across the screen, the system retrieves one data bit from each bitplane. Each of the data bits is taken from a different bitplane, and one or more bitplanes are used to fully define the video display screen. For each pixel, data-bits in the same x,y position in each bitplane are combined by the system hardware to create a binary value. This value determines the color that appears on the video display for that pixel.

[[File:LibFig27-8.png|frame|center|Bits from Each Bitplane Select Pixel Color]]

You will find more information showing how the data bits actually select the color of the displayed pixel in the section called “ViewPort Color Selection”.

=== Role of the Copper (Coprocessor) ===

The Amiga has a special-purpose coprocessor, called the ''Copper'', that can control nearly the entire graphics system. The Copper can control register updates, reposition sprites, change the color palette, and update the blitter. The graphics and animation routines use the Copper to set up lists of instructions for handling displays, and advanced programmers can create their own custom Copper lists.

== Display Routines and Structures ==

{{Note|title=Caution|text=This section describes the lowest-level graphics interface to the system hardware. If you use any of the routines and the data structures described in these sections, your program will essentially take over the entire display. In general, this is not compatible with Intuition’s multiwindow operating environment since Intuition calls these low-level routines for you.}}

The descriptions of the display routines, as well as those of the drawing routines, occasionally use the same terminology as that in the Intuition articles. These routines and data structures are the same ones that Intuition software uses to produce its displays.

The computer produces a display from a set of instructions you define. You organize the instructions as a set of parameters known as the View structure (see the <graphics/view.h> include file for more information).

The following figure shows how the system interprets the contents of a View structure. This drawing shows a complete display composed of two different component parts, which could (for example) be a low-resolution, multicolored part and a high-resolution, two-colored part.

[[File:LibFig27-9.png|frame|center|The Display Is Composed of ViewPorts]]

A complete display consists of one or more ViewPorts, whose display sections are vertically separated from each other by at least one blank scan line (non-interlaced). (If the system must make many changes to the display during the transition from one ViewPort to the next, there may be two or more blank scanlines between the ViewPorts.)

The viewable area defined by each ViewPort is rectangular. It may be only a portion of the full ViewPort, it may be the full ViewPort, or it may be ''larger'' than the full ViewPort, allowing it to be moved within the limits of its DisplayClip (discussed later). You are essentially defining a display consisting of a number of stacked rectangular areas in which separate sections of graphics rasters can be shown.

=== Limitations on the Use of Viewports ===

The system software for defining ViewPorts allows only vertically stacked fields to be defined.

The following figure shows acceptable and unacceptable display configurations.

[[File:LibFig27-10.png|frame|center|Correct and Incorrect Uses of ViewPorts]]

A ViewPort is related to the custom screen option of Intuition. In a custom screen, you can split the screen into slices as shown in the “correct” illustration of the above figure. Each custom screen can have its own set of colors, use its own resolution, and show its own display area.

=== Characteristics of a ViewPort ===

To describe a ViewPort fully, you need to set the following parameters: height, width, depth and display mode.

In addition to these parameters, you must tell the system the location in memory from which the data for the ViewPort display should be retrieved (by associating with it a BitMap structure) and how to position the final ViewPort display on the screen. The ViewPort will take on the user’s default Workbench colors unless otherwise instructed with a ColorMap. See the section called “Preparing the ColorMap Structure” for more information.

=== ViewPort Size Specifications ===

The following figure illustrates that the variables DHeight, and DWidth specify the size of a ViewPort.

[[File:LibFig27-11.png|frame|center|Size Definition for a ViewPort]]

==== ViewPort Height ====

The DHeight field of the ViewPort structure determines how many video lines will be reserved to show the height of this display segment. The size of the actual segment depends on whether you define a non-interlaced or an interlaced display. An interlaced ViewPort displays twice as many lines as does a non-interlaced ViewPort in the same physical height.

For example, a complete View consisting of two ViewPorts might be defined as follows:

<ul>
<li>ViewPort
1 is 150 lines, high-resolution mode (uses the top three-quarters of the display).</li>
<li>ViewPort
2 is 49 lines of low-resolution mode (uses the bottom quarter of the display and allows the space for the required blank line between ViewPorts).</li></ul>

Initialize the height directly in DHeight. Nominal height for a non-interlaced display is 200 lines for NTSC, 256 for PAL. Nominal height for an interlaced display is 400 lines for NTSC, 512 for PAL.

To set your ViewPort to the maximum supported (displayable) height, use the following code fragment:

<pre>struct DimensionInfo querydims;
struct Rectangle *oscan;
struct ViewPort viewport;

if (GetDisplayInfoData( NULL,(UBYTE *)&querydims, sizeof(struct DimensionInfo),
DTAG_DIMS, modeID ))
{
/* Use StdOScan instead of MaxOScan to get standard overscan */
/* dimensions as set by the user in Overscan Preferences */
oscan = &querydims.MaxOScan;
viewPort->DHeight = oscan->MaxY - oscan->MinY + 1;
}</pre>

==== ViewPort Width ====

The DWidth variable in the ViewPort structure determines how wide, in pixels, the display segment will be. To set your ViewPort to the maximum supported (displayable) NTSC high-resolution width, use the following fragment:

<pre>
struct DimensionInfo querydims;
struct Rectangle *oscan;
struct ViewPort viewport;

/* Use PAL_MONITOR_ID instead of NTSC_MONITOR_ID to get PAL dimensions */
if (GetDisplayInfoData( NULL,(UBYTE *)&querydims, sizeof(querydims),
DTAG_DIMS, NTSC_MONITOR_ID|HIRES_KEY ))
{
/* Use StdOScan instead of MaxOScan to get standard overscan */
/* dimensions as set by the user in Overscan Preferences */
oscan = &querydims.MaxOScan;
viewPort->DWidth = oscan->MaxX - oscan->MinX + 1;
}
</pre>

You may specify a smaller value of pixels per line to produce a narrower display segment or simply set ViewPort.DWidth to the nominal value for this resolution.

Although the system software allows you define low-resolution displays as wide as 362 pixels and high-resolution displays as wide as 724 pixels, you should use caution in exceeding the normal values of 320 or 640, respectively. Because display overscan varies from one monitor to another, many video displays will not be able to show all of a wider display, and sprite display may also be affected. However, if you use the standard overscan values (DimensionInfo.StdOScan) provided by the function GetDisplayInfoData() as shown above, the user’s preference for the size of the display will be satisfied.

If you are using hardware sprites or VSprites with your display, and you specify ViewPort widths exceeding 320 or 640 pixels (for low or high-resolution, respectively), it is likely that some hardware sprites will not be properly rendered on the screen.

These sprites may not be rendered because playfield DMA (direct memory access) takes precedence over sprite DMA when an extra-wide display is produced. See the ''Amiga Hardware Reference Manual'' for a more complete description of this phenomenon.

=== ViewPort Color Selection ===

The maximum number of colors that a ViewPort can display is determined by the depth of the BitMap that the ViewPort displays. The depth is specified when the BitMap is initialized.

See the section below called “Preparing the BitMap Structure.”

Depth determines the number of bitplanes used to define the colors of the rectangular image you are trying to build (the raster image) and the number of different colors that can be displayed at the same time within a ViewPort.

For any single pixel, the system can display any one of 4,096 possible colors.

The following table shows depth values and the corresponding number of possible colors for each value.

{| class="wikitable"
|+ Depth Values and Number of Colors in the ViewPort
! Colors !! Depth Value !! Notes
|-
| 2 || 1
|-
| 4 || 2
|-
| 8 || 3 || 1
|-
| 16 || 4 || 1, 2
|-
| 32 || 5 || 1, 2, 3
|-
| 16 || 6 || 1, 4
|-
| 64 || 6 || 1, 2, 3, 5
|-
| 4,096 || 6 || 1, 2, 3, 6
|}

Notes:

# Not available for SUPERHIRES.
# Single-playfield mode only - DUALPF ''not'' one of the ViewPort’s attributes.
# Low-resolution mode only - neither HIRES nor SUPERHIRES one of the ViewPort attributes.
# Dual Playfield mode - DUALPF is an attribute of this ViewPort. Up to eight colors (in three planes) for each playfield.
# Extra-Half-Brite mode - EXTRA_HALFBRITE is an attribute of this ViewPort.
# Hold-And-Modify mode only - HAM is an attribute of this ViewPort.

The color palette used by a ViewPort is specified in a ColorMap. See the section called “Preparing the ColorMap” for more information.

Depending on whether single- or dual-playfield mode is used, the system will use different color register groupings for interpreting the on-screen colors. The table below details how the depth and the different ViewPort modes affect the registers the system uses.

{| class="wikitable"
|+ Color Registers Used in Single-playfield Mode
! Color !! Depth !! Registers Used
|-
| 1 || 0,1
|-
| 2 || 0-3
|-
| 3 || 0-7
|-
| 4 || 0-15
|-
| 5 || 0-31 || (if EXTRA_HALFBRITE is an attribute of this ViewPort.)
|-
| 6 || 0-31 || (if HAM is an attribute of this ViewPort.)
|}

The following table shows the five possible combinations when DUALPF ''is'' an attribute of the ViewPort.

{| class="wikitable"
|+ Color Registers Used in Dual-playfield Mode
! Depth (PF-1} || Color Registers !! Depth (PF-2) || Color Registers
|-
| 1 || 0,1 || 1 || 8,9
|-
| 2 || 0-3 || 1 || 8,9
|-
| 2 || 0-3 || 2 || 8-11
|-
| 3 || 0-7 || 2 || 8-11
|-
| 3 || 0-7 || 3 || 8-15
|}

=== ViewPort Display Modes ===

The system has many different display modes that you can specify for each ViewPort. Under 1.3, the eight constants that control the modes are DUALPF, PFBA, HIRES, SUPERHIRES, LACE, HAM, SPRITES, and EXTRA_HALFBRITE. Some, but not all of the modes can be combined in a ViewPort. HIRES and LACE combine to make a high-resolution, interlaced ViewPort, but HIRES and SUPERHIRES conflict, and cannot be combined.

Set the display mode for a ViewPort by using the VideoControl() function as described in [[Display Database]].

The DUALPF and PFBA modes are related. DUALPF tells the system to treat the raster specified by this ViewPort as the first of two independent and separately controllable playfields. It also modifies the manner in which the pixel colors are selected for this raster (see the above table).

When PFBA is specified, it indicates that the second playfield has video priority over the first one. Playfield relative priorities can be controlled when the playfield is split into two overlapping regions. Single-playfield and dual-playfield modes are discussed in “Advanced Topics” below.

HIRES tells the system that the raster specified by this ViewPort is to be displayed with (nominally) 640 horizontal pixels, rather than the 320 horizontal pixels of Lores mode.

SUPERHIRES tells the system that the raster specified by this ViewPort is to be displayed with (nominally) 1,280 horizontal pixels. This can be used with 31 kHz scan rates to provide the VGA and Productivity modes. SUPERHIRES modes require ECS. See [[#Determining Chip Versions|Determining Chip Versions]] for an explanation of how to find out if the ECS is present.

LACE tells the system that the raster specified by this ViewPort is to be displayed in interlaced mode. If the ViewPort is non-interlaced and the View is interlaced, the ViewPort will be displayed at its specified height and will look only slightly different than it would look when displayed in a non-interlaced View (this is handled by the system automatically). See “Interlaced Mode vs. Non-interlaced Mode” below for more information.

HAM tells the system to use “hold-and-modify” mode, a special mode that lets you display up to 4,096 colors on screen at the same time. It is described in the “Advanced Topics” section.

SPRITES tells the system that you are using sprites in this display (either VSprites or Simple Sprites). The system will load color registers for the sprites. Note that since the mouse pointer is a sprite, omitting this mode will prevent the mouse pointer from being displayed when this ViewPort is frontmost.

See [[Graphics Sprites, Bobs and Animation]] for more information about sprites.

EXTRA_HALFBRITE tells the system to use the Extra-Half-Brite mode, a special mode that allows you to display up to 64 colors on screen at the same time. It is described in the “Advanced Topics” section.

If you peruse the <graphics/view.h> include file you will see another flag, EXTENDED_MODE. Never set this flag yourself; it is used by the system to control more advanced mode features.

Be sure to read the section the [[Display Database]] for additional information about the ViewPort mode.

==== Single-playfield Mode vs. Dual-playfield Mode ====

When you specify single-playfield mode you are asking that the system treat all bitplanes as part of the definition of a single playfield image. Each of the bitplanes defined as part of this ViewPort contributes data bits that determine the color of the pixels in a single playfield.

[[File:LibFig27-12.png|frame|center|A Single-playfield Display]]

If you use dual-playfield mode, you can define two independent, separately controllable playfield areas as shown below.

[[File:LibFig27-13.png|frame|center|A Dual-playfield Display]]

In the previous figure, PFBA was included in the display mode. If PFBA had not been included, the relative priorities would have been reversed; playfield 2 would have appeared to be behind playfield 1.

=== Low-resolution Mode vs. High-resolution Mode ===

In LORES mode, horizontal lines of 320 pixels fill most of the ordinary viewing area. The system software lets you define a screen segment width up to 362 pixels in this mode, or you can define a screen segment as narrow as you desire (minimum of 16 pixels). In HIRES mode, 640 pixels fill a horizontal line. In this mode you can specify any width from 16 to 724 pixels. In SUPERHIRES mode, 1,280 pixels fill a horizontal line. In this mode you can specify any width from 16 to 1,448 pixels. The fact that many monitor manufacturers set their monitors to overscan the video display normally limits you to showing only 16 to 320 pixels per line in LORES, 16 to 640 pixels per line in HIRES, or 16 to 1,280 pixels per line in SUPERHIRES. The user can set the monitor’s viewable screen size with the Preferences Overscan editor.

[[File:LibFig27-14.png|frame|center|How HIRES and SUPERHIRES Affect the Width of Pixels]]

==== Interlaced Mode vs. Non-interlaced Mode ====

In interlaced mode, there are twice as many lines available as in non-interlaced mode, providing better vertical resolution in the same display area.

[[File:LibFig27-15.png|frame|center|How LACE Affects Vertical Resolution]]

If the View structure does not specify LACE, and the ViewPort specifies LACE, only the top half of the ViewPort data will be displayed.

If the View structure specifies LACE and the ViewPort is non-interlaced, the same ViewPort data will be repeated in both fields. The height of the ViewPort display is the height specified in the ViewPort structure.

If both the View and the ViewPort are interlaced, the ViewPort will be built with double the normal vertical resolution. That means it will need twice as much data space in memory as a non-interlaced picture to fill the display.

==== ViewPort Display Memory ====

The picture you create in memory can be larger than the screen image that can be displayed within your ViewPort. This big picture (called a raster and represented by the BitMap structure) can have a maximum size dependent upon the version of the Agnus chip in the Amiga. The ECS Agnus can handle rasters up to 16,384x16,384 pixels. Older Agnus chips are limited to rasters up to 1,024x1,024 pixels. The section on [[#Determining Chip Versions|Determining Chip Versions]] explains how to find out which Agnus is installed.

The example in the following figure introduces terms that tell the system how to find the display data and how to display it in the ViewPort. These terms are RHeight, RWidth, RyOffset, RxOffset, DHeight, DWidth, DyOffset and DxOffset.

[[File:LibFig27-16.png|frame|center|ViewPort Data Area Parameters]]

The terms RHeight and RWidth do not appear in actual system data structures. They refer to the dimensions of the raster and are used here to relate the size of the raster to the size of the display area.

RHeight is the number of rows in the raster and RWidth is the number of bytes per row times 8. The raster shown in the figure is too big to fit entirely in the display area, so you tell the system which pixel of the raster should appear in the upper left corner of the display segment specified by your ViewPort. The variables that control that placement are RyOffset and RxOffset.

To compute RyOffset and RxOffset, you need RHeight, RWidth, DHeight, and DWidth. The DHeight and DWidth variables define the height and width in pixels of the portion of the display that you want to appear in the ViewPort. The example shows a full-screen, low-resolution mode (320-pixel), non-interlaced (200-line) display formed from the larger overall picture.

Normal values for RyOffset and RxOffset are defined by the formulas:

0 < = RyOffset < = (RHeight - DHeight)
0 < = RxOffset < = (RWidth - DWidth)

Once you have defined the size of the raster and the section of that raster that you wish to display, you need only specify where to put this ViewPort on the screen. This is controlled by the ViewPort variables DyOffset and DxOffset. These are offsets relative to the View.DxOffset and DyOffset.

Possible NTSC values for DyOffset range from -23 to +217 (-46 to +434 if the ViewPort is interlaced), PAL values range from -15 to +267 (-30 to +534 for interlaced ViewPorts). Possible values for DxOffset range from -18 to +362 (-36 to +724 if the ViewPort is Hires, -72 to +1,448 if SuperHires), when the View is in its default, initialized position.

The parameters shown in the figure above are distributed in the following data structures:

* View (information about the whole display) includes the variables that you use to position the whole display on the screen. The View structure contains a Modes field used to determine if the whole display is to be interlaced or non-interlaced. It also contains pointers to its list of ViewPorts and pointers to the Copper instructions produced by the system to create the display you have defined.

* ViewPort (information about this segment of the display) includes the values DxOffset and DyOffset that are used to position this portion relative to the overall View. The ViewPort also contains the variables DHeight and DWidth, which define the size of this display segment; a Modes variable; and a pointer to the local ColorMap. The VideoControl() function and its various tags are used to manipulate the ColorMap and ViewPort.Modes. Each ViewPort also contains a pointer to the next ViewPort. You create a linked list of ViewPorts to define the complete display.

* RasInfo (information about the raster) contains the variables RxOffset and RyOffset. It also contains pointers to the BitMap structure and to a companion RasInfo structure if this is a dual playfield.

* BitMap (information about memory usage) tells the system where to find the display and drawing area memory and shows how this memory space is organized, including the display’s depth.

You must allocate enough memory for the display you define. The memory you use for the display may be shared with the area control structures used for drawing. This allows you to draw into the same areas that you are currently displaying on the screen.

As an alternative, you can define two BitMaps. One of them can be the active structure (that being displayed) and the other can be the inactive structure. If you draw into one BitMap while displaying another, the user cannot see the drawing taking place. This is called ''double-buffering'' of the display. See “Advanced Topics” below for an explanation of the steps required for double-buffering. Double-buffering takes twice as much memory as single-buffering because two full displays are produced.

To determine the amount of required memory for each ViewPort for single-buffering, you can use the following formula.

<pre>
#include <graphics/gfx.h>

/* Depth, Width, and Height get set to something reasonable. */
UBYTE Depth, Width, Height;

/* Calculate resulting VP size. */
bytes_per_ViewPort = Depth * RASSIZE(Width, Height);
</pre>

RASSIZE() is a system macro attuned to the current design of the system memory allocation for display rasters. See the <graphics/gfx.h> include file for the formula with which RASSIZE() is calculated.

For example, a 32-color ViewPort (depth = 5), 320 pixels wide by 200 lines high currently uses 40,000 bytes. A 16-color ViewPort (depth = 4), 640 pixels wide by 400 lines high currently uses 128,000 bytes.

=== Forming a Basic Display ===

Here are the data structures that you need to define to create a basic display:

<pre>
struct View view; /* These get used in all versions of the OS */
struct ViewPort viewPort;
struct BitMap bitMap;
struct RasInfo rasInfo;
struct ColorMap *cm;

struct ViewExtra *vextra; /* Extra View data */
struct ViewPortExtra *vpextra; /* Extra ViewPort data */
struct MonitorSpec *monspec; /* Monitor data */
struct DimensionInfo dimquery; /* Display dimension data */
</pre>

ViewExtra and ViewPortExtra are data structures used to hold extended data about their corresponding parent structure. ViewExtra contains information about the video monitor being used to render the View. ViewPortExtra contains information required for clipping of the ViewPort.

GfxNew() is used to create these extended data structures and GfxAssociate() is used to associate the extended data structure with an appropriate parent structure. Although GfxAssociate() can associate a ViewPortExtra structure with a ViewPort, it is better to use VideoControl() with the VTAG_VIEWPORTEXTRA_SET tag instead. Keep in mind that GfxNew() allocates memory for the resulting data structure which must be returned using GfxFree() before the application exits. The function GfxLookUp() will find the address of an extended data structure from the address of its parent.

==== Preparing the View Structure ====

The following code prepares the View structure for further use:

<pre>
InitView(&view); /* Initialize the View. */
view.Modes |= LACE; /* Only interlaced, 1.3 displays require this */
</pre>

A ViewExtra structure must also be created with GfxNew() and associated with this View with GfxAssociate() as shown in the example programs RGBBoxes.c and WBClone.c.

<pre>
/* Form the ModeID from values in <displayinfo.h> */
modeID=DEFAULT_MONITOR_ID | HIRESLACE_KEY;

/* Make the ViewExtra structure */
if( vextra=GfxNew(VIEW_EXTRA_TYPE) )
{
/* Attach the ViewExtra to the View */
GfxAssociate(&view , vextra);
view.Modes |= EXTEND_VSTRUCT;

/* Initialize the MonitorSpec field of the ViewExtra */
if( monspec=OpenMonitor(NULL,modeID) )
vextra->Monitor=monspec;
else
fail("Could not get MonitorSpec\n");
}
else fail("Could not get ViewExtra\n");
</pre>

==== Preparing the BitMap Structure ====

The BitMap structure tells the system where to find the display and drawing memory and how this memory space is organized. The following code section prepares a BitMap structure, including allocation of memory for the bitmap. This is done with two functions, InitBitMap() and AllocRaster(). InitBitMap() takes four arguments–a pointer to a BitMap and the depth, width, and height of the desired bitmap. Once the bitmap is initialized, memory for its bitplanes must be allocated. AllocRaster() takes two arguments–width and height. Here is a code section to initialize a bitmap:

<pre>
/* Init BitMap for RasInfo. */
InitBitMap(&bitMap, DEPTH, WIDTH, HEIGHT);

/* Set the plane pointers to NULL so the cleanup routine will
know if they were used. */
for(depth=0; depth<DEPTH; depth++)
bitMap.Planes[depth] = NULL;

/* Allocate space for BitMap. */
for(depth=0; depth<DEPTH; depth++)
{
bitMap.Planes[depth] = (PLANEPTR)AllocRaster(WIDTH, HEIGHT);
if (bitMap.Planes[depth] == NULL)
cleanExit(RETURN_WARN);
}
</pre>

This code allocates enough memory to handle the display area for as many bitplanes as the depth you have defined.

==== Preparing the RasInfo Structure ====

The RasInfo structure provides information to the system about the location of the BitMap as well as the positioning of the display area as a window against a larger drawing area.

Use the following steps to prepare the RasInfo structure:

<pre>
/* Initialize the RasInfos. */
rasInfo.BitMap = &bitMap; /* Attach the corresponding BitMap. */
rasInfo.RxOffset = 0; /* Align upper left corners of display */
rasInfo.RyOffset = 0; /* with upper left corner of drawing area. */
rasInfo.Next = NULL; /* for a single playfield display, there
* is only one RasInfo structure present */
</pre>

The system may be made to reinterpret the RxOffset and RyOffset values in a ViewPort’s RasInfo structure by calling ScrollVPort() with the address of the ViewPort. Changing one or both offsets and calling ScrollVPort() has the effect of scrolling the ViewPort.

==== Preparing the ViewPort Structure ====

To prepare the ViewPort structure for further use, you call InitVPort() and initialize certain fields as follows:

<pre>
InitVPort(&viewPort); /* Initialize the ViewPort. */
viewPort.RasInfo = &rasInfo; /* The rasInfo must also be initialized */
viewPort.DWidth = WIDTH;
viewPort.DHeight = HEIGHT;

/* Under 1.3, you should set viewPort.Modes here to select a display mode. */
/* Under Release 2, use VideoControl() with VTAG_NORMAL_DISP_SET to select */
/* a display mode by attaching a DisplayInfo structure to the ViewPort. */
</pre>

The InitVPort() routine presets certain default values in the ViewPort structure. The defaults include:

* Modes variable set to zero–this means you select a low-resolution display. (To alter this, use VideoControl() with the VTAG_NORMAL_DISP_SET tag as explained below.)

* Next variable set to NULL–no other ViewPort is linked to this one. If you want a display with multiple ViewPorts, you must fill in the link yourself.

If you want to create a View with two or more ViewPorts you must declare and initialize the ViewPorts as above. Then link them together using the ViewPort.Next field with a NULL link for the ViewPort at the end of the chain:

<pre>
viewPortA.Next = &viewPortB; /* Tell first one the address of the second. */
viewPortB.Next = NULL; /* There are no others after this one. */
</pre>

Once a ViewPort has been prepared, a ViewPortExtra structure must also be created with GfxNew(), initialized, and associated with the ViewPort via the VideoControl() function. In addition, a DisplayInfo for this mode must be attached to the ViewPort. The fragment below shows how to do this. For complete examples, refer to the program listings of RGBBoxes.c and WBClone.c.

<pre>
struct TagItem vcTags[] = /* These tags will be passed to the */
{ /* VideoControl() function to set up */
{ VTAG_ATTACH_CM_SET, NULL }, /* the extended ViewPort structures */
{ VTAG_VIEWPORTEXTRA_SET, NULL }, /* required in Release 2. The NULL */
{ VTAG_NORMAL_DISP_SET, NULL }, /* ti_Data field of these tags must */
{ VTAG_END_CM, NULL } /* be filled in before making the */
}; /* call to VideoControl(). */

struct DimensionInfo dimquery; /* Release 2 structure for display size data */

/* Make a ViewPortExtra and get ready to attach it */
if( vpextra = GfxNew(VIEWPORT_EXTRA_TYPE) )
{
vcTags[1].ti_Data = (ULONG) vpextra;

/* Initialize the DisplayClip field of the ViewPortExtra structure */
if( GetDisplayInfoData( NULL , (UBYTE *) &dimquery ,
sizeof(struct dimquery) , DTAG_DIMS, modeID) )
{
vpextra->DisplayClip = dimquery.Nominal;

/* Make a DisplayInfo and get ready to attach it */
if( !(vcTags[2].ti_Data = (ULONG) FindDisplayInfo(modeID)) )
fail("Could not get DisplayInfo\n");
}
else fail("Could not get DimensionInfo\n");
}
else fail("Could not get ViewPortExtra\n");

/* This is for backwards compatibility with, for example, */
/* a 1.3 screen saver utility that looks at the Modes field */
viewPort.Modes = (UWORD) (modeID & 0x0000ffff);
</pre>

==== Preparing the ColorMap Structure ====

When the View is created, Copper instructions are generated to change the current contents of each color register just before the topmost line of a ViewPort so that this ViewPort’s color registers will be used for interpreting its display. To set the color registers you create a ColorMap for the ViewPort with GetColorMap() and call SetRGB4(). Here are the steps used in 1.3 to initialize a ColorMap:

<pre>
if( view.ColorMap=GetColorMap( 4L ) )
LoadRGB4((&viewPort, colortable, 4);
</pre>

A ColorMap is attached to the View–usually along with DisplayInfo and ViewExtra–by calling the VideoControl() function.

<pre>
/* RGB values for the four colors used. */
#define BLACK 0x000
#define RED 0xf00
#define GREEN 0x0f0
#define BLUE 0x00f

/* Define some colors in an array of UWORDS. */
static UWORD colortable[] = { BLACK, RED, GREEN, BLUE };

/* Fill the TagItem Data field with the address of the properly initialized
(including ViewPortExtra) structure to be passed to VideoControl(). */
vc[0].ti_Data = (ULONG)viewPort;

/* Init ColorMap. 2 planes deep, so 4 entries (2 raised to #planes power). */
if(cm = GetColorMap( 4L ) )
{
/* For applications that must be compatible with 1.3, replace the next 2 */
/* lines with: viewPort.ColorMap=cm; */
if( VideoControl( cm , vcTags ) )
fail("Could not attach extended structures\n");

/* Change colors to those in colortable. */
LoadRGB4(&viewPort, colortable, 4);
}
</pre>

{{Note|title=The 4 Is For Bits, Not Entries.|text=The 4 in the name LoadRGB4() refers to the fact that each of the red, green, and blue values in a color table entry consists of four bits. It has nothing to do with the fact that this particular color table contains four entries. The call GetRGB4() returns the RGB value of a single entry of a ColorMap. SetRGB4CM() allows individual control of the entries in the ColorMap before or after linking it into the ViewPort.}}

The LoadRGB4() call above could be replaced with the following:

<pre>
register USHORT entry;

/* Operate on the same four ColorMap entries as above. */
for (entry = 0; entry < 4; entry++)
{
/* Call SetRGB4CM() with the address of the ColorMap, the entry to be
changed, and the Red, Green, and Blue values to be stored there.
*/
SetRGB4CM(viewPort.ColorMap, entry,
/* Extract the three color values from the one colortable entry. */
((colortable[entry] & 0x0f00) >> 8),
((colortable[entry] & 0x00f0) >> 4),
(colortable[entry] & 0x000f));
}
</pre>

Notice above how the four bits for each color are masked out and shifted right to get values from 0 to 15.

{{Note|title=WARNING!|text=It is important to use ''only'' the standard system ColorMap-related calls to access the ColorMap entries. These calls will remain compatible with recent and future enhancements to the ColorMap structure.}}

You might need to specify more colors in the color map than you think. If you use a dual playfield display (covered later in this article) with a depth of 1 for each of the two playfields, this means a total of four colors (two for each playfield). However, because playfield 2 uses color registers starting from number 8 on up when in dual-playfield mode, the color map must be initialized to contain at least 10 entries.

That is, it must contain entries for colors 0 and 1 (for playfield 1) and color numbers 8 and 9 (for playfield 2). Space for sprite colors must be allocated as well. For Amiga system software version 1.3 and earlier, ''when in doubt'', allocate a ColorMap with 32 entries, just in case.

==== Creating the Display Instructions ====

Now that you have initialized the system data structures, you can request that the system prepare a set of display instructions for the Copper using these structures as input data.

During the one or more blank vertical lines that precede each ViewPort, the Copper is busy changing the characteristics of the display hardware to match the characteristics you expect for this ViewPort.

This may include a change in display resolution, a change in the colors to be used, or other user-defined modifications to system registers.

Here is the code that creates the display instructions:

<pre>
/* Construct preliminary Copper instruction list. */
MakeVPort( &view, &viewPort );
</pre>

In this line of code, &view is the address of the View structure and &viewPort is the address of the first ViewPort structure. Using these structures, the system has enough information to build the instruction stream that defines your display.

MakeVPort() creates a special set of instructions that controls the appearance of the display.

If you are using animation, the graphics animation routines create a special set of instructions to control the hardware sprites and the system color registers.

In addition, the advanced user can create special instructions (called user Copper instructions) to change system operations based on the position of the video beam on the screen.

All of these special instructions must be merged together before the system can use them to produce the display you have designed. This is done by the system routine MrgCop() (which stands for “Merge Coprocessor Instructions”). Here is a typical call:

<pre>
/* Merge preliminary lists into a real Copper list in the view structure. */
MrgCop( &view );
</pre>

=== Loading and Displaying the View ===

To display the View, you need to load it using LoadView() and turn on the direct memory access (DMA). A typical call is shown below.

<pre>
LoadView(&view);
</pre>

The &view argument is the address of the View structure defined in the example above.

There are two macros, defined in <graphics/gfxmacros.h>, that control display DMA: ON_DISPLAY and OFF_DISPLAY. They simply turn the display DMA control bit in the DMA control register on or off.

If you are drawing to the display area and do not want the user to see intermediate steps in the drawing, you can turn off the display. Because OFF_DISPLAY shuts down the display DMA and possibly speeds up other system operations, it can be used to provide additional memory cycles to the blitter or the ''68000''. The distribution of system DMA, however, allows four-channel sound, disk read/write, and a sixteen-color, low-resolution display (or four-color, high-resolution display) to operate at the same time with no slowdown (7.1 MHz effective rate) in the operation of the ''68000''. Using OFF_DISPLAY in a multitasking environment may, however, be an unfriendly thing to do to the other running processes. Use OFF_DISPLAY with discretion.

==== A Custom ViewPort Example ====

The following example creates a View consisting of one ViewPort set to an NTSC, high-resolution, interlaced display mode of nominal dimensions. This example shows both the old 1.3 way of setting up the ViewPort and the new method used in Release 2.

<pre>
;/* RGBBoxes.c simple ViewPort example -- works with 1.3 and Release 2
LC -b1 -cfistq -v -y -j73 RGBBoxes.c
Blink FROM LIB:c.o,RGBBoxes.o TO RGBBoxes LIBRARY LIB:LC.lib,LIB:Amiga.lib
quit
*/

#include <exec/types.h>
#include <graphics/gfx.h>
#include <graphics/gfxbase.h>
#include <graphics/gfxmacros.h>
#include <graphics/copper.h>
#include <graphics/view.h>
#include <graphics/displayinfo.h>
#include <graphics/gfxnodes.h>
#include <graphics/videocontrol.h>
#include <libraries/dos.h>
#include <utility/tagitem.h>

#include <clib/graphics_protos.h>
#include <clib/exec_protos.h>
#include <clib/dos_protos.h>

#include <stdio.h>
#include <stdlib.h>

#define DEPTH 2 /* The number of bitplanes. */
#define WIDTH 640 /* Nominal width and height */
#define HEIGHT 400 /* used in 1.3. */

#ifdef LATTICE
int CXBRK(void) { return(0); } /* Disable Lattice CTRL/C handling */
int chkabort(void) { return(0); } /* really */
#endif

VOID drawFilledBox(WORD , WORD ); /* Function prototypes */
VOID cleanup(int );
VOID fail(STRPTR);

struct GfxBase *GfxBase = NULL;

/* Construct a simple display. These are global to make freeing easier. */
struct View view, *oldview=NULL; /* Pointer to old View we can restore it.*/
struct ViewPort viewPort = { 0 };
struct BitMap bitMap = { 0 };
struct ColorMap *cm=NULL;

struct ViewExtra *vextra=NULL; /* Extended structures used in Release 2 */
struct MonitorSpec *monspec=NULL;
struct ViewPortExtra *vpextra=NULL;
struct DimensionInfo dimquery = { 0 };

UBYTE *displaymem = NULL; /* Pointer for writing to BitMap memory. */

#define BLACK 0x000 /* RGB values for the four colors used. */
#define RED 0xf00
#define GREEN 0x0f0
#define BLUE 0x00f

/*
* main(): create a custom display; works under either 1.3 or Release 2
*/
VOID main(VOID)
{
WORD depth, box;
struct RasInfo rasInfo;
ULONG modeID;

struct TagItem vcTags[] =
{
{VTAG_ATTACH_CM_SET, NULL },
{VTAG_VIEWPORTEXTRA_SET, NULL },
{VTAG_NORMAL_DISP_SET, NULL },
{VTAG_END_CM, NULL }
};

/* Offsets in BitMap where boxes will be drawn. */
static SHORT boxoffsets[] = { 802, 2010, 3218 };

static UWORD colortable[] = { BLACK, RED, GREEN, BLUE };

/* Open the graphics library */
GfxBase = (struct GfxBase *)OpenLibrary("graphics.library", 33L);
if(GfxBase == NULL)
fail("Could not open graphics library\n");

/* Example steals screen from Intuition if Intuition is around. */
oldview = GfxBase->ActiView; /* Save current View to restore later. */

InitView(&view); /* Initialize the View and set View.Modes. */
view.Modes |= LACE; /* This is the old 1.3 way (only LACE counts). */

if(GfxBase->LibNode.lib_Version >= 36)
{
/* Form the ModeID from values in <displayinfo.h> */
modeID=DEFAULT_MONITOR_ID | HIRESLACE_KEY;

/* Make the ViewExtra structure */
if( vextra=GfxNew(VIEW_EXTRA_TYPE) )
{
/* Attach the ViewExtra to the View */
GfxAssociate(&view , vextra);
view.Modes |= EXTEND_VSTRUCT;

/* Create and attach a MonitorSpec to the ViewExtra */
if( monspec=OpenMonitor(NULL,modeID) )
vextra->Monitor=monspec;
else
fail("Could not get MonitorSpec\n");
}
else fail("Could not get ViewExtra\n");
}

/* Initialize the BitMap for RasInfo. */
InitBitMap(&bitMap, DEPTH, WIDTH, HEIGHT);

/* Set the plane pointers to NULL so the cleanup routine */
/* will know if they were used. */
for(depth=0; depth<DEPTH; depth++)
bitMap.Planes[depth] = NULL;

/* Allocate space for BitMap. */
for (depth=0; depth<DEPTH; depth++)
{
bitMap.Planes[depth] = (PLANEPTR)AllocRaster(WIDTH, HEIGHT);
if (bitMap.Planes[depth] == NULL)
fail("Could not get BitPlanes\n");
}

rasInfo.BitMap = &bitMap; /* Initialize the RasInfo. */
rasInfo.RxOffset = 0;
rasInfo.RyOffset = 0;
rasInfo.Next = NULL;

InitVPort(&viewPort); /* Initialize the ViewPort. */
view.ViewPort = &viewPort; /* Link the ViewPort into the View. */
viewPort.RasInfo = &rasInfo;
viewPort.DWidth = WIDTH;
viewPort.DHeight = HEIGHT;

/* Set the display mode the old-fashioned way */
viewPort.Modes=HIRES | LACE;

if(GfxBase->LibNode.lib_Version >= 36)
{
/* Make a ViewPortExtra and get ready to attach it */
if( vpextra = GfxNew(VIEWPORT_EXTRA_TYPE) )
{
vcTags[1].ti_Data = (ULONG) vpextra;

/* Initialize the DisplayClip field of the ViewPortExtra */
if( GetDisplayInfoData( NULL , (UBYTE *) &dimquery ,
sizeof(dimquery) , DTAG_DIMS, modeID) )
{
vpextra->DisplayClip = dimquery.Nominal;

/* Make a DisplayInfo and get ready to attach it */
if( !(vcTags[2].ti_Data = (ULONG) FindDisplayInfo(modeID)) )
fail("Could not get DisplayInfo\n");
}
else fail("Could not get DimensionInfo \n");
}
else fail("Could not get ViewPortExtra\n");

/* This is for backwards compatibility with, for example, */
/* a 1.3 screen saver utility that looks at the Modes field */
viewPort.Modes = (UWORD) (modeID & 0x0000ffff);
}

/* Initialize the ColorMap. */
/* 2 planes deep, so 4 entries (2 raised to the #_planes power). */
cm = GetColorMap(4L);
if(cm == NULL)
fail("Could not get ColorMap\n");

if(GfxBase->LibNode.lib_Version >= 36)
{
/* Get ready to attach the ColorMap, Release 2-style */
vcTags[0].ti_Data = (ULONG) &viewPort;

/* Attach the color map and Release 2 extended structures */
if( VideoControl(cm,vcTags) )
fail("Could not attach extended structures\n");
}
else
/* Attach the ColorMap, old 1.3-style */
viewPort.ColorMap = cm;

LoadRGB4(&viewPort, colortable, 4); /* Change colors to those in colortable. */

MakeVPort( &view, &viewPort ); /* Construct preliminary Copper instruction list. */

/* Merge preliminary lists into a real Copper list in the View structure. */
MrgCop( &view );

/* Clear the ViewPort */
for(depth=0; depth<DEPTH; depth++)
{
displaymem = (UBYTE *)bitMap.Planes[depth];
BltClear(displaymem, (bitMap.BytesPerRow * bitMap.Rows), 1L);
}

LoadView(&view);

/* Now fill some boxes so that user can see something. */
/* Always draw into both planes to assure true colors. */
for (box=1; box<=3; box++) /* Three boxes; red, green and blue. */
{
for (depth=0; depth<DEPTH; depth++) /* Two planes. */
{
displaymem = bitMap.Planes[depth] + boxoffsets[box-1];
drawFilledBox(box, depth);
}
}

Delay(10L * TICKS_PER_SECOND); /* Pause for 10 seconds. */
LoadView(oldview); /* Put back the old View. */
WaitTOF(); /* Wait until the the View is being */
/* rendered to free memory. */
FreeCprList(view.LOFCprList); /* Deallocate the hardware Copper list */
if(view.SHFCprList) /* created by MrgCop(). Since this */
FreeCprList(view.SHFCprList);/* is interlace, also check for a */
/* short frame copper list to free. */
FreeVPortCopLists(&viewPort); /* Free all intermediate Copper lists */
/* from created by MakeVPort(). */
cleanup(RETURN_OK); /* Success. */
}

/*
* fail(): print the error string and call cleanup() to exit
*/
void fail(STRPTR errorstring)
{
printf(errorstring);
cleanup(RETURN_FAIL);
}

/*
* cleanup(): free everything that was allocated.
*/
VOID cleanup(int returncode)
{
WORD depth;

/* Free the color map created by GetColorMap(). */
if(cm) FreeColorMap(cm);

/* Free the ViewPortExtra created by GfxNew() */
if(vpextra) GfxFree(vpextra);

/* Free the BitPlanes drawing area. */
for(depth=0; depth<DEPTH; depth++)
{
if (bitMap.Planes[depth])
FreeRaster(bitMap.Planes[depth], WIDTH, HEIGHT);
}

/* Free the MonitorSpec created with OpenMonitor() */
if(monspec) CloseMonitor( monspec );

/* Free the ViewExtra created with GfxNew() */
if(vextra) GfxFree(vextra);

/* Close the graphics library */
CloseLibrary((struct Library *)GfxBase);

exit(returncode);
}

/*
* drawFilledBox(): create a WIDTH/2 by HEIGHT/2 box of color
* "fillcolor" into the given plane.
*/
VOID drawFilledBox(WORD fillcolor, WORD plane)
{
UBYTE value;
WORD boxHeight, boxWidth, width;

/* Divide (WIDTH/2) by eight because each UBYTE that */
/* is written stuffs eight bits into the BitMap. */
boxWidth = (WIDTH/2)/8;
boxHeight = HEIGHT/2;

value = ((fillcolor & (1 << plane)) != 0) ? 0xff : 0x00;

for( ; boxHeight; boxHeight--)
{
for(width=0 ; width < boxWidth; width++)
*displaymem++ = value;

displaymem += (bitMap.BytesPerRow - boxWidth);
}
}
</pre>

==== Exiting Gracefully ====

The preceding sample program provides a way of exiting gracefully with the cleanup() subroutine. This function returns to the memory manager all dynamically-allocated memory chunks. Notice the calls to FreeRaster() and FreeColorMap(). These calls correspond directly to the allocation calls AllocRaster() and GetColorMap() located in the body of the program. Now look at the calls within cleanup() to FreeVPortCopLists() and FreeCprList(). When you call MakeVPort(), the graphics system dynamically allocates some space to hold intermediate instructions from which a final Copper instruction list is created. When you call MrgCop(), these intermediate Copper lists are merged together into the final Copper list, which is then given to the hardware for interpretation. It is this list that provides the stable display on the screen, split into separate ViewPorts with their own colors and resolutions and so on.

When your program completes, you must see that it returns all of the memory resources that it used so that those memory areas are again available to the system for reassignment to other tasks. Therefore, if you use the routines MakeVPort() or MrgCop(), you must also arrange to use FreeCprList() (pointing to each of those lists in the View structure) and FreeVPortCopLists() (pointing to the ViewPort that is about to be deallocated). If your View is interlaced, you will also have to call FreeCprList(&view.SHFCprList) because an interlaced view has a separate Copper list for each of the two fields displayed. Do not confuse FreeVPortCopLists() with FreeCprList(). The former works on intermediate Copper lists for a specific ViewPort, the latter directly on a hardware Copper list from the View.

As a final caveat, notice that when you do free everything, the memory manager or other programs may immediately change the contents of the freed memory. Therefore, if the Copper is still executing an instruction stream (as a result of a previous LoadView()) when you free that memory, the display will malfunction. Once another View has been installed via LoadView(), do a WaitTOF() for the new View to begin displaying, and then you can begin freeing up your resources. WaitTOF() waits for the vertical blanking period to begin and all vertical blank interrupts to complete before returning to the caller. The routine WaitBOVP() (for “WaitBottomOfViewPort”) ''busy'' waits until the vertical beam reaches the bottom of the specified ViewPort before returning to the caller. This means no other tasks run until this function returns.

=== Custom ViewPort Example ===

The following program will create a display with the same attributes as the user’s Workbench screen. It does this by first inquiring as to those attributes, duplicating them, and then creating a similar display.

<pre>
/**********************************************************************/
/* */
/* WBClone.c: To clone the Workbench using graphics calls */
/* */
/* Compile : SAS/C 5.10a LC -b1 -cfist -L -v -y */
/* */
/**********************************************************************/

#include <exec/types.h>
#include <exec/exec.h>
#include <clib/exec_protos.h>
#include <intuition/screens.h>
#include <intuition/intuition.h>
#include <intuition/intuitionbase.h>
#include <clib/intuition_protos.h>
#include <graphics/gfx.h>
#include <graphics/gfxbase.h>
#include <graphics/view.h>
#include <graphics/gfxnodes.h>
#include <graphics/videocontrol.h>
#include <clib/graphics_protos.h>

#include <stdio.h>
#include <stdlib.h>

#define INTUITIONNAME "intuition.library"

#ifdef LATTICE
int CXBRK(void) { return(0); } /* Disable Lattice CTRL/C handling */
int chkabort(void) { return(0); } /* really */
#endif

/*********************************************************************/
/* GLOBAL VARIABLES */
/*********************************************************************/

struct IntuitionBase *IntuitionBase = NULL ;
struct GfxBase *GfxBase = NULL ;

/**********************************************************************/
/* */
/* VOID Error (char *String) */
/* */
/* Print string and exit */
/* */
/**********************************************************************/

VOID Error (char *String)
{
VOID CloseAll (VOID) ;

printf (String) ;

CloseAll () ;
exit(0) ;
}

/**********************************************************************/
/* */
/* VOID Init () */
/* */
/* Opens all the required libraries allocates all memory, etc. */
/* */
/**********************************************************************/

VOID Init ( VOID )
{
/* Open the intuition library.... */
if ((IntuitionBase = (struct IntuitionBase *)OpenLibrary (INTUITIONNAME, 37L)) == NULL)
Error ("Could not open the Intuition.library") ;

/* Open the graphics library.... */
if ((GfxBase = (struct GfxBase *)OpenLibrary (GRAPHICSNAME, 36L)) == NULL)
Error ("Could not open the Graphics.library") ;
}

/**********************************************************************/
/* */
/* VOID CloseAll () */
/* */
/* Closes and tidies up everything that was used. */
/* */
/**********************************************************************/

VOID CloseAll ( VOID )
{
/* Close everything in the reverse order in which they were opened */

/* Close the Graphics Library */
if (GfxBase)
CloseLibrary ((struct Library *) GfxBase) ;

/* Close the Intuition Library */
if (IntuitionBase)
CloseLibrary ((struct Library *) IntuitionBase) ;
}
/**********************************************************************/
/* */
/* VOID DestroyView(struct View *view) */
/* */
/* Close and free everything to do with the View */
/* */
/**********************************************************************/

VOID DestroyView(struct View *view)
{
struct ViewExtra *ve;

if (view)
{
if (ve = (struct ViewExtra *)GfxLookUp(view))
{
if (ve->Monitor)
CloseMonitor(ve->Monitor);

GfxFree((struct ExtendedNode *)ve);
}

/* Free up the copper lists */
if (view->LOFCprList)
FreeCprList(view->LOFCprList);

if (view->SHFCprList)
FreeCprList(view->SHFCprList);

FreeVec(view);
}
}

/**********************************************************************/
/* */
/* struct View *DupView(struct View *v, ULONG ModeID) */
/* */
/* Duplicate the View. */
/* */
/**********************************************************************/

struct View *DupView(struct View *v, ULONG ModeID)
{
/* Allocate and init a View structure. Also, get a ViewExtra
* structure and attach the monitor type to the View.
*/

struct View *view = NULL;
struct ViewExtra *ve = NULL;
struct MonitorSpec *mspc = NULL;

if (view = AllocVec(sizeof(struct View), MEMF_PUBLIC | MEMF_CLEAR))
{
if (ve = GfxNew(VIEW_EXTRA_TYPE))
{
if (mspc = OpenMonitor(NULL, ModeID))
{
InitView(view);
view->DyOffset = v->DyOffset;
view->DxOffset = v->DxOffset;
view->Modes = v->Modes;
GfxAssociate(view, (struct ExtendedNode *)ve);
ve->Monitor = mspc;
}
else printf("Could not open monitor\n");
}
else printf("Could not get ViewExtra\n");
}
else printf("Could not create View\n");

if (view && ve && mspc)
return(view);
else
{
DestroyView(view);
return(NULL);
}
}

/**********************************************************************/
/* */
/* VOID DestroyViewPort(struct ViewPort *vp) */
/* */
/* Close and free everything to do with the ViewPort. */
/* */
/**********************************************************************/

VOID DestroyViewPort(struct ViewPort *vp)
{
if (vp)
{
/* Find the ViewPort's ColorMap. From that use VideoControl
* to get the ViewPortExtra, and free it.
* Then free the ColorMap, and finally the ViewPort itself.
*/
struct ColorMap *cm = vp->ColorMap;
struct TagItem ti[] =
{
{VTAG_VIEWPORTEXTRA_GET, NULL}, /* <-- This field will be filled in */
{VTAG_END_CM, NULL}
};

if (cm)
{
if (VideoControl(cm, ti) == NULL)
GfxFree((struct ExtendedNode *)ti[0].ti_Data);
else
printf("VideoControl error in DestroyViewPort()\n");

FreeColorMap(cm);
}
else
{
printf("Could not free the ColorMap\n");
}

FreeVPortCopLists(vp);

FreeVec(vp);
}
}

/**********************************************************************/
/* */
/* struct ViewPort *DupViewPort(struct ViewPort *vp, ULONG ModeID) */
/* */
/* Duplicate the ViewPort. */
/* */
/**********************************************************************/

struct ViewPort *DupViewPort(struct ViewPort *vp, ULONG ModeID)
{
/* Allocate and initialise a ViewPort. Copy the ViewPort width and
* heights, offsets, and modes values. Allocate and initialize a
* ColorMap.
*
* Also, allocate a ViewPortExtra, and copy the TextOScan values of the
* ModeID from the database into the ViewPortExtra.
*/

#define COLOURS 32
struct ViewPort *Myvp;
struct ViewPortExtra *vpe;
struct ColorMap *cm;
struct TagItem ti[] = /* to attach everything */
{
{VTAG_ATTACH_CM_SET, NULL}, /* these NULLs will be replaced in the code */
{VTAG_VIEWPORTEXTRA_SET, NULL},
{VTAG_NORMAL_DISP_SET, NULL},
{VTAG_END_CM, NULL}
};
struct DimensionInfo query = {0};
UWORD colour;
int c;
ULONG gotinfo = NULL;

if (Myvp = AllocVec(sizeof(struct ViewPort), MEMF_CLEAR | MEMF_PUBLIC))
{
if (vpe = (struct ViewPortExtra *)GfxNew(VIEWPORT_EXTRA_TYPE))
{
if (cm = GetColorMap(32))
{
if (gotinfo = GetDisplayInfoData(NULL, (APTR)&query,
sizeof(query), DTAG_DIMS, ModeID))
{
InitVPort(Myvp);

/* duplicate the ViewPort structure */
Myvp->DWidth = vp->DWidth;
Myvp->DHeight = vp->DHeight;
Myvp->DxOffset = vp->DxOffset;
Myvp->DyOffset = vp->DyOffset;
Myvp->Modes = vp->Modes;
Myvp->SpritePriorities = vp->SpritePriorities;
Myvp->ExtendedModes = vp->ExtendedModes;

/* duplicate the Overscan values */
vpe->DisplayClip = query.TxtOScan;

/* attach everything together */
ti[0].ti_Data = (ULONG)Myvp;
ti[1].ti_Data = (ULONG)vpe;
ti[2].ti_Data = (ULONG)FindDisplayInfo(ModeID);
if (VideoControl(cm, ti) != NULL)
{
printf("VideoControl error in CreateViewPort()\n");
}

/* copy the colours from the workbench */
for (c = 0; c < COLOURS; c++)
{
if ((colour = GetRGB4(vp->ColorMap, c)) != -1)
{
SetRGB4CM(cm, c, (colour >> 8),
((colour >> 4) & 0xf), (colour & 0xf));
}
}
}
else printf("Database error\n");
}
else printf("Could not get the ColorMap\n");
}
else printf("Could not get the ViewPortExtra\n");
}
else printf("Could not get the ViewPort\n");

if (Myvp && vpe && cm && gotinfo)
return(Myvp);
else
{
DestroyViewPort(vp);
return(NULL);
}
}

/***********************************************************************************/
/* */
/* VOID DestroyBitMap(struct BitMap *Mybm, SHORT width, SHORT height, SHORT depth) */
/* */
/* Close and free everything to do with the BitMap */
/* */
/***********************************************************************************/

VOID DestroyBitMap(struct BitMap *Mybm, SHORT width, SHORT height, SHORT depth)
{
int i;

if (Mybm)
{
for (i = 0; (i < depth); i++)
{
if (Mybm->Planes[i])
FreeRaster(Mybm->Planes[i], width, height);
}
FreeVec(Mybm);
}
}

/***********************************************************************/
/* */
/* struct BitMap *CreateBitMap(SHORT width, SHORT height, SHORT depth) */
/* */
/* Create the BitMap. */
/* */
/***********************************************************************/

struct BitMap *CreateBitMap(SHORT width, SHORT height, SHORT depth)
{
/* Allocate a BitMap structure, initialise it, and allocate each plane. */

struct BitMap *Mybm;
PLANEPTR allocated = (PLANEPTR) 1;
int i;

if (Mybm = AllocVec(sizeof(struct BitMap), MEMF_CLEAR | MEMF_PUBLIC))
{
InitBitMap(Mybm, depth, width, height);
for (i = 0; ((i < depth) && (allocated)); i++)
allocated = (Mybm->Planes[i] = AllocRaster(width, height));

if (allocated == NULL)
{
printf("Could not allocate all the planes\n");
DestroyBitMap(Mybm, width, height, depth);
Mybm = NULL;
}
}
else printf("Could not get BitMap\n");

return(Mybm);
}

/********************************************************************************/
/* */
/* VOID ShowView(struct View *view, struct ViewPort *vp, struct BitMap *bm, */
/* SHORT width, SHORT height) */
/* */
/* Assemble and display the View. */
/* */
/********************************************************************************/

VOID ShowView(struct View *view, struct ViewPort *vp, struct BitMap *bm,
SHORT width, SHORT height)
{
/* Attach the BitMap to the ViewPort via a RasInfo. Attach the ViewPort
* to the View. Clear the BitMap, and draw into it by attaching the BitMap
* to a RastPort. Then MakeVPort(), MrgCop() and LoadView().
* Just wait for the user to press <RETURN> before returning.
*/

struct RastPort *rp;
struct RasInfo *ri;

if (rp = AllocVec(sizeof(struct RastPort), MEMF_CLEAR | MEMF_PUBLIC))
{
if (ri = AllocVec(sizeof(struct RasInfo), MEMF_CLEAR | MEMF_PUBLIC))
{
InitRastPort(rp);
ri->BitMap = rp->BitMap = bm;
vp->RasInfo = ri;
view->ViewPort = vp;

/* render */
SetRast(rp, 0); /* clear the background */
SetAPen(rp, ((1 << bm->Depth) - 1)); /* use the last pen */
Move(rp, 0, 0);
Draw(rp, width, 0);
Draw(rp, width, height);
Draw(rp, 0, height);
Draw(rp, 0, 0);

/* display it */
MakeVPort(view, vp);
MrgCop(view);
LoadView(view);

getchar();

/* bring back the system */
RethinkDisplay();

FreeVec(ri);
}
else printf("Could not get RasInfo\n");

FreeVec(rp);
}
else printf("Could not get RastPort\n");

}

/**********************************************************************/
/* */
/* VOID main (int argc, char *argv[]) */
/* */
/* Clone the Workbench View using Graphics Library calls. */
/* */
/**********************************************************************/

VOID main (int argc, char *argv[])
{
struct Screen *wb;
struct View *Myview;
struct ViewPort *Myvp;
struct BitMap *Mybm;
ULONG ModeID;
ULONG IbaseLock;

Init () ; /* to open the libraries */

/* To clone the Workbench using graphics calls involves duplicating
* the Workbench ViewPort, ViewPort mode, and Intuition's View.
* This also involves duplicating the DisplayClip for the overscan
* value, the colours, and the View position.
*
* When this is all done, the View, ViewPort, ColorMap and BitMap
* (and ViewPortExtra, ViewExtra and RasInfo) all have to be linked
* together, and the copperlists made to create the display.
*
* This is not as difficult as it sounds (trust me!)
*/

/* First, lock the Workbench screen, so no changes can be made to it
* while we are duplicating it.
*/
if (wb = LockPubScreen("Workbench"))
{
/* Find the Workbench's ModeID. This is a 32-bit number that
* identifies the monitor type, and the display mode of that monitor.
*/
ModeID = GetVPModeID(&wb->ViewPort);

/* We need to duplicate Intuition's View structure, so lock IntuitionBase
* to prevent the View changing under our feet.
*/
IbaseLock = LockIBase(0);
if (Myview = DupView(&IntuitionBase->ViewLord, ModeID))
{
/* The View has been cloned, so we don't need to keep it locked. */
UnlockIBase(IbaseLock);

/* Now duplicate the Workbench's ViewPort. Remember, we still have
* the Workbench locked.
*/
if (Myvp = DupViewPort(&wb->ViewPort, ModeID))
{
/* Create a BitMap to render into. This will be of the
* same dimensions as the Workbench.
*/
if (Mybm = CreateBitMap(wb->Width, wb->Height, wb->BitMap.Depth))
{
/* Now we have everything copied, show something */
ShowView(Myview, Myvp, Mybm, wb->Width-1, wb->Height-1);

/* Now free up everything we have allocated */
DestroyBitMap(Mybm, wb->Width, wb->Height, wb->BitMap.Depth);
}
DestroyViewPort(Myvp);
}
DestroyView(Myview);
}
else
{
UnlockIBase(IbaseLock);
}
UnlockPubScreen(NULL, wb);
}
CloseAll () ;
}
</pre>

== Advanced Topics ==

This section covers advanced display topics such as dual-playfield mode, double-buffering, EHB mode and HAM mode.

=== Creating a Dual-Playfield Display ===

In dual-playfield mode, you have two separately controllable playfields. You specify dual-playfield by using any ModeID that includes DPF in its name as listed in <graphics/displayinfo.h>.

In dual-playfield mode, you always define two RasInfo data structures. Each of these structures defines one of the playfields. There are five different ways you can configure a dual-playfield display, because there are five different distributions of the bitplanes which the system hardware allows.

{| class="wikitable"
|+ Bitplane Assignment in Dual-playfield Mode
! Number of Bitplanes !! Playfield 1 Depth !! Playfield 2 Depth
|-
| 2 || 1 || 1
|-
| 3 || 2 || 1
|-
| 4 || 2 || 2
|-
| 5 || 3 || 2
|-
| 6 || 3 || 3
|}

If the ModeID includes DPF2 in its name, then the playfield priorities are swapped and playfield 2 will be displayed in front of playfield 1. In this way, you can get more bitplanes in the background playfield than you have in the foreground playfield.

The playfield priority affects only one ViewPort at a time. If you have multiple ViewPorts with dual-playfields, the playfield priority is set for each one individually.

Here’s a summary of the steps you need to take to create a dual-playfield display:

# Allocate one View structure and one ViewPort structure.
# Allocate two BitMap structures. Allocate two RasInfo structures (linked together), each pointing to a separate BitMap. The two RasInfo structures are linked together as follows: <syntaxhighlight lang="C" line>
struct RasInfo playfield1, playfield2;

playfield1.Next = &playfield2;
playfield2.Next = NULL;
</syntaxhighlight>
# Initialize each BitMap structure to describe one playfield, using one of the permissible bitplane distributions shown in the above table and allocate memory for the bitplanes themselves. Note that BitMap 1 and BitMap 2 need ''not'' be the same width and height.
# Initialize the ViewPort structure. Specify dual-playfield mode by selecting a ModeID that includes DPF (or DPF2) in its name as listed in <graphics/displayinfo.h>. Set the ViewPort.RasInfo field to the address of the playfield 1 RasInfo.
# Set up the ColorMap information
# Call MakeVPort(), MrgCop() and LoadView() to display the newly created ViewPort.

For display purposes, each of the two BitMaps is assigned to a separate ViewPort. To ''draw'' separately into the BitMaps, you must also assign these BitMaps to two separate RastPorts. The section called “Initializing a RastPort Structure” shows you how to use a RastPort data structure to control your drawing routines.

=== Creating a Double-Buffered Display ===

To produce smooth animation or similar effects, it is occasionally necessary to double-buffer your display. To prevent the user from seeing your graphics rendering while it is in progress, you will want to draw into one memory area while actually displaying a different area.

There are two methods of creating and displaying a double-buffered display. The simplest method is to create two complete Views and switch back and forth between them with LoadView() and WaitTOF().

The second method consists of creating two separate display areas and two sets of pointers to those areas for a single View. This is more complicated but takes less memory.

<ul>
<li>Allocate one ViewPort structure and one View structure.</li>
<li>Allocate two BitMap structures and one RasInfo structure. Initialize each BitMap structure to describe one drawing area and allocate memory for the bitplanes themselves. Initialize the RasInfo structure, setting the RasInfo.BitMap field to the address of one of the two BitMaps you created.
</li>
<li>Call MakeVPort(), MrgCop() and LoadView(). When you call MrgCop(), the system uses the information you have provided to create a Copper instruction list for the Copper to execute. The system allocates memory for a long-frame (LOF) Copper list and, if this is an interlaced display, a short-frame (SHF) Copper list as well. The system places a pointer to the long-frame Copper list in View.LOFCprList and a pointer to a short-frame Copper list (if this is an interlaced display) in View.SHFCprList. The Copper instruction stream referenced by these pointers applies to the first BitMap.</li>
<li>Save the values in View.LOFCprList and View.SHFCprlist and reset these fields to zero. Place a pointer to the second BitMap structure in the RasInfo.BitMap field. Next call MakeVPort() and MrgCop().</li>
<li>When you perform MrgCop() with the Copper instruction list fields of the View set to zero, the system automatically allocates and fills in a new list of instructions for the Copper. Now you have created two sets of instruction streams for the Copper, one that works with data in the first BitMap and the other that works with data in the second BitMap.</li>
<li>You can save pointers to the second list of Copper instructions as well. Then, to perform the double-buffering, alternate between the two Copper lists. The code for the double-buffering loop would be as follows: call WaitTOF(), change the Copper instruction list pointers in the View, call LoadView() to show one of the BitMaps while drawing into the other BitMap, and repeat.</li></ul>

Remember that you will have to call FreeCprList() on both sets of Copper lists when you have finished.

=== Extra-Half-Brite Mode ===

In the Extra-Half-Brite mode you can create a single-playfield, low-resolution display with up to 64 colors, double the normal maximum of 32. This requires your ViewPort to be defined with six bitplanes. You specify EHB by selecting any ModeID which includes EXTRAHALFBRITE in its name as defined in the include file <graphics/displayinfo.h>.

When setting up the color palette for an EHB display, you only specify values for registers 0 to 31. If you draw using color numbers 0 through 31, the pixel you draw will be the color specified in that particular system color register. If you draw using a color number from 32 to 63, then the color displayed will be half the intensity value of the corresponding color register from 0 to 31. For example, if color register 0 is set to 0xFFF (white), then color number 32 would be half this value or 0x777 (grey).

EHB mode uses all six bitplanes. The color register (0 through 31) is obtained from the bit combinations from planes 5 to 1, in that order of significance. Plane 6 is used to determine whether the full intensity (bit value 0) color or half-intensity (bit value 1) color is to be displayed.

=== Hold-And-Modify Mode ===

In hold-and-modify mode you can create a single-playfield, low-resolution display in which 4,096 different colors can be displayed simultaneously. This requires your ViewPort to be defined with six bitplanes. You specify HAM by selecting any ModeID which includes HAM in its name as defined in <graphics/displayinfo.h>.

When you draw into the BitMap associated with this ViewPort, you can choose colors in one of four different ways. If you draw using color numbers 0 to 15, the pixel you draw will appear in the color specified in that particular system color register. If you draw with any other color value (16 to 63) the color displayed depends on the color of the pixel that is to the immediate left of this pixel on the screen. To see how this works, consider how the bitplanes are used in HAM.

Hold-and-modify mode requires six bitplanes. Planes 5 and 6 are used to modify the way bits from planes 1 through 4 are treated, as follows:

* If the bit combination from planes 6 and 5 for any given pixel is 00, normal color selection procedure is followed. Thus, the bit combinations from planes 4 to 1, in that order of significance, are used to choose one of 16 color registers (registers 0 through 15).
* If the bit combination in planes 6 and 5 is 01, the color of the pixel immediately to the left of this pixel is duplicated and then modified. The bit combinations from planes 4 through 1 are used to replace the four bits representing the blue value of the preceding pixel color. (No color registers are changed.)
* If the bit combination in planes 6 and 5 is 10, then the color of the pixel immediately to the left of this pixel is duplicated and modified. The bit combinations from planes 4 through 1 are used to replace the four bits representing the red value of the preceding pixel color.
* If the bit combination in planes 6 and 5 is 11, then the color of the pixel immediately to the left of this pixel is duplicated and modified. The bit combinations from planes 4 through 1 are used to replace the four bits representing the green value of the preceding pixel color.

You can use just five bitplanes in HAM mode. In that case, the data for the sixth plane is automatically assumed to be 0. Note that for the first pixel in each line, hold-and-modify begins with the background color. The color choice does ''not'' carry over from the preceding line.

{{Note|text=Since a typical hold-and-modify pixel only changes one of the three RGB color values at a time, color selection is limited. HAM mode does allow for the display of 4,096 colors simultaneously, but there are only 64 color options for any given pixel (not 4,096). The color of a pixel depends on the color of the preceding pixel.}}

== User Copper Lists ==

The Copper coprocessor allows you to produce mid-screen changes in certain hardware registers in addition to changes that the system software already provides. For example, it is the Copper that allows the Amiga to split the viewing area into multiple draggable screens, each with its own independent set of colors.

To create your own mid-screen effects on the system hardware registers, you provide “user Copper lists” that can be merged into the system Copper lists.

In the ViewPort data structure there is a pointer named UCopIns. If this pointer value is non-NULL, it points to a user Copper list that you have dynamically allocated and initialized to contain your own special hardware-stuffing instructions.

You allocate a user Copper list by an instruction sequence such as the following:

<pre>struct UCopList *uCopList = NULL;

/* Allocate memory for the Copper list. Make certain that the initial */
/* memory is cleared. */
uCopList = (struct UCopList *)
AllocMem(sizeof(struct UCopList), MEMF_PUBLIC|MEMF_CLEAR);

if (uCopList == NULL)
return(FALSE);</pre>
boxNote:User Copper lists do ''not'' have to be in Chip RAM.

=== Copper List Macros ===

Once this pointer to a user Copper list is available, you can use it with system macros (<graphics/gfxmacros.h>) to instruct the system what to add to its own list of things for the Copper to do within a specific ViewPort. The file <graphics/gfxmacros.h> provides the following five macro functions that implement user Copper instructions.

initializes the Copper list buffer. It is used to specify how many instructions are going to be placed in the Copper list. It is called as follows.

CINIT(uCopList, num_entries);

The uCopList argument is a pointer tot he user Copper list and num_entries is the number of entries in the list.

waits for the video beam to reach a particular horizontal and vertical position. Its format is:

CWAIT(uCopList, v, h)

Again, uCopList is the pointer to the Copper list. The v argument is the vertical position for which to wait, specified relative to the top of the ViewPort. The legal range of values (for both NTSC and PAL) is from 0 to 255; h is the horizontal position for which to wait. The legal range of values (for both NTSC and PAL) is from 0 to 226.

installs a particular value into a specified system register. Its format is:

CMOVE(uCopList, reg, value)

Again, uCopList is the pointer to the Copper list. The reg argument is the register to be affected, specified in this form: custom.''register-name'' where the ''register-name'' is one of the registers listed in the Custom structure in <hardware/custom.h>. The value argument to CMOVE is the value to place in the register.

increments the user Copper list pointer to the next position in the list. It is usually invoked for the programmer as part of the macro definitions CWAIT or CMOVE. Its format is:

CBump(uCopList)

where uCopList is the pointer to the user Copper list.

terminates the user Copper list. Its format is:

CEND(uCopList)

where uCopList is the pointer to the user Copper list.

Executing any of the user Copper list macros causes the system to dynamically allocate special data structures called intermediate Copper lists that are linked into your user Copper list (the list to which uCopList points) describing the operation. When you call the function MrgCop(&view) as shown in the section called “Forming A Basic Display,” the system uses all of its intermediate Copper lists to sort and merge together the real Copper lists for the system (LOFCprList and SHFCprList).

When your program exits, you must return to the system all of the memory that you allocated or caused to be allocated. This means that you must return the intermediate Copper lists, as well as the user Copper list data structure. Here are two different methods for returning this memory to the system.

<pre>/* Returning memory to the system if you have NOT
* obtained the ViewPort from Intuition. */
FreeVPortCopLists(viewPort);

/* Returning memory to the system if you HAVE
* obtained the ViewPort from Intuition. */
CloseScreen(screen); /* Intuition only */</pre>

User Copper lists may be clipped, under Release 2 and later, to ViewPort boundaries if the appropriate tag (VTAG_USERCLIP_SET) is passed to VideoControl(). Under earlier releases, the user Copper list would “leak” through to lower ViewPorts.

=== Copper List Example ===

The example program below shows the use of user Copper lists under Intuition.

<pre>/* UserCopperExample.c
User Copper List Example
For SAS/C 5.10a,
compile with: LC -b1 -cfist -L -v -y UserCopperExample.c
link with lc.lib and amiga.lib
*/

#include <exec/types.h>
#include <exec/memory.h>
#include <graphics/gfxbase.h>
#include <graphics/gfxmacros.h>
#include <graphics/copper.h>
#include <graphics/videocontrol.h>
#include <intuition/intuition.h>
#include <intuition/preferences.h>
#include <hardware/custom.h>
#include <libraries/dos.h>

#include <clib/exec_protos.h> /* Prototypes. */
#include <clib/graphics_protos.h>
#include <clib/intuition_protos.h>
#include <clib/dos_protos.h>

#include <stdlib.h>

/* Use this structure to gain access to the custom registers. */
extern struct Custom far custom;

/* Global variables. */
struct GfxBase *GfxBase = NULL;
struct IntuitionBase *IntuitionBase = NULL;
struct Screen *screen = NULL;
struct Window *window = NULL;

VOID main( VOID ), cleanExit( WORD );
WORD openAll( VOID ), loadCopper( VOID );

/*
* The main() routine -- just calls subroutines
*/
VOID main( VOID )
{
WORD ret_val;
struct IntuiMessage *intuiMessage;

/* Open the libraries, a screen and a window. */
ret_val = openAll();
if (RETURN_OK == ret_val)
{
/* Create and attach the user Copper list. */
ret_val = loadCopper();
if (RETURN_OK == ret_val)
{
/* Wait until the user clicks in the close gadget. */
(VOID) Wait(1<<window->UserPort->mp_SigBit);

while (intuiMessage = (struct IntuiMessage *)GetMsg(window->UserPort))
ReplyMsg((struct Message *)intuiMessage);
}
}
cleanExit(ret_val);
}

/*
* openAll() -- opens the libraries, screen and window
*/
WORD openAll( VOID )
{
#define MY_WA_WIDTH 270 /* Width of window. */

WORD ret_val = RETURN_OK;

/* Prepare to explicitly request Topaz 60 as the screen font. */
struct TextAttr topaz60 =
{
(STRPTR)"topaz.font",
(UWORD)TOPAZ_SIXTY, (UBYTE)0, (UBYTE)0
};

GfxBase = (struct GfxBase *)OpenLibrary("graphics.library", 37L);
if (GfxBase == NULL)
ret_val = ERROR_INVALID_RESIDENT_LIBRARY;
else
{
IntuitionBase = (struct IntuitionBase *)
OpenLibrary("intuition.library", 37L);

if (IntuitionBase == NULL)
ret_val = ERROR_INVALID_RESIDENT_LIBRARY;
else
{
screen = OpenScreenTags( NULL,
SA_Overscan, OSCAN_STANDARD,
SA_Title, "User Copper List Example",
SA_Font, (ULONG)&topaz60,
TAG_END);

if (NULL == screen)
ret_val = ERROR_NO_FREE_STORE;
else
{
window = OpenWindowTags( NULL,
WA_CustomScreen, screen,
WA_Title, "<- Click here to quit.",
WA_IDCMP, CLOSEWINDOW,
WA_Flags, WINDOWDRAG|WINDOWCLOSE|INACTIVEWINDOW,
WA_Left, (screen->Width-MY_WA_WIDTH)/2,
WA_Top, screen->Height/2,
WA_Height, screen->Font->ta_YSize + 3,
WA_Width, MY_WA_WIDTH,
TAG_END);

if (NULL == window)
ret_val = ERROR_NO_FREE_STORE;
}
}
}

return(ret_val);
}

/*
* loadCopper() -- creates a Copper list program and adds it to the system
*/
WORD loadCopper( VOID )
{
register USHORT i, scanlines_per_color;
WORD ret_val = RETURN_OK;
struct ViewPort *viewPort;
struct UCopList *uCopList = NULL;
struct TagItem uCopTags[] =
{
{ VTAG_USERCLIP_SET, NULL },
{ VTAG_END_CM, NULL }
};

UWORD spectrum[] =
{
0x0604, 0x0605, 0x0606, 0x0607, 0x0617, 0x0618, 0x0619,
0x0629, 0x072a, 0x073b, 0x074b, 0x074c, 0x075d, 0x076e,
0x077e, 0x088f, 0x07af, 0x06cf, 0x05ff, 0x04fb, 0x04f7,
0x03f3, 0x07f2, 0x0bf1, 0x0ff0, 0x0fc0, 0x0ea0, 0x0e80,
0x0e60, 0x0d40, 0x0d20, 0x0d00
};

#define NUMCOLORS 32

/* Allocate memory for the Copper list. */
/* Make certain that the initial memory is cleared. */
uCopList = (struct UCopList *)
AllocMem(sizeof(struct UCopList), MEMF_PUBLIC|MEMF_CLEAR);

if (NULL == uCopList)
ret_val = ERROR_NO_FREE_STORE;
else
{
/* Initialize the Copper list buffer. */
CINIT(uCopList, NUMCOLORS);

scanlines_per_color = screen->Height/NUMCOLORS;

/* Load in each color. */
for (i=0; i<NUMCOLORS; i++)
{
CWAIT(uCopList, (i*scanlines_per_color), 0);
CMOVE(uCopList, custom.color[0], spectrum[i]);
}

CEND(uCopList); /* End the Copper list */

viewPort = ViewPortAddress(window); /* Get a pointer to the ViewPort. */
Forbid(); /* Forbid task switching while changing the Copper list. */
viewPort->UCopIns=uCopList;
Permit(); /* Permit task switching again. */

/* Enable user copper list clipping for this ViewPort. */
(VOID) VideoControl( viewPort->ColorMap, uCopTags );

RethinkDisplay(); /* Display the new Copper list. */

return(ret_val);
}
}

/*
* cleanExit() -- returns all resources that were used.
*/
VOID cleanExit( WORD retval )
{
struct ViewPort *viewPort;

if (NULL != IntuitionBase)
{
if (NULL != screen)
{
if (NULL != window)
{
viewPort = ViewPortAddress(window);
if (NULL != viewPort->UCopIns)
{
/* Free the memory allocated for the Copper. */
FreeVPortCopLists(viewPort);
RemakeDisplay();
}
CloseWindow(window);
}
CloseScreen(screen);
}
CloseLibrary((struct Library *)IntuitionBase);
}

if (NULL != GfxBase)
CloseLibrary((struct Library *)GfxBase);

exit((int)retval);
}
</pre>

== ECS and Genlocking Features ==

The Enhanced Chip Set (ECS) Denise chip (''8373-R2a''), coupled with the Release 2 graphics library, opens up a whole new set of genlocking possibilities. Unlike the old Denise, whose only genlocking ability allowed keying on color register zero, the ECS Denise allows keying on any color register. Also, the ECS Denise allows keying on any bitplane of the ViewPort being genlocked. With the ECS Denise, the border area surrounding the display can be made transparent (always passes video) or opaque (overlays using color 0). All the new features are set individually for each ViewPort. These features can be used in conjunction with each other, making interesting scenarios possible.

=== Genlock Control ===

Using VideoControl(), a program can enable, disable, or obtain the state of a ViewPort’s genlocking features. It returns NULL if no error occurred. The function uses a tag based interface:

<pre>error = BOOL VideoControl( struct ColorMap *cm, struct TagItem *ti );</pre>
The ti argument is a list of video commands stored in an array of TagItem structures. The cm argument specifies which ColorMap and, indirectly, which ViewPort these genlock commands will be applied to. The possible commands are:

<pre>VTAG_BITPLANEKEY_GET, _SET, _CLR
VTAG_CHROMA_PLANE_GET, _SET
VTAG_BORDERBLANK_GET, _SET, _CLR
VTAG_BORDERNOTRANS_GET, _SET, _CLR
VTAG_CHROMAKEY_GET, _SET, _CLR
VTAG_CHROMAPEN_GET, _SET, _CLR</pre>
This section covers only the genlock VideoControl() tags. See <graphics/videocontrol.h> for a complete list of all the available tags you can use with VideoControl().

VTAG_BITPLANEKEY_GET

is used to find out the status of the bitplane keying mode. VTAG_BITPLANEKEY_SET and VTAG_BITPLANEKEY_CLR activate and deactivate bitplane keying mode. If bitplane key mode is on, genlocking will key on the bits set in a specific bitplane from the ViewPort (the specific bitplane is set with a different tag). The data portion of these tags is NULL.

For inquiry commands like VTAG_BITPLANEKEY_GET (tags ending in _GET), VideoControl() changes the _GET tag ID (ti_Tag) to the corresponding _SET or _CLR tag ID, reflecting the current state of the genlock mode. For example, when passed the following tag array:

<pre>struct TagItem videocommands[] =
{
{VTAG_BITPLANEKEY_GET, NULL},
{VTAG_END_CM, NULL}
};</pre>
VideoControl()

changes the VTAG_BITPLANEKEY_GET tag ID (ti_Tag) to VTAG_BITPLANEKEY_SET if bitplane keying is currently on, or to VTAG_BITPLANEKEY_CLR if bitplane keying is off. In both of these cases, VideoControl() only uses the tag’s ID, ignoring the tag’s data field (ti_Data).

The VTAG_CHROMA_PLANE_GET tag returns the number of the bitplane keyed on when bitplane keying mode is on. VideoControl() changes the tag’s data value to the bitplane number. VTAG_CHROMA_PLANE_SET sets the bitplane number to the tag’s data value.

VTAG_BORDERBLANK_GET

is used to obtain the border blank mode status. This tag works exactly like VTAG_BITPLANEKEY_GET. VideoControl() changes the tag’s ID to reflect the current border blanking state. VTAG_BORDERBLANK_SET and VTAG_BORDERBLANK_CLR activate and deactivate border blanking. If border blanking is on, the Amiga will not display anything in its display border, allowing an external video signal to show through the border area. On the Amiga display, the border appears black. The data portion of these tags is NULL.

The VTAG_BORDERNOTRANS_GET, _SET and _CLR tags are used, respectively, to obtain the status of border-not-transparent mode, and to activate and to deactivate this mode. If set, the Amiga display’s border will overlay external video with the color in register 0. Because border blanking mode takes precedence over border-not-transparent mode, setting border-not-transparent has no effect if border blanking is on. The data portion of these tags is NULL.

The VTAG_CHROMAKEY_GET, _SET and _CLR tags are used, respectively, to obtain the status of chroma keying mode, and to activate and deactivate chroma keying mode. If set, the genlock will key on colors from specific color registers (the specific color registers are set using a different tag). If chroma keying is not set, the genlock will key on color register 0. The data portion of these tags is NULL.

VTAG_CHROMAPEN_GET

obtains the chroma keying status of an individual color register. The tag’s ti_Data field contains the register number. Like the other _GET tags, VideoControl() changes the tag ID (ti_Tag) to one that reflects the current state of the mode. VTAG_CHROMAPEN_SET and VTAG_CHROMAPEN_CLR activate and deactivate chroma keying for each individual color register. Chroma keying can be active for more than one register. By turning off border blanking and activating chroma keying mode, but turning off chroma keying for each color register, a program can overlay every part of an external video source, completely blocking it out.

After using VideoControl() to set values in the ColorMap, the corresponding ViewPort has to be rebuilt with MakeVPort(), MrgCop() and LoadView(), so the changes can take effect. A program that uses a screen’s ViewPort rather than its own ViewPort should use the Intuition functions MakeScreen() and RethinkDisplay() to make the display changes take effect.

The following code fragment shows how to access the genlock modes.

<pre>struct Screen *genscreen;
struct ViewPort *vp;
struct TagItem vtags [24];

/* The complete example opened a window, rendered some colorbars, */
/* and added gadgets to allow the user to turn the various genlock */
/* modes on and off. */

vp = &(genscreen->ViewPort);

/* Ascertain the current state of the various modes. */

/* Is borderblanking on? */
vtags[0].ti_Tag = VTAG_BORDERBLANK_GET;
vtags[0].ti_Data = NULL;

/* Is bordertransparent set? */
vtags[1].ti_Tag = VTAG_BORDERNOTRANS_GET;
vtags[1].ti_Data = NULL;

/* Key on bitplane? */
vtags[2].ti_Tag = VTAG_BITPLANEKEY_GET;
vtags[2].ti_Tag = NULL;

/* Get plane which is used to key on */
vtags[3].ti_Tag = VTAG_CHROMA_PLANE_GET;
vtags[3].ti_Data = NULL;

/* Chromakey overlay on? */
vtags[4].ti_Tag = VTAG_CHROMAKEY_GET;
vtags[4].ti_Data = NULL;

for (i = 0; i < 16; i++)
{
/* Find out which colors overlay */
vtags[i + 5].ti_Tag = VTAG_CHROMA_PEN_GET;
vtags[i + 5].ti_Data = i;
}

/* Indicate end of tag array */
vtags[21].ti_Tag = VTAG_END_CM;
vtags[21].ti_Data = NULL;

/* And send the commands. On return the Tags themselves will
* indicate the genlock settings for this ViewPort's ColorMap.
*/
error = VideoControl(vp->ColorMap, vtags);

/* The complete program sets gadgets to reflect current states. */

/* Will only send single commands from here on. */
vtags[1].ti_Tag = VTAG_END_CM;

/* At this point the complete program gets an input event and sets/clears the
genlock modes as requested using the vtag list and VideoControl().
*/

/* send video command */
error = VideoControl(vp->ColorMap, vtags);

/* Now use MakeScreen() and RethinkDisplay() to make the VideoControl()
* changes take effect. If we were using our own ViewPort rather than
* borrowing one from a screen, we would instead do:
*
* MakeVPort(ViewAddress(),vp);
* MrgCop(ViewAddress());
* LoadView(ViewAddres());
*/
MakeScreen(genscreen);
RethinkDisplay();

/* The complete program closes and frees everything it had opened or allocated. */

/* The complete example calls the CheckPAL function, which is included below in its
entirety for illustrative purposes.
*/

BOOL CheckPAL(STRPTR screenname)
{
struct Screen *screen;
ULONG modeID = LORES_KEY;
struct DisplayInfo displayinfo;
BOOL IsPAL;

if (GfxBase->LibNode.lib_Version >= 36)
{
/*
* We got at least V36, so lets use the new calls to find out what
* kind of videomode the user (hopefully) prefers.
*/

if (screen = LockPubScreen(screenname))
{
/*
* Use graphics.library/GetVPModeID() to get the ModeID of the specified screen.
* Will use the default public screen (Workbench most of the time) if NULL It is
* _very_ unlikely that this would be invalid, heck it's impossible.
*/
if ((modeID = GetVPModeID(&(screen->ViewPort))) != INVALID_ID)
{
/*
* If the screen is in VGA mode, we can't tell whether the system is PAL
* or NTSC. So to be foolproof we fall back to the displayinfo of the default
* monitor by inquiring about just the LORES_KEY displaymode if we don't know.
* The default.monitor reflects the initial video setup of the system, thus
* for either ntsc.monitor or pal.monitor. We only use the displaymode of the
* is an alias specified public screen if it's display mode is PAL or NTSC and
* NOT the default.
*/
if (!((modeID & MONITOR_ID_MASK) == NTSC_MONITOR_ID ||
(modeID & MONITOR_ID_MASK) == PAL_MONITOR_ID))
modeID = LORES_KEY;
}
UnlockPubScreen(NULL, screen);
} /* if fails modeID = LORES_KEY. Can't lock screen, so fall back on default monitor. */

if (GetDisplayInfoData(NULL, (UBYTE *) & displayinfo,
sizeof(struct DisplayInfo), DTAG_DISP, modeID))
{
if (displayinfo.PropertyFlags & DIPF_IS_PAL)
IsPAL = TRUE;
else
IsPAL = FALSE;
/* Currently the default monitor is always either PAL or NTSC. */
}
}
else
/* < V36. The enhancements to the videosystem in V36 (and above) cannot be better
* expressed than with the simple way to determine PAL in V34.
*/
IsPAL= (GfxBase->DisplayFlags & PAL) ? TRUE : FALSE;

return(IsPAL);
}
</pre>

== Accessing the Blitter Directly ==

To use the blitter directly, you must first be familiar with how its registers control its operation. This topic is covered thoroughly in the ''Amiga Hardware Reference Manual'' and is not repeated here. There are two basic approaches you can take to perform direct programming of the blitter: synchronous and asynchronous.

* Synchronous programming of the blitter is used when you want to do a job with the blitter right away. For synchronous programming, you first get exclusive access to the blitter with OwnBlitter(). Next call WaitBlit() to ensure that any previous blitter operation that might have been in progress is completed. Then set up your blitter operation by programming the blitter registers. Finally, start the blit and call DisownBlitter().

* Asynchronous programming of the blitter is used when the blitter operation you want to perform does not have to happen immediately. In that case, you can use the QBlit() and QBSBlit() functions in order to queue up requests for the use of the blitter on a non-exclusive basis. You share the blitter with system tasks.

Whichever approach you take, there is one rule you should generally keep in mind about using the blitter directly:

{{Note|title=Don’t Tie Up The Blitter|text=The system uses the blitter extensively for disk and display operation. While your task is using the blitter, many other system processes will be locked out. Therefore, use it only for brief periods and relinquish it as quickly as possible.}}

To use QBlit() and QBSBlit(), you must create a data structure called a bltnode (blitter node) that contains a pointer to the blitter code you want to execute. The system uses this structure to link blitter usage requests into a first-in, first-out (FIFO) queue. When your turn comes, your own blitter routine can be repeatedly called until your routine says it is finished using the blitter.

Two separate blitter queues are maintained. One queue is for the QBlit() routine. You use QBlit() when you simply want something done and you do not necessarily care when it happens. This may be the case when you are moving data in a memory area that is not currently being displayed.

The second queue is maintained for QBSBlit(). QBS stands for “queue-beam-synchronized”. QBSBlit() requests form a beam-synchronized FIFO queue. When the video beam gets to a predetermined position, your blitter routine is called. Beam synchronization takes precedence over the simple FIFO. This means that if the beam sync matches, the beam-synchronous blit will be done before the non-synchronous blit in the first position in the queue. You might use QBSBlit() to draw into an area of memory that is currently being displayed to modify memory that has already been “passed-over” by the video beam. This avoids display flicker as an area is being updated.

The sole input to both QBlit() and QBSBlit() is a pointer to a bltnode data structure, defined in the include file <hardware/blit.h>. Here is a copy of the structure, followed by details about the items you must initialize:

<pre>
struct bltnode
{
struct bltnode *n;
int (*function)();
char stat;
short blitsize;
short beamsync;
int (*cleanup)();
};
</pre>

This is a pointer to the next bltnode, which, for most applications will be zero. You should not link bltnodes together. This is to be performed by the system in a separate call to QBlit() or QBSBlit().

This is the address of your blitter function that the blitter queuer will call when your turn comes up. Your function must be formed as a subroutine, with an RTS instruction at the end. Follow Amiga programming conventions by placing the return value in D0 (or in C, use return(value)).

If you return a nonzero value, the system will call your routine again next time the blitter is idle until you finally return 0. This is done so that you can maintain control over the blitter; for example, it allows you to handle all five bitplanes if you are blitting an object with 32 colors. For display purposes, if you are blitting multiple objects and then saving and restoring the background, you must be sure that all planes of the object are positioned before another object is overlaid. This is the reason for the lockup in the blitter queue; it allows all work per object to be completed before going on to the next one.

{{Note|text=Not all C compilers can handle (*function)() properly! The system actually tests the processor ''status codes'' for a condition of equal-to-zero (Z flag set) or not-equal-to-zero (Z flag clear) when your blitter routine returns. Some C compilers do not set the processor status code properly (i.e., according to the value returned), thus it is not possible to use such compilers to write the (*function)() routine. In that case assembly language should be used. Blitter functions are normally written in assembly language anyway so they can take advantage of the ability of QBlit() and QBSBlit() to pass them parameters in processor registers.}}

The register passing conventions for these routines are as follows. Register A0 receives a pointer to the system hardware registers so that all hardware registers can be referenced as an offset from that address. Register A1 contains a pointer to the current bltnode. You may have queued up multiple blits, each of which perhaps uses the same blitter routine. You can access the data for this particular operation as an offset from the value in A1. For instance, a typical user of these routines can precalculate the blitter register values to be placed in the blitter registers and, when the routine is called, simply copy them in. For example, you can create a new structure such as the following:

<pre>
INCLUDE "exec/types.i"
INCLUDE "hardware/blit.i"

STRUCTURE mybltnode,0
; Make this new structure compatible with a bltnode
; by making the first element a bltnode structure.
STRUCT bltnode,bn_SIZEOF
UWORD bltcon1 ; Blitter control register 1.
UWORD fwmask ; First and last word masks.
UWORD lwmask
UWORD bltmda ; Modulos for sources a, b,and c.
UWORD bltmdb
UWORD bltmdc
UWORD any_more_data ; add anything else you want
LABEL mbn_SIZEOF
</pre>

Other forms of data structures are certainly possible, but this should give you the general idea.

Tells the system whether or not to execute the clean-up routine at the end. This byte should be set to CLEANUP (0x40) if cleanup is to be performed. If not, then the bltnode cleanup variable can be zero.

The value that should be in the VBEAM counter for use during a beam-synchronous blit before the function() is called.

The system cooperates with you in planning when to start a blit in the routine QBSBlit() by not calling your routine until, for example, the video beam has already passed by the area on the screen into which you are writing. This is especially useful during single buffering of your displays. There may be time enough to write the object between scans of the video display. You will not be visibly writing while the beam is trying to scan the object. This avoids flicker (part of an old view of an object along with part of a new view of the object).

The address of a routine that is to be called after your last return from the QBlit() routine. When you finally return a zero, the queuer will call this subroutine (ends in RTS or return()) as the clean-up. Your first entry to the function may have dynamically allocated some memory or may have done something that must be undone to make for a clean exit. This routine must be specified.

Exec Signals

2025-01-26T19:27:19Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

== Exec Signals ==

[[Exec Tasks|Tasks]] often need to coordinate with other concurrent system activities (like other [[Exec Tasks|tasks]] and [[Exec Interrupts|interrupts]]). This coordination is handled by Exec through the synchronized exchange of specific event indicators called ''signals''.

This is the primary mechanism responsible for all inter-task communication and synchronization on the Amiga. This signal mechanism operates at a low level and is designed for high performance. Signals are used extensively by the Exec message system as a way to indicate the arrival of an inter-task message. The message system is described in more detail in [[Exec Messages and Ports]].

{{Note|title=Not for Beginners.|text=This section concentrates on details about signals that most applications do not need to understand for general Amiga programming. For a general overview of signals, see [[Introduction to Exec]].}}

== The Signal System ==

The signal system is designed to support independent simultaneous events, so several signals can occur at the same time. Each task has 32 independent signals, 16 of which are pre-allocated for use by the operating system. The signals in use by a particular task are represented as bits in a 32-bit field in its Task structure (<exec/tasks.h>). Two other 32-bit fields in the Task structure indicate which signals the task is waiting for, and which signals have been received.

Signals are ''task relative''. A task can only allocate its own signals, and may only wait on its own signals. In addition, a task may assign its own significance to a particular signal. Signals are not broadcast to all tasks; they are directed only to individual tasks. A signal has meaning to the task that defined it and to those tasks that have been informed of its meaning.

For example, signal bit 12 may indicate a timeout event to one task, but to another task it may indicate a message arrival event. You can never wait on a signal that you did not directly or indirectly allocate yourself, and any other task that wishes to signal you must use a signal that ''you'' allocated.

=== Signal Allocation ===

As mentioned above, a task assigns its own meaning to a particular signal. Because certain system libraries may occasionally require the use of a signal, there is a convention for signal allocation. It is unwise ever to make assumptions about which signals are actually in use.

Before a signal can be used, it must be allocated with the AllocSignal() function. When a signal is no longer needed, it should be freed for reuse with FreeSignal().

<syntaxhighlight lang="C" line>
BYTE AllocSignal( LONG signalNum );
VOID FreeSignal( LONG signalNum );
</syntaxhighlight>

AllocSignal() marks a signal as being in use and prevents the accidental use of the same signal for more than one event. You may ask for either a specific signal number, or more commonly, you would pass -1 to request the next available signal. The state of the newly allocated signal is cleared (ready for use). Generally it is best to let the system assign you the next free signal. Of the 32 available signals, the lower 16 are reserved for system use (see [[#Reserved_System_Signals|Reserved System Signals]]). This leaves the upper 16 signals free for application programs to allocate. Other subsystems that you may call depend on AllocSignal().

The following example asks for the next free signal to be allocated for its use:

<syntaxhighlight lang="C" line>
if (-1 == (signal = IExec->AllocSignal(-1)))
IDOS->Printf("no signal bits available\n");
else
{
IDOS->Printf("allocated signal number %ld\n", signal);
/* Other code could go here */
IExec->FreeSignal(signal)
}
</syntaxhighlight>

The value returned by AllocSignal() is a signal bit number. This value cannot be used directly in calls to signal-related functions without first being converted to a mask:

<syntaxhighlight lang="C" line>
uint32 mask = 1UL << signal;
or
uint32 mask = (uint32)1 << signal;
</syntaxhighlight>

It is important to realize that signal bit allocation is relevant ''only'' to the running task. You ''cannot'' allocate a signal from another task. Note that functions which create a signal MsgPort will allocate a signal from the task that calls the function. Such functions include OpenWindow() and AllocSysObject(). For this reason, only the creating task may Wait() (directly or indirectly) on the MsgPort's signal. Functions which call Wait() include DoIO(), WaitIO() and WaitPort().

=== Waiting for a Signal ===

Signals are most often used to wake up a task upon the occurrence of some external event. Applications call the Exec Wait() function, directly or indirectly, in order to enter a wait state until some external event triggers a signal which awakens the task.

Though signals are usually not used to interrupt an executing task, they can be used this way. Task ''exceptions'', described in [[Exec_Interrupts|Exec Interrupts]], allow signals to act as a task-local interrupt.

The Wait() function specifies the set of signals that will wake up the task and then puts the task to sleep (into the waiting state).

<syntaxhighlight lang="C" line>
ULONG Wait( ULONG signalSet );
</syntaxhighlight>

Any one signal or any combination of signals from this set are sufficient to awaken the task. Wait() returns a mask indicating which signals satisfied the Wait() call. Note that when signals are used in conjunction with a message port, a set signal bit does not necessarily mean that there is a message at the message port.

See [[Exec_Messages_and_Ports|Exec Messages and Ports]] for details about proper handling of messages.

Because tasks (and interrupts) normally execute asynchronously, it is often possible to receive a particular signal before a task actually Wait()s for it. In such cases the Wait() will be immediately satisfied, and the task will not be put to sleep.

The Wait() function implicitly clears those signal bits that satisfied the wait condition. This effectively resets those signals for reuse. However, keep in mind that a task might get more signals while it is still processing the previous signal. If the same signal is received multiple times and the signal bit is not cleared between them, some signals will go unnoticed.

Be aware that using Wait() will break a Forbid() or Disable() state. Wait() cannot be used in supervisor mode or within interrupts.

A task may Wait() for a combination of signal bits and will wake up when any of the signals occur. Wait() returns a signal mask specifying which signal or signals were received. Usually the program must check the returned mask for each signal it was waiting on and take the appropriate action for each that occurred. The order in which these bits are checked is often important.

Here is a hypothetical example of a process that is using the console and timer devices, and is waiting for a message from either device and a possible break character issued by the user:

<syntaxhighlight lang="C" line>
uint32 consoleSignal = 1L << ConsolePort->mp_SigBit;
uint32 timerSignal = 1L << TimerPort->mp_SigBit;
uint32 userSignal = SIGBREAKF_CTRL_C; /* Defined in <dos/dos.h> */

uint32 signals = IExec->Wait(consoleSignal | timerSignal | userSignal);

if (signals & consoleSignal)
IDOS->Printf("new character\n");

if (signals & timeOutSignal)
IDOS->Printf("timeout\n");

if (signals & userSignal)
IDOS->Printf("User Ctrl-C Abort\n");
</syntaxhighlight>

This code will put the task to sleep waiting for a new character, or the expiration of a time period, or a <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">Ctrl</kbd> + <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">C</kbd> break character issued by the user. Notice that this code checks for an incoming character signal before checking for a timeout. Although a program can check for the occurrence of a particular event by checking whether its signal has occurred, this may lead to busy wait polling. Such polling is wasteful of the processor and is usually harmful to the proper function of the Amiga system. However, if a program needs to do constant processing and also check signals (a compiler for example) SetSignal(0,0) can be used to get a copy of your task's current signals.

<syntaxhighlight lang="C" line>
ULONG SetSignal( ULONG newSignals, ULONG signalSet );
</syntaxhighlight>

SetSignal() can also be used to set or clear the state of the signals. Implementing this can be dangerous and should generally not be done. The following fragment illustrates a possible use of SetSignal().

<syntaxhighlight lang="C" line>
uint32 signals = SetSignal(0,0); /* Get current state of signals */

if (signals & SIGBREAKF_CTRL_C) /* Check for Ctrl-C. */
{
IDOS->Printf("Break\n"); /* Ctrl-C signal has been set. */
IExec->SetSignal(0, SIGBREAKF_CTRL_C) /* Clear Ctrl-C signal. */
}
</syntaxhighlight>

==== Looking for Break Keys ====

One common usage of signals on the Amiga is for processing a user break. The OS reserves 16 of a tasks 32 signals for system use. Four of those 16 signals are used to tell a task about the <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">Ctrl</kbd> + <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">C</kbd>, <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">D</kbd>, <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">E</kbd>, and <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">F</kbd> break keys. An application can process these signals. Usually, only CLI-based programs receive these signals because the Amiga's console handler is about the only user input source that sets these signals when it sees the <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">Ctrl</kbd> + <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">C</kbd>, <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">D</kbd>, <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">E</kbd>, and <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">F</kbd> key presses.

The signal masks for each of these key presses are defined in <dos/dos.h>:

<syntaxhighlight lang="C" line>
SIGBREAKF_CTRL_C
SIGBREAKF_CTRL_D
SIGBREAKF_CTRL_E
SIGBREAKF_CTRL_F
</syntaxhighlight>

Note that these are ''bit masks'' and '''not''' ''bit numbers''.

=== Generating a Signal ===

Signals may be generated from both tasks and system interrupts with the Signal() function.

<syntaxhighlight lang="C" line>
VOID Signal( struct Task *task, ULONG signalSet );
</syntaxhighlight>

For example Signal(tc,mask) would signal the task with the specified mask signals. More than one signal can be specified in the mask. The following example code illustrates Wait() and Signal().

<syntaxhighlight lang="C" line>
// signals.c

#include <exec/types.h>
#include <exec/memory.h>
#include <dos/dos.h>

#include <proto/exec.h>
#include <proto/dos.h>

static CONST_STRPTR VersTag = "$VER: signals 53.1 (20.6.2012)";

void subtaskcode(void); /* prototype for our subtask routine */

struct Task *maintask = NULL;
uint32 mainsig = 0;

int main()
{
BOOL Done = FALSE;
BOOL WaitingForSubtask = TRUE;

/* We must allocate any special signals we want to receive. */
int8 mainsignum = IExec->AllocSignal(-1);
if (mainsignum == -1)
IDOS->Printf("No signals available\n");
else
{
mainsig = 1U << mainsignum; /* subtask can access this global */
maintask = IExec->FindTask(NULL); /* subtask can access this global */

IDOS->Printf("We alloc a signal, create a task, wait for signals\n");

struct Task *subtask = IDOS->CreateTaskTags("subtask", 0, subtaskcode, 16000, TAG_END);

if (subtask == NULL)
IDOS->Printf("Can't create subtask\n");
else
{
IDOS->Printf("After subtask signals, press CTRL-C or CTRL-D to exit\n");

while (!Done || WaitingForSubtask)
{
/* Wait on the combined mask for all of the signals we are
* interested in. All processes have the CTRL_C thru CTRL_F
* signals. We're also Waiting on the mainsig we allocated
* for our subtask to signal us with. We could also Wait on
* the signals of any ports/windows our main task created ... */

uint32 wakeupsigs = IExec->Wait(mainsig | SIGBREAKF_CTRL_C | SIGBREAKF_CTRL_D);

/* Deal with all signals that woke us up - may be more than one */
if (wakeupsigs & mainsig)
{
IDOS->Printf("Signalled by subtask\n");
WaitingForSubtask = FALSE; /* OK to kill subtask now */
}

if (wakeupsigs & SIGBREAKF_CTRL_C)
{
IDOS->Printf("Got CTRL-C signal\n");
Done = TRUE;
}

if(wakeupsigs & SIGBREAKF_CTRL_D)
{
IDOS->Printf("Got CTRL-D signal\n");
Done = TRUE;
}
}
}

IExec->FreeSignal(mainsignum);
}
}

void subtaskcode(void)
{
IExec->Signal(maintask, mainsig);
IExec->RemTask(0); // Remove myself from the system.
}
</syntaxhighlight>

== Reserved System Signals ==

There are 16 signal bits which are reserved for system use. Applications are never allowed to use these signal bits unless explicitly documented (e.g. SIGF_SINGLE).

=== SIGB_ABORT ===

Reserved for system use.

=== SIGB_CHILD ===

Reserved for system use.

=== SIGB_SINGLE (SIGB_BLIT) ===

When a system function needs a Task to stop and IExec->Wait() for a single signal it will use SIGB_SINGLE.

This signal used to be named SIGB_BLIT when it was used to wait on the classic hardware blitter.

=== SIGB_INTUITION ===

Reserved for system use.

=== SIGB_NET ===

Reserved for system use.

=== SIGB_DOS ===

SIGB_DOS is currently used as the wait signal bit for the embedded message port in the process structure. This message port is initialised by the IDOS->CreateNewProc() function. This message port is used by default for DosPacket transactions via IDOS->DoPkt() and IDOS->WaitPkt() and it is also used for sending the initial ACTION_STARTUP DosPacket for DOS handlers. This message port is also where the workbench.library sends the initial struct WBStartup message to every process it starts.

=== SIGBREAKB_CTRL_C ===

The SIGBREAKB_CTRL_C signal bit is used extensively as the general purpose "Break" signal. It is used by all shell handler commands
and many applications to invoke a normal exit of the program. It is up to all applications to follow this recommendation.

Applications should never crash or generally misbehave when receiving a SIGBREAKB_CTRL_C signal bit from any source.

=== SIGBREAKB_CTRL_D ===

The SIGBREAKB_CTRL_D signal bit is used mostly by the shell handler to stop execution of a script file or non-interactive stream. It may also be used by applications.

Applications should never crash or generally misbehave when receiving a SIGBREAKB_CTRL_D signal bit from any source.

=== SIGBREAKB_CTRL_E ===

The SIGBREAKB_CTRL_E signal bit is not currently used by the shell handler but may be used by some other handlers, OS subsystems or multi-process applications for general undefined inter process signaling.

Applications should never crash or generally misbehave when receiving a SIGBREAKB_CTRL_E signal bit from any source.

=== SIGBREAKB_CTRL_F ===

The SIGBREAKB_CTRL_F signal bit is not currently used by the shell handler but may be used by some other handlers, OS subsystems or multi-process applications for general undefined inter process signaling.

Applications should never crash or generally misbehave when receiving a SIGBREAKB_CTRL_F signal bit from any source.

== Signalling with SIGB_SINGLE ==

Many of a task's 32 signal bits are reserved for the operating system's private use, but, like any good rule, there is an exception. One of these bits, the SIGB_SINGLE bit, can be useful to some applications, if used correctly.

Many system functions need to put their task to sleep while waiting for a single event, which requires using one of the task's signals. Rather than forcing each of these system functions to allocate a signal, then Wait(), then deallocate the signal, the operating system
has permanently allocated one signal, the SIGB_SINGLE, for this type of signalling. When a system function needs stop a task to Wait()
for a single signal, it can use SIGB_SINGLE.

The only purpose a program can use SIGB_SINGLE for is Wait()ing because the task cannot call any system functions while it is using SIGB_SINGLE. A program that calls system functions while using SIGB_SINGLE can cause itself and the operating system serious problems because the system functions can use SIGB_SINGLE as well. If a program calls a system function while using SIGB_SINGLE, two bad
things can happen:

1) The errant task's event takes place before the system function waits on SIGB_SINGLE (or while the system function is waiting on
SIGB_SINGLE). In this case, the system function will think its event has taken place because its signal became set. The errant task will never find out that its event has taken place, as the system function will clear the SIGB_SINGLE bit after Wait()ing on it.

2) The errant task's event and the system function's event take place while the system function is waiting on SIGB_SINGLE. In this case,
the system function will function normally, clear the SIGB_SINGLE bit, and exit. The errant task will never know that its event has
taken place.

Before Wait()ing on SIGB_SINGLE, clear it using SetSignal():

<syntaxhighlight lang="C" line>
IExec->SetSignal(0, SIGF_SINGLE); // Note SIGF_SINGLE is the bit mask. SIGB_SINGLE is the signal bit.
</syntaxhighlight>

This step is necessary because it is possible that the last system function that used the SIGB_SINGLE signal did not clear the SIGB_SINGLE bit.

Also, an application should not wait on other signals while it is waiting on SIGB_SINGLE. Waiting on other signals at the same time
makes it possible for a program to wake up while the SIGB_SINGLE is still outstanding. If this happens, the program will still have to
go back to sleep, which requires calling a system function.

=== SIGB_SINGLE Example ===

Below is a simple example of using the SIGB_SINGLE signal. It starts a child process and waits for that child process to signal
the main process using the SIGB_SINGLE signal.

<syntaxhighlight lang="C" line>
// This example program illustrates simple usage of the SIGB_SINGLE
// signal for "single shot" signalling. This signal is one of the
// system private signals, but applications can use it in certain
// cases, but only if used carefully. Specifically, applications
// should use it only to Wait() on, and using only that signal
// (applications cannot Wait() on other signals in the same
// Wait()). Not following these rules can cause serious system
// problems.

#include <exec/types.h>
#include <exec/memory.h>
#include <dos/dosextens.h>
#include <dos/dostags.h>

#include <proto/exec.h>
#include <proto/dos.h>

#include <stdio.h>

int32 childprocesscode(void); /* prototype for our childprocess routine. */

struct Process *mainprocess = NULL, *childprocess = NULL;
UBYTE childprocessname[] = "RKM_signal_childprocess";

BPTR output;

int main(int argc, char **argv)
{
if (output = IDOS->Open("CONSOLE:", MODE_OLDFILE)) /* Open the console for the */
/* child process. */
{
mainprocess = (struct Process *)IExec->FindTask(NULL); /* childprocess can */
/* access this global.*/

if (childprocess = IDOS->CreateNewProcTags(
NP_Entry, childprocesscode, /* The child process */
NP_Name, childprocessname,
NP_Output, output,
NP_FreeSeglist, FALSE,
NP_CloseOutput, TRUE,
NP_Child, TRUE,
TAG_END))
{
IDOS->Printf("Main Process: Created a child process and waiting on SIGB_SINGLE.\n");

IDOS->FFlush(IDOS->Output()); /* Make sure the Printf() above appears */
/* in the console window before the child */
/* process starts printing to the console. */

IExec->SetSignal(0, SIGF_SINGLE); /* Use SIGF_SINGLE only after */
/* clearing it. */

/* Wake up the child. */
IExec->Signal((struct Task *)childprocess, SIGBREAKF_CTRL_F);

IExec->Wait(SIGF_SINGLE); /* Only use SIGF_SINGLE for Wait()ing and */
/* Wait on that signal alone! */

IDOS->Printf("Main Process: Received signal from child.\n");
}
else
IDOS->Printf("Main Process: Can't create child process. Exiting.\n");
}
else
IDOS->Printf("Main Process: Can't open CONSOLE:. Exiting.\n");
}

int32 childprocesscode(void) /* This function is what CreateNewProcTags() */
{ /* loads as the child process. This child */
/* signals the parent using SIGF_SINGLE. */

/* Wait for a startup signal. This is to allow the parent process to
* print its banner message and clear SIGF_SINGLE.
*/
IExec->Wait(SIGBREAKF_CTRL_F);

IDOS->Printf("Child Process: I'm alive and starting a 5 second TimeDelay()");
IDOS->FFlush(IDOS->Output());

for (uint32 x = 0; x < 5; x++)
{
IDOS->Delay(50); /* Delay for 5 seconds, printing a */
IDOS->Printf(" ."); /* dot during each second. */
}

IDOS->Delay(50);

IDOS->Printf(" Finished.\n");
IDOS->Printf("Child Process: Signalling main process and exiting. Bye.\n");
IDOS->FFlush(IDOS->Output());

IExec->Signal((struct Task *)mainprocess, SIGF_SINGLE); /* Finished waiting, */
/* signal the main */
/* process and exit */
/* child process. */
return 0;
}
</syntaxhighlight>

== Function Reference ==

The following chart gives a brief description of the Exec functions that control task signalling. See the SDK for details about each call.

{| class="wikitable"
! Exec Signal Function
! Description
|-
| AllocSignal()
| Allocate a signal bit.
|-
| FreeSignal()
| Free a signal bit allocated with AllocSignal().
|-
| SetSignal()
| Query or set the state of the signals for the current task.
|-
| Signal()
| Signal a task by setting signal bits in its Task structure.
|-
| Wait()
| Wait for one or more signals from other tasks or interrupts.
|}

How to Build Stubs for 68k Libraries

2025-01-26T19:27:08Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= Author =

Roman Kargin 
Copyright © 2013 Roman Kargin 
Proofreading and grammar corrections by the AmigaOS Wiki team. 

= Introduction =

The idea for this tutorial came from when we was playing with Dopus5 source code and wanted to make one single function from the 68k version of dopus5.library to work from native AmigaOS 4 code. While we have all kind of auto generation tools to build all kind of protos/interfaces/inlines/stubs/etc, it still wasn't clear to me how to do what I needed.

Since the beginning a very helpful article was Thomas Rapp's [http://thomas-rapp.homepage.t-online.de/ppclib.html How to create PPC stubs for M68K libraries] where he shows how to use fd2pragma and IDLTool to build a jpeg.l.main stub from a 68k jpeg.library, as well as helpful answers from Fredrik Wikstrom. In the end, all this information was important to write down so I put everything into this tutorial. I hope other developers will find it useful.

= PowerPC->68k Glue Stubs =

While 68k libraries are old and almost all libraries on AmigaOS today are PowerPC native ones, there are still some old AmigaOS 3.x libraries which are necessary and have no native PowerPC replacement. In that case we need to create for them necessary PowerPC->68k glue stub files, so we can call those 68k library routines from native, PowerPC code, or, we can use EmulateTags(). The latter makes it easy for your code to use both PowerPC and 68k native libraries transparently with only a small bit of small overhead; just a few instructions. But this only works when the PowerPC native code is available and when there are just a few functions in the library. Quite often, you just don't want to deal with all this because of the large number of functions in a 68k library and the different ways of using them from the code. In this case, creating of PowerPC->68k stubs is a simpler and faster way.

For a better explanation of what a PowerPC->68k stub is, refer to the [[Migration_Guide|Migration Guide]]. In short, if you have, let's say, the 68k version of dopus5.library and want to use it from native AmigaOS 4 binaries then you need to create dopus5.l.main. When code in your native binary needs to interface to a old AmigaOS3 library, the system (ramlib to be more precise) will automatically scan its library search path for the file "dopus5.l.main" and if found, it will open it and obtain the interface from there. That l.main file is pure non-startup code which contains the necessary stubs. You do not need to write the stubs from scratch manually. This is a job for different set of tools (fd2pragma, fdtrans and IDLTool). The library.l.main code consists of 2 files if you auto generate them: PowerPC->68k cross call stubs and vectors. Of course you can write them from scratch manually, but its a pain and there are already tools which do it for you.

The name of the file in general does not matter. A library does not necessarily have to be named ".library" and could be named ".module" or whatever. Ramlib will search for the first "." in the library name, starting from the end, the first part up to and including the dot plus one more character, usually the 'l' in library, is used, another dot is appended, then the interface name is added. It then calls the exec function.

For example, if the interface name is 'main' and the library name is 'foobar' then this is what it looks for:

foobar.library -> foobar.l.main
foobar.blabla -> foobar.b.main
foobar.module -> foobar.m.main

{{Note|text=Because of the way RamLib parses glue-stubs names, you can't call your glue stub for "foobar.library" as "foobar.library.main". It is understandable from the explanation above, but it can be misleading when you run for example "snoopy" and can see how it tries to search for "foobar.library.main", but it didn't tries to search for a file, just for "resident" code in memory. The real file ramlib will look for is only foobar.l.main when the main library is called as foobar.library.}}

{{Note|text=You can't put your glue stub files in directories other than PROGDIR:, PROGDIR:Libs or LIBS: as RamLib will not find them. If you have let's say a directory "modules" where you store some of your plugins (which in reality are libraries), then you can't put your glue stub files in the same "modules" directory, but to the place mention above.}}

= pragmas/fd/sfd/protos =

Often, old 68k libraries were not done with GCC. On old m68k machines, SAS/C was the popular C compiler and pure assembler was even more popular for everyday needs. So many of those old libraries were provided with includes for SAS/C only or for assembler (like .i files) or a mix of the two. You may have such library with which you have only a pragma file and a bunch of proto files for functions which are present in more than one proto file (i.e. no .fd file at all, no single include with all protos). The first thing to do is to create a single proto file from those different proto files you have in different places, manually make your .fd file from pragma (check all offsets and order how they are placed in pragma file, and in the same order put them to your new .fd). Then when you have only one proto file and one .fd file, you can generate a .sfd file and an .xml one with fd2pragma. Then generate from it all includes/vectors/stubs and only after that you can generate lib.l.main :) Usually its not that hard, and most old libraries have .fd files and a single proto include file, but sometimes you will have to do it for difficult libs, so you will know what to do.

All we need to know now is that libraries have a jump table. Jump tables are a list of library functions at specific offsets. Offsets can't be changed because they are function offsets in the library that your code will call. Be it with the old SAS/C, an assembler or the new GCC on AmigaOS 4, if we work with a 68k library and create any fd/proto files from scratch then the offsets should always be the same.

For example you have dopus_pragmas.h file and dopus.fd files (fd files are a standard way to describe the interface for libraries) and dopus_pragmas entries look like this:

<syntaxhighlight lang="C" line>
#pragma libcall DOpusBase RemovedFunc0 1e 0
#pragma libcall DOpusBase Random 24 001
#pragma libcall DOpusBase Atoh 2a 0802
....
</syntaxhighlight>

It means that the first "user" library function in a jump table starts at offset 0x1e (30) and then multiply by 6 for every function. So first function is at 30 (0x1e), second one is at 36 (0x24), the next one is at 42 (0x2a) and so on for all the functions. That means that if for example function Atoh() in the jump table is placed at offset 0x2a, then every single code and includes file which we will generate for AmigaOS 4 should respect that jump-table offset.

If we look at the dopus_lib.fd file we see:

<syntaxhighlight lang="C" line>
* "dopus.library"
##base _DOpusBase
##bias 30
*
* Support routines for Directory Opus and associated programs
* (c) Copyright 1995 Jonathan Potter
*
##public
RemovedFunc0()()
Random(limit)(d0)
*
Atoh(str,len)(a0,d0)
....
</syntaxhighlight>

This means that public functions start from offset 30 (bias 30), and they are placed in the same order as they are in the pragma file. So if you change the order of function names in the FD file you will end calling a function instead of another one, which of course means crashes, bugs and problems.

So respect offsets in the jump table.

Note that .sfd files work like .fd files but with more possibilities. You won't find them in old 68k dev archives of libraries as its something new. They contain a lot more information than .fd and are easier to use. But more or less they follow the same logic, the same respect for offsets, etc. To see a full description of .fd and .sfd formats check the fd2pragma guide.

= Now What? =

We have 2 methods to build lib.l.main and required includes. But for both of them you need .fd file as a minimum (if you have .sfd its even better), and a proto file which will describe all (or not all) your functions. While .fd/.sfd should be done by the original developer, you still can make them from scratch if you have a pragma file with lib calls (you make this file with the same order and the same offsets). If you don't have one proto file, but many in different includes, then you can make your own one, just copy one by one all the protos from all the include files, while all your FD entries will not have necessary proto descriptions in proto file (by the way, if you don't have proto for some functions, then entries from the fd/sfd file will be reserved when you will auto generate AmigaOS code/includes, so respect offsets).

Let's say we have dopus_lib.fd and only protos in different includes in different places. We then create proto file from all those includes (in referring to the dopus_lib.fd), and then auto-tools time coming. As I say we have 2 ways:

== Method 1: fdtrans + sfd ==

1. generate a .sfd file:

ram:> fd2pragma dopus5_lib.fd clib our_proto.h special 112
SourceFile: dopus5_lib.fd
ResultFile: dopus5_lib.sfd

2. generate xml and ppc->68k crosscall stubs via fdtrans:

ram:> fdtrans dopus5_lib.sfd -x -s

Change manually in the cross call-stubs file (dopus5.c) "main_vectors" in "main_v1_vectors", as it seems some typo between different tools. No other changes is needed, fdtrans automatically insert including of interface (while fd2pragma will skip it, see later).

3. generate proto/interface/inline (i.e. includes) and vectors:

ram:> idltool -p -i -n -c dopus5.xml

4. build dopus5.l.main
ram:> gcc -Iinclude -nostartfiles dopus5.c -o dopus5.l.main

5. build a test program to use one function from dopus5.library, here StrConcat()

<syntaxhighlight lang="C" line>
#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/dopus5.h>

struct Library *DOpusBase;
struct DOpusIFace *IDOpus;

int main(int argc, char **argv)
{
TEXT buffer[256] = "First part-";
CONST_STRPTR concat = "Second part";

// Need dopus library
if (!(DOpusBase = IExec->OpenLibrary("PROGDIR:dopus5.library", 1))) {
IDOS->Printf("Can't open library\n");
}
else {
if (!(IDOpus = (struct DOpusIFace*)IExec->GetInterface(DOpusBase, "main", 1, NULL))) {
IDOS->Printf("Can't get interface\n");
}
else {
IDOpus->StrConcat(buffer, concat, 36);
IDOS->Printf("Result=%s\n", buffer);

IExec->DropInterface((struct Interface*)IDOpus);
}

IExec->CloseLibrary(DOpusBase);
}

return 0;
}
</syntaxhighlight>

ram:> gcc -Iinclude testcase-native-fdtrans.c
ram:> a.out
ram:> Result=First part-Second part

It works!

== Method 2: fd2pragma + fd ==

1. Create an XML file:

ram:> fd2pragma dopus5_lib.fd clib proto.h special 140
SourceFile: dopus5_lib.fd
Resultfile: dopus5.xml

2. generate ppc->68k crosscall stubs:

ram:> fd2pragma dopus5_lib.fd clib proto.h special 141
SourceFile: dopus5_lib.fd
Resultfile: dopus5.c

In the result file (dopus5.c) manually add including of interfaces/dopus5.h file and replace value "main_vectors" with "main_v1_vectors"

3. generate proto/interface/inline (i.e. includes) and vectors:

ram:> idltool -p -i -n -c dopus5.xml

4. build dopus5.l.main

ram:> gcc -Iinclude -nostartfiles dopus5.c -o dopus5.l.main

5. build a test program (its a bit different compared to the previous test program because the name of the interface is a bit different (big/small letters, 5 at end, etc) :

<syntaxhighlight lang="C" line>
#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/dopus5.h>

struct Library *DOpusBase;
struct Dopus5IFace *IDopus5;

int main(int argc, char **argv)
{
TEXT buffer[256] = "First part-";
CONST_STRPTR concat = "Second part";

// Need dopus library
if (!(DOpusBase = IExec->OpenLibrary("PROGDIR:dopus5.library", 1))) {
IDOS->Printf("Can't open library");
}
else {
if (!(IDopus5 = IExec->GetInterface(DOpusBase, "main", 1, NULL))) {
IDOS->Printf("Can't get interface");
}
else {
IDopus5->StrConcat(buffer, concat, 36);
IDOS->Printf("Result=%s\n", buffer);

IExec->DropInterface((struct Interface*)IDopus5);
}

IExec->CloseLibrary(DOpusBase);
}

return 0;
}
</syntaxhighlight>

Then hard-reboot is needed if you did the previous test with dopus5.l.main done from fd2trans as it is still in memory (and it can freeze the OS because of different code of the same stub libs), and then:

ram:> gcc -Iinclude testcase-native-fd2pragma.c
ram:> a.out
ram:> Result=First part-Second part

It works as well!

== Conclusion ==

Which method is better? In my opinion, the fdtrans one because:

# You need less changes (no need to manually include interfaces/dopus5.h file).
# The code of stubs from fdtrans look better and cleaner in comparison with the code of stubs from fd2pragma. For example even small things like comments saying what values in hex mean in your offset jump table is pretty nice (especially when you work manually with pragmas, where hex offsets are present).
# Size of dopus.l.main done from fd2pragma output is larger in comparison with the size of dopus.l.main created from fdtrans output.

= I want one single function to work =

Now for something interesting. You may want to check if it all works from AmigaOS 4 and with your new lib.l.main and native AmigaOS includes, code, etc. You then choose any "simple" function from the library and make a simple AmigaOS 4 native test program for it. Let's say it will be the StrConcat() function from dopus5.library, which is described in the pragma file as:

<syntaxhighlight lang="C" line>
#pragma libcall DOpusBase StrConcat 47a 09803
</syntaxhighlight>

and in dopus_lib.fd like:

<syntaxhighlight lang="C" line>
StrConcat(s1,s2,len)(a0/a1,d0)
</syntaxhighlight>

We then simply calculate:

1. 0x47a = 1146 
2. 1146 / 6 = 191 
3. 191 - 4 (i.e. 30/6 from beginning 5, but 30 is our first one, so -4) = 187 

i.e. entry in jump table for StrConcat is 187. The entry in the dopus_lib.fd file for Strconcat is also 187 in the list of functions (+ header of .fd)

In other words you can build your .fd file from scratch, which will look like this:

<syntaxhighlight lang="C" line>
* "dopus.library"
##base _DOpusBase
##bias 30
*
* Support routines for Directory Opus and associated programs
* (c) Copyright 1995 Jonathan Potter
*
##public
aa()()
aa()()
aa()()
aa()()
.... 186 entries to fill the gap in jump table ....
StrConcat(s1,s2,len)(a0/a1,d0)
....
##end
</syntaxhighlight>

Obviously, you can go the more elegant way and use .sfd instead, which have "reserved" keyword, so no need to put all those empty-functions like:

<syntaxhighlight lang="C" line>
==id $Id: dopus5_lib.sfd,v 1.0 2013/03/29 09:24:08 noname Exp $
* "dopus5.library"
==base _DopusBase
==basetype struct Library *
==libname dopus5.library
==bias 30
==public
==include <exec/types.h>
==reserve 186
BOOL StrConcat(char * s1, char * s2, int len) (a0,a1,d0)
==end
</syntaxhighlight>

And when you will generate all necessary stuff via fd2grama/fdtrans/idltool from .fd or from .sfd, offsets will be respected. When you will call IDopus->StrConcat(blablab) from your code it will work because StrConcat will be found in the jump-table at the right offset.

= Final words =

As usual, there is nothing hardcore in here. This is just a short article about the problems which I encountered. I hope that it can be of any help for new developers. Thanks to Fredrik Wikstrom for hints about offsets calculation, Colin Wenzel for explaining how RamLib works when it scans paths for stubs, to Jeffrey Gilpin for his knowledge and many others for proofreading and grammar corrections.

= Links =

[1] Libraries and devices: https://wiki.amigaos.net/wiki/Libraries_and_Devices

[2] RamLib autodoc.

[3] fd2pragma guide from: http://aminet.net/dev/misc/fd2pragma.lha

[4] How to create PPC stubs for M68K libraries: http://thomas-rapp.homepage.t-online.de/ppclib.html

Intuition Input and Output Methods

2025-01-26T19:26:50Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

== Intuition Input and Output Methods ==

This article discusses the input and output (I/O) techniques used with Intuition. I/O facilities are also available through Exec's device subsystems, such as the console, serial and parallel devices. For more information on these, see [[Devices|Devices]].

For graphical output to the Amiga's display, programs can use Intuition's drawing features or handle rendering directly through calls to the graphics library. See the graphics library articles for more information on display rendering. For more about Intuition's drawing features see [[Intuition_Images,_Line_Drawing_and_Text|Intuition Images, Line Drawing and Text]].

== Overview of System I/O ==

This section provides a very simplified model of how Amiga I/O and application programs interact. The main elements of the Amiga's I/O system are shown in the diagram below. Input events begin when mouse movement is detected by the gameport device or key presses are received by the keyboard device. These and other input events are merged into a single stream by the input device, which then submits the stream to Intuition for further processing.

[[File:LibFig9-1.png|frame|center|Amiga Input Block Diagram]]

The application program can receive its input from Intuition or the Console device. The application may choose to listen to neither, one or both of these input sources.

[[File:LibFig9-2.png|frame|center|Amiga Output Block Diagram]]

An application's display output can go through the high level interfaces of the console device or through the Intuition library. Additionally, display output may be sent directly to the graphics library. Notice that both the Console and Intuition call the graphics library to render to the display.

== Intuition Input ==

The Amiga has an input device to monitor all input activity. The input activity nominally includes keyboard and mouse events, but which can be extended to include other types of input signals. When the user moves the mouse, presses a mouse button or types on the keyboard, the input device detects the activity from the specific device, and constructs an InputEvent.

An InputEvent is a message describing a single event, such as the transition of a key on the keyboard from up to down.

The input device then passes the input events down a prioritized chain of input handlers, which are routines in memory that process the input events. The sequence of input events passing through this chain of input handlers is known as the ''input stream''. Any handler linked into this chain can monitor and modify the event stream.

Each input handler may block (consume) events, allow events to pass through to the next handler in the chain or add new events to the sequence.

Other devices and programs can add input events to the input stream by sending messages to the input device. For instance, AmigaDOS is able to generate an input event whenever a disk is inserted or removed.

See the [[Input Device]] for more information on the Input device.

=== Intuition as an Input Handler ===

Intuition is an input handler linked into the input stream, and it monitors and modifies events that it receives. The input arrives at Intuition as a single stream of events. These events are filtered, altered, and enhanced by Intuition, then dispatched to windows as appropriate, or passed down to input handlers lower in the chain. If the active window has a console attached to it, then it can receive the input events that are still left in the stream, which can include some events that Intuition played a role in forming.

Many kinds of input event undergo little conversion by Intuition. For instance, raw keyboard events are not modified by Intuition (with the exception of a few keystrokes that have special meaning). Other events may produce differing results based on Intuition's view of the system. For example, when the mouse select button is pressed, the event may become a gadget down-press event, a window activation event, or it may remain a simple button press, depending on the mouse position and the arrangement of windows and screens. Still other events are consumed by Intuition, and the application is not directly notified. An example would be when the select button is pressed over a system gadget.

Intuition is also the originator of certain kinds of events. For example, a window-refreshing event is generated when Intuition discovers that part of a window is in need of redrawing. This might have resulted indirectly from some other input (for example, the user might have dragged a window), but not necessarily (the refresh might have been necessitated by a program bringing a window to the front).

=== Receiving Input Events from Intuition ===

There are two channels through which a window can receive events destined for it. The usual way is for the application to ask Intuition to send it messages which are based on the input event that Intuition has processed. These messages, called IntuiMessages, are standard Amiga Exec messages, and are sent to a port called an Intuition Direct Communications Message Port, or IDCMP. Every window may have an IDCMP associated with it (pointed to by Window.UserPort).

There are many classes of IntuiMessages, and the application can control which classes of events are routed to its window's port by setting the appropriate IDCMP flags. When Intuition has an event to send, but the window does not have the corresponding IDCMP flag set, the event is generally passed along to the next input handler in the chain. One input handler that resides below Intuition's is the console device's handler. If your application's window has a console attached to it, the console device will generally convert events it receives into console code sequences, and send those to your console. In this manner, you can hear these events.

Because IntuiMessages and the IDCMP are the primary way in which applications receive communication from Intuition, discussions elsewhere in the manual frequently refer to events from Intuition as messages, IntuiMessages, or IDCMP messages. However, most of the information sent as IntuiMessages is also available through the console device, though that option is used less often. Elsewhere in this article, you can learn how getting your events through the console differs from getting them through your IDCMP.

Whichever way an application chooses to get its messages, it is frequently designed to be event-driven. That is to say, after some amount of initialization, the application will go into a state where it is waiting for some event to happen. This event could be an input event, or some other kind of event. Based on the event received, the application would take appropriate action, and return to its waiting state.

=== IDCMP Events and the Input Focus ===

Although at any given time many applications may be waiting for input, in most cases only the active application (the one with the currently active window) will receive IDCMP messages.

Since the IDCMP messages are, in general, directed to a single window, this window is said to have the ''input focus''; the input from a variety of sources is focused on this single location.

The active window is generally selected by the user, although it is possible for applications to change the active window. See [[Intuition_Windows|Intuition Windows]] for information on selecting or setting the active window. Be aware that changing the active window will change the input focus. Usually this change is performed following user action; the user selects a window with the mouse, or activates a new application. Changes to the input focus without user control, such as activating another window while the user is working in an application, may confuse the user. Perform such changes with great care.

Not all events are sent only to the active IDCMP. Some events, such as "disk inserted," may be useful to many programs, so Intuition translates these events into separate messages, one for each application.

== Intuition Output ==

Visual program output, the information written to the display, is sent through one of three channels.

* Imagery may be sent to the graphics library primitives. Graphics library includes functions for line drawing, area fill, specialized animation and output of text. See [[Graphics_Primitives|Graphics Primitives]], [[Graphics_Library_and_Text|Graphics Library and Text]] and [[Graphics_Sprites,_Bobs_and_Animation|Graphics Sprites, Bobs and Animation]] for more information on these functions.

* Use the Intuition library support functions for rendering text, graphical imagery, and line drawing. These provide some of the same functions as the graphics library routines, but the Intuition functions perform more of the detail work for you. See [[Intuition_Images,_Line_Drawing_and_Text|Intuition Images, Line Drawing and Text]] for more information on Intuition rendering functions. Also see, of course, the articles on screens, windows, gadgets menus and requesters for information on managing the display.

* Output character-based data via the console device. The console device is discussed in the next section.

== Console Device I/O ==

A program receives its input stream either directly from Intuition or via another mechanism known as the console device.

The console device may be used both as a source for input and as a mechanism for output. Often, it is convenient to use only the console device for input and output. In particular, character-based programs can open the console and use it for all I/O without worrying about windows, bitmaps, or message ports.

The console device gives the program "cooked" input data, including key code conversions to ASCII and conversions of Intuition generated events, such as IDCMP_CLOSEWINDOW, to ANSI escape sequences.

The console device output provides features such as automatic line wrapping and scrolling. If an application just wants to output text, it may choose to use the console device, which provides formatted text with little fuss.

If the application is not character-based, it may be better for the it to use an IDCMP for input and render graphics and text directly through Intuition and the graphics library primitives.

If necessary, it is possible to open both the console device and an IDCMP for input. Such a program might need ASCII input, formatted output and the IDCMP verification functions (for example, to verify that it has finished writing to the window before the user can bring up a requester).

For more information on the console device, see the [[Console_Device|Console Device]].

== Using the IDCMP ==

The IDCMP allow the application to receive information directly from Intuition. The program can use the IDCMP to learn about mouse, keyboard and other Intuition events. Also, certain useful Intuition features, most notably the verification functions (described under "IDCMP Flags" below), require that the IDCMP be opened, as this is the only mechanism available for accessing these features.

The IDCMP consists of a pair of message ports, which may be allocated and initialized by Intuition at the request of the program. Alternately, the application may choose to manage part of the allocation, such that one port is supplied by the application and one port is supplied by Intuition. These ports are standard Exec message ports, used to allow interprocess communications in the Amiga multitasking environment. To learn more about message ports and message passing, see [[Exec_Messages_and_Ports|Exec Messages and Ports]].

The IDCMP is always associated with a window, it is not possible to have an IDCMP without an open window. The IDCMP is made up of several fields in the Window structure:

; IDCMPFlags
: stores the IDCMP flags currently set for this port. This field should never be directly set by the application; use the function ModifyIDCMP() or set them when the window is opened instead.

; UserPort
: is a pointer to the standard Exec message port where the application receives input event messages from Intuition

; WindowPort
: is a pointer to the reply message port used by Intuition. The messages sent by Intuition are set up such that ReplyMsg() will return them to this port.

To open these ports automatically, set at least one of the IDCMP flags in the OpenWindowTagList() call. To free these ports later in the program, call the function ModifyIDCMP() with NULL for the IDCMP flags or simply close the window.

{{Note|title=Don't Reply Any Messages After the IDCMP is Freed|text=If an IDCMP is freed, either by calling ModifyIDCMP() or by closing the window, Intuition will reclaim and deallocate all messages waiting at that port without waiting for a ReplyMsg(). If the program attempts to ReplyMsg() to an IntuiMessages after the IDCMP is closed, the system will probably crash.}}

If the IDCMP flags are NULL when the window is opened, no ports will be allocated when the window is created. To have Intuition allocate these ports later, call the function ModifyIDCMP() with any of the IDCMP flags set.

Once the IDCMP is opened, with the ports allocated, the program can receive many types of information directly from Intuition, based on the IDCMP flags that are set.

The IDCMP allows the application to receive only the events that it considers important. The program can, for instance, choose to learn about gadget events but may not want to learn about other mouse or keyboard events. This is done by providing a "filter" or "mask" value for the IDCMP which tells Intuition which events it should send to this specific port. Only messages with a type matching one of the flags set in the Window structure's IDCMPFlags field will be sent to this port. These values may be set at creation time, or modified by calling the function ModifyIDCMP().

Messages sent to the IDCMP are instances of the structure IntuiMessage. This is an extended form of the Exec Message structure which allows Intuition to send user interface specific information to the application. The IntuiMessage structure is discussed at length below.

After the application opens an IDCMP, it must monitor the port for messages. At a minimum, this involves removing all messages from the port and replying to them. An event loop which processes messages arriving at the IDCMP is discussed below.

=== Standard IntuiMessage Event Loop ===

The application should handle events quickly. Any delay in this handling will make the user interface appear sluggish to the user. Additionally, certain events such as IDCMP_SIZEVERIFY may time-out if the application does not respond to them quickly (this is to help prevent system deadlocks). The action taken by Intuition when an event times-out may not match the action desired by the program. When IDCMP_SIZEVERIFY times out, the window sizing operation is cancelled by Intuition.

Code should be able to handle the case where there are multiple events waiting at the port. When events are being generated quickly, Intuition may post many events to the IDCMP before the application regains control. This can happen regardless of how fast the application processes the messages waiting at the port. Since messages queue up but signals do not, the application may not see a signal for each message posted. Because of these facts, the code should remove all the messages waiting at the port, regardless of the number, each time Wait() returns.

Code should also be able to handle the case where the signal is set but no events are waiting at the port. This could happen if a new message arrives at the IDCMP while an application is still processing the previous message. Since applications typically process all queued messages before returning to Wait(), the second message gets handled with the signal bit still set. The subsequent call to Wait() will return immediately even though no message is present. These cases should be quietly ignored.

=== Event Loop Example ===

This example shows how to receive Intuition events. It reports on a variety of events: close window, keyboard, disk insertion and removal, select button up and down and menu button up and down. Note that the menu button events will only be received by the program if the WA_RMBTrap attribute is set for the window.

<syntaxhighlight lang="C" line>
/*
** eventloop.c - standard technique to handle IntuiMessages from an IDCMP.
*/
#include <exec/types.h>
#include <intuition/intuition.h>

#include <proto/dos.h>
#include <proto/exec.h>
#include <proto/intuition.h>

/* our function prototypes */
BOOL handleIDCMP(struct Window *win, BOOL done);

struct Library *IntuitionBase = NULL;
struct IntuitionIFace *IIntuition = NULL;

/*
** main routine.
** Open required library and window, then process the events from the
** window. Free all resources when done.
*/
int main(int argc, char **argv)
{
BOOL done;
struct Window *win;

IntuitionBase = (struct IntuitionBase *)IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace *)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
if (IIntuition != NULL)
{
if (win = IIntuition->OpenWindowTags(NULL,
WA_Title, "Press Keys and Mouse in this Window",
WA_Width, 500,
WA_Height, 50,
WA_Activate, TRUE,
WA_CloseGadget, TRUE,
WA_RMBTrap, TRUE,
WA_IDCMP, IDCMP_CLOSEWINDOW | IDCMP_VANILLAKEY |
IDCMP_RAWKEY | IDCMP_DISKINSERTED |
IDCMP_DISKREMOVED | IDCMP_MOUSEBUTTONS,
TAG_END))
{
done = FALSE;

/* perform this loop until the message handling routine signals
** that we are done.
**
** When the Wait() returns, check which signal hit and process
** the correct port. There is only one port here, so the test
** could be eliminated. If multiple ports were being watched,
** the test would become:
**
** signals = Wait( (1L << win1->UserPort->mp_SigBit) |
** (1L << win2->UserPort->mp_SigBit) |
** (1L << win3->UserPort->mp_SigBit))
** if (signals & (1L << win1->UserPort->mp_SigBit))
** done = handleWin1IDCMP(win1,done);
** else if (signals & (1L << win2->UserPort->mp_SigBit))
** done = handleWin2IDCMP(win2,done);
** else if (signals & (1L << win3->UserPort->mp_SigBit))
** done = handleWin3IDCMP(win3,done);
**
** Note that these could all call the same routine with different
** window pointers (if the handling was identical).
**
** handleIDCMP() should remove all of the messages from the port.
*/
while (!done)
{
uint32 signals = IExec->Wait(1L << win->UserPort->mp_SigBit);
if (signals & (1L << win->UserPort->mp_SigBit))
done = handleIDCMP(win,done);
};
IExec->CloseWindow(win);
}
}

IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);
return 0;
}

/*
** handleIDCMP() - handle all of the messages from an IDCMP.
*/
BOOL handleIDCMP(struct Window *win, BOOL done)
{
struct IntuiMessage *message;
uint16 code;
int16 mousex, mousey;
uint32 class;

/* Remove all of the messages from the port by calling GetMsg()
** until it returns NULL.
**
** The code should be able to handle three cases:
**
** 1. No messages waiting at the port, and the first call to GetMsg()
** returns NULL. In this case the code should do nothing.
**
** 2. A single message waiting. The code should remove the message,
** processes it, and finish.
**
** 3. Multiple messages waiting. The code should process each waiting
** message, and finish.
*/
while (NULL != (message = (struct IntuiMessage *)IExec->GetMsg(win->UserPort)))
{
/* It is often convenient to copy the data out of the message.
** In many cases, this lets the application reply to the message
** quickly. Copying the data is not required, if the code does
** not reply to the message until the end of the loop, then
** it may directly reference the message information anywhere
** before the reply.
*/
class = message->Class;
code = message->Code;
mousex = message->MouseX;
mousey = message->MouseY;

/* The loop should reply as soon as possible. Note that the code
** may not reference data in the message after replying to the
** message. Thus, the application should not reply to the message
** until it is done referencing information in it.
**
** Be sure to reply to every message received with GetMsg().
*/
IExec->ReplyMsg((struct Message *)message);

/* The class contains the IDCMP type of the message. */
switch (class)
{
case IDCMP_CLOSEWINDOW:
done = TRUE;
break;
case IDCMP_VANILLAKEY:
IDOS->Printf("IDCMP_VANILLAKEY (%lc)\n",code);
break;
case IDCMP_RAWKEY:
IDOS->Printf("IDCMP_RAWKEY\n");
break;
case IDCMP_DISKINSERTED:
IDOS->Printf("IDCMP_DISKINSERTED\n");
break;
case IDCMP_DISKREMOVED:
IDOS->Printf("IDCMP_DISKREMOVED\n");
break;
case IDCMP_MOUSEBUTTONS:
/* the code often contains useful data, such as the ASCII
** value (for IDCMP_VANILLAKEY), or the type of button
** event here.
*/
switch (code)
{
case SELECTUP:
IDOS->Printf("SELECTUP at %d,%d\n",mousex,mousey);
break;
case SELECTDOWN:
IDOS->Printf("SELECTDOWN at %d,%d\n",mousex,mousey);
break;
case MENUUP:
IDOS->Printf("MENUUP\n");
break;
case MENUDOWN:
IDOS->Printf("MENUDOWN\n");
break;
default:
IDOS->Printf("UNKNOWN CODE\n");
break;
}
break;
default:
IDOS->Printf("Unknown IDCMP message\n");
break;
}
}
return(done);
}
</syntaxhighlight>

=== Setting up a Custom User Port ===

An application can use its own message port for the IDCMP instead of the one set up by Intuition, although some care is required.

As described earlier, IDCMP communication takes place through a pair of Exec message ports attached to a window: the UserPort and the WindowPort. The UserPort is the port where the application receives IDCMP messages from Intuition. The WindowPort is the reply port where Intuition receives replies from the application (via the ReplyMsg() function).

In the simplest case, Intuition allocates (and deallocates) both of these ports when the program opens a window with non-NULL IDCMP flags. Intuition will also allocate these ports if the application calls ModifyIDCMP() with non-NULL flags for a window that has NULL IDCMP flags. These port variables will be set to NULL if there is no message port allocated, otherwise they will contain a pointer to a message port.

If the WindowPort is not already opened when either OpenWindow() or ModifyIDCMP() is called, it will be allocated and initialized.

The UserPort is checked separately to see whether it is already opened.

When Intuition initializes the UserPort, it also allocates a signal bit with a call to AllocSignal(). Since the application makes the call to OpenWindowTagList() or ModifyIDCMP(), this signal bit is valid for the application's task. The address of the application's task is saved in the SigTask variable of the message port.

The program may choose to supply its own UserPort. This might be done in an environment where the program is using several windows and would prefer to monitor the input using only one message port. This is done by with the following procedure:

# Create a port for the IDCMP by calling either the Exec function AllocSysObject(ASOT_PORT) which returns a pointer to a port.
# Open the windows with no IDCMP flags set. This will prevent Intuition from allocating a port for this window.
# Place a pointer to the port created in step 1 into the UserPort field of the Window structure.
# Call ModifyIDCMP() to set the desired IDCMP flags for the port. Intuition will use the port supplied with the window.
# When an application decides to close a window that has a shared IDCMP, there may be messages waiting at the port for any of the windows including the window being closed. It is essential that messages destined for a given window be removed and replied to before that window is closed.
# CloseWindowSafely() performs proper message cleanup before closing such a window. It also sets the window's UserPort to NULL so that Intuition knows not to delete the port which should be done by the application in this case. It is incorrect (and dangerous) to simply call CloseWindow() on a window that has a shared IDCMP.
# After all windows have been closed, and the port has been removed from each, delete the port that was created in step 1.

{{Note|title=Be Careful with Shared IDCMP Ports|text=If the application is sharing an IDCMP among several windows, it must be very careful not to call ModifyIDCMP(window,NULL) for any of the windows that are using the shared port, as this will free the port and the signal bit.}}

==== Closing a Window with a Shared IDCMP ====

As promised in the last section, this example shows the CloseWindowSafely() function. Use this function to close any windows that share an IDCMP port with another window.

<syntaxhighlight lang="C" line>
/* CloseWindowSafely
**
** these functions close an Intuition window that shares a port with other
** Intuition windows.
**
** We are careful to set the UserPort to NULL before closing, and to free
** any messages that it might have been sent.
*/
#include <exec/types.h>
#include <intuition/intuition.h>

/*
** Entry point to CloseWindowSafely()
** Strip all IntuiMessages from an IDCMP which are waiting for a specific
** window. When the messages are gone, set the UserPort of the window to NULL
** and call ModifyIDCMP(win,0). This will free the Intuition arts of the
** IDMCMP and trun off message to this port without changing the original
** UserPort (which may be in use by other windows).
*/
VOID CloseWindowSafely(struct Window *win)
{
/* we forbid here to keep out of race conditions with Intuition */
IExec->Forbid();

/* send back any messages for this window that have not yet been processed */
IIntuition->StripIntuiMessages(win->UserPort, win);

/* clear UserPort so Intuition will not free it */
win->UserPort = NULL;

/* tell Intuition to stop sending more messages */
IIntuition->ModifyIDCMP(win, 0L);

/* turn multitasking back on */
IExec->Permit();

/* Now it's safe to really close the window */
IIntuition->CloseWindow(win);
}
</syntaxhighlight>

{{Note|title=Use WA_UserPort Instead|text=Use of the WA_UserPort tag can be used to achieve the same result as CloseWindowSafely(). Using WA_UserPort is the preferred way to share IDCMP ports between multiple windows.}}

=== IntuiMessages ===

The IntuiMessage structure is an Exec Message that has been extended to include Intuition specific information. The ExecMessage field in the IntuiMessage is an actual instance of a Message structure and is used by Exec to manage the transmission of the message. The Intuition extensions of the IntuiMessage are used to transmit specialized Intuition data to the program.

<syntaxhighlight lang="C" line>
struct IntuiMessage
{
struct Message ExecMessage;
ULONG Class;
UWORD Code;
UWORD Qualifier;
APTR IAddress;
WORD MouseX, MouseY;
ULONG Seconds, Micros;
struct Window *IDCMPWindow;
struct IntuiMessage *SpecialLink;
};
</syntaxhighlight>

The IntuiMessage structure fields are as follows:

; ExecMessage
: This field is maintained by Exec. It is used for linking the message into the system and broadcasting it to a message port. See [[Exec_Messages_and_Ports|Exec Messages and Ports]] for more information on the Message structure and its use.

; Class
: Class contains the IDCMP type of this specific message. By comparing the Class field to the IDCMP flags, the application can determine the type of this message. Each message may only have a single IDCMP type.

; Code
: Code contains data set by Intuition, such as menu numbers or special code values. The meaning of the Code field changes depending on the IDCMP type, or Class, of the message. Often the code field will simply contain a copy of the code of the input event which generated this IntuiMessage.

: For example, when the message is of class IDCMP_RAWKEY, Code contains the raw key code generated by the keyboard device. When the message is of class IDCMP_VANILLAKEY, Code contains the key mapped ASCII character.

; Qualifier
: This contains a copy of the ie_Qualifier field that is transmitted to Intuition by the input device. This field is useful if your program handles raw key codes, since the Qualifier tells the program, for instance, whether or not the Shift key or Ctrl key is currently pressed. Check the <devices/inputevent.h> file for the definitions of the qualifier bits.

; MouseX and MouseY
: Every IntuiMessage will have the mouse coordinates in these variables. The coordinates can either be expressed as absolute offsets from the upper left corner of the window, or expressed as the amount of change since the last reported positions (delta).

: If IDCMP_DELTAMOVE is set, then these numbers will represent delta positions from the last position. All messages will have zero in these values except IDCMP_MOUSEMOVE and IDCMP_MOUSEBUTTON events, which will have the correct delta values for the movement. If IDCMP_DELTAMOVE is not set, then these numbers are the actual window offset values.

; Seconds and Micros
: These values are copies of the current system clock, in seconds and microseconds. They are set when Intuition generates the message.

: Microseconds (Micros) range from zero up to one million minus one. The 32 bits allocated to the Seconds variable has enough accuracy to count up to 139 years. Time is measured from January 1, 1978.

; IAddress
: Typically this variable contains the address of some Intuition object, such as a gadget. The type of the object depends on the Class of the IntuiMessage. Do not assume that the object is of a certain type before checking the Class of the object.

: The IAddress pointer is defined ''only'' for the following IDCMP Classes. Do not attempt to dereference or otherwise interpret the IAddress field of any other type of IntuiMessage.

:{| class="wikitable"
! IntuiMessage Class
! Meaning of IAddress Field
|-
| IDCMP_GADGETDOWN || IAddress points to the gadget.
|-
| IDCMP_GADGETUP || IAddress points to the gadget.
|-
| IDCMP_RAWKEY || IAddress points to the dead-key information.
|-
| IDCMP_IDCMPUPDATE || IAddress points to a tag item list.
|-
| Other classes || No meaning.
|}

: In particular, for IDCMP_MOUSEMOVE IntuiMessages emanating from GACT_FOLLOWMOUSE gadgets, the IAddress field does not point to the gadget. Interpreting the IAddress as a gadget pointer and trying to access the gadget's fields before ascertaining that the event is an IDCMP_GADGETUP or IDCMP_GADGETDOWN event is incorrect, and can lead to subtle or serious problems.

: (Note that GadTools gadgets do arrange for the IAddress to point to the gadget when IDCMP_MOUSEMOVE messages appear).

; IDCMPWindow
: Contains the address of the window to which this message was sent. If the application is sharing the window's UserPort between multiple windows, IDCMPWindow allows it to determine which of the windows the message was sent to.

; SpecialLink
: For system use only.

=== IDCMP Flags ===

The application specifies the information it wants Intuition to send to it via the IDCMP by setting IDCMP flags. These may be set either when opening the window or by calling ModifyIDCMP().

The flags set may be viewed as a filter, in that Intuition will only post IntuiMessages to an IDCMP if the matching flag is set. Thus, the application will only receive the IDCMP messages whose Class matches one of the bits set in the window's IDCMP.

For many of these messages, there is a separation of the act of filtering these messages and causing Intuition to send the messages in the first place. For instance, menu help events may be activated for a window by setting the WA_MenuHelp attribute when the window is opened. However, the IDCMP will only receive the messages if the IDCMP_MENUHELP flag is set. If this flag is not set, then the events are passed downstream in the input and may be picked up by the console device.

=== Mouse Event Message Classes and Flags ===

; IDCMP_MOUSEBUTTONS
: Contains reports about mouse button up and down events. The events will be sent to the application only if they are not used internally by Intuition.

: The Code field contains information on the specific mouse button event this message represents. The Code field will be equal to SELECTDOWN, SELECTUP, MENUDOWN, MENUUP, MIDDLEDOWN or MIDDLEUP, depending on the button pressed or released. In general, the select button is the left mouse button, the menu button is the right mouse button and the middle button is an optional third button usually located between the select and menu buttons.

: Often, a mouse button event has extra meaning to Intuition, and the application may hear about it through a more specific message, for example a gadget or menu event. Other times, no event is generated at all, such as when the user depth-arranges a screen by clicking on the screen depth gadget. Note that menu button events are normally consumed by Intuition for menu handling. If an application wishes to hear IDCMP_MOUSEBUTTONS events for the menu button, it must set the WA_RMBTrap attribute for its window. See [[Intuition_Windows|Intuition Windows]] for more information.

; IDCMP_MOUSEMOVE
: Reports about mouse movements, sent in the form of ''x'' and ''y'' coordinates relative to the upper left corner of the window. One message will be sent to the application for each "tick" of the mouse.

: The application can opt to receive IDCMP_MOUSEMOVE events only while certain gadgets are active, or during normal window operation. These events are sent whenever a gadget with GACT_FOLLOWMOUSE gadget is active, or for any window that has the WA_ReportMouse attribute set. This window attribute can be set or cleared by the application at will. See [[Intuition_Windows|Intuition Windows]] for full details.

: Requesting IDCMP_MOUSEMOVE messages can create a very large volume of messages arriving at the window's IDCMP. Do not request these messages unless the program is prepared to keep up with them. Intuition limits the number of mouse move events that pile up at your IDCMP.

: All IDCMP messages contain a mouse ''x'' and ''y'' position that can be absolute values or delta values. See IDCMP_DELTAMOVE, below. If the application requires a less frequent reporting of the mouse position, consider using IDCMP_INTUITICKS. While IDCMP_MOUSEMOVE events are generated by changes in the mouse's position, IDCMP_INTUITICKS IntuiMessages are based on a timer. Since they contain mouse coordinates, they effectively sample the mouse position. These message come often enough for many applications, but not so frequently as to swamp the application.

: The program will not be sent IDCMP_MOUSEMOVE messages while Intuition has the layers of the screen locked (during menu operations and window sizing/dragging). This avoids problems of messages accumulating while the program is blocked, waiting to render into a locked layer.

; IDCMP_DELTAMOVE
: IDCMP_DELTAMOVE is not a message type, and events will never be sent to the application with this IDCMP identifier. This flag is a modifier, which changes how mouse movements are reported. When this flag is set, mouse movements are sent as delta values rather than as absolute positions.

: The deltas are the amount of change of the mouse position from the last reported position. If the mouse does not move, then the delta values will be zero.

: This flag works in conjunction with the IDCMP_MOUSEMOVE flag. When IDCMP_DELTAMOVE is set, IDCMP_MOUSEBUTTONS messages will also have relative values, instead of the absolute window position of the mouse.

: Delta mouse movements are reported even after the Intuition pointer has reached the limits of the display. That is, if the pointer has reached the edge of the display and the user continues to move the mouse in the same direction, the IDCMP_MOUSEMOVE messages will continue to report changes in the mouse position even though the pointer is no longer moving.

=== Gadget Event Message Classes and Flags ===

; IDCMP_GADGETDOWN
: IDCMP_GADGETDOWN messages are sent when the user selects a gadget that was created with the GACT_IMMEDIATE flag set. The IntuiMessage structure's IAddress field will contain a pointer to the selected gadget.

; IDCMP_GADGETUP
: IDCMP_GADGETUP messages are sent when the user selects a gadget that was created with the GACT_RELVERIFY flag set. The IntuiMessage structure's IAddress field will contain a pointer to the selected gadget.

; IDCMP_CLOSEWINDOW
: IDCMP_CLOSEWINDOW messages are sent when the user selects the window's close gadget. Intuition does not close the window when the close gadget is selected. Rather, an IDCMP_CLOSEWINDOW message is sent to the window's IDCMP. It is up to the application to clean up and close the window itself. If closing a window means losing some data (perhaps the spreadsheet the user was working on), it would be appropriate for the application to first confirm that the user really meant to close the window.

=== Menu Event Message Classes and Flags ===

; IDCMP_MENUPICK
: This flag indicates that the user has pressed the menu button. If a menu item was selected, the menu number of the menu item can be found in the Code field of the IntuiMessage. If no item was selected, the Code field will be equal to MENUNULL.

; IDCMP_MENUVERIFY
: This is a special verification mode which allows the program to confirm that it is prepared to handle Intuition rendering, in this case, allowing menus to be drawn in the screen.

: This is a special kind of verification, in that any window in the entire screen that has this flag set must respond before the menu operations may proceed. Also, the active window of the screen is allowed to cancel the menu operation. This is unique to IDCMP_MENUVERIFY. Refer to [[Intuition_Menus|Intuition Menus]] for a complete description.

: Also see the "Verification Functions" section below for more information.

; IDCMP_MENUHELP
: This message is sent by Intuition when the user selects the Help key while the menu system is activated. If a menu item was selected, the menu number of the menu item can be found in the Code field of the IntuiMessage. If no item was selected, the Code field will be equal to MENUNULL.

: These messages will only be sent if the WA_MenuHelp attribute is set for the window.

: The menu number returned in IDCMP_MENUHELP may specify a position that cannot be generated through normal menu activity. For instance, the menu number may indicate one of the menu headers with no item or sub-item. See [[Intuition_Menus|Intuition Menus]] for more information.

=== Requester Event Message Classes and Flags ===

; IDCMP_REQSET
: Intuition sends an IDCMP_REQSET message to the window each time a requester opens in that window.

; IDCMP_REQCLEAR
: Intuition sends an IDCMP_REQCLEAR message to the window each time a requester is cleared from that window.

; IDCMP_REQVERIFY
: Set this flag to allow the application to ensure it is prepared for Intuition to render a requester in the window. With this flag set, Intuition sends the application a message that a requester is pending, and then waits for the application to reply before drawing the requester in the window.

: If several requesters open in the window, Intuition asks the application to verify only the first one. After that, Intuition assumes that all output is being held off until all the requesters are gone.

: By setting the IDCMP_REQSET and IDCMP_REQCLEAR flags, the application can track how many requesters are open in the window and when the last requester is cleared. Once all of the requesters are cleared from the window, it is safe to write to the window until another IDCMP_REQVERIFY is received.

: See the "Verification Functions" section below for more discussion on using this flag.

=== Window Event Message Classes and Flags ===

; IDCMP_NEWSIZE
: Intuition sends this message after the user has resized the window. After receiving this, the program can examine the size variables in the window structure to discover the new size of the window. The message is sent, even if the size of the window did not actually change.

; IDCMP_REFRESHWINDOW
: This message is sent whenever the window needs refreshing. This flag makes sense only with windows that have a refresh type of WA_SimpleRefresh or WA_SmartRefresh.

: As a minimum, the application must call BeginRefresh() and EndRefresh() for the window after receiving an IDCMP_REFRESHWINDOW event. Create the window with the WA_NoCareRefresh attribute if you do not want to manage these events. See [[Intuition_Windows|Intuition Windows]] for details.

: Most of the graphics library calls used for display output are compatible with Intuition, with the exception of ScrollRaster(). Intuition will not send an IDCMP_REFRESHWINDOW event when damage is caused to a window by ScrollRaster(). This may happen in a simple refresh window which is partially obscured by another window; the region that scrolls out from behind the front window will be damaged, but the window will receive no notification. Check the LAYERREFRESH bit in the Layer structure Flags field to see if damage did happen as a result of ScrollRaster().

; IDCMP_SIZEVERIFY
: Set this flag if the program must complete some operation before the user sizes the window. When the user sizes the window, Intuition sends an IDCMP_SIZEVERIFY message to the application and then waits until the program replies before allowing the user to size the window. See the "Verification Functions" section below for some things to consider when using this flag.

; IDCMP_ACTIVEWINDOW and IDCMP_INACTIVEWINDOW
: Set these flags to discover when the window becomes activated or deactivated.

=== Other Event Message Classes and Flags ===

; IDCMP_VANILLAKEY
: IDCMP_VANILLAKEY messages return keyboard events translated into the current default character keymap. The mapped character value is returned in the Code field of the IntuiMessage structure.

: An IDCMP_VANILLAKEY message is sent only if the translation results in a single byte value, therefore the program cannot read the "Help" or function keys using IDCMP_VANILLAKEY.

: Programs using IDCMP_VANILLAKEY which also require the additional information of special keys, such as the "Help" key and the function keys, may set both IDCMP_VANILLAKEY and IDCMP_RAWKEY. When this combination is used, all keypresses that map to single character values will be returned as IDCMP_VANILLAKEY events; all other keyboard events will be sent as IDCMP_RAWKEY messages. Note that IDCMP_VANILLAKEY processing uses all of the key-up events, so the application will only receive key-down events in the IDCMP_RAWKEY format.

; IDCMP_RAWKEY
: IDCMP_RAWKEY messages give the raw keycodes from the keyboard. The numeric value of the keycode is sent in the Code field. Separate codes are returned for key down and key up. Qualifier codes, such as "Shift" or "Alt" and whether this key is a repeat, may be found in the Qualifier field of the message.

: In general, the application should not assume any correspondence between the keycode and the key value. Character positions on the keyboard change from country to country, and the application should respect the keymap set by the user.

: Programs using IDCMP_RAWKEY messages should perform their own key mapping by calling the console.device function RawKeyConvert(), or the keymap.library function MapRawKey(). (The latter is a bit more convenient, but is only available under V36 and higher). The Autodoc for the MapRawKey() function shows how you can process so-called ''dead keys''. A dead key is a key combination that has no immediate effect, but instead modifies a subsequent keystroke. For example, on the default keymap, Alt-F is a dead key for the acute accent mark. The sequence of Alt-F followed by the E key yields an e with an acute accent.

: For an example of key mapping using the RawKeyConvert() call, see the rawkey.c example in [[Intuition_Keyboard|Intuition Keyboard]].

: The application can assume that certain keys will always return the same raw keycode, these keys do not have to be mapped. In general these keys are in the high part of the keymap, above hex 40, and includes all non-alphanumeric keys. The fixed keys include the function keys, backspace, delete, help and cursor keys.

; IDCMP_NEWPREFS
: IDCMP_NEWPREFS messages are sent when the system Preferences are changed by a call to SetPrefs(). The program can learn of these changes by setting this flag.

: After receiving a message of class IDCMP_NEWPREFS, the application should call GetPrefs() to obtain a copy of the new Preferences.

: Under the new Preferences scheme used in Release 2 and later versions of the OS, an IDCMP_NEWPREFS message will not always be sent when the user changes a Preferences setting. Only Preferences values available under V34, i.e., those that can be modified by a call to SetPrefs(), will cause an IDCMP_NEWPREFS message to be sent. New Preferences items such as overscan or font settings rely on file system notification for monitoring changes. See [[Preferences]] for more information.

: This message type is broadcast to all IDCMP that have this flag set, not just to the active window. If the application has this flag set, it should be prepared to handle the event even if it is not active.

; IDCMP_DISKINSERTED and IDCMP_DISKREMOVED
: When the user inserts or removes a disk from any drive, Intuition will send one of these message types.

: This message type is broadcast to all IDCMP that have this flag set, not just to the active window. If the application has this flag set, it should be prepared to handle the event even if it is not active.

; IDCMP_INTUITICKS
: Intuition sends these messages to the active window based on an internal timer which "ticks" roughly ten times a second. This provides the application with simple timer events from Intuition.

: Intuition does not allow IDCMP_INTUITICKS events to accumulate at a port. After an IDCMP_INTUITICKS message has been sent to a port, Intuition will not send another until the application replies to the first. This means that an application that has not been able to service the IDCMP for an extended period can expect at most one IDCMP_INTUITICKS message to be waiting at the port.

: These events are to be used as "prods‚" and not as time counters. Do not rely on the timing accuracy of the event, or on the exact frequency at which they appear. Remember, IDCMP_INTUITICKS will only be sent to the active window. If the user selects another window, the events will no longer be received at the first window.

; IDCMP_IDCMPUPDATE
: Used for notification from BOOPSI custom gadgets. See the [[BOOPSI_-_Object_Oriented_Intuition|BOOPSI section]] for more information. The IAddress field contains a pointer to a tag item list. Tag lists are described in [[Utility_Library|Utility Library]].

; IDCMP_CHANGEWINDOW
: This message provides the window with notification of any change in the size or position of a window.

There are two other message classes reserved for system use:

; IDCMP_WBENCHMESSAGE
: Special messages for Workbench, system use only.

; IDCMP_LONELYMESSAGE
: For internal tracking by Intuition, system use only.

=== Verification Functions ===

IDCMP_SIZEVERIFY, IDCMP_REQVERIFY and IDCMP_MENUVERIFY are exceptional in that Intuition sends an IntuiMessage to the application and then waits for the application to reply before Intuition proceeds. The application replies by calling the Exec function ReplyMsg().

The implication is that the user requested some operation but the operation will not happen immediately and, in fact, will not happen at all until the application says it is safe. Because this delay can be frustrating and intimidating, the program should strive to make the delay as short as possible. An application should always reply to a verification message as soon as possible.

These problems may be overcome by setting up a separate task to monitor the IDCMP and respond to incoming IntuiMessages immediately. This is recommended where there is heavy traffic through the IDCMP, which occurs when many IDCMP flags are set. Monitoring with a separate task may not be appropriate if the main program must synchronize with the event before it can respond to the message.

In previous versions of the operating system, it was not safe to leave any of the VERIFY functions enabled at a time when the task is unable to respond for a long period. This restriction included calls to AmigaDOS directly (with Open(), for example), or indirectly (with OpenLibrary(), for a disk based library, for example), when a VERIFY function was active. This was because there are many cases where AmigaDOS will put up a requester prompting the user for input, and Intuition may end up waiting for the application to reply to the VERIFY message, while the application waits for the AmigaDOS call to finish. This deadlock would freeze the Amiga.

Beginning with V36, Intuition will no longer wait forever for the application to respond to the verify messages. These messages will now time-out; that is, if the application does not respond within a set period, Intuition will act as if it had. Even in this case, though, the machine will appear to be locked up until the time-out occurs.

The application should use ModifyIDCMP() to turn off all VERIFY messages before calling AmigaDOS, or functions that may call AmigaDOS.

If the application sets up a separate task to monitor the IDCMP, and the task monitoring the IDCMP does not call AmigaDOS functions, and if the monitor task will always be able to reply to the VERIFY message without any help from the other task, then the above warning does not apply.

For additional information, see the IDCMP_MENUVERIFY discussion in [[Intuition_Menus|Intuition Menus]], the IDCMP_REQVERIFY discussion in [[Intuition_Requesters|Intuition Requesters]] and the IDCMP_SIZEVERIFY discussion in [[Intuition_Windows|Intuition Windows]].

This message type is broadcast to all IDCMP on the screen that have this flag set, not just to the active window. If the application has this flag set, it should be prepared to handle the event even if it is not active.

== Function Reference ==

The following are brief descriptions of the Intuition functions that relate to the use of input and output under Intuition. See the SDK for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| ModifyIDCMP()
| Change the message filter for an IDCMP.
|-
| StripIntuiMessages()
| Remove and reply all IntuiMessages on a port that have been sent to a particular window.
|}

Datatypes Library

2025-01-26T19:26:35Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= Introduction =

The purpose of the DataTypes Library is to provide tools for handling data in an object-oriented way. The object-oriented approach means that your application can work with numerous data file standards without having to worry about the complex details of each one. Instead you only need to understand the simple conventions of the library.

The DataTypes Library is built on Intuition's BOOPSI facility (BOOPSI is an acronym for Basic Object-Oriented Programming System for Intuition). Although not required, it is very helpful to know a little about [[BOOPSI_-_Object_Oriented_Intuition|how BOOPSI works]] before trying to use the DataTypes Library. Some familiarity with object-oriented theory and practice is also helpful, though not required.

Since the library uses the TagItem structure for passing parameters to functions, you will have to understand how TagItems work before you can call the library functions. For more information on TagItems refer to the [[Utility_Library|Utility Library]].

== Spelling Conventions ==

In software development, the term “datatype” or “data type” is often used in the general sense, whereas the AmigaOS DataTypes framework establishes a rather special context. In order to avoid possible confusion, this documentation uses capitalized spelling in reference to components and programming entities that are part of the said framework, such as: the DataTypes Library, a DataType subclass, a DataType object, Picture DataType, etc.

== Why Use DataTypes? ==

Here's a summary of main properties and features:

* Support for multiple file formats across various types of data (text, sound, image, animation etc.). Load data the easy way without having to write dedicated loader code!

* Simple and consistent handling of multiple data standards. Once you have learned how to manipulate one type of data with the DataTypes Library, you will find that the other types are handled in much the same way.

* Extensible. New data types can be added to those already supported.

* Clipboard support. The DataTypes Library provides a consistent and easy-to-use interface to the Amiga's [[Clipboard_Device|clipboard device]] to encourage data sharing between applications.

* Intuition gadget support. Because the DataTypes Library is implemented with BOOPSI, the data objects it handles can also be treated as gadgets. Gadget operations can be performed on data objects within Intuition's task context, the same as other BOOPSI gadgets.

* Automatic conversion from one format to another. Future versions of the DataTypes Library will support other types of data objects. Conversion from one format to another will be automatically handled by the library.

* Validation. For example, you can easily check to see if a file is a valid JPEG (AIFF, AmigaGuide etc.) or not.

= Classes, Objects and Methods =

The jargon used to describe the DataTypes Library may be a little confusing if you have never worked with object-oriented systems before. For instance, the kinds of data supported by the library are divided into ''classes'' and ''subclasses''. The term ''class'' is used here in a familiar way; the members of a class simply have a common set of properties. The members of a subclass have all the properties of the parent class (superclass) and additional properties specific to the subclass. (Each subclass can be further broken down into sub-subclasses and so on.)

{| class="wikitable"
| Class || Ungulate || Has hooves, can run.
|-
| Subclass || Cow || Has udder, can be milked (also has hooves and can run).
|-
| Object || Daisy || An instance of class Cow; can run and can be milked.
|}

An actual instance of a class or subclass is referred to as an ''object''. The term ''object'' is appropriate because in general we want to ignore the details of each individual case and concentrate instead on what we can do with an object based on its class. In the example above the Daisy object can run and can be milked. The operations that can be performed with an object are referred to as ''methods'' and the object is said to ''inherit'' the methods and other attributes of its parent class (which in turn inherits the methods and attributes of its parent class, if it has one).

The datatypes.library implements ''datatypesclass'' from which all other DataType classes inherit from. The following BOOPSI class diagram illustrates how the various DataTypes classes relate to each other.

[[File:DataTypesClassDiagram.png|frame|center|DataTypes Class Diagram]]

{| class="wikitable"
|+ DataTypes Library Object Classes
! Object Classes
! Autodoc File Showing the Methods Supported
! Type of Data Object
|-
| Picture class
| picture_dtc.doc
| IFF graphic image file
|-
| Sound class
| sound_dtc.doc
| IFF audio sample file
|-
| Text class
| text_dtc.doc
| ASCII characters
|-
| AmigaGuide class
| amigaguide_dtc.doc
| Hypertext databases
|-
| Animation class
| animation_dtc.doc
| Animations containing graphics and sound
|}

The examples programs listed below demonstrate how to perform some basic ''methods'' on ILBM and 8SVX class objects.

= DataTypes Class Attributes =

DataType classes have other attributes in addition to the methods (operations) that they support. For each attribute, there is a corresponding TagItem defined in the DataTypes Library that you can use to examine or set that attribute in a particular object. For example, picture objects have a display mode attribute. The tag that controls this attribute is named PDTA_ModeID and is described in the Autodoc file picture_dtc.doc. See the Autodoc files for each class (as shown in Table 1) for a complete list of all class attributes.

The class attribute descriptions in the include files also have a set of codes that indicate the ''applicability'' of the attribute. The codes are as follows:

{| class="wikitable"
| I - Initialize
| You can initialize the attribute when the object is created
|-
| S - Set
| You can set the attribute to a new value after the object is created
|-
| G - Get
| You can get the value of the attribute after the object is created
|-
| N - Notify
| Changing the attribute triggers the object to send notification
|-
| U - Update
| Attribute can be set using the object's OM_UPDATE method
|}

These codes may seem a little mysterious until you have actually tried using the DataTypes Library. The N and U codes in particular are for special applications that want to implement their own object classes, an advanced topic beyond the scope of this article.

= Basic Functions of the DataTypes Library =

If all these new concepts seem a little daunting, rest assured; the DataTypes Library uses conventional C language function calls to get the job done. The calls you will be using most often are listed below. Notice that for each of these basic functions of DataTypes Library there is an equivalent BOOPSI call in the Intuition Library.

{| class="wikitable"
! datatypes.library
! intuition.library
! Purpose
|-
| NewDTObject()
| NewObject()
| Create a DataType object in memory from a file or clip
|-
| DisposeDTObject()
| DisposeObject()
| Free an object created earlier with NewDTObject() (or NewObject() )
|-
| GetDTAttrs()
| GetAttr()
| Get attributes of a DataType object
|-
| SetDTAttrs()
| SetAttrs()
| Set attributes for a DataType object
|-
| DoDTMethod()
| IDoMethod()
| Perform the given method (operation) with a DataType object
|}

There are also additional functions used to access DataType objects.

{| class="wikitable"
! Function Name
! Purpose
|-
| AddDTObject() || Add a DataType object to a window.
|-
| RefreshDTObjectA() || Refresh the rendering of a DataType object.
|-
| RemoveDTObject() || Remove a DataType object from a window.
|-
| GetDTMethods() || Get a list of the methods that a DataTypes object supports. Write, Copy, and Select are examples of methods that an object may support.
|-
| GetDTTriggerMethods() || Get a list of the trigger methods that a DataType object supports. An action like Play, Pause, and Resume are examples of trigger methods that an object may support.
|-
| PrintDTObject() || Asynchronously print a DataType object.
|-
| GetDTString() || Get the localized text string for a DataTypes text id. Useful for obtaining localized error messages.
|}

In a typical application the sequence of calls might be performed
like this:

# Use NewDTObject() to create an object in memory from given data.
# Get (or perhaps set) attributes of the object using GetDTAttr() (or SetDTAttrs() ).
# Perform ''methods'' (operations) with the object using DoDTMethod().
# Free the object and any memory or other resources it was using with the DisposeDTObject() call.

= Basic Structures of the DataTypes Library =

There are a lot of structures used with DataTypes Library function calls; too many to summarize in this article. However, here's a listing of the relevant include files that contain the structure definitions of interest to class users.

{| class="wikitable"
| <datatypes/datatypes.h>
| Group IDs, error numbers plus library overhead
|-
| <datatypes/datatypesclass.h>
| Defines DataType methods and associated structures
|-
| <datatypes/picture.h>
| Structures specific to the picture class
|-
| <datatypes/sound.h>
| Structures specific to the sound class
|-
| <datatypes/text.h>
| Structures specific to the text class
|-
| <libraries/amigaguide.h>
| Structures and methods for AmigaGuide databases
|-
| <intuition/classusr.h>
| Defines general BOOPSI object methods
|-
| <intuition/gadgetclass.h>
| Defines gadget methods and associated structures
|}

The two most important definitions in these include files appear in <intuition/classusr.h>. The objects used with DataTypes Library functions (and the BOOPSI functions in Intuition) are defined as follows:

<syntaxhighlight lang="C" line>
typedef ULONG Object; /* abstract handle */
</syntaxhighlight>

Since we want to treat objects as black boxes and don't really care how they are implemented, this definition is very appropriate. When a method is performed with an object, the parameter used to identify the method is a Msg structure defined as follows:

<syntaxhighlight lang="C" line>
typedef struct {
ULONG MethodID;
/* method-specific data goes here */
} *Msg;
</syntaxhighlight>

Some methods require more information than just the method identifier. Such methods have a custom structure defined in the include files. All method structures, however, begin with a field that contains the method ID.

= Creating a DataType Object =

The DataTypes function NewDTObjectA() must be used to create a new DataType object.

<syntaxhighlight lang="C" line>
Object *dto = IDataTypes->NewDTObjectA (APTR name, struct TagItem *attrs);
</syntaxhighlight>

The pointer that NewDTObjectA() returns is a pointer to a BOOPSI object. Like other BOOPSI objects, DataType objects are "black boxes" and are not to be peeked and poked without using the provided interface.

To create a DataType object, NewDTObjectA() needs to know the where to obtain the data used to create the object. By default the name is treated as file name.

The attrs tag list is a list of tag/value pairs, each of which contains an initial value for an attribute. There are a number of attributes defined in <datatypes/datatypesclass.h> that can be used at creation time.

; DTA_SourceType
: Specify the type of the source data. The default is DTST_FILE.
:{| class="wikitable"
| DTST_RAM || Source data is in RAM.
|-
| DTST_FILE || Source data is a file. Name is the name of the file.
|-
| DTST_CLIPBOARD || Source data is in the clipboard. Name is the unit number. For example, (APTR)0, for clipboard unit zero.
|-
| DTST_HOTLINK || Reserved for future use.
|}

; DTA_Handle
: Can be used instead of the name field. If the source type is DTST_FILE then handle must be a valid BPTR file handle. If the source type is DTST_CLIPBOARD then handle must be a valid IFFHandle.

; DTA_DataType
: Can be used to specify the class for handling the data. Data must be a pointer to a valid DataType. This should only be used when attempting to create a new object that doesn't have source data, or could be handled by multiple classes (for example, could be used to force an object to be handled by the AmigaGuide class).

; DTA_GroupID
: If this tag is present, then the data must be of the specified type, or the object creation will fail with ERROR_OBJECT_WRONG_TYPE. This can be used by a Sound editor to ensure that only sounds can be loaded, for example.

There are additional attributes that can specified at creation time, but are dependant on the data type of the object being created. See the header files <datatypes/#?class.h> for more attributes.

The following attributes, which are defined in <intuition/gadgetclass.h>, are also valid.
{| class="wikitable"
! Tag !! Description
|-
| GA_Left || Specify the left edge of the gadget.
|-
| GA_RelRight || Specify the left edge of the gadget being relative to the right edge of the containing window.
|-
| GA_Top || Specify the top edge of the gadget.
|-
| GA_RelBottom || Specify the top edge of the gadget being relative to the bottom edge of the containing window.
|-
| GA_Width || Specify the width of the gadget.
|-
| GA_RelWidth || Specify the width of the gadget being relative to the width of the containing window.
|-
| GA_Height || Specify the heigh of the gadget.
|-
| GA_RelHeight || Specify the heigh of the gadget being relative to the height of the containing window.
|-
| GA_ID || Specify a ID associated with the gadget.
|-
| GA_UserData || Attach application data to the gadget.
|-
| GA_Immediate || Indicate that the application should be notified of gadget down events for this gadget.
|-
| GA_RelVerify || Indicate that the application should be notified of gadget up events for this gadget.
|-
| GA_Previous || For adding the gadget to a list of gadgets.
|-
| GA_DrawInfo || A pointer to a struct DrawInfo.
|}

In order for the application to receive information from the DataType object, it must set up a target for the notification attributes that the object sends out.

; ICA_TARGET
: Specify a target for the notification attributes that the DataType object sends out.

; ICA_MAP
: Specify an attribute mapping for the notification attributes that the DataType object sends out.

The usual method to obtain notification is to set up an ICA_TARGET of ICTARGET_IDCMP so that the application will receive the attributes via the IDCMP_IDCMPUPDATE Intuition message class. But it is also possible to set up another BOOPSI object as the receiver.

If NewDTObjectA() is successful, it returns a pointer to a DataType object. Otherwise it returns NULL and the reason for failure can be obtained using IoErr(). See the Autodocs for datatypes.library for more information.

= Obtaining Environment Information for a DataType =

In order to embed a DataType object in a window, it is neccessary to ask the object what its minimum environment is. For example, since the remap code doesn't handle remapping HAM pictures, they must be shown on a HAM screen, and therefore can't be added to a window that is on a non-HAM screen.

<syntaxhighlight lang="C" line>
ULONG modeid = INVALID_ID;
LONG nomwidth, nomheight;
BOOL useScreen = FALSE;
struct dtFrameBox dtf;
struct FrameInfo fri;

/* Get the attributes that we are interested in */
IDataTypes->GetDTAttrs(dto,
/* Get the mode ID */
PDTA_ModeID, &modeid,

/* Get the desired size */
DTA_NominalHoriz, &nomwidth,
DTA_NominalVert, &nomheight,

TAG_END);

/* Clear the structures */
IUtility->ClearMem(&dtf, sizeof (struct dtFrameBox));
IUtility->ClearMem(&fri, sizeof (struct FrameInfo));

/* Fill in the message */
dtf.MethodID = DTM_FRAMEBOX;
dtf.dtf_FrameInfo = &fri;
dtf.dtf_ContentsInfo = &fri;
dtf.dtf_SizeFrameInfo = sizeof (struct FrameInfo);

/* Perform the frame method */
if (IDataTypes->DoDTMethodA (dto, NULL, NULL, (Msg) &dtf))
{
/* Check to see if the object requires a HAM screen */
if (fri.fri_PropertyFlags & DIPF_IS_HAM)
{
IDOS->Printf ("HAM\n");
useScreen = TRUE;
}
/* Check to see if the object requires an ExtraHalfBrite screen */
else if (fri.fri_PropertyFlags & DIPF_IS_EXTRAHALFBRITE)
{
IDOS->Printf ("ExtraHalfBrite\n");
useScreen = TRUE;
}
/* A safety check to see if a screen is required */
else if ((fri.fri_PropertyFlags == 0) && (modeid & 0x800) && (modeid != INVALID_ID))
{
IDOS->Printf ("ModeID=0x%08lx\n", modeid);
useScreen = TRUE;
}
}
else
{
/* No special environment required, can be attached to any screen mode */
}
</syntaxhighlight>

= Adding a DataType Object to a Window =

A DataType object must be added to a window using the AddDTObject() function of DataTypes.

<syntaxhighlight lang="C" line>
LONG AddDTObject (struct Window *w, struct Requester *r, Object *dto, LONG pos)
</syntaxhighlight>

This function will add a DataTypes object to the existing gadget list for the specified window. The recommended value for pos is -1 which will cause the DataType object to be added to the end of the list.

DataType objects should not be added using the WA_Gadgets attribute to OpenWindowTagList() or by using the AddGList() function. There is special information that DataTypes requires that will not obtained if any method other than AddDTObject() is used.

When the DataType object is added to the window, the layout method for the object will be invoked. It is possible that the layout will take a while to perform, in that case the object will spawn a process to handle the layout asynchronously. In order to refresh the object's visual information, it is necessary to obtain IDCMP_IDCMPUPDATE messages from the object and refresh the object when a DTA_Sync attribute is received.

The following code fragment illustrates adding a DataType object to a window.

<syntaxhighlight lang="C" line>
Object *dto;

struct IntuiMessage *imsg;
struct Window *win;
ULONG sigr;

struct TagItem *tstate, *tags;
ULONG tidata;
ULONG errnum;

BOOL going = TRUE;

/* Set the pertinent attributes of the DataType object */
IDataTypes->SetDTAttrs (dto, NULL, NULL,

/* Set the dimensions of the object */
GA_Left, win->BorderLeft,
GA_Top, win->BorderTop,
GA_Width, win->Width - win->BorderLeft - win->BorderRight,
GA_Height, win->Height - win->BorderTop - win->BorderBottom,

/* Make sure we receive IDCMP_IDCMPUPDATE messages from
* the object */
ICA_TARGET, ICTARGET_IDCMP,
TAG_END);

/* Add the object to the window */
IDataTypes->AddDTObject (win, NULL, dto, -1);

/* Refresh the DataType object */
IDataTypes->RefreshDTObjects (dto, win, NULL, NULL);

/* Keep going until we're told to stop */
while (going)
{
/* Wait for an event */
sigr = IExec->Wait ((1L << win->UserPort->mp_SigBit) | SIGBREAKF_CTRL_C);

/* Did we get a break signal */
if (sigr & SIGBREAKF_CTRL_C)
going = FALSE;

/* Pull Intuition messages */
while (imsg = (struct IntuiMessage *) IExec->GetMsg (win->UserPort))
{
/* Handle each message */
switch (imsg->Class)
{
case IDCMP_IDCMPUPDATE:
/* Get a pointer to the attribute list */
tstate = tags = (struct TagItem *) imsg->IAddress;

/* Step through the attribute list */
while (tag = IUtility->NextTagItem (&tstate))
{
tidata = tag->ti_Data;
switch (tag->ti_Tag)
{
/* Change in busy state */
case DTA_Busy:
if (tidata)
IIntuition->SetWindowPointer (win, WA_BusyPointer, TRUE, TAG_END);
else
IIntuition->SetWindowPointer (win, WA_Pointer, NULL, TAG_END);
break;

/* Error message */
case DTA_ErrorLevel:
if (tidata)
{
errnum = IUtility->GetTagData (DTA_ErrorNumber, NULL, tags);
IDOS->PrintErrorMsg (errnum, (STRPTR) options[OPT_NAME]);
}
break;

/* Time to refresh */
case DTA_Sync:
/* Refresh the DataType object */
IDataTypes->RefreshDTObjects (dto, win, NULL, NULL);
break;
}
}
break;
}

/* Done with the message, so reply to it */
IExec->ReplyMsg ((struct Message *) imsg);
}
}
</syntaxhighlight>

= Removing a DataType Object from a Window =

A DataType object must be removed from the window using the RemoveDTObject() function.

<syntaxhighlight lang="C" line>
LONG RemoveDTObject (struct Window *w, Object *dto)
</syntaxhighlight>

This function removes the DataType object from the window's gadget list.

This is the only way that a DataType object should be removed from the window list. Using RemoveGList() is not supported, nor is removing the object manually.

= Setting an Existing DataType Object's Attributes =

An objects attributes are not necessarily static. An application can ask an object to set certain attributes using the SetDTAttrs() function.

<syntaxhighlight lang="C" line>
ULONG SetDTAttrsA (Object *dto, struct Window *w, struct Requester *r, struct TagItem *attrs)
</syntaxhighlight>

The return value is DataType object specific, but generally a non-zero value means that the object needs to be visually refreshed.

The following fragment illustrates how to set the current top values for a DataType object, using the VarArgs version of SetDTAttrsA().

<syntaxhighlight lang="C" line>
IDataTypes->SetDTAttrs(dto, window, NULL,
DTA_TopVert, 0,
DTA_TopHoriz, 0,
TAG_END);
</syntaxhighlight>

This will cause the DataType object to update its vertical and horizontal top values. If the object has been added to a window, then the display will be updated accordingly.

Note that it is not OK to call SetGadgetAttrs() or SetAttrs() on a DataType object.

= Getting a DataType Object's Attributes =

The DataTypes function GetDTAttrsA() is used to obtain the values for a list of attributes from a DataType object.

<syntaxhighlight lang="C" line>
ULONG GetDTAttrsA (Object *dto, struct TagItem *attrs)
</syntaxhighlight>

Where dto is a pointer to a DataType object returned by NewDTObjectA().

And attrs is a TAG_END terminated array of attributes. Where the data element of each pair contains the address of the storage variable for that attribute.

This function will return a number that indicates that number of attributes that it was able to obtain. For example if four attributes asked for and GetDTAttrs returns a four, then all the attributes were obtained.

The following code fragment illustrates how to get the current top values
for a DataTypes object using the VarArgs form of GetDTAttrsA().

<syntaxhighlight lang="C" line>
LONG topv, toph;

if (IDataTypes->GetDTAttrs (dto, DTA_TopVert, &topv, DTA_TopHoriz, &toph, TAG_END) == 2)
{
IDOS->Printf ("Top: vertical=%ld, horizontal=%ld\n", topv, toph);
}
else
{
IDOS->Printf ("couldn't obtain the top values\n");
}
</syntaxhighlight>

= A Simple DataTypes Example =

The example program listed here should clarify some of the concepts discussed so far. Suppose you have a communications program and want to add the capability of playing back a user-specified 8SVX sample file for the bell sound (Ctrl-G). The program below shows how to play a sound with the DataTypes Library.

In this program, objects are of class 8SVX (a subclass of the Sound DataType). The method performed with the object is named DTM_TRIGGER (described in the Autodoc file sound_dtc.doc). The DTM_TRIGGER method (with type set to STM_PLAY) causes a sampled sound to be played on the Amiga's audio hardware. Since the DTM_TRIGGER method requires other information in addition to the method ID, a dtTrigger structure is used. This structure is defined in <datatypes/datatypesclass.h>.

Note that if the Sound DataType is enhanced to support other types of sound files in a future version of AmigaOS, the code given here will automatically support the new type. This example expects the file name and path to a sound file.

<syntaxhighlight lang="C" line>
/* Run from CLI only. */

#include <exec/types.h>
#include <datatypes/datatypesclass.h> /* This includes other files we need */

#include <proto/exec.h> /* Prototypes for system functions */
#include <proto/intuition.h>
#include <proto/datatypes.h>
#include <proto/dos.h

struct IntuitionIFace *IIntuition = NULL;
struct DataTypesIFace *IDataTypes = NULL;

int main(int argc, char **argv)
{
APTR dtobject = NULL /* Pointer to a DataTypes object */
struct dtTrigger mydtt; /* A trigger structure for the DTM_TRIGGER method */

if(argc <= 1 ) /* CLI only, at least one argument please. */
{
IDOS->Printf("Give a file name too.\n");
return RETURN_FAIL;
}

struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);

struct Library *DataTypesBase = IExec->OpenLibrary("datatypes.library", 50);
IDataTypes = (struct DataTypesIFace*)IExec->GetInterface(DataTypesBase, "main", 1, NULL);

if (IIntuition != NULL && IDataTypes != NULL)
{
/* Attempt to make an 8svx sound object from the file name the user */
/* specified in the command line. For a list of possible error */
/* returns, see the Autodocs for NewDTObjectA(). The group ID tag */
/* will allow only Sound DataType files to be accepted for the call.*/
if (dtobject = IDataTypes->NewDTObject(argv[1], DTA_GroupID, GID_SOUND,
TAG_END) )
{
mydtt.MethodID = DTM_TRIGGER; /* Fill in the dtTrigger struct */
mydtt.dtt_GInfo = NULL;
mydtt.dtt_Function = STM_PLAY;
mydtt.dtt_Data = NULL;

/* The return value of the DTM_TRIGGER method used with the 8svx */
/* Sound DataType is undefined in V39. This is likely to change */
/* in future versions of the Amiga operating system. */
uint32 dores = IDataTypes->DoDTMethodA(dtobject, NULL, NULL, &mydtt);

// Let the 8svx sound finish playing. Another way is to use
// SDTA_SignalTask and SDTA_SignalBit to find out when it is
// finished playing.
IExec->Wait(SIGBREAKF_CTRL_C);

IDataTypes->DisposeDTObject(dtobject);
}
else IDOS->Printf("Couldn't create new object or not a sound data file\n");
}
else IDOS->Printf("Can't open interfaces\n");

IExec->DropInterface((struct Interface*)IDataTypes);
IExec->CloseLibrary(DataTypesBase);

IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);

return 0;
}
</syntaxhighlight>

In addition to playing back a sampled sound, the DataTypes Library allows sound objects to become gadgets (the library includes default imagery for a sound gadget). Since all DataTypes are implemented as a subclass of the BOOPSI ''gadgetclass'', they all support the methods of gadget objects as described in [[BOOPSI_-_Object_Oriented_Intuition|BOOPSI]].

= Embedding DataTypes =

Since DataTypes are a subclass of the Intuition ''gadgetclass'', DataType objects can be attached to an Intuition window in a similiar way that gadgets can be added to a window. DataTypes use a parallel set of functions because it requires additional information that the Intuition functions weren't able to provide.

Currently the handling of the data is limited to reading, writing, printing, viewing (audio or visual), and clipboard access. Utilities like MultiView or MultiViewer are examples of applications that can embed DataType objects.

= Determining Data Type =

One of the main features of the DataTypes system is its ability to determine the type of a block of data. This data block can reside in a file or the clipboard.

The following functions are used to determine the DataType of a data block:

{| class="wikitable"
| ObtainDataTypeA() || Obtain the DataType descriptor for a data block.
|-
| ReleaseDataType() || Release the DataType descriptor for a data block.
|}

The data type detection functions use the DataType structure.

<syntaxhighlight lang="C" line>
struct DataType
{
struct Node dtn_Node1;
struct Node dtn_Node2;
struct DataTypeHeader *dtn_Header;
struct List dtn_ToolList;
STRPTR dtn_FunctionName;
struct TagItem *dtn_AttrList;
ULONG dtn_Length;
};
</syntaxhighlight>

The DataType structure is read-only. The only pertinent field is the dtn_Header field, which points to a DataTypeHeader structure.

<syntaxhighlight lang="C" line>
struct DataTypeHeader
{
STRPTR dth_Name;
STRPTR dth_BaseName;
STRPTR dth_Pattern;
WORD *dth_Mask;
ULONG dth_GroupID;
ULONG dth_ID;
WORD dth_MaskLen;
WORD dth_Pad;
UWORD dth_Flags;
WORD dth_Priority;
};
</syntaxhighlight>

The DataTypeHeader structure fields are as follows:

; dth_Name
: Descriptive name of the data type. For example, the description for an ILBM data type could possibly be "Amiga BitMap Picture".

; dth_BaseName
: This is the base name for the data type and is used to obtain the class that handles this data type.

; dth_GroupID
: This identifies the general type of data that the object contains. Following are the possible values:
:{| class="wikitable"
| GID_SYSTEM || Fonts, Executables, Libraries, Devices, etc...
|-
| GID_TEXT || Formatted or unformatted text.
|-
| GID_DOCUMENT || Formatted text with embedded DataTypes (such as pictures).
|-
| GID_SOUND || Audio samples.
|-
| GID_INSTRUMENT || Audio samples used for playing music.
|-
| GID_MUSIC || Musical scores.
|-
| GID_PICTURE || Graphic picture or brush.
|-
| GID_ANIMATION || Moving picture or cartoon.
|-
| GID_MOVIE || Moving picture or cartoon with sound.
|}

; dth_ID
: This is an individual indentifier for the DataType. For IFF files it is the same as the FORM type, for example ILBM for an Amiga BitMap picture. For non-IFF files, it is the first four characters of dth_Name.

; dth_Flags
: The flags field contains, among other information, the coarse type of data. The type can be obtained by ANDing DTF_TYPE_MASK with this field.
:{| class="wikitable"
| DTF_IFF || Interchange File Format
|-
| DTF_BINARY || Non-readable characters
|-
| DTF_ASCII || Readable characters
|-
| DTF_MISC || Disks and drawers
|}

; dth_Pattern
; dth_Mask
; dth_MaskLen
; dth_Priority
: These fields are used by the detection code in datatypes.library for determining the data type. See the "Defining a DataType Descriptor" section for more information.

Following is a code fragment that shows how to determine the data type of a file. This fragment uses functions from the DataTypes Library, DOS Library, and IFFParse Library.

<syntaxhighlight lang="C" line>
STRPTR name = "somefilename";
BPTR lock;

struct DataTypeHeader *dth;
struct DataType *dtn;
UBYTE idesc[5];
STRPTR tdesc;
STRPTR gdesc;
UWORD ttype;

/* Obtain a lock on the file that we want information on */
if (lock = IDOS->Lock (name, ACCESS_READ))
{
/* Get a pointer to the appropriate DataType structure */
if (dtn = IDataTypes->ObtainDataTypeA (DTST_FILE, (APTR)lock, NULL))
{
/* Get a pointer to the DataTypeHeader structure */
dth = dtn->dtn_Header;

/* Get the coarse type */
ttype = dth->dth_Flags & DTF_TYPE_MASK;

/* Get a pointer to the text strings */
tdesc = IDataTypes->GetDTString (ttype + DTMSG_TYPE_OFFSET);
gdesc = IDataTypes->GetDTString (dth->dth_GroupID);

/* Convert the ID to a string. */
IIFFParse->IDtoStr (dth->dth_ID, idesc);

/* Display the information */
IDOS->Printf (" Description: %s\n", dth->dth_Name);
IDOS->Printf (" Base Name: %s\n", dth->dth_BaseName);
IDOS->Printf (" Type: %d - %s\n", ttype, tdesc);
IDOS->Printf (" Group: %s\n", gdesc);
IDOS->Printf (" ID: %s\n", idesc);

/* Release the DataType structure now that we are done with it */
IDataTypes->ReleaseDataType (dtn);
}

/* Release the DOS lock on the file */
IDOS->UnLock (lock);
}
</syntaxhighlight>

= A Picture Class Example =

Here is a second, more complex example showing how to use all the DataTypes Library functions described so far. In this example the objects used are of class ILBM, a subclass of the Picture DataType.

Two methods will be performed with the object, DTM_PROCLAYOUT and DTM_FRAMEBOX. Both these methods have associated structures (gpLayout and dtFrameBox respectively). DTM_PROCLAYOUT makes the object available within the context of your application task (as opposed to Intuition's). DTM_FRAMEBOX queries the display environment required by the picture.

Other attributes of the picture are obtained with a call to GetDTAttrs() and then a matching Intuition screen is created and the ILBM object is displayed. This example expects the file and path name of a picture file.

<syntaxhighlight lang="C" line>
/* Run from CLI only.
*/

#include <exec/types.h>
#include <datatypes/datatypes.h>
#include <datatypes/pictureclass.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/datatypes.h>
#include <proto/graphics.h>

struct IntuitionIFace *IIntuition = NULL;
struct GraphicsIFace *IGraphics = NULL;
struct DataTypesIFace *IDataTypes = NULL;

int main(int argc, char **argv)
{
APTR dtobject=NULL; /* Pointer to a DataTypes object */
uint32 res; /* Variable for function return values */
struct dtFrameBox mydtFrameBox; /* Use this with DTM_FRAMEBOX method */
struct FrameInfo myFrameInfo; /* For info returned from DTM_FRAMEBOX */
struct gpLayout mygpLayout; /* Use this with DTM_PROCLAYOUT method */

uint32 modeID = INVALID_ID; /* Variables for storing the display */
struct Screen *myScreen=NULL; /* environment information obtained */
struct BitMap *bm = NULL; /* the DataType object. */
uint32 *cregs = NULL;
uint32 i,r,g,b,numcolors;

struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
struct Library *GfxBase = IExec->OpenLibrary("graphics.library", 50);
struct Library *DataTypesBase = IExec->OpenLibrary("datatypes.library", 50);

IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
IGraphics = (struct GraphicsIFace*)IExec->GetInterface(GfxBase, "main", 1, NULL);
IDataTypes = (struct DataTypesIFace*)IExec->GetInterface(DataTypesBase, "main", 1, NULL);

if (IIntuition != NULL)
{
if (IGraphics != NULL)
{
if (IDataTypes != NULL)
{
if(argc > 1 ) /* CLI only, at least one argument please. */
{
/* Attempt to create a picture object in memory from the file */
/* name given by the user in the command line. If we wanted to */
/* show the picture in a screen set up ahead of time, we could */
/* set PDTA_Remap to TRUE and provide a pointer to the screen */
/* with the PDTA_Screen tag (datatypes.library handles the rest).*/
/* However in this case we want to first find out the attributes */
/* of the picture object and set up a matching screen and do the */
/* remapping later. Therefore PDTA_Remap is set to false. */
/* The group ID tag ensures that we get only a picture file type.*/
if (dtobject = IDataTypes->NewDTObject(argv[1], PDTA_Remap, FALSE,
DTA_GroupID, GID_PICTURE,
TAG_END) )
{
/* Here we want to find the display environment required by */
/* this picture. To do that, perform the DTM_FRAMEBOX method */
/* on the object. The DataTypes Library fills in the struct */
/* FrameBox you give it with the info on the display needed. */
mydtFrameBox.MethodID = DTM_FRAMEBOX;
mydtFrameBox.dtf_GInfo = NULL;
mydtFrameBox.dtf_ContentsInfo = NULL;
mydtFrameBox.dtf_FrameInfo = &myFrameInfo;
mydtFrameBox.dtf_SizeFrameInfo= sizeof (struct FrameInfo);
mydtFrameBox.dtf_FrameFlags = 0L;

/* The return value from DTM_FRAMEBOX is currently undefined */
res = IIntuition->IDoMethodA(dtobject, &mydtFrameBox);

/* OK, now do the layout (remap) of the object on our process */
mygpLayout.MethodID = DTM_PROCLAYOUT;
mygpLayout.gpl_GInfo = NULL;
mygpLayout.gpl_Initial= 1L;

/* The return value of DTM_PROCLAYOUT is non-zero for success */
if( res = IIntuition->IDoMethodA(dtobject, &mygpLayout) )
{
/* Get the attributes of this picture object. You could */
/* use a series of GetAttr() function calls here instead. */
res = IDataTypes->GetDTAttrs(dtobject, PDTA_ModeID, &modeID,
PDTA_CRegs, &cregs,
PDTA_BitMap, &bm,
TAG_END);

/* Did we get all threee attributes? */
if( (modeID!=INVALID_ID) && (cregs) && (bm) )
{
/* Open a screen that matches the picture object */
if( myScreen = IIntuition->OpenScreenTags( NULL,
SA_Width, myFrameInfo.fri_Dimensions.Width,
SA_Height, myFrameInfo.fri_Dimensions.Height,
SA_Depth, myFrameInfo.fri_Dimensions.Depth,
SA_DisplayID, modeID,
SA_BitMap, bm,
TAG_END) )
{
/* Now fill in the color registers for this screen */
numcolors = 2<<(myFrameInfo.fri_Dimensions.Depth-1);
for( i=0; i < numcolors; i++ )
{
r = cregs[i * 3 + 0];
g = cregs[i * 3 + 1];
b = cregs[i * 3 + 2];
IGraphics->SetRGB32(&myScreen->ViewPort, i, r, g, b);
}

IDOS->Printf("Ctrl-C in this window to quit\n");
/* Wait for the user to have a look... */
IExec->Wait(SIGBREAKF_CTRL_C);

IIntuition->CloseScreen(myScreen);
}
else IDOS->Printf("Couldn't open required screen\n");
}
else IDOS->Printf("Couldn't get picture attributes\n");

IDataTypes->DisposeDTObject(dtobject);
}
else IDOS->Printf("Couldn't perform PROC_LAYOUT\n");
}
else IDOS->Printf("Couldn't create new object or not a picture file\n");
}
else IDOS->Printf("Give a file name too.\n");
}
else IDOS->Printf("Can't open DataTypes Library\n");
}
else IDOS->Printf("Can't open Graphics Library\n");
}
else IDOS->Printf("Can't open Intuition Library\n");

IExec->DropInterface((struct Interface*)IDataTypes);
IExec->DropInterface((struct Interface*)IGraphics);
IExec->DropInterface((struct Interface*)IIntuition);

IExec->CloseLibrary(DataTypesBase);
IExec->CloseLibrary(GfxBase);
IExec->CloseLibrary(IntuitionBase);

return 0;
}
</syntaxhighlight>

As with 8SVX objects, the DataTypes Library allows ILBM objects to be treated as gadgets. Remember that all DataTypes are a subclass of the BOOPSI ''gadgetclass'' and therefore support the gadget methods described in [[BOOPSI Gadgets]].

How to open and use the exec debug interface

2025-01-26T19:26:27Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

[[Category:Debug]]
== Author ==

Alfkil Wennermark 
Copyright (c) 2010 Alfkil Wennermark 
Used by permission.

== Tutorial ==

Next step in my small series concerns itself with how to open and use the "secret" (but very useful) debug interface. Thanks to Steven Solie and Thomas Frieden.

Probably the best way to trap exceptions from within your code is to use the debug interface, that is "hidden" inside exec.library. The main problem with this interface is, that it is not very well documented. My main source of documentation on this issue is the amigaos-nat.c file from Thomas Friedens [[GDB_for_Beginners|GDB]] sources. These can be found inside [https://sourceforge.net/projects/adtools/ the adtools project on sourceforge.net].

The following code just plainly opens the interface, attaches a debug hook to itself, causes an exception and tells you what has happened. Normally you wouldn't attach the hook to your own process. Rather you would open whatever code you want to debug with fx. LoadSeg(), run it with CreateNewProc() (or some other way) and attach the debug hook to it. To keep things simple, though, this code just attaches the hook to itself.

<syntaxhighlight lang="C" line>
/* debugtrap.cExample of use of the exec debug interface
by Alfkil Wennermark 2010

Thanks to Steven Solie, Thomas Frieden and others

This code is partially copied from Thomas' GDB source
*/

#include <proto/exec.h>
#include <proto/dos.h>

#include <exec/types.h>
#include <exec/interrupts.h>
#include <exec/tasks.h>

#include <dos/dos.h>

#include <stdio.h>

struct DebugIFace *IDebug = 0;

struct KernelDebugMessage
{
uint32 type;
union
{
struct ExceptionContext *context;
struct Library *library;
} message;
};

static ULONG amigaos_debug_callback(struct Hook *, struct Task *, struct KernelDebugMessage *);

struct Hook debug_hook;
struct Task *amiga_task;

BPTR exec_seglist;
ULONG debug_data = 1234;

void init()
{
IDebug = (struct DebugIFace *)IExec->GetInterface((struct Library *)SysBase, "debug", 1, 0);
if (!IDebug)
{
printf("Can't get DEBUG access\n");
exit(RETURN_FAIL);
}

debug_hook.h_Entry = (ULONG (*)())amigaos_debug_callback;
debug_hook.h_Data =(APTR)&debug_data;

/* NB: Ideally we would start up another task, that
we want to debug, and attach ourselves to that
task using the debug hook, but for simplicity
we just use our own task here */
amiga_task = IExec->FindTask(NULL);
IDebug->AddDebugHook(amiga_task, &debug_hook);
}

void end()
{
IDebug->AddDebugHook(amiga_task, 0);

if (IDebug)IExec->DropInterface((struct Interface *)IDebug);
IDebug = NULL;
}

ULONG
amigaos_debug_callback(struct Hook *hook, struct Task *currentTask,
struct KernelDebugMessage *dbgmsg)
{
struct ExecIFace *IExec = (struct ExecIFace *)((struct ExecBase *)SysBase)->MainInterface;

uint32 *data = (uint32 *)hook->h_Data;

/* these are the 4 types of debug msgs: */
switch (dbgmsg->type)
{
case DBHMT_REMTASK:
*data = 9;
break;

case DBHMT_EXCEPTION:
*data = 11;
break;

case DBHMT_OPENLIB:
*data = 13;
break;

case DBHMT_CLOSELIB:
*data = 15;
break;

default:
*data = 0;
break;
}
/* returning 1 will suspend the task ! */
return 0;
}

int main()
{
init();

/* Cause an exception on purpose: */
uint32 *beef = 0;
*beef = 0L;

printf("We received a");
switch (debug_data)
{
case 9:
printf(" REMTASK");
break;
case 11:
printf("n EXCEPTION");
break;
case 13:
printf("n OPENLIB");
break;
case 15:
printf(" CLOSELIB");
break;

default:
printf("n unknown");
break;
}
printf(" signal!n");

end();

return RETURN_OK;
}
</syntaxhighlight>

AmiDock and Dockies

2025-01-26T19:26:20Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= Introduction =

AmiDock is a tool to maintain a graphical menu bars (Docks) at the Workbench screen that can be used or to execute other programs from a selection of icons (either in the main Dock or in sub-Docks as specified by the AmiDock preferences), or to handle special kind of application called "Dockies", which can provide different functionality: render different kind of data right into the dock, provide user with a menu related to the Docky of choice and so on.

AmiDock implemented as commodity, and together with being responsible for creating and controlling Docks and Dockies it provide different functionality such as ARexx support and a rich API by which your Dockies can control most of AmiDock's features.

= What is a Dock and a Docky? =

== Dock ==

A Dock is an area or window where the user can put a program icon or an interactive program.

[[File:Laucher_dock.png|center]]

== Docky ==

A Docky is a little program to be placed in a dock. Dockies are able to control most of AmiDock's features and provides a great way to expand AmiDock beyond its default functionality. Dockies may be invisible to the user or show static or dynamic (animated) content. You may change their behavior, size and look according to requirements. Dockies are one of two main types:

=== Standalone Dockies ===

A standalone Docky is a special type of program which is made to show an icon in a Dock, delivering some functionality to the user. It is the most common type of Docky. This Docky type uses the standard shared library feature of AmigaOS as a common interface.

=== Application Dockies ===

The second type of Docky is an application Docky which may sometimes be known as an 'AppDocky' or 'AppDockIcon Docky'. An AppDocky is a Docky which is introduced to the system at run time by an application using the application.library registration mechanism for applications. The biggest difference between the two types of Dockies types is that AppDockies belong to a running application and usually are used to represent the current state of the owning application.

To sum up in "standalone dockies" the docky itself is the application (the only reason of existence of the application is the docky) while for "AppDockIcon dockies" the docky is just a graphical representation of a bigger application (the docky is just here to add user friendliness or visual feedback of the surrounding application)

= How to create and manipulate a simple docky =

You write a docky just like you'd write a standard Exec library. In your code you must implement certain specifically-named functions like DockyGet(), DockyProcess(), DockySet() etc. The docky manager (AmiDock) calls these functions when it needs to.

See the [http://os4depot.net/share/utility/docky/datetime_docky.lha datetime.docky source code] to get started.

= FAQ =

== Is it possible to create an application docky and then update its content on the fly and how? ==

Set the icon type to APPICONT_Docky; but you'll need to create a real docky as well then. If it doesn't need to be truly active it is possible just to change the icon's imagery (I think you have to un-register/re-register to get it to change though, so no good for frequent changes)

== I have successfully drawn a datatype (a picture) in a Docky and the picture file has more than 256 colors but it is rendered in 256 colors only. Why? ==

Just add PDTA_DestMode, PMODE_V43 to the NewDTObject call. You might also want to add DTA_GroupID, GID_PICTURE in order to restrict the file type to pictures.

== How are context menus created? ==

Context menus are dynamically built in response to DOCKYGET_ContextMenu attribute:

<syntaxhighlight lang="C" line>
BOOL DockyGet (struct DockyIFace *Self, uint32 msgType, uint32 *msgData)
{
switch (msgType)
{
/* ... */

case DOCKYGET_ContextMenu:
{
Object *contextMenu = (Object *)msgData;

Object *item1 = PopupMenuItemObject,
PMIA_Title, GetString(&li, LOCALE_ITEM_PREFS),
PMIA_ID, PMID_PREFS,
PopupMenuItemEnd;

Object *item2 = PopupMenuItemObject,
PMIA_Title, GetString(&li, LOCALE_ITEM_SAVEASDEFAULT),
PMIA_ID, PMID_SAVEASDEFAULT,
PopupMenuItemEnd;

Object *item3 = PopupMenuItemObject,
PMIA_Title, GetString(&li, LOCALE_ITEM_USEASDEFAULT),
PMIA_ID, PMID_USEASDEFAULT,
PopupMenuItemEnd;

if (item1 && item2 && item3)
{
IIntuition->IDoMethod(contextMenu, OM_ADDMEMBER, item1);
IIntuition->IDoMethod(contextMenu, OM_ADDMEMBER, item2);
IIntuition->IDoMethod(contextMenu, OM_ADDMEMBER, item3);
}

}
break;

/* ... */
}
</syntaxhighlight>

== How do you use an alpha layer for a Docky? ==

On non-composited screens, AmiDock uses a "fake" transparency effect (i.e. the bitmap is filled with the contents of the window behind the dock), meaning that you can only add things over the background but you cannot render half or totally transparent contents without doing the blending at the same time (or you'll lose background information).

So if you want to support this configuration you need to follow this rule or provide an alternate rendering if you want to do fancy stuff when compositing is enabled.

Now, what you are trying to do should work on composited screens, but you have to tell AmiDock that you are using composited mode (see DOCKYGET_SupportsComposite and DOCKYGET_CompositeMode) so that it does not try to de-multiply the docky bitmap. Also I'm not sure you can use legacy pens to fill alpha channel, you're better off with direct ARGB painting (see SetRPAttrs() with RPTAG_APenColor).

== Is there a way to trigger a redraw from outside the docky? ==

Use DOCKYGET_NeedsAttention for this. This is how a docky can be notified from an external task by signaling AmiDock process. Quite straightforward, this is how e.g. [http://os4depot.net/share/utility/docky/winbar-docky.lha winbar.docky] ([http://os4depot.net/share/utility/docky/winbar_docky_src.zip source code is here], prefsobjects_macro.h include file which is required [http://openamiga.org/attachment/project/29/prefsobjects_macros.h here]) is told to rethink its layout in response to a change in preferences, or Intuition windows list. A shared structure and [[Exec_Mutexes|Mutex]] to protect the data. By the way, winbar.docky source code can be helpful not only for that, but for all other things such as adding context menus, firing requests to AmiDock or other of the many still undocumented features of the API.

You are notified about the task/bit to signal through DOCKYSET_DockyAttention (you would store it in the library base for an easy access by the main program). When your program signals AmiDock, every docky is sent the DOCKYGET_NeedsAttention message, so it is a good idea to use a flag to know if the notification really comes from your program.

== How does DOCKYGET_SupportsComposite work? ==

When compositing is enabled, a docky receives a DOCKYGET_SupportsComposite query. If it returns TRUE, it will then receive a DOCKYGET_CompositeMode query to which it can reply either DOCKYCOMPMODE_PreblendedRGB (0) or DOCKYCOMPMODE_RawRGB (1). The former has no advantages over the previous method, but was included for backward compatibility. The latter, however, allows you to directly *copy* the source ARGB data to the destination bitmap (or buffer) rather than blend it yourself. This way, it will be AmiDock itself that does the blending (once) without the need to undo the
previous blending to get the raw RGB data.

One thing to take into account when using this method, though, is that on a 16-bit screen you will get an actual 16-bit destination bitmap, not 32-bit as it happens when returning FALSE to DOCKYGET_SupportsComposite. In this case, you will need to write the alpha channel separately to the
(8-bit) bitmap provided in the DockyRenderDestination's alpha.RP field.

= See Also =

1. SDK:Documentation/AutoDocs/docky.doc

2. SYS:Documentation/Commodities/AmiDock_Arexx.doc

3. SDK:Examples/AmiDock/

Multiple Assigns

2025-01-26T19:26:03Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= Introduction =

One of the features in AmigaDOS since the OS 2.x days is Multiple Assigning. This feature allows an AmigaDOS assign to carry over several directories which can be on different volumes. This makes it possible to split up assigns such as libs: and fonts:.

The article [[Directory Scanning]] contains an example called find.c that illustrates scanning a path that can contain a multiassign. However, besides being rather complicated, find.c makes a special case of scanning assigns, which isn't necessary (find.c also did something evil--find.c uses DOSBase's private pointer to the utility.library, essentially using the utility.library without opening it). The method needed to scan a multiassign directory also works on conventional directories.

Scanning a multiassign requires calling the dos.library function GetDeviceProc() in a loop to see each directory of the multiassign. Using GetDeviceProc(), the application doesn't have to concern itself with the differences between assigns, multiassigns, and volumes. The application just keeps calling GetDeviceProc() until it gets back a NULL.

<syntaxhighlight lang="C" line>
struct DevProc *GetDeviceProc( STRPTR name, struct DevProc *dp );
</syntaxhighlight>

The name can be any valid dos path. If there is a device name present, GetDeviceProc() will find the device's entry in the dos list and copy some information into a DevProc structure:

<syntaxhighlight lang="C" line>
struct DevProc {
struct MsgPort *dvp_Port; /* Device's Message port, also called a Process identifier */
BPTR dvp_Lock; /* Lock on root of assign or lock on root of volume */
ULONG dvp_Flags;
struct DosList *dvp_DevNode;/* DON'T TOUCH OR USE! */
};
</syntaxhighlight>

The important fields here are dvp_Lock and dvp_Port. The dvp_Lock field is a lock on the root of the object named in GetDeviceProc(). It serves as a starting point in locating the named object. If the object name contains an assign (i.e. libs:), dvp_Lock is the root of the assign. For example, on a typical system, the libs: assign refers to the libs directory on the SYS: volume. Calling GetDeviceProc() on libs: in this case will yield a lock on SYS:libs.

If the named object contains a dos volume, dvp_Lock is either a lock on the root of the dos volume or NULL. If the object named in GetDeviceProc() contains a non-file system device (i.e., ser:, par:, prt:, etc.) or it does not contain a device name, dvp_Lock is NULL.

The dvp_Port field points to a message port. This message port is connected to the handler process of a DOS device. The handler process controls a DOS device. DOS functions (like the Lock() function) use this message port to talk to the handler process of the named object. For example, from the libs: example above, the dvp_Port field refers to the message port of the handler process for the SYS: volume.

Note that dvp_Lock is only a lock on the root of the named object. If the named object is a path several directories deep (for example, libs:gadgets/colorwheel.gadget), it's up to the application to handle the rest of the path. The application also has to handle the case where the named object is a path without a device name.

Although an application can send DOS packets directly to the message port (dvp_Port) of a handler process, normally it is easier to use functions from dos.library. The multilist.c example uses the Lock() function to lock the named object. Multilist has to do something a little unorthodox to use Lock(). Lock() accepts a path name to the object to lock. Lock() understands absolute paths (i.e. paths with a logical device name like dh1: or libs:) and relative paths. If Lock() receives an absolute path name, Lock() can find the device's handler process using the logical device name in the absolute path. For a relative path, Lock() does not have enough information to find the named object, so it assumes the path is relative to the current directory and file system (each process has a current directory and file system).

This makes Lock() a little more difficult to use in multilist.c because, when processing an absolute path, multilist has to process the logical device name separately from the rest of the path. It has to use GetDeviceProc() to find the root of a logical device name (which can be an assign, multiassign, volume name, etc.) then it has to strip the logical device name from the absolute path. Without a logical device name, the path has become relative rather than absolute. The path is now relative to dvp_Lock and dvp_Port. In order for Lock() to work with this relative path, multilist must temporarily set the current directory and file system to the values in dvp_Lock and dvp_Port, respectively.

Note that the Autodoc for GetDeviceProc() says to check IoErr() for ERROR_NO_MORE_ENTRIES after receiving a NULL from GetDeviceProc(). Due to a bug, DOS does not set the error value correctly. Also note that the Autodoc says to check the DevProc structure's dvp_Flags field for the DVPF_ASSIGN flag. This was necessary in the 2.00 and 2.01 releases of the operating system due to a bug in DOS, but is no longer necessary.

= Code Example =

The following example, multilist.c, accepts an arbitrary path name and lists the contents of it. The function DoAllAssigns() does all of the multiassign work. DoAllAssigns() accepts a path and a function pointer. It gets a lock on the object named in the path, and passes the lock to the function. This example is based on a Usenet posting by Randell Jesup.

<syntaxhighlight lang="C" line>
/* This example illustrates how to scan DOS file names without */
/* having to make a special case for assigns and multiassigns. */
/* The DoAllAssigns() routine accepts an arbitrary dos path and */
/* a pointer to a function. DoAllAssigns() will call this function */
/* passing it a lock to the object named in the path. */

#define BUFSIZE 1024

#include <exec/types.h>
#include <exec/memory.h>
#include <dos/dosextens.h>
#include <dos/exall.h>

#include <clib/dos_protos.h>
#include <clib/exec_protos.h>
#include <stdio.h>
#include <strings.h>

BOOL DoAllAssigns(char *, BOOL (*)());
BOOL ListContents(BPTR);

extern struct DosLibrary *DOSBase;

void main(int argc, char **argv)
{
if (DOSBase->dl_lib.lib_Version >= 37)
{
if (argc > 1)
{
(void) DoAllAssigns(argv[1], &ListContents);
}
}
}

/* Pass this routine a directory lock and it prints the names of the */
/* files and directories in that directory. If you pass this routine */
/* a file lock, it just prints the file's name. */
BOOL ListContents(BPTR lock)
{
struct ExAllControl *myeac;
struct ExAllData *myead;
APTR buffer;
BOOL done;
struct FileInfoBlock *myfib;

if (myfib = AllocDosObject(DOS_FIB, NULL))
{
if (Examine(lock, myfib) == DOSTRUE)
{
if (myfib->fib_DirEntryType > 0)
{
if (buffer = AllocVec(BUFSIZE, MEMF_PUBLIC))
{
if (myeac = AllocDosObject(DOS_EXALLCONTROL, NULL))
{
myeac->eac_LastKey = 0;

do
{
done = ExAll(lock, buffer, BUFSIZE, ED_NAME, myeac);
myead = buffer;
while (myead)
{
printf("%s\n", myead->ed_Name);
myead = myead->ed_Next;
}
} while (done != 0);
FreeDosObject(DOS_EXALLCONTROL, myeac);
}
FreeVec(buffer);
}
}
else printf("%s\n", myfib->fib_FileName);
}
FreeDosObject(DOS_FIB, myfib);
}
return TRUE;
}

/* This routine accepts a path string that may include a device name. From */
/* that string, this routine locks the object named in the path and calls */
/* the function passback_func() on the lock. DoAllAssigns() should work on */
/* paths with assigns and multiassigns, as well as a file system-based device */
/* (i.e. df0:, work:, ram:, etc.) */

BOOL DoAllAssigns(char *dos_path, BOOL (*passback_func)(BPTR lock))
{
struct DevProc *dp=NULL;
struct MsgPort *old_fsport;
BPTR lock, old_curdir;
char *rest_of_path;

while(dp = GetDeviceProc(dos_path, dp))
{ /* I need to cut the device name from */
rest_of_path = strchr(dos_path,':'); /* the front of dos_path so I can give */
/* that substring to Lock(). */
if (rest_of_path == NULL) /* There was no device name to */
rest_of_path = dos_path; /* cut off, use the whole string. */
else
rest_of_path++; /* Increment string pointer to just past the colon. */

old_fsport = SetFileSysTask(dp->dvp_Port); /* in case dp->dvp_Lock is NULL. */
old_curdir = CurrentDir(dp->dvp_Lock); /* Lock() locks relative to the */
/* current directory and falls back to the root of */
/* the current file system if dp->dvp_Lock is NULL. */

lock = Lock(rest_of_path,SHARED_LOCK);

(void) SetFileSysTask(old_fsport); /* reset the process' default file system */
(void) CurrentDir(old_curdir); /* port and current dir to their initial */
/* values for clean up later. */

if (lock)
{
if (!(*passback_func)(lock))
{
printf("function returned false\n");
UnLock(lock); /* UnLock() will ignore NULL lock */
FreeDeviceProc(dp);
return FALSE;
}
UnLock(lock);
}
}
if (IoErr() == ERROR_NO_MORE_ENTRIES)
return TRUE; /* At present, a bug in DOS prevents this case, */
else /* so DoAllAssigns() always returns FALSE. */
return FALSE;
}
</syntaxhighlight>

Writing IFF

2025-01-26T19:25:59Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

=== Writing IFF Files ===

IFFParse provides facilities for writing IFF files. Again, IFFParse makes no assumptions about the data you’re writing, and concerns itself with verifying the syntax of your output.

=== Creating Chunks in a File ===

Because the IFF specification has nesting and scoping rules, you can nest chunks inside one another. One instance is the BMHD chunk, which is commonly nested inside a FORM chunk. Thus, it is necessary for you to inform IFFParse when you are starting and ending chunks.

==== PushChunk() ====

To tell IFFParse you are about to begin writing a new chunk, you use the function PushChunk():

<syntaxhighlight lang="C" line>
error = IIFFParse->PushChunk(iff, ID_ILBM, ID_BMHD,chunksize);
</syntaxhighlight>

The chunk ID and size are written to the stream. IFFParse will enforce the chunk size you specified; attempts to write past the end of the chunk will be truncated. If, as a chunk size argument, you pass IFFSIZE_UNKNOWN, the chunk will be expanded in size as you write data to it.

==== PopChunk() ====

When you are through writing data to a chunk, you complete the write by calling PopChunk():

<syntaxhighlight lang="C" line>
error = IIFFParse->PopChunk(iff);
</syntaxhighlight>

If you wrote fewer bytes than you declared with PushChunk(), PopChunk() will return an error. If you specified IFFSIZE_UNKNOWN, PopChunk() will seek backward on the stream and write the final size. If you specified a chunk size that was odd, PopChunk() will write the pad byte automatically.

PushChunk() and PopChunk() nest; every call to PushChunk() must have a corresponding call to PopChunk().

=== Writing Chunk Data ===

Writing the IFF chunk data is done with either the WriteChunkBytes() or WriteChunkRecords() functions.

<syntaxhighlight lang="C" line>
error = IIFFParse->WriteChunkBytes(iff, buf, size);
error = IIFFParse->WriteChunkRecords(iff, buf, recsize, numrec);
</syntaxhighlight>

If you specified a valid chunk size when you called PushChunk(), WriteChunkBytes() and WriteChunkRecords() will truncate attempts to write past the end of the chunk.

Code to write an ILBM file might take the following form:

<syntaxhighlight lang="C" line>
iff = IIFFParse->AllocIFF ();
iff->iff_Stream = IDOS->Open ("foo", MODE_NEWFILE);
IIFFParse->InitIFFasDOS (iff);
IIFFParse->OpenIFF (iff, IFFF_WRITE);

IIFFParse->PushChunk (iff, ID_ILBM, ID_FORM, IFFSIZE_UNKNOWN);

IIFFParse->PushChunk (iff, ID_ILBM, ID_BMHD, sizeof (struct BitMapHeader));
IIFFParse->WriteChunkBytes (iff, &bmhd, sizeof (bmhd));
IIFFParse->PopChunk (iff);

IIFFParse->PushChunk (iff, ID_ILBM, ID_CMAP, cmapsize);
IIFFParse->WriteChunkBytes (iff, cmapdata, cmapsize);
IIFFParse->PopChunk (iff);

IIFFParse->PushChunk (iff, ID_ILBM, ID_BODY, IFFSIZE_UNKNOWN);
packwritebody (iff);
IIFFParse->PopChunk (iff);

IIFFParse->PopChunk (iff);

IIFFParse->CloseIFF (iff);
IDOS->Close (iff->iff_Stream);
IIFFParse->FreeIFF (iff);
</syntaxhighlight>

Again, error checking is not present for clarity. See the example code ClipFTXT.c which writes a simple FTXT clip to the clipboard.

=== A Note on Seekability ===

As you can see from the above examples, IFFParse works best with a stream that can seek randomly. However, it is not possible to seek on some streams (e.g., pipes).

IFFParse will read and write streams with limited or no seek capability. In the case of reading, only forward-seek capability is desirable. Failing this, IFFParse will fake forward seeks with a number of short reads.

In the case of writing, if the stream lacks random seek capability, IFFParse will buffer ''the entire contents'' of the file until you do the final PopChunk(), or when you CloseIFF() the handle. At that time, the entire stream will be written in one go. This buffering happens whether or not you specify all the chunk sizes to PushChunk().

{{Note|title=About the Internal Buffering|text=The current implementation of this internal buffering could be more efficient. Be aware that the AmigaOS development team reserves the right to alter this behavior of the parser, to improve performance or reduce memory requirements. We mention this behavior on the off chance it is important to you.}}

ASL Font Requester

2025-01-26T19:25:55Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

The ASL library also contains a font requester. Using the font requester is very similar to using the file requester. First, allocate a requester structure with AllocAslRequest() or AllocAslRequestTags(). The type should be set to ASL_FontRequest in order to get a FontRequester structure:

<syntaxhighlight lang="C" line>
struct FontRequester {
APTR fo_Reserved1[2];
struct TextAttr fo_Attr; /* Returned TextAttr */
UBYTE fo_FrontPen; /* Returned pens, if selected */
UBYTE fo_BackPen;
UBYTE fo_DrawMode;
APTR fo_UserData;
/* missing from asl.h but present in this structure */
SHORT fo_LeftEdge, fo_TopEdge, fo_Width, fo_Height;
};
</syntaxhighlight>

Once the requester is set up, call AslRequest() or AslRequestTags() to make the requester appear on screen. These functions return TRUE if the user makes a selection. In that case, the font selected is returned as a TextAttr structure in the fo_Attr field of the FontRequester structure. (The TextAttr structure is defined in <graphics/text.h>. See the SDK for a complete listing.) If the user cancels the font requester FALSE is returned.

[[File:LibFig16-2.png|frame|center|The ASL Font Requester]]

When the requester is no longer needed, call FreeAslRequest() to deallocate the requester data structure.

= Specifying Font Requester Options With TagItems =

As with a file requester, the font requester is specified with a TagItem list. There are several tags that are specific to the font requester:

{| class="wikitable"
! Font Requester Tag Name
! Used For
|-
| ASLFO_InitialName || Initial font name selection
|-
| ASLFO_InitialSize || Initial font size
|-
| ASLFO_InitialStyle || Initial setting of font Style gadget
|-
| ASLFO_Flags || Various font requester options
|-
| ASLFO_InitialFrontPen || Initial setting of Front Color gadget
|-
| ASLFO_InitialBackPen || Initial setting of Back Color gadget
|-
| ASLFO_ModeList || Alternate strings for Mode cycle gadget (see below)
|-
| ASLFO_MinHeight || Specifies the minimum height of fonts to be listed
|-
| ASLFO_MaxHeight || Specifies the maximum height of fonts to be listed
|-
| ASLFO_DoFrontPen || Causes the requester to display the Front Color selection gadget (this replaces the FONF_FRONTCOLOR flag in ASL_FuncFlags used in V37).
|-
| ASLFO_DoBackPen || Causes the requester to display the Back Color selection gadget (this replaces the FONF_BACKCOLOR flag in ASL_FuncFlags used in V37).
|-
| ASLFO_DoStyle || Causes the requester to display Style checkbox gadgets (this replaces the FONF_STYLES flag in ASL_FuncFlags used in V37).
|-
| ASLFO_DoDrawMode || Causes the requester to display the Mode cycle gadget.(this replaces the FONF_DRAWMODE flag in ASL_FuncFlags used in V37).
|-
| ASLFO_FixedWidthOnly || Causes the requester to list only fixed-width fonts (this replaces the FONF_FIXEDWIDTH flag in ASL_FuncFlags used in V37).
|-
| ASLFO_InitialDrawMode || Initial setting of the font Mode gadget.
|}

Note that the last two tags only limit the range of font sizes that the font requester displays, the user is free to type in any value.

Font requesters have additional special options that are controlled through the ASL_FuncFlags tag. This tag works the same way as it does with file requesters but with different options available. Recall that the data for this tag is divided into bit fields, each of which controls a requester option. The flags used with the ASL_FuncFlags tag in a font requester are defined in <libraries/asl.h>:

{| class="wikitable"
! Font Requester Flags
! Used For
|-
| FONF_FRONTCOLOR
| Enables font color selection gadgets
|-
| FONF_BACKCOLOR
| Enables font background color selection gadget
|-
| FONF_STYLES
| Enables font style selection gadget
|-
| FONF_FIXEDWIDTH
| Limits display to fixed width fonts only
|-
| FONF_DRAWMODE
| Enables font draw mode gadget
|}

A simple font requester (one without any of the above FONF_ flags set) only lets the user choose a font and a Y size. Setting the flags above adds options to the font requester. FONF_FRONTCOLOR and FONF_BACKCOLOR add color selection gadgets to the requester, one for choosing a font's foreground color (labeled "Text") and the other for choosing the background color (labeled "Field"). The font requester records the user's setting in the FontRequester's fo_FrontPen and fo_BackPen fields.

FONF_STYLES sets up several gadgets to choose the style of the font (bold, italics, underline). The font requester saves these settings in the fo_Attr.ta_Style bit field according to the style flags defined in <graphics/text.h>. FONF_FIXEDWIDTH limits the font name display to fixed width (non-proportional) fonts (note that this does not prevent the user from typing in a proportional font name).

FONF_DRAWMODE adds a cycle gadget to the font requester so the user can choose the draw mode. The draw mode is saved in the requester's fo_DrawMode field. The number stored there corresponds to the draw mode's position in the gadget's cycle.

The draw mode cycle gadget initially is labeled "Mode" and has three elements in its cycle: "JAM1", "JAM2", and "Complement". These yield a result of 0, 1, and 2, respectively. It is possible to change the names and number of draw modes with the ASL_ModeList tag. This tag accepts a pointer to an array of strings. The first string replaces "Mode" as the label for the draw mode cycle gadget. The strings that follow replace the elements of the cycle gadget. The last entry in the array has to be NULL to tell the requester where the list of entries ends.

= Example Font Requester =

The following example illustrates how to use a font requester.

<syntaxhighlight lang="C" line>
/*
** fontreq.c
*/

#include <exec/types.h>
#include <libraries/asl.h>

#include <proto/asl.h>
#include <proto/exec.h>
#include <proto/dos.h>

struct AslIFace *IAsl = NULL;

/* Our replacement strings for the "mode" cycle gadget. The
** first string is the cycle gadget's label. The other strings
** are the actual strings that will appear on the cycle gadget.
*/
CONST_STRPTR modelist[] =
{
"Amiga Modes",
"Mode 0",
"Mode 1",
"Mode 2",
"Mode 3",
"Mode 4",
NULL
};

int main(int argc, char **argv)
{
struct FontRequester *fr;

struct Library *AslBase = IExec->OpenLibrary("asl.library", 50);
IAsl = (struct AslIFace*)IExec->GetInterface(AslBase, "main", 1, NULL);

if (IAsl != NULL)
{
if (fr = (struct FontRequester *)
IAsl->AllocAslRequestTags(ASL_FontRequest,
/* tell the requester to use my custom mode names */
ASL_ModeList, modelist,

/* Supply initial values for requester */
ASL_FontName, "topaz.font",
ASL_FontHeight, 11,
ASL_FontStyles, FSF_BOLD | FSF_ITALIC,
ASL_FrontPen, 0x00,
ASL_BackPen, 0x01,

/* Only display font sizes between 8 and 14, inclusive. */
ASL_MinHeight, 8,
ASL_MaxHeight, 14,

/* Give all the gadgetry, but only display fixed width fonts */
ASL_FuncFlags, FONF_FRONTCOLOR | FONF_BACKCOLOR |
FONF_DRAWMODE | FONF_STYLES | FONF_FIXEDWIDTH,
TAG_END))
{
/* Pop up the requester */
if (IAsl->AslRequest(fr, NULL))
{
/* The user selected something, report their choice */
IDOS->Printf("%s\n YSize = %ld Style = 0x%lx Flags = 0x%lx\n"
" FPen = 0x%lx BPen = 0x%lx DrawMode = 0x%lx\n",
fr->fo_Attr.ta_Name,
fr->fo_Attr.ta_YSize,
fr->fo_Attr.ta_Style,
fr->fo_Attr.ta_Flags,
fr->fo_FrontPen,
fr->fo_BackPen,
fr->fo_DrawMode);
}
else
/* The user cancelled the requester, or some kind of error
** occurred preventing the requester from opening. */
IDOS->Printf("Request Cancelled\n");

IAsl->FreeAslRequest(fr);
}
}

IExec->DropInterface((struct Interface*)IAsl);
IExec->CloseLibrary(AslBase);

return 0;
}
</syntaxhighlight>

Revision 5

2025-01-26T19:25:52Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

== Authors ==

Hook-based callback function extensions for SANA-II (SANA-IIR5) 
by Olaf Barthel and Heinz Wrobel

== Introduction ==

The last changes proposed for the SANA-II networking driver standard were intended to address the demands of dial-up networking. A new issue has come up which concerns the application and deployment of PowerPC native networking drivers. So far the SANA-II standard only caters well for the Motorola 68000 platform, and the only way to support it on the PowerPC involves a considerable overhead. This is what the following proposal intends to address.

Please feel free to comment; you can contact me through the [http://www.amigaos.net/contact AmigaOS contact form]. Note that the issues discussed in this document are just a list of proposed changes.

== The problem: parameter passing to the copying functions ==

The SANA-II driver interface is intended to transform data between the hardware layer and the link layer, to be used by networking software such as TCP/IP stacks. This transformation is performed by call-back functions which are supplied by the networking software at the time the device driver is opened. The device driver then invokes these functions later in order to transfer data received and data to be sent.

These copying functions are designed for low overhead. They use up to three parameters and are documented in the copybuff.doc file which comes with the SANA-II specification. Here is an excerpt which describes the <tt>CopyFromBuff</tt> function, which is associated with the <tt>S2_CopyFromBuff</tt> tag:

<pre>
any_sana2_protocol/CopyFromBuff any_sana2_protocol/CopyFromBuff

NAME
CopyFromBuff -- Copy n bytes from an abstract data structure.

SYNOPSIS
success = CopyFromBuff(to, from, n)
d0 a0 a1 d0

BOOL CopyToBuff(VOID *, VOID *, ULONG);

FUNCTION
This function copies 'n' bytes of data in the abstract data structure
pointed to by 'from' into the contigous memory pointed to by 'to'.
'to' must contain at least 'n' bytes of usable memory or innocent
memory will be overwritten.

INPUTS
to - pointer to contiguous memory to copy to.
from - pointer to abstract structure to copy from.
n - number of bytes to copy.

RESULT
success - TRUE if operation was successful, else FALSE.

NOTES
This function must be callable from interupts. In particular, this
means that this function may not directly or indirectly call any
system memory functions (since those functions rely on Forbid() to
protect themselves) and that you must not compile this function
with stack checking enabled. See the Exec Interupts
chapter for more details on what is legal in a routine called from
an interupt handler.

'C' programmers should not compile with stack checking (option '-v'
in SAS) and should geta4() or __saveds.</pre>
As one can see, the function parameters are passed in 68000 registers. Compare this to the packet filter function, which is associated with the <tt>S2_PacketFilter</tt> tag: it is intended to be invoked as a hook function, as part of the <tt>Hook</tt> interface in <tt>utility.library/CallHookPkt</tt>.

The problem with 68000 register parameters is that on the PowerPC platform, this form of parameter passing may require the use of emulation code. This is costly and may incur a severe performance penalty. It is an even greater problem if PowerPC native networking software is calling PowerPC native networking driver software and the other way round. In both cases the runtime environment will have to enter emulation mode, return to to PowerPC native execution, dip into emulation mode and return to native PowerPC execution. It would be much better if the chain of execution would stay in PowerPC mode all the time.

However, if a hook function is used (such as for the packet filter), the operating system may be able to decide whether the function to be invoked needs emulating or could be called straight away. The <tt>Hook</tt> effectively works as an abstraction which makes the function invocation platform independent.

The following proposal therefore intends to wrap the copying functions into the standardized <tt>Hook</tt> interface.

== New data structures and commands ==

=== Data structures ===

The SANA-IIR4 proposal lists ten copying functions, which can be grouped into two categories: data copying and direct memory access. These functions are:

* Data copying:
** <tt>S2_CopyToBuff</tt>
** <tt>S2_CopyFromBuff</tt>
** <tt>S2_CopyToBuff16</tt>
** <tt>S2_CopyFromBuff16</tt>
** <tt>S2_CopyToBuff32</tt>
** <tt>S2_CopyFromBuff32</tt>

* Direct memory access:
** <tt>S2_DMACopyToBuff32</tt>
** <tt>S2_DMACopyFromBuff32</tt>
** <tt>S2_DMACopyToBuff64</tt>
** <tt>S2_DMACopyFromBuff64</tt>

There are three 'flavours' of the data copying functions. These cater for certain buffer memory alignment requirements which the underlying hardware requires or which can be used to boost transfer efficiency. For the direct memory access functions there are two variants which cater for certain memory alignment requirements in the same manner as the copying functions.

All these functions are using basically the same set of parameters and 68000 registers. The parameters and result codes are used for different purposes, though. In order to translate the parameters for use with the <tt>Hook</tt> interface one needs to define a 'hook message' and a set of parameters the hook function is invoked with.

I propose the following hook messages to be used :

<syntaxhighlight lang="C" line>
struct SANA2HookMsg
{
ULONG shm_Method;
ULONG shm_MsgSize;
};
</syntaxhighlight>

In this data structure the <tt>shm_Method</tt> field would indicate the task to be performed. This can a be request to copy data or to store a log message. The <tt>shm_MsgSize</tt> field tells you how large the data structure is (for future enhancements which may cause the data structure to grow).

For copying operations the message would look like this:

<syntaxhighlight lang="C" line>
struct SANA2CopyHookMsg
{
ULONG schm_Method;
ULONG schm_MsgSize;

APTR schm_To;
APTR schm_From;
ULONG schm_Size;
};
</syntaxhighlight>

The structure members would be used as follows:

<ul>
<li><tt>schm_Method</tt>
This must be one <tt>S2_CopyToBuff</tt>, <tt>S2_CopyFromBuff</tt>, <tt>S2_CopyToBuff16</tt>, <tt>S2_CopyFromBuff16</tt>, <tt>S2_CopyToBuff32</tt>, <tt>S2_CopyFromBuff32</tt>, <tt>S2_DMACopyToBuff32</tt>, <tt>S2_DMACopyFromBuff32</tt>, <tt>S2_DMACopyToBuff64</tt> or <tt>S2_DMACopyFromBuff64</tt> to identify the function to be performed.</li>
<li><tt>schm_MsgSize</tt>
Size of this message data structure in bytes. This must be >= 20 for this message type.
The driver shall set <tt>schm_MsgSize</tt> always correctly to be compliant. The protocol stack shall use this field to validate the message and to reject/ignore bad messages via a <tt>FALSE</tt> hook function return value. For DMA related hooks, a <tt>FALSE</tt> return value is equivalent to a <tt>NUL</tt>L pointer.</li>
<li><tt>schm_To</tt>
Equivalent to the <tt>to</tt> parameter of the <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt> and <tt>DMACopyToBuff</tt> functions.</li>
<li><tt>schm_From</tt>
Equivalent to the <tt>from</tt> parameter of the <tt>CopyFromBuff</tt> and <tt>CopyToBuff</tt> functions.</li>
<li><tt>schm_Size</tt>
Equivalent to the <tt>n</tt> parameter of the <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt>, functions.</li></ul>

For logging operations the message would look like this:

<syntaxhighlight lang="C" line>
struct SANA2LogHookMsg
{
ULONG slhm_Method;
ULONG slhm_MsgSize;

ULONG slhm_Priority;
STRPTR slhm_Name;
STRPTR slhm_Message;
};
</syntaxhighlight>

The structure members would be used as follows:

<ul>
<li><tt>slhm_Method</tt>
This must be <tt>S2_Log</tt>, as defined in the SANA-IIR4 specification.</li>
<li><tt>slhm_MsgSize</tt>
Size of this message data structure in bytes. This must be >= 20 for this message type.
The driver shall set <tt>slhm_MsgSize</tt> always correctly to be compliant. The protocol stack shall use this field to validate the message and to reject/ignore bad messages via a <tt>FALSE</tt> hook function return value. For DMA related hooks, a <tt>FALSE</tt> return value is equivalent to a <tt>NULL</tt> pointer.</li>
<li><tt>slhm_Priority</tt>
The smaller this value, the more important the message to be logged or displayed. The following priority levels are defined (similar to the Unix syslog() mechanism):
<ul>
<li><tt> #define S2LOG_Emergency 0 </tt>
A panic condition.</li>
<li><tt> #define S2LOG_Alert 1 </tt>
A condition that should be corrected immediately.</li>
<li><tt> #define S2LOG_Critical 2 </tt>
Critical conditions.</li>
<li><tt> #define S2LOG_Error 3 </tt>
A plain error.</li>
<li><tt> #define S2LOG_Warning 4 </tt>
A warning message.</li>
<li><tt> #define S2LOG_Notice 5 </tt>
Conditions that are not error conditions, but should possibly be handled specially.</li>
<li><tt> #define S2LOG_Information 6 </tt>
An informational message.</li>
<li><tt> #define S2LOG_Debug 7 </tt>
Messages that contain information normally of use only when debugging.</li></ul>

Only these priority values may be used by a driver. It is suggested that a driver is configurable to generate different types of messages or not, e.g., a driver may be configured to only emit <tt>S2LOG_Emergency</tt> and <tt>S2LOG_Debug</tt> messages.</li>
<li><tt> slhm_Name </tt>
Pointer to a <tt>NUL</tt>-terminated string which identifies the source of this message. This can be <tt>NULL</tt> in which case the OS device name of the driver shall be used by the protocol stack.</li>
<li><tt> slhm_Message </tt>
Pointer to a <tt>NUL</tt>-terminated string which contains the log message. The text should not contain any formatting characters such as line feeds or carriage returns. The <tt>slhm_Message</tt> member must never be <tt>NULL</tt>.
All message texts shall preferrably be formatted in the current user's locale. If that is not possible, the english language shall be used. <tt>slhm_Name</tt> and <tt>slhm_Message</tt> shall only contain printable characters.</li></ul>

The hook function itself would be invoked with the following parameters:

<syntaxhighlight lang="C" line>
result = hook_function(hook,sana2req,sana2hookmsg)

ULONG hook_function(struct Hook *hook,
struct IOSana2Req *sana2req,
struct SANA2HookMsg *sana2hookmsg);
</syntaxhighlight>

Note that the result would not necessarily be of type <tt>ULONG</tt>. It would be a 32 bit value, which would either be a boolean result code (for <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt> and their like) or the pointer to a memory address (for <tt>DMACopyToBuff</tt>, <tt>DMACopyFromBuff</tt> and their like).

=== Commands ===

The 'traditional' copy call-back functions are installed at <tt>OpenDevice()</tt> time, and they are found in a <tt>TagItem</tt> list which is passed along with the <tt>IOSana2Req</tt>. For the new <tt>Hook</tt>-based call-back functionality, I propose to introduce a new command. This command would take care of installing one single <tt>Hook</tt> which will be invoked with the parameters described in section 3.1. The hook function can key off the <tt>SANA2HookMsg->schm_Method</tt> field to figure out which function should be performed. Once the <tt>Hook</tt> is installed via the command as follows, the driver shall ignore any and all tags passed to it during <tt>OpenDevice()</tt> time.

The command is tentatively defined as follows:

<pre>
sana2.device/S2_SANA2HOOK sana2.device/S2_SANA2HOOK

NAME
S2_SANA2HOOK -- Install a Hook to perform operations such as copying,
overriding the call-back functions installed at
OpenDevice() time.

FUNCTION
The S2_SANA2HOOK command is to replace the 'traditional' call-back
functions installed through the TagItem list found in the
IOSana2Req->ios2_BufferManagement field. Instead of assigning a
function pointer for each copying function, all operations are
to be performed through a Hook. This is intended to make the
interface more portable and less dependant on a certain hardware
architecture.

The hook message and the hook data structures allow for more than
copying to be done.

IO REQUEST
ios2_Command - S2_SANA2HOOK
ios2_Data - Points to a struct Sana2Hook, which looks
like this:

struct Sana2Hook
{
struct Hook s2h_Hook;
Tag * s2h_Methods;
};

The structure fields have the following purposes:

s2h_Hook
A standard Hook structure, ready to be
called. Once installed, the complete Hook
structure including its Node structure is
off limits! The s2h_Hook remains installed
until CloseDevice().

s2h_Methods
Points to a table of Tag values, each
identifying a copy method supported
(S2_CopyToBuff, S2_CopyFromBuff,
S2_CopyToBuff16, S2_CopyFromBuff16,
S2_CopyToBuff32, S2_CopyFromBuff32,
S2_DMACopyToBuff32, S2_DMACopyFromBuff32,
S2_DMACopyToBuff64 or S2_DMACopyFromBuff64)
or the logging facility (S2_Log).
The table must be terminated by TAG_END.

The driver will check the table and
verify that the mandatory S2_CopyToBuff
and S2_CopyFromBuff commands are present.
Additional functionality is used as
available if the driver supports it.

ios2_DataLength - Must be >= 20, which is the default length of
the Sana2Hook structure. This may grow in
the future, and larger values for ios2_DataLength
may indicate additional functionality associated
with the Sana2Hook.

RESULTS
ios2_Error - IOERR_NOCMD if this command is not supported
by the driver.

IOERR_BADLENGTH if IOSana2Req->ios2_DataLength
is < 20.

IOERR_UNITBUSY if the Hook was already
installed or if any of the CMD_READ, CMD_WRITE,
S2_MULTICAST or S2_BROADCAST have already been
invoked.

S2WERR_FUNCTIONS_MISSING if the table pointed
to by Sana2Hook->s2h_Methods does not
include the S2_CopyToBuff and S2_CopyFromBuff
tags.

NOTES
The S2_SANA2HOOK command shall be invoked right after OpenDevice()
as very first command.

When the command has been executed, the driver must use the
newly installed Hook for all its copying or logging and cease to
use the call-back functions provided at OpenDevice() time.

The contents of the Sana2Hook structure, as passed to the
driver, must not be modified. This includes the MinNode
at the beginning of the Hook structure which the driver may
need to use for its own purposes.

The table pointed to by Sana2Hook->s2h_Methods must
include at least the S2_CopyToBuff and S2_CopyFromBuff tags.
It must be valid until CloseDevice() is called.

This field is to be treated as private by a protocol stack.
IOSana2Req structures may be duplicated by copying
ios2_BufferManagement, io_Device, and io_Unit.
</pre>

The new command value is defined as follows:

<pre>
#define S2_SANA2HOOK 0xC008
</pre>

The new error code is defined as follows:

<pre>
#define S2WERR_FUNCTIONS_MISSING 24 /* mandatory copy functions are missing */
</pre>

== Application and driver software use of the new functions ==

Since plenty of software exists which uses the 'traditional' <tt>TagItem</tt> list provided at <tt>OpenDevice()</tt> time it is recommend that drivers always examine these parameters and do not expect a <tt>S2_SANA2HOOK</tt> command to be sent later.

If the new <tt>Hook</tt>-based callback functions are to be used, then the driver must invoke the Hooks via <tt>utility.library/CallHookPkt</tt>. It must not invoke the hook functions through local assembly language stubs or the <tt>amiga.lib/CallHook</tt> and <tt>amiga.lib/CallHookA</tt> functions.

== Caveats ==

The functionality proposed above suggests that one could do entirely without the <tt>TagItem</tt> list passed in at <tt>OpenDevice()</tt> time. However, at this time it is hard to tell how existing driver software will react to empty <tt>TagItem</tt> lists or even a NULL pointer in the <tt>IOSana2Req->ios2_BufferManagement</tt> field. It is therefore recommend to always provide for a <tt>TagItem</tt> list which includes proper (i.e. they must point to working functions and may not be <tt>NULL</tt>) function pointers for the <tt>S2_CopyToBuff</tt> and <tt>S2_CopyFromBuff</tt> tags. Once the device has been opened successfully, the next step is to try and install the copy <tt>Hook</tt> through the proposed <tt>S2_SANA2HOOK</tt> command. If the command fails, the application can still expect that the <tt>S2_CopyToBuff</tt> and <tt>S2_CopyFromBuff</tt> tags supplied at <tt>OpenDevice()</tt> time will work.

Note that the <tt>ios2_BufferManagement</tt> field provided by the driver on <tt>OpenDevice()</tt> time in conjunction with <tt>io_Device</tt> and <tt>io_Unit</tt> is the unique identifier for all requests coming from this protocol stack until <tt>CloseDevice()</tt>. The driver must not ever change the <tt>ios2_BufferManagement</tt> field for a protocol stack at run time, even if <tt>S2_SANAHOOK</tt> is called to request extended features.

== Changes ==

02-May-2012:

* Conversion to MediaWiki format.

22-Mar-2004:

* Conversion to HTML

21-Jan-2004:

* Added clarifications for <tt>schm_MsgSize</tt>, <tt>slhm_MsgSize</tt>, <tt>slhm_Priority</tt>, <tt>slhm_Name</tt>, <tt>slhm_Message</tt> and <tt>s2h_Hook</tt>.
* Updated the <tt>S2_SANA2HOOK</tt> documentation.
* Shortened section 4.
* Updated section 5.

30-Nov-2003:

* Extended the applicability of the <tt>Hook</tt> to logging.
* Renamed <tt>S2_COPYHOOK</tt> to <tt>S2_SANA2HOOK</tt>, which matches the extended scope it should cover.
* The message passed to the <tt>Hook</tt> now includes a size field which holds the size of the message, expressed in bytes.

06-Oct-2003:

* Replaced the list of new tag items with a single <tt>Hook</tt>, which is installed through a new command.
* Added "Caveats" and "Changes" sections
* Removed the documentation for the originally proposed <tt>TagItem</tt> (sections 3.2.1 through 3.2.10)

BattClock Resource

2025-01-26T19:25:31Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

== Introduction ==

The battery-backed clock (BattClock) keeps Amiga time while the system is powered off. The time from the BattClock is loaded into the Amiga system clock as part of the boot sequence.

The BattClock Resource component provides access to the BattClock. Three [[#Function reference|functions]] allow you to read the BattClock value, reset it and set it to a value you desire.

The [[Utility Library]] contains time functions which convert the number of seconds since 12:00 AM, January 1, 1978 to a date and time we can understand, and vice versa. You will find these functions useful when dealing with the BattClock. The example program below uses the Amiga2Date() utility function to convert the value returned by ReadBattClock(). See the [[Utility Library]] page for a discussion of the scope of the library, and the [[Autodocs:Main|autodocs]] for a listing of its functions.

{{Note|title=''So, you want to be a Time Lord?''|This resource will allow you to set the BattClock to any value you desire. Keep in mind that this time will endure a reboot and could adversely affect your system!}}

== Example ==

<syntaxhighlight lang="C" line>
#include <exec/types.h>
#include <dos/dos.h>
#include <utility/date.h>
#include <resources/battclock.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/battclock.h>
#include <proto/utility.h>

int main()
{
STRPTR ampm;
uint32 AmigaTime;
struct ClockData MyClock;
CONST CONST_STRPTR Days[] = {"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"};
CONST CONST_STRPTR Months[] = {"January", "February", "March", "April", "May", "June", "July", "August",
"September", "October", "November", "December"};

struct Library *BattClockBase = IExec->OpenResource(BATTCLOCKNAME);
struct BattClockIFace *IBattClock = (struct BattClockIFace *) IExec->GetInterface(BattClockBase, "main", 1, NULL);

if (IBattClock != NULL) {
/* Get number of seconds till now */
AmigaTime = IBattClock->ReadBattClock();

/* Convert to a ClockData structure */
IUtility->Amiga2Date(AmigaTime, &MyClock);
IDOS->Printf("\nRobin, tell everyone the BatDate and BatTime");

/* Print the Date */
IDOS->Printf("\n\nOkay Batman, the BatDate is ");
IDOS->Printf("%s, %s %ld, %ld", Days[MyClock.wday], Months[MyClock.month-1], MyClock.mday, MyClock.year);

/* Convert military time to normal time and set AM/PM */
if (MyClock.hour < 12) {
ampm = "AM"; /* hour less than 12, must be morning */
}
else {
ampm = "PM"; /* hour greater than 12,must be night */
MyClock.hour -= 12; /* subtract the extra 12 of military */
};

if (MyClock.hour == 0) {
MyClock.hour = 12; /* don't forget the 12s */
}

/* Print the time */
IDOS->Printf("\n the BatTime is ");
IDOS->Printf("%02ld:%02ld:%02ld %s\n\n", MyClock.hour, MyClock.min, MyClock.sec, ampm);

IExec->DropInterface((struct Interface*) IBattClock);
}
else
IDOS->Printf("Error: Unable to open the %s\n", BATTCLOCKNAME);

return 0;
}
</syntaxhighlight>

Additional programming information on the BattClock Resource can be found in the respective include files and in the BattClock Resource and Utility Library [[Autodocs:Main|autodocs]].

== Function reference ==

{| class="wikitable"
| ReadBattClock() || Read the time from the BattClock. Returns the time as the number of seconds since 12:00 AM, January 1, 1978.
|-
| ResetBattClock() || Reset the BattClock to 12:00 AM, January 1, 1978.
|-
| WriteBattClock() || Set the BattClock to the number of seconds you pass it relative to 12:00 AM, January 1, 1978.
|}

GadTools Gadgets

2025-01-26T19:25:24Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

=== Introduction ===

{{Note|text=GadTools-based GUIs are largely obsolete. Prefer to use a modern BOOPSI-based GUI system instead.}}

The heart of GadTools is in its ability to easily create and manipulate a sophisticated and varied array of gadgets. GadTools supports the following kinds of gadgets:

{| class="wikitable"
|+ Standard Gadget Types Supported by the GadTools Library
! Gadget Type
! Description or Example Usage
|-
| Button
| Familiar action gadgets, such as "OK" or "Cancel".
|-
| String
| For text entry.
|-
| Integer
| For numeric entry.
|-
| Checkboxes
| For on/off items.
|-
| Mutually exclusive
| Radio buttons, select one choice among several.
|-
| Cycle
| Multiple-choice, pick one of a small number of choices.
|-
| Sliders
| To indicate a level within a range.
|-
| Scrollers
| To indicate a position in a list or area.
|-
| Listviews
| Scrolling lists of text.
|-
| Palette
| Color selection.
|-
| Text-display
| Read-only text.
|-
| Numeric-display
| Read-only numbers.
|}

GadTools gadget handling consists of a body of routines to create, manage and delete any of the 12 kinds of standard gadgets listed in the previous table, such as buttons, sliders, mutually exclusive buttons and scrolling lists.

To illustrate the flexibility, power and simplicity that GadTools offers, consider the GadTools slider gadget. This gadget is used to indicate and control the level of something, for example volume, speed or color intensity. Without GadTools, applications have to deal directly with Intuition proportional and their arcane variables, such as HorizBody to control the slider knob's size and HorizPot to control the knob's position. Using the GadTools slider allows direct specification of the minimum and maximum levels of the slider, as well as its current level. For example, a color slider might have a minimum level of 0, a maximum level of 15 and a current level of 11.

To simplify event-processing for the slider, GadTools only sends the application a message when the knob has moved far enough to cause the slider level, as expressed in application terms, to change. If a user were to slowly drag the knob of this color slider all the way to the right, the program will only hear messages for levels 12, 13, 14 and 15, with an optional additional message when the user releases the mouse-button.

Changing the current level of the slider from within the program is as simple as specifying the new level in a function call. For instance, the application might set the slider's value to 5.

As a final point, the slider is very well-behaved. When the user releases the mouse-button, the slider immediately snaps to the centered position for the level. If a user sets their background color to light gray, which might have red = green = blue = 10, all three color sliders will have their knobs at precisely the same relative position, instead of anywhere in the range that means "ten".

==== The NewGadget Structure ====

For most gadgets, the NewGadget structure is used to specify its common attributes. Additional attributes that are unique to specific kinds of gadgets are specified as tags sent to the CreateGadget() function (described below).

The NewGadget structure is defined in <intuition/gadtools.h> as:

<syntaxhighlight lang="C" line>
struct NewGadget
{
WORD ng_LeftEdge, ng_TopEdge;
WORD ng_Width, ng_Height;
UBYTE *ng_GadgetText;
struct TextAttr *ng_TextAttr;
UWORD ng_GadgetID;
ULONG ng_Flags;
APTR ng_VisualInfo;
APTR ng_UserData;
};
</syntaxhighlight>

The fields of the NewGadget structure are used as follows:

; ng_LeftEdge, ng_TopEdge
: Define the position of the gadget being created.

; ng_Width, ng_Height
: Define the size of the gadget being created.

; ng_GadgetText
: Most gadgets have an associated label, which might be the text in a button or beside a checkmark. This field contains a pointer to the appropriate string. Note that only the pointer to the text is copied, the text itself is not. The string supplied must remain constant and valid for the life of the gadget.

; ng_TextAttr
: The application must specify a font to use for the label and any other text that may be associated with the gadget.

: Used to describe general aspects of the gadget, which includes where the label is to be placed and whether the label should be rendered in the highlight color. The label may be positioned on the left side, the right side, centered above, centered below or dead-center on the gadget. For most gadget kinds, the label is placed on the left side by default, exceptions will be noted.

; ng_GadgetID, ng_Flags, ng_UserData
: These user fields are copied into the resulting Gadget structure.

; ng_VisualInfo
: This field must contain a pointer to an instance of the VisualInfo structure, which contains information needed to create and render GadTools gadgets. The VisualInfo structure itself is private to GadTools and subject to change. Use the specialized GadTools functions for accessing the VisualInfo pointer, defined below. Never access or modify fields within this structure.

==== Creating Gadgets ====

The main call used to create a gadget with GadTools is CreateGadget(). This function can be used to create a single gadget or it can be called repeatedly to create a linked list of gadgets. It takes three arguments followed by a set of tags:

<syntaxhighlight lang="C" line>
struct Gadget *CreateGadget( ULONG kind, struct Gadget *prevgad, struct NewGadget *newgad,
struct TagItem *taglist);
struct Gadget *CreateGadgetA(ULONG kind, struct Gadget *prevgad, struct NewGadget *newgad,
Tag tag1, ...);
</syntaxhighlight>

Set the kind argument to one of the 12 gadget types supported by GadTools. Set the prevgad argument to the gadget address returned by CreateContext() if this is the first (or only) gadget in the list. Subsequent calls to CreateGadget() can be used to create and link gadgets together in a list in which case the prevgad argument is set to the address of the gadget returned by the preceding call to CreateGadget().

Set the newgad argument to the address of the NewGadget structure describing the gadget to be created and set any special attributes for this gadget type using the tag arguments, tag1 or taglist. For instance, the following code fragment might be used to create the color slider discussed earlier:

<syntaxhighlight lang="C" line>
slidergad = IGadTools->CreateGadget(SLIDER_KIND, newgadget, prevgad,
GTSL_Min, 0,
GTSL_Max, 15,
GTSL_Level, 11,
TAG_END);
</syntaxhighlight>

CreateGadget() typically allocates and initializes all the necessary Intuition structures, including in this case the Gadget, IntuiText and PropInfo structures, as well as certain buffers. For more about these underlying structures, see [[Intuition_Gadgets|Intuition Gadgets]].

Since CreateGadget() is a tag-based function, it is easy to add more tags to get a fancier gadget. For example, GadTools can optionally display the running level beside the slider. The caller must supply a printf()-style formatting string and the maximum length that the string will resolve to when the number is inserted:

<syntaxhighlight lang="C" line>
slidergad = IGadTools->CreateGadget(SLIDER_KIND, newgadget, prevgad,
GTSL_Min, 0,
GTSL_Max, 15,
GTSL_Level, 11,
GTSL_LevelFormat, "%2ld", /* printf()-style formatting string */
GTSL_MaxLevelLen, 2, /* maximum length of string */
TAG_END);
</syntaxhighlight>

The level, 0 to 15 in this example, would then be displayed beside the slider. The formatting string could instead be "%2ld/15" so the level would be displayed as "0/15" through "15/15".

==== Handling Gadget Messages ====

GadTools gadgets follow the same input model as other Intuition components. When the user operates a GadTools gadget, Intuition notifies the application about the input event by sending an IntuiMessage. The application can get these messages at the Window.UserPort. However GadTools gadgets use different message handling functions to get and reply these messages. Instead of the Exec functions GetMsg() and ReplyMsg(), applications should get and reply these messages through a pair of special GadTools functions, GT_GetIMsg() and GT_ReplyIMsg().

<syntaxhighlight lang="C" line>
struct IntuiMessage *GT_GetIMsg(struct MsgPort *iport);
VOID GT_ReplyIMsg(struct IntuiMessage *imsg);
</syntaxhighlight>

For GT_GetIMsg(), the iport argument should be set to the window's UserPort. For GT_ReplyIMsg(), the imsg argument should be set to a pointer to the IntuiMessage returned by GT_GetIMsg().

These functions ensure that the application only sees the gadget events that concern it and in a desirable form. For example, with a GadTools slider gadget, a message only gets through to the application when the slider's level actually changes and that level can be found in the IntuiMessage's Code field:

<syntaxhighlight lang="C" line>
imsg = IGadTools->GT_GetIMsg(win->UserPort);
object = imsg->IAddress;
class = imsg->Class;
code = imsg->Code;
IGadTools->GT_ReplyIMsg(imsg);
switch (class)
{
case IDCMP_MOUSEMOVE:
if (object == slidergad)
{
IDOS->Printf("Slider at level %ld\n", code);
}
...
break;
...
}
</syntaxhighlight>

In general, the IntuiMessages received from GadTools contain more information in the Code field than is found in regular Intuition gadget messages. Also, when dealing with GadTools a lot of messages (mostly IDCMP_MOUSEMOVEs) do not have to be processed by the application. These are two reasons why dealing with GadTools gadgets is much easier than dealing with regular Intuition gadgets. Unfortunately this processing cannot happen magically, so applications must use GT_GetIMsg() and GT_ReplyIMsg() where they would normally have used GetMsg() and ReplyMsg().

GT_GetIMsg() actually calls GetMsg() to remove a message from the specified window's UserPort. If the message pertains to a GadTools gadget then some dispatching code in GadTools will be called to process the message. What the program will receive from GT_GetIMsg() is actually a copy of the real IntuiMessage, possibly with some supplementary information from GadTools, such as the information typically found in the Code field.

The GT_ReplyIMsg() call will take care of cleaning up and replying to the real IntuiMessage.

{{Note|title=Warning|text=When an IDCMP_MOUSEMOVE message is received from a GadTools gadget, GadTools arranges to have the gadget's pointer in the IAddress field of the IntuiMessage. While this is extremely convenient, it is also untrue of messages from regular Intuition gadgets (described in [[Intuition_Gadgets|Intuition Gadgets]]). Do not make the mistake of assuming it to be true.}}

This description of the inner workings of GT_GetIMsg() and GT_ReplyIMsg() is provided for understanding only; it is crucial that the program make no assumptions or interpretations about the real IntuiMessage. Any such inferences are not likely to hold true in the future. See the section on documented side-effects for more information.

=== IDCMP Flags ===

The various GadTools gadget types require certain classes of IDCMP messages in order to work. Applications specify these IDCMP classes when the window is opened or later with ModifyIDCMP() (see [[Intuition_Windows|Intuition Windows]] for more on this). Each kind of GadTools gadget requires one or more of these IDCMP classes: IDCMP_GADGETUP, IDCMP_GADGETDOWN, IDCMP_MOUSEMOVE, IDCMP_MOUSEBUTTONS and IDCMP_INTUITICKS. As a convenience, the IDCMP classes required by each kind of gadget are defined in <libraries/gadtools.h>. For example, SLIDERIDCMP is defined to be:

<syntaxhighlight lang="C" line>
#define SLIDERIDCMP (IDCMP_GADGETUP | IDCMP_GADGETDOWN | IDCMP_MOUSEMOVE)
</syntaxhighlight>

{{Note|title=Always OR the IDCMP Flag Bits|text=When specifying the IDCMP classes for a window, never add the flags together, always OR the bits together. Since many of the GadTools IDCMP constants have multiple bits set, adding the values will not lead to the proper flag combination.}}

If a certain kind of GadTools gadget is used, the window must use all IDCMP classes required by that kind of gadget. Do not omit any that are given for that class, even if the application does require the message type.

Because of the way GadTools gadgets are implemented, programs that use them always require notification about window refresh events. Even if the application performs no rendering of its own, it may not use the WFLG_NOCAREREFRESH window flag and must always set IDCMP_REFRESHWINDOW. See the section on "Gadget Refresh Functions" below for more on this.

=== Freeing Gadgets ===

After closing the window, the gadgets allocated using CreateGadget() must be released. FreeGadgets() is a simple call that will free all the GadTools gadgets that it finds, beginning with the gadget whose pointer is passed as an argument.

<syntaxhighlight lang="C" line>
VOID FreeGadgets( struct Gadget *gad );
</syntaxhighlight>

The gad argument is a pointer to the first gadget to be freed. It is safe to call FreeGadgets() with a NULL gadget pointer, the function will then return immediately. Before calling FreeGadgets(), the application must first either remove the gadgets or close the window.

When the gadget passed to FreeGadgets() is the first gadget in a linked list, the function frees all the GadTools gadgets on the list without patching pointers or trying to maintain the integrity of the list. Any non-GadTools gadgets found on the list will not be freed, hence the result will not necessarily form a nice list since any intervening GadTools gadgets will be gone.

See the section on "Creating Gadget Lists" for more information on using linked lists of gadgets.

=== Simple GadTools Gadget Example ===

The example listed here shows how to use the NewGadget structure and the GadTools library functions discussed above to create a simple button gadget.

<syntaxhighlight lang="C" line>
/* simplegtgadget.c
Simple example of a GadTools gadget.
*/
#define INTUI_V36_NAMES_ONLY

#include <exec/types.h>
#include <intuition/intuition.h>
#include <intuition/gadgetclass.h>
#include <libraries/gadtools.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/gadtools.h>

/* Gadget defines of our choosing, to be used as GadgetID's. */
#define MYGAD_BUTTON (4)

VOID process_window_events(struct Window *);
VOID gadtoolsWindow(VOID);

struct TextAttr Topaz80 = { "topaz.font", 8, 0, 0, };

struct InuitionIFace *IIntuition;
struct GadToolsIFace *IGadTools;

/*
** Open all libraries and run. Clean up when finished or on error..
*/
int main()
{
struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);

struct Library *GadToolsBase = IExec->OpenLibrary("gadtools.library", 50);
IGadTools = (struct GadToolsIFace*)IExec->GetInterface(GadToolsBase, "main", 1, NULL);

if (IIntuition != NULL && IGadTools != NULL)
{
gadtoolsWindow();
}

IExec->DropInterface((struct Interface*)IGadTools);
IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(GadToolsBase);
IExec->CloseLibrary(IntuitionBase);
return 0;
}

/*
** Prepare for using GadTools, set up gadgets and open window.
** Clean up and when done or on error.
*/
VOID gadtoolsWindow(VOID)
{
struct Screen *mysc;
struct Window *mywin;
struct Gadget *glist, *gad;
struct NewGadget ng;
void *vi;

glist = NULL;

if ( (mysc = IIntuition->LockPubScreen(NULL)) != NULL )
{
if ( (vi = IGadTools->GetVisualInfo(mysc, TAG_END)) != NULL )
{
/* GadTools gadgets require this step to be taken */
gad = IGadTools->CreateContext(&glist);

/* create a button gadget centered below the window title */
ng.ng_TextAttr = &Topaz80;
ng.ng_VisualInfo = vi;
ng.ng_LeftEdge = 150;
ng.ng_TopEdge = 20 + mysc->WBorTop + (mysc->Font->ta_YSize + 1);
ng.ng_Width = 100;
ng.ng_Height = 12;
ng.ng_GadgetText = "Click Here";
ng.ng_GadgetID = MYGAD_BUTTON;
ng.ng_Flags = 0;
gad = IGadTools->CreateGadget(BUTTON_KIND, gad, &ng, TAG_END);

if (gad != NULL)
{
if ( (mywin = IIntuition->OpenWindowTags(NULL,
WA_Title, "GadTools Gadget Demo",
WA_Gadgets, glist, WA_AutoAdjust, TRUE,
WA_Width, 400, WA_InnerHeight, 100,
WA_DragBar, TRUE, WA_DepthGadget, TRUE,
WA_Activate, TRUE, WA_CloseGadget, TRUE,
WA_IDCMP, IDCMP_CLOSEWINDOW |
IDCMP_REFRESHWINDOW | BUTTONIDCMP,
WA_PubScreen, mysc,
TAG_END)) != NULL )
{
IGadTools->GT_RefreshWindow(mywin, NULL);

process_window_events(mywin);

IIntuition->CloseWindow(mywin);
}
}
/* FreeGadgets() must be called after the context has been
** created. It does nothing if glist is NULL
*/
IGadTools->FreeGadgets(glist);
IGadTools->FreeVisualInfo(vi);
}
IIntuition->UnlockPubScreen(NULL, mysc);
}
}

/*
** Standard message handling loop with GadTools message handling functions
** used (GT_GetIMsg() and GT_ReplyIMsg()).
*/
VOID process_window_events(struct Window *mywin)
{
struct IntuiMessage *imsg;
struct Gadget *gad;
BOOL terminated = FALSE;

while (!terminated)
{
IExec->Wait (1 << mywin->UserPort->mp_SigBit);

/* Use GT_GetIMsg() and GT_ReplyIMsg() for handling */
/* IntuiMessages with GadTools gadgets. */
while ((!terminated) && (imsg = IGadTools->GT_GetIMsg(mywin->UserPort)))
{
/* GT_ReplyIMsg() at end of loop */

switch (imsg->Class)
{
case IDCMP_GADGETUP: /* Buttons only report GADGETUP */
gad = (struct Gadget *)imsg->IAddress;
if (gad->GadgetID == MYGAD_BUTTON)
IDOS->Printf("Button was pressed.\n");
break;
case IDCMP_CLOSEWINDOW:
terminated = TRUE;
break;
case IDCMP_REFRESHWINDOW:
/* This handling is REQUIRED with GadTools. */
IGadTools->GT_BeginRefresh(mywin);
IGadTools->GT_EndRefresh(mywin, TRUE);
break;
}
/* Use the toolkit message-replying function here... */
IGadTools->GT_ReplyIMsg(imsg);
}
}
}
</syntaxhighlight>

=== Modifying Gadgets ===

The attributes of a gadget are set up when the gadget is created. Some of these attributes can be changed later by using the GT_SetGadgetAttrs() function:

<syntaxhighlight lang="C" line>
VOID GT_SetGadgetAttrs (struct Gadget *gad, struct Window *win, struct Requester *req, Tag tag1, ... );
VOID GT_SetGadgetAttrsA(struct Gadget *gad, struct Window *win, struct Requester *req, struct TagItem *taglist);
</syntaxhighlight>

The gad argument specifies the gadget to be changed while the win argument specifies the window the gadget is in. Currently, the req argument is unused and must be set to NULL.

The gadget attributes are changed by passing tag arguments to these functions. The tag arguments can be either a set of TagItems on the stack for GT_SetGadgetAttrs(), or a pointer to an array of TagItems for GT_SetGadgetAttrsA(). The tag items specify the attributes that are to be changed for the gadget. Keep in mind though that not every gadget attribute can be modified this way.

For example, in the slider gadget presented earlier, the level-formatting string may not be changed after the gadget is created. However, the slider's level may be changed to 5 as follows:

<syntaxhighlight lang="C" line>
IGadTools->GT_SetGadgetAttrs(slidergad, win, req,
GTSL_Level, 5,
TAG_END);
<syntaxhighlight lang="C" line>

Here are some other example uses of GT_SetGadgetAttrs() to change gadget attributes after it is created.

<syntaxhighlight lang="C" line>
/* Disable a button gadget */
IGadTools->GT_SetGadgetAttrs(buttongad, win, NULL,
GA_Disabled, TRUE,
TAG_END);

/* Change a slider's range to be 1 to 100, currently at 50 */
IGadTools->GT_SetGadgetAttrs(slidergad, win, NULL,
GTSL_Min, 1,
GTSL_Max, 100,
GTSL_Level, 50,
TAG_END);

/* Add a node to the head of listview's list, and
make it the selected one */
IGadTools->GT_SetGadgetAttrs(listviewgad, win, NULL,
/* detach list before modifying */
GTLV_Labels, ~0,
TAG_END);
IExec->AddHead(&lvlabels, &newnode);
IGadTools->GT_SetGadgetAttrs(listviewgad, win, NULL,
/* re-attach list */
GTLV_Labels, &lvlabels,
GTLV_Selected, 0,
TAG_END);
</syntaxhighlight>

When changing a gadget using these functions, the gadget will automatically update its visuals. No refresh is required, nor should any refresh call be performed.

{{Note|title=Warning|text=The GT_SetGadgetAttrs() functions may not be called inside of a GT_BeginRefresh()/GT_EndRefresh() pair. This is true of Intuition gadget functions generally, including those discussed in [[Intuition_Gadgets|Intuition Gadgets]].}}

In the sections that follow all the possible attributes for each kind of gadget are discussed. The tags are also described in the Autodocs for GT_SetGadgetAttrs() in the SDK.

{{Note|title=Important|text=Tags that can only be sent to CreateGadget() and not to GT_SetGadgetAttrs() will be marked as ''create only'' in the discussion that follows. Those that are valid parameters to both functions will be marked as ''create and set''.}}

=== The Kinds of GadTools Gadgets ===

This section discusses the unique features of each kind of gadget supported by the GadTools library.

==== Button Gadgets ====

Button gadgets (BUTTON_KIND) are perhaps the simplest kind of GadTools gadget. Button gadgets may be used for objects like the "OK" and "Cancel" buttons in requesters. GadTools will create a hit-select button with a raised bevelled border. The label supplied will be centered on the button's face. Since the label is not clipped, be sure that the gadget is large enough to contain the text supplied.

Button gadgets recognize only one tag:

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable or ghost the button gadget, to FALSE otherwise. The default is FALSE. (Create and set.)

When the user selects a button gadget, the program will receive an IDCMP_GADGETUP event.

If clicking on a button causes a requester to appear, for example a button that brings up a color requester, then the button text should end in ellipsis (...), as in "Quit..."

==== Text-Entry and Number-Entry Gadgets ====

Text-entry (STRING_KIND) and number-entry (INTEGER_KIND) gadgets are fairly typical Intuition string gadgets. The typing area is contained by a border which is a raised ridge.

Text-entry gadgets accept the following tags:

; GTST_String (STRPTR)
: A pointer to the string to be placed into the text-entry gadget buffer or NULL to get an empty text-entry gadget. The string itself is actually copied into the gadget's buffer. The default is NULL. (Create and set.)

; GTST_MaxChars (UWORD)
: The maximum number of characters that the text-entry gadget should hold. The string buffer that gets created for the gadget will actually be one bigger than this number, in order to hold the trailing NULL. The default is 64. (Create only.)

Number-entry gadgets accept the following tags:

; GTIN_Number (ULONG)
: The number to be placed into the number-entry gadget. The default is zero. (Create and set.)

; GTIN_MaxChars (UWORD)
: The maximum number of digits that the number-entry gadget should hold. The string buffer that gets created for the gadget will actually be one bigger than this, in order to hold the trailing NULL. The default is 10. (Create only.)

Both text-entry and number-entry gadgets, which are collectively called string gadgets, accept these common tags:

; STRINGA_Justification
: This attribute controls the placement of the string or number within its box and can be one of GACT_STRINGLEFT, GACT_STRINGRIGHT or GACT_STRINGCENTER. The default is GACT_STRINGLEFT. (Create only.)

; STRINGA_ReplaceMode (BOOL)
: Set STRINGA_ReplaceMode to TRUE to get a string gadget which is in replace-mode, as opposed to auto-insert mode. (Create only.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the string gadget, otherwise to FALSE. The default is FALSE. (Create and set.)

; STRINGA_ExitHelp (BOOL)
: Set this attribute to TRUE if the application wants to hear the Help key from within this string gadget. This feature allows the program to hear the press of the Help key in all cases. If TRUE, pressing the help key while this gadget is active will terminate the gadget and send a message. The program will receive an IDCMP_GADGETUP message having a Code value of 0x5F, the rawkey code for Help. Typically, the program will want to reactivate the gadget after performing the help-display. The default is FALSE. (Create only.)

; GA_TabCycle (BOOL)
: If the user types Tab or Shift Tab into a GA_TabCycle gadget, Intuition will activate the next or previous such gadget in sequence. This gives the user easy keyboard control over which text-entry or number-entry gadget is active. Tab moves to the next GA_TabCycle gadget in the gadget list and Shift Tab moves to the previous one. When the user presses Tab or Shift Tab, Intuition will deactivate the gadget and send this program an IDCMP_GADGETUP message with the code field set to 0x09, the ASCII value for a tab. Intuition will then activate the next indicated gadget. Check the shift bits of the qualifier field to learn if Shift Tab was typed. The ordering of the gadgets may only be controlled by the order in which they were added to the window. For special cases, for example, if there is only one string gadget in the window, this feature can be suppressed by specifying the tagitem pair {GA_TabCycle, FALSE}. The default is TRUE. (Create only.)

; GTST_EditHook (struct Hook *)
: Pointer to a custom editing hook for this string or integer gadget. See [[Intuition_Gadgets|Intuition Gadgets]] for more information on string gadget edit-hooks.

As with all Intuition string gadgets, the program will receive an IDCMP_GADGETUP message only when the user presses Enter, Return, Help, Tab or Shift Tab while typing in the gadget. Note that, like Intuition string gadgets, the program will not hear anything if the user deactivates the string gadget by clicking elsewhere. Therefore, it is a good idea to always check the string gadget's buffer before using its contents, instead of just tracking its value as IDCMP_GADGETUP messages are received for this gadget.

Be sure the code is designed so that nothing drastic happens, like closing a requester or opening a file, if the IDCMP_GADGETUP message has a non-zero Code field; the program will want to handle the Tab and Help cases intelligently.

To read the string gadget's buffer, look at the Gadget's StringInfo Buffer:

<syntaxhighlight lang="C" line>
((struct StringInfo *)gad->SpecialInfo)->Buffer
</syntaxhighlight>

To determine the value of an integer gadget, look at the Gadget's StringInfo LongInt in the same way.

Always use the GTST_String or GTIN_Number tags to set these values. Never write to the StringInfo->Buffer or StringInfo->LongInt fields directly.

GadTools string and integer gadgets do not directly support the GA_Immediate property (which would cause Intuition to send an IDCMP_GADGETDOWN event when such a gadget is first selected). However, this property can be very important. Therefore, the following technique can be used to enable this property.

{{Note|title=Warning|text=Note that the technique shown here relies on directly setting flags in a GadTools gadget; this is not normally allowed since it hinders future compatibility. Do not attempt to change other flags or properties of GadTools gadgets except through the defined interfaces of CreateGadgetA() and GT_SetGadgetAttrsA(). Directly modifying flags or properties is legal only when officially sanctioned by the AmigaOS development team.}}

To get the GA_Immediate property, pass the {GA_Immediate, TRUE} tag to CreateGadgetA().

==== Checkbox Gadgets ====

Checkboxes (CHECKBOX_KIND) are appropriate for presenting options which may be turned on or off. This kind of gadget consists of a raised box which contains a checkmark if the option is selected or is blank if the option is not selected. Clicking on the box toggles the state of the checkbox.

The width and height of a checkbox are by default not scaled and fixed (CHECKBOXWIDTH by CHECKBOXHEIGHT). To scale a checkbox gadget, set the GTCB_Scaled tag to TRUE, and set the desired width and height in the ng_Width and ng_Height fields of the NewGadget structure.

The checkbox may be controlled with the following tags:

; GTCB_Checked (BOOL)
: Set this attribute to TRUE to set the gadget's state to ''checked''. Set it to FALSE to mark the gadget as ''unchecked''. The default is FALSE. (Create and set.)

; GTCB_Scaled (BOOL)
: Scales the checkbox gadget if set to TRUE. The default is FALSE. (Create and set.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the checkbox, to FALSE otherwise. The default is FALSE. (Create and set.)

When the user selects a checkbox, the program will receive an IntuiMessage with a class of IDCMP_GADGETUP. As this gadget always toggles, the program can easily track the state of the gadget. Feel free to read the gadget->Flags GFLG_SELECTED bit. Note, however, that the Gadget structure itself is not synchronized to the IntuiMessages received. If the user clicks a second time, the GFLG_SELECTED bit can toggle again before the program gets a chance to read it. This is true of any of the dynamic fields of the Gadget structure, and is worth being aware of, although only rarely will an application have to account for it.

==== Mutually-Exclusive Gadgets ====

Use mutually exclusive gadgets (MX_KIND), or ''radio buttons'', when the user must choose only one option from a short list of possibilities. Mutually exclusive gadgets are appropriate when there are a small number of choices, perhaps eight or less.

A set of mutually exclusive gadgets consists of a list of labels and beside each label, a small raised oval that looks like a button. Exactly one of the ovals is recessed and highlighted, to indicate the selected choice. The user can pick another choice by clicking on any of the raised ovals. This choice will become active and the previously selected choice will become inactive. That is, the selected oval will become recessed while the previous one will pop out, like the buttons on a car radio.

Mutually exclusive gadgets recognize these tags:

; GTMX_Labels (STRPTR *)
: A NULL-pointer-terminated array of strings which are to be the labels beside each choice in the set of mutually exclusive gadgets. This array determines how many buttons are created. This array must be supplied to CreateGadget() and may not be changed. The strings themselves must remain valid for the lifetime of the gadget. (Create only.)

; GTMX_Active (UWORD)
: The ordinal number, counting from zero, of the active choice of the set of mutually exclusive gadgets. The default is zero. (Create and set.)

; GTMX_Spacing (UWORD)
: The amount of space, in pixels, that will be placed between successive choices in a set of mutually exclusive gadgets. The default is one. (Create only.)

; GTMX_Scaled (BOOL)
: Indicates whether the mutually exclusive gadget should be scaled or not. The default is FALSE. (Create only.)

; GTMX_TitlePlace (UWORD)
: Where to place the title of the mutually exclusive gadget. The gadget obtains its title from the ng_GadgetText field of the NewGadget structure. The default is no title. (Create only.)
:{| class="wikitable"
| PLACETEXT_LEFT || Right-align text on left side
|-
| PLACETEXT_RIGHT || Left-align text on right side
|-
| PLACETEXT_ABOVE || Center text above
|-
| PLACETEXT_BELOW || Center text below
|}

When the user selects a new choice from a set of mutually exclusive gadgets, the program will receive an IDCMP_GADGETDOWN IntuiMessage. Look in the IntuiMessage's Code field for the ordinal number of the new active selection.

The ng_GadgetText field of the NewGadget structure is used to display the title for mutually exclusive gadgets. The text position specified in ng_Flags determines whether the item labels are placed to the left or the right of the radio buttons themselves. By default, the labels appear on the left. Do not specify PLACETEXT_ABOVE, PLACETEXT_BELOW or PLACETEXT_IN for this kind of gadget.

To scale a mutually exclusive gadget, set the GTMX_Scaled tag to TRUE, and set the desired width and height in the ng_Width and ng_Height fields of the NewGadget structure. The default value of GTMX_Scaled is FALSE, meaning use the default size of MXWIDTH by MXHEIGHT respectively. If you scale mutually exclusive gadgets, you must also set the
GTMX_Spacing tag to NewGadget.ng_TextAttr->ta_YSize + 1 to properly space the buttons with respect to the font.

==== Cycle Gadgets ====

Like mutually exclusive gadgets, cycle gadgets (CYCLE_KIND) allow the user to choose exactly one option from among several.

The cycle gadget appears as a raised rectangular button with a vertical divider near the left side. A circular arrow glyph appears to the left of the divider, while the current choice appears to the right. Clicking on the cycle gadget advances to the next choice, while shift-clicking on it changes it to the previous choice.

Cycle gadgets are more compact than mutually exclusive gadgets, since only the current choice is displayed. They are preferable to mutually exclusive gadgets when a window needs to have several such gadgets as in the PrinterGfx Preferences editor, or when there is a medium number of choices. If the number of choices is much more than about a dozen, it may become too frustrating and inefficient for the user to find the desired choice. In that case, use a listview (scrolling list) instead.

The tags recognized by cycle gadgets are:

; GTCY_Labels (STRPTR *)
: Like GTMX_Labels, this tag is associated with a NULL-pointer-terminated array of strings which are the choices that this gadget allows. This array must be supplied to CreateGadget() and can be changed. The strings themselves must remain valid for the lifetime of the gadget. (Create and set.)

; GTCY_Active (UWORD)
: The ordinal number, counting from zero, of the active choice of the cycle gadget. The default is zero. (Create and set.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the cycle gadget, to FALSE otherwise. The default is FALSE. (Create and set.)

When the user clicks or shift-clicks on a cycle gadget, the program will receive an IDCMP_GADGETUP IntuiMessage. Look in the Code field of the IntuiMessage for the ordinal number of the new active selection.

==== Slider Gadgets ====

Sliders are one of the two kinds of proportional gadgets offered by GadTools. Slider gadgets (SLIDER_KIND) are used to control an amount, a level or an intensity, such as volume or color. Scroller gadgets (SCROLLER_KIND) are discussed below.

Slider gadgets accept the following tags:

; GTSL_Min (WORD)
: The minimum level of a slider. The default is zero. (Create and set.)

; GTSL_Max (WORD)
: The maximum level of a slider. The default is 15. (Create and set.)

; GTSL_Level (WORD)
: The current level of a slider. The default is zero. When the level is at its minimum, the knob will be all the way to the left for a horizontal slider or all the way at the bottom for a vertical slider. Conversely, the maximum level corresponds to the knob being to the extreme right or top. (Create and set.)

; GTSL_LevelFormat (STRPTR)
: The current level of the slider may be displayed in real-time alongside the gadget. To use the level-display feature, the program must be using a monospace font for this gadget.

: GTSL_LevelFormat specifies a printf()-style formatting string used to render the slider level beside the slider (the complete set of formatting options is described in the Exec library function RawDoFmt()). Be sure to use the "l" (long word) modifier for the number. Field-width specifiers may be used to ensure that the resulting string is always of constant width. The simplest would be "%2ld". A 2-digit hexadecimal slider might use "%02lx", which adds leading zeros to the number. Strings with extra text, such as "%3ld hours", are permissible. If this tag is specified, the program must also provide GTSL_MaxLevelLen. By default, the level is not displayed. (Create only.)

; GTSL_MaxLevelLen (UWORD)
: The maximum length of the string that will result from the given level-formatting string. If this tag is specified, the program must also provide GTSL_LevelFormat. By default, the level is not displayed. (Create only.)

; GTSL_LevelPlace
: To choose where the optional display of the level is positioned. It must be one of PLACETEXT_LEFT, PLACETEXT_RIGHT, PLACETEXT_ABOVE or PLACETEXT_BELOW. The level may be placed anywhere with the following exception: the level and the label may not be both above or both below the gadget. To place them both on the same side, allow space in the gadget's label (see the example). The default is PLACETEXT_LEFT. (Create only.)

; GTSL_DispFunc (LONG (*function)(struct Gadget *, WORD))
: Optional function to convert the level for display. A slider to select the number of colors for a screen may operate in screen depth (1 to 5, for instance), but actually display the number of colors (2, 4, 8, 16 or 32). This may be done by providing a GTSL_DispFunc function which returns 1 << level. The function must take a pointer to the Gadget as the first parameter and the level, a WORD, as the second and return the result as a LONG. The default behavior for displaying a level is to do so without any conversion. (Create only.)

; GA_Immediate (BOOL)
: Set this to TRUE to receive an IDCMP_GADGETDOWN IntuiMessage when the user presses the mouse button over the slider. The default is FALSE. (Create only.)

; GA_RelVerify (BOOL)
: Set this to TRUE to receive an IDCMP_GADGETUP IntuiMessage when the user releases the mouse button after using the slider. The default is FALSE. (Create only.)

; PGA_Freedom
: Specifies which direction the knob may move. Set to LORIENT_VERT for a vertical slider or LORIENT_HORIZ for a horizontal slider. The default is LORIENT_HORIZ. (Create only.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the slider, to FALSE otherwise. The default is FALSE. (Create and set.)

Up to three different classes of IntuiMessage may be received at the port when the user plays with a slider, these are IDCMP_MOUSEMOVE, IDCMP_GADGETUP and IDCMP_GADGETDOWN. The program may examine the IntuiMessage Code field to discover the slider's level.

IDCMP_MOUSEMOVE IntuiMessages will be heard whenever the slider's level changes. IDCMP_MOUSEMOVE IntuiMessages will not be heard if the knob has not moved far enough for the level to actually change. For example if the slider runs from 0 to 15 and is currently set to 12, if the user drags the slider all the way up the program will hear no more than three IDCMP_MOUSEMOVEs, one each for 13, 14 and 15.

If {GA_Immediate, TRUE} is specified, then the program will always hear an IDCMP_GADGETDOWN IntuiMessage when the user begins to adjust a slider. If {GA_RelVerify, TRUE} is specified, then the program will always hear an IDCMP_GADGETUP IntuiMessage when the user finishes adjusting the slider. If IDCMP_GADGETUP or IDCMP_GADGETDOWN IntuiMessages are requested, the program will always hear them, even if the level has not changed since the previous IntuiMessage.

Note that the Code field of the IntuiMessage structure is a UWORD, while the slider's level may be negative, since it is a WORD. Be sure to copy or cast the IntuiMessage->Code into a WORD if the slider has negative levels.

If the user clicks in the container next to the knob, the slider level will increase or decrease by one. If the user drags the knob itself, then the knob will snap to the nearest integral position when it is released.

Here is an example of the screen-depth slider discussed earlier:

<syntaxhighlight lang="C" line>
/* NewGadget initialized here. Note the three spaces
* after "Slider:", to allow a blank plus the two digits
* of the level display
*/
ng.ng_Flags = PLACETEXT_LEFT;
ng.ng_GadgetText = "Slider: ";

LONG DepthToColors(struct Gadget *gad, WORD level)
{
return ((WORD)(1 << level));
}

...

gad = IGadTools->CreateGadget(SLIDER_KIND, gad, &ng,
GTSL_Min, 1,
GTSL_Max, 5,
GTSL_Level, current_depth,
GTSL_MaxLevelLen, 2,
GTSL_LevelFormat, "%2ld",
GTSL_DispFunc, DepthToColors,
TAG_END);
</syntaxhighlight>

==== Scroller Gadgets ====

Scrollers (SCROLLER_KIND) bear some similarity to sliders, but are used for a quite different job: they allow the user to adjust the position of a limited view into a larger area. For example, Workbench's windows have scrollers that allow the user to see icons that are outside the visible portion of a window. Another example is a scrolling list in a file requester which has a scroller that allows the user to see different parts of the whole list.

A scroller consists of a proportional gadget and usually also has a pair of arrow buttons.

While the slider deals in minimum, maximum and current level, the scroller understands Total, Visible and Top. For a scrolling list, Total would be the number of items in the entire list, Visible would be the number of lines visible in the display area and Top would be the number of the first line displayed in the visible part of the list. Top would run from zero to Total - Visible. For an area-scroller such as those in Workbench's windows, Total would be the height (or width) of the whole area, Visible would be the visible height (or width) and Top would be the top (or left) edge of the visible part.

Note that the position of a scroller should always represent the position of the visible part of the project and never the position of a cursor or insertion point.

Scrollers respect the following tags:

; GTSC_Top (WORD)
: The top line or position visible in the area that the scroller represents. The default is zero. (Create and set.)

; GTSC_Total (WORD)
: The total number of lines or positions that the scroller represents. The default is zero. (Create and set.)

; GTSC_Visible (WORD)
: The visible number of lines or positions that the scroller represents. The default is two. (Create and set.)

; GTSC_Arrows (UWORD)
: Asks for arrow gadgets to be attached to the scroller. The value supplied will be used as the width of each arrow button for a horizontal scroller or the height of each arrow button for a vertical scroller, the other dimension will be set by GadTools to match the scroller size. It is generally recommend that arrows be provided. The default is no arrows. (Create only.)

; GA_Immediate (BOOL)
: Set this to TRUE to receive an IDCMP_GADGETDOWN IntuiMessage when the user presses the mouse button over the scroller. The default is FALSE. (Create only.)

; GA_RelVerify (BOOL)
: Set this to TRUE to receive an IDCMP_GADGETUP IntuiMessage when the user releases the mouse button after using the scroller. The default is FALSE. (Create only.)

; PGA_Freedom
: Specifies which direction the knob may move. Set to LORIENT_VERT for a vertical scroller or LORIENT_HORIZ for a horizontal scroller. The default is LORIENT_HORIZ. (Create only.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the scroller, to FALSE otherwise. The default is FALSE. (Create and set.)

The IntuiMessages received for a scroller gadget are the same in nature as those for a slider defined above, including the fact that messages are only heard by the program when the knob moves far enough for the Top value to actually change. The Code field of the IntuiMessage will contain the new Top value of the scroller.

If the user clicks on an arrow gadget, the scroller moves by one unit. If the user holds the button down over an arrow gadget, it repeats.

If the user clicks in the container next to the knob, the scroller will move by one page, which is the visible amount less one. This means that when the user pages through a scrolling list, any pair of successive views will overlap by one line. This helps the user understand the continuity of the list. If the program is using a scroller to pan through an area then there will be an overlap of one unit between successive views. It is recommended that Top, Visible and Total be scaled so that one unit represents about five to ten percent of the visible amount.

==== Listview Gadgets ====

Listview gadgets (LISTVIEW_KIND) are scrolling lists. They consist of a scroller with arrows, an area where the list itself is visible and optionally a place where the current selection is displayed, which may be editable. The user can browse through the list using the scroller or its arrows and may select an entry by clicking on that item.

There are a number of tags that are used with listviews:

; GTLV_Labels (struct List *)
: An Exec list whose nodes' ln_Name fields are to be displayed as items in the scrolling list. If the list is empty, an empty List structure or a NULL value may be used for GTLV_Labels. This tag accepts a value of "~0" to detach the list from the listview, defined below. The default is NULL. (Create and set.)

; GTLV_Top (UWORD)
: The ordinal number of the top item visible in the listview. The default is zero. (Create and set.)

; GTLV_ReadOnly (BOOL)
: Set this to TRUE for a read-only listview, which the user can browse, but not select items from. A read-only listview can be recognized because the list area is recessed, not raised. The default is FALSE. (Create only.)

; GTLV_ScrollWidth (UWORD)
: The width of the scroller to be used in the listview. Any value specified must be reasonably bigger than zero. The default is 16. (Create only.)

; GTLV_ShowSelected (struct Gadget *)
: Use this tag to show the currently selected entry displayed underneath the listview. Set its value to NULL to get a read-only (TEXT_KIND) display of the currently selected entry or set it to a pointer to an already-created GadTools STRING_KIND gadget to allow the user to directly edit the current entry. By default, there is no display of the currently selected entry. (Create only.)

; GTLV_Selected (UWORD)
: Ordinal number of the item to be placed into the display of the current selection under the listview. This tag is ignored if GTLV_ShowSelected is not used. Set it to "~0" to have no current selection. The default is "~0". (Create and set.)

; LAYOUTA_Spacing (UWORD)
: Extra space, in pixels, to be placed between the entries in the listview. The default is zero. (Create only.)

The program will only hear from a listview when the user selects an item from the list. The program will then receive an IDCMP_GADGETUP IntuiMessage. This message will contain the ordinal number of the item within the list that was selected in the Code field of the message. This number is independent of the displayed listview, it is the offset from the start of the list of items.

If the program attaches a display gadget by using the TagItem {GTLV_ShowSelected, NULL}, then whenever the user clicks on an entry in the listview it will be copied into the display gadget.

If the display gadget is to be editable, then the program must first create a GadTools STRING_KIND gadget whose width matches the width of the listview. The TagItem {GTLV_ShowSelected, stringgad} is used to install the editable gadget, where stringgad is the pointer returned by CreateGadget(). When the user selects any entry from the listview, it gets copied into the string gadget. The user can edit the string and the program will hear normal string gadget IDCMP_GADGETUP messages from the STRING_KIND gadget.

The Exec List and its Node structures may not be modified while they are attached to the listview, since the list might be needed at any time. If the program has prepared an entire new list, including a new List structure and all new nodes, it may replace the currently displayed list in a single step by calling GT_SetGadgetAttrs() with the TagItem {GTLV_Labels, newlist}. If the program needs to operate on the list that has already been passed to the listview, it should detach the list by setting the GTLV_Labels attribute to "~0". When done modifying the list, resubmit it by setting GTLV_Labels to once again point to it. This is better than first setting the labels to NULL and later back to the list, since setting GTLV_Labels to NULL will visually clear the listview. If the GTLV_Labels attribute is set to "~0", the program is expected to set it back to something determinate, either a list or NULL, soon after.

The height specified for the listview will determine the number of lines in the list area. When creating a listview, it will be no bigger than the size specified in the NewGadget structure. The size will include the current-display gadget, if any, that has been requested via the GTLV_ShowSelected tag. The listview may end up being less tall than the application asked for, since the calculated height assumes an integral number of lines in the list area.

By default, the gadget label will be placed above the listview. This may be overridden using ng_Flags.

==== Palette Gadgets ====

Palette gadgets (PALETTE_KIND) let the user pick a color from a set of several. A palette gadget consists of a number of colored squares, one for each color available. There may also be an optional indicator square which is filled with the currently selected color. To create a color editor, a palette gadget would be combined with some sliders to control red, green and blue components, for example.

Palette gadgets use the following tags:

; GTPA_Depth (UWORD)
: The number of bitplanes that the palette represents. There will be 1 << depth (2^depth) squares in the palette gadget. The default is one. (Create only.)

; GTPA_Color (UBYTE)
: The selected color of the palette. The default is one. (Create and set.)

; GTPA_ColorOffset (UBYTE)
: The first color to use in the palette. For example, if GTPA_Depth is two and GTPA_ColorOffset is four, then the palette will have squares for colors four, five, six and seven. The default is zero. (Create only.)

; GTPA_IndicatorWidth (UWORD)
: The desired width of the current-color indicator. By specifying this tag, the application is asking for an indicator to be placed to the left of the color selection squares. The indicator will be as tall as the gadget itself. By default there is no indicator. (Create only.)

; GTPA_IndicatorHeight (UWORD)
: The desired height of the current-color indicator. By specifying this tag, the application is asking for an indicator to be placed above the color selection squares. The indicator will be as wide as the gadget itself. By default there is no indicator. (Create only.)

; GA_Disabled (BOOL)
: Set this attribute to TRUE to disable the palette gadget, to FALSE otherwise. The default is FALSE. (Create and set.)

An IDCMP_GADGETUP IntuiMessage will be received when the user selects a color from the palette. The current-color indicator is recessed, indicating that clicking on it has no effect.

If the palette is wide and not tall, use the GTPA_IndicatorWidth tag to put the indicator on the left. If the palette is tall and narrow, put the indicator on top using GTPA_IndicatorHeight.

By default, the gadget's label will go above the palette gadget, unless GTPA_IndicatorWidth is specified, in which case the label will go on the left. In either case, the default may be overridden by setting the appropriate flag in the NewGadget's ng_Flags field.

The size specified for the palette gadget will determine how the area is subdivided to make the individual color squares. The actual size of the palette gadget will be no bigger than the size given, but it can be smaller in order to make the color squares all exactly the same size.

==== Text-Display and Numeric-Display Gadgets ====

Text-display (TEXT_KIND) and numeric-display (NUMBER_KIND) gadgets are read-only displays of information. They are useful for displaying information that is not editable or selectable, while allowing the application to use the GadTools formatting and visuals. Conveniently, the visuals are automatically refreshed through normal GadTools gadget processing. The values displayed may be modified by the program in the same way other GadTools gadgets may be updated.

Text-display and number-display gadgets consist of a fixed label (the one supplied as the NewGadget's ng_GadgetText), as well as a changeable string or number (GTTX_Text or GTNM_Number respectively). The fixed label is placed according to the PLACETEXT_ flag chosen in the NewGadget ng_Flags field. The variable part is aligned to the left-edge of the gadget.

Text-display gadgets recognize the following tags:

; GTTX_Text (STRPTR)
: Pointer to the string to be displayed or NULL for no string. The default is NULL. (Create and set.)

; GTTX_Border (BOOL)
: Set to TRUE to place a recessed border around the displayed string. The default is FALSE. (Create only.)

; GTTX_CopyText (BOOL)
: This flag instructs the text-display gadget to copy the supplied GTTX_Text string instead of using only a pointer to the string. This only works for the value of GTTX_Text set at CreateGadget() time. If GTTX_Text is changed, the new text will be referenced by pointer, not copied. Do not use this tag without a non-NULL GTTX_Text. (Create only.)

Number-display gadgets have the following tags:

; GTNM_Number (LONG)
: The number to be displayed. The default is zero. (Create or set.)

; GTNM_Border (BOOL)
: Set to TRUE to place a recessed border around the displayed number. The default is FALSE. (Create only.)

Since they are not selectable, text-display and numeric-display gadgets never cause IntuiMessages to be sent to the application.

==== Generic Gadgets ====

If the application requires a specialized gadget which does not fit into any of the defined GadTools kinds but would still like to use the GadTools gadget creation and deletion functions, it may create a GadTools generic gadget and use it any way it sees fit. In fact, all of the kinds of GadTools gadgets are created out of GadTools GENERIC_KIND gadgets.

The gadget that gets created will heed almost all the information contained in the NewGadget structure supplied.

If ng_GadgetText is supplied, the gadget's GadgetText will point to an IntuiText structure with the provided string and font. However, do not specify any of the PLACETEXT ng_Flags, as they are currently ignored by GENERIC_KIND gadgets. PLACETEXT flags may be supported by generic GadTools gadgets in the future.

It is up to the program to set the Flags, Activation, GadgetRender, SelectRender, MutualExclude and SpecialInfo fields of the Gadget structure.

The application must also set the GadgetType field, but be certain to preserve the bits set by CreateGadget().

For instance, to make a gadget boolean, use:

<syntaxhighlight lang="C" line>
gad->GadgetType |= GTYP_BOOLGADGET;
</syntaxhighlight>

and not

<syntaxhighlight lang="C" line>
gad->GadgetType = GTYP_BOOLGADGET;
</syntaxhighlight>

Using direct assignment, (the = operator), clears all other flags in the GadgetType field and the gadget may not be properly freed by FreeGadgets().

=== Functions for Setting up GadTools Menus and Gadgets ===

This section gives all the details on the functions used to set up GadTools menus and gadgets that were mentioned briefly earlier in this article.

==== GetVisualInfo() and FreeVisualInfo() ====

In order to ensure their best appearance, GadTools gadgets and menus need information about the screen on which they will appear. Before creating any GadTools gadgets or menus, the program must get this information using the GetVisualInfo() call.

<syntaxhighlight lang="C" line>
APTR GetVisualInfoA( struct Screen *screen, struct TagItem *taglist );
APTR GetVisualInfo( struct Screen *screen, Tag tag1, ... );
</syntaxhighlight>

Set the screen argument to a pointer to the screen you are using. The tag arguments, tag1 or taglist, are reserved for future extensions. Currently none are recognized, so only TAG_END should be used.

The function returns an abstract handle called the VisualInfo. For GadTools gadgets, the ng_VisualInfo field of the NewGadget structure must be set to this handle before the gadget can be added to the window. GadTools menu layout and creation functions also require the VisualInfo handle as an argument.

There are several ways to get the pointer to the screen on which the window will be opened. If the application has its own custom screen, this pointer is known from the call to OpenScreen() or OpenScreenTags(). If the application already has its window opened on the Workbench or some other public screen, the screen pointer can be found in Window.WScreen. Often the program will create its gadgets and menus before opening the window. In this case, use LockPubScreen() to get a pointer to the desired public screen, which also provides a lock on the screen to prevent it from closing. See [[Intuition_Screens|Intuition Screens]] and [[Intuition_Windows|Intuition Windows]] for more about public screens.

The VisualInfo data must be freed after all the gadgets and menus have been freed but before releasing the screen. Custom screens are released by calling CloseScreen(), public screens are released by calling CloseWindow() or UnlockPubScreen(), depending on the technique used. Use FreeVisualInfo() to free the visual info data.

<syntaxhighlight lang="C" line>
VOID FreeVisualInfo( APTR vi );
</syntaxhighlight>

This function takes just one argument, the VisualInfo handle as returned by GetVisualInfo(). The sequence of events for using the VisualInfo handle could look like this:

<syntaxhighlight lang="C" line>
void init()
{
myscreen = IIntuition->LockPubScreen(NULL);
if (!myscreen)
{
cleanup("Failed to lock default public screen");
}
vi = IGadTools->GetVisualInfo(myscreen);
if (!vi)
{
cleanup("Failed to GetVisualInfo");
}
/* Create gadgets here */
ng.ng_VisualInfo = vi;
...
}

void cleanup(STRPTR errorstr)
{
/* These functions may be safely called with a NULL parameter: */
IGadTools->FreeGadgets(glist);
IGadTools->FreeVisualInfo(vi);

if (myscreen)
IIntuition->UnlockPubScreen(NULL, myscreen);

IDOS->Printf(errorstr);
}
</syntaxhighlight>

==== CreateContext() ====

Use of GadTools gadgets requires some per-window context information. CreateContext() establishes a place for that information to go. This function must be called before any GadTools gadgets are created.

<syntaxhighlight lang="C" line>
struct Gadget *CreateContext( struct Gadget **glistptr );
</syntaxhighlight>

The glistptr argument is a double-pointer to a Gadget structure. More specifically, this is a pointer to a NULL-initialized pointer to a Gadget structure.

The return value of CreateContext() is a pointer to this gadget, which should be fed to the program's first call to CreateGadget(). This pointer to the Gadget structure returned by CreateContext(), may then serve as a handle to the list of gadgets as they are created. The code fragment listed in the next section shows how to use CreateContext() together with CreateGadget() to make a linked list of GadTools gadgets.

=== Creating Gadget Lists ===

In the discussion of CreateGadget() presented earlier, the examples showed only how to make a single gadget. For most applications that use GadTools, however, a whole list of gadgets will be needed. To do this, the application could use code such as this:

<syntaxhighlight lang="C" line>
struct NewGadget *newgad1, *newgad2, *newgad3;
struct Gadget *glist = NULL;
struct Gadget *pgad;

...
/* Initialize NewGadget structures */
...

/* Note that CreateContext() requires a POINTER to a NULL-initialized
* pointer to struct Gadget:
*/
pgad = IGadTools->CreateContext(&glist);

pgad = IGadTools->CreateGadget(BUTTON_KIND, pgad, newgad1, TAG_END);
pgad = IGadTools->CreateGadget(STRING_KIND, pgad, newgad2, TAG_END);
pgad = IGadTools->CreateGadget(MX_KIND, pgad, newgad3, TAG_END);

if (!pgad)
{
IGadTools->FreeGadgets(glist);
exit_error();
}
else
{
if ( mywin = IIntuition->OpenWindowTags(NULL,
WA_Gadgets, glist,
...
/* Other tags... */
...
TAG_END) )
{
/* Complete the rendering of the gadgets */
IGadTools->GT_RefreshWindow(win, NULL);
...
/* and continue on... */
...
IIntuition->CloseWindow(mywin);
}

IGadTools->FreeGadgets(glist);
}
</syntaxhighlight>

The pointer to the previous gadget, pgad in the code fragment above, is used for three purposes. First, when CreateGadget() is called multiple times, each new gadget is automatically linked to the previous gadget's NextGadget field, thus creating a gadget list. Second, if one of the gadget creations fails (usually due to low memory, but other causes are possible), then for the next call to CreateGadget(), pgad will be NULL and CreateGadget() will fail immediately. This means that the program can perform several successive calls to CreateGadget() and only have to check for failure at the end.

Finally, although this information is hidden in the implementation and not important to the application, certain calls to CreateGadget() actually cause several Intuition gadgets to be allocated and these are automatically linked together without program interaction, but only if a previous gadget pointer is supplied. If several gadgets are created by a single CreateGadget() call, they work together to provide the functionality of a single GadTools gadget. The application should always act as though the gadget pointer returned by CreateGadget() points to a single gadget instance. See "Documented Side-Effects" for a warning.

There is one exception to the fact that a program only has to check for failure after the last CreateGadget() call and that is when the application depends on the successful creation of a gadget and caches or immediately uses the gadget pointer returned by CreateGadget().

For instance, if the program wants to create a string gadget and save a pointer to the string buffer, it might do so as follows:

<syntaxhighlight lang="C" line>
gad = IGadTools->CreateGadget(STRING_KIND, gad, &ng,
GTST_String, "Hello World",
TAG_END);
if (gad)
{
stringbuffer = ((struct StringInfo *)(gad->SpecialInfo))->Buffer;
}

/* Creation can continue here: */
gad = IGadTools->CreateGadget(..._KIND, gad, &ng2,
...
TAG_END);
</syntaxhighlight>

A major benefit of having a reusable NewGadget structure is that often many fields do not change and some fields change incrementally. For example, the application can set just the NewGadget's ng_VisualInfo and ng_TextAttr only once and never have to modify them again even if the structure is reused to create many gadgets. A set of similar gadgets may share size and some positional information so that code such as the following might be used:

<syntaxhighlight lang="C" line>
/* Assume that the NewGadget structure 'ng' is fully
* initialized here for a button labelled "OK"
*/
gad = IGadTools->CreateGadget(BUTTON_KIND, gad, &ng,
TAG_END);

/* Modify only those fields that need to change: */
ng.ng_GadgetID++;
ng.ng_LeftEdge += 80;
ng.ng_GadgetText = "Cancel";
gad = IGadTools->CreateGadget(BUTTON_KIND, gad, &ng,
TAG_END);
</syntaxhighlight>

{{Note|title=Warning|text=All gadgets created by GadTools currently have the GADTOOL_TYPE bit set in their GadgetType field. It is not correct to check for, set, clear or otherwise rely on this since it is subject to change.}}

=== Gadget Refresh Functions ===

Normally, GadTools gadgets are created and then attached to a window when the window is opened, either through the WA_FirstGadget tag or the NewWindow.FirstGadget field. Alternately, they may be added to a window after it is open by using the functions AddGList() and RefreshGList().

Regardless of which way gadgets are attached to a window, the program must then call the GT_RefreshWindow() function to complete the rendering of GadTools gadgets. This function takes two arguments.

<syntaxhighlight lang="C" line>
VOID GT_RefreshWindow( struct Window *win, struct Requester *req );
</syntaxhighlight>

This win argument is a pointer to the window that contains the GadTools gadgets. The req argument is currently unused and should be set to NULL. This function should only be called immediately after adding GadTools gadgets to a window. Subsequent changes to GadTools gadget imagery made through calls to GT_SetGadgetAttrs() will be automatically performed by GadTools when the changes are made. (There is no need to call GT_RefreshWindow() in that case.)

As mentioned earlier, applications must always ask for notification of window refresh events for any window that uses GadTools gadgets. When the application receives an IDCMP_REFRESHWINDOW message for a window, Intuition has already refreshed its gadgets. Normally, a program would then call Intuition's BeginRefresh(), perform its own custom rendering operations, and finally call EndRefresh(). But for a window that uses GadTools gadgets, the application must call GT_BeginRefresh() and GT_EndRefresh() in place of BeginRefresh() and EndRefresh(). This allows the the GadTools gadgets to be fully refreshed.

<syntaxhighlight lang="C" line>
VOID GT_BeginRefresh( struct Window *win );
VOID GT_EndRefresh ( struct Window *win, LONG complete );
</syntaxhighlight>

For both functions, the win argument is a pointer to the window to be refreshed. For GT_EndRefresh(), set the complete argument to TRUE if refreshing is complete, set it to FALSE otherwise. See the discussion of BeginRefresh() and EndRefresh() in [[Intuition_Windows|Intuition Windows]] for more about window refreshing.

When using GadTools gadgets, the program may not set the window's WFLG_NOCAREREFRESH flag. Even if there is no custom rendering to be performed, GadTools gadgets requires this minimum code to handle IDCMP_REFRESHWINDOW messages:

<syntaxhighlight lang="C" line>
case IDCMP_REFRESHWINDOW:
IGadTools->GT_BeginRefresh(win);
/* custom rendering, if any, goes here */
IGadTools->GT_EndRefresh(win, TRUE);
break;
</syntaxhighlight>

=== Other GadTools Functions ===

This section discusses some additional support functions in the GadTools library that serve special needs.

==== GT_FilterIMsg() and GT_PostFilterIMsg() ====

For most GadTools programs, GT_GetIMsg() and GT_ReplyIMsg() work perfectly well. In rare cases an application may find they pose a bit of a problem. A typical case is when all messages are supposed to go through a centralized ReplyMsg() that cannot be converted to a GT_ReplyIMsg(). Since calls to GT_GetIMsg() and GT_ReplyIMsg() must be paired, there would be a problem.

For such cases, the GT_FilterIMsg() and GT_PostFilterIMsg() functions are available. These functions allow GetMsg() and ReplyMsg() to be used in a way that is compatible with GadTools.

{{Note|title=Warning|text=These functions are for specialized use only and will not be used by the majority of applications. See GT_GetIMsg() and GT_ReplyIMsg() for standard message handling.}}

<syntaxhighlight lang="C" line>
struct IntuiMessage *GT_FilterIMsg( struct IntuiMessage *imsg );
struct IntuiMessage *GT_PostFilterIMsg( struct IntuiMessage *imsg );
</syntaxhighlight>

The GT_FilterIMsg() function should be called right after GetMsg(). It takes a pointer to the original IntuiMessage and, if the message applies to a GadTools gadget, returns either a modified IntuiMessage or a NULL. A NULL return signifies that the message was consumed by a GadTools gadget (and not needed by the application).

The GT_PostFilterIMsg() function should be called before replying to any message modified by GT_FilterIMsg(). It takes a pointer to the modified version of an IntuiMessage obtained with GT_FilterIMsg() and returns a pointer to the original IntuiMessage.

The typical calling sequence for a program that uses these functions, is to call GetMsg() to get the IntuiMessage. Then, if the message applies to a window which contains GadTools gadgets, call GT_FilterIMsg(). Any message returned by GT_FilterIMsg() should be used like a message returned from GT_GetIMsg().

When done with the message, the application must call GT_PostFilterIMsg() to perform any clean up necessitated by the previous call to GT_FilterIMsg(). In all cases, the application ''must'' then reply the original IntuiMessage using ReplyMsg(). This is true even for consumed messages as these are ''not'' replied by GadTools. For example, the application could use code such as this:

<syntaxhighlight lang="C" line>
/* port is a message port receiving different messages */
/* gtwindow is the window that contains GadTools gadgets */

imsg = IExec->GetMsg(port);

/* Is this the window with GadTools gadgets? */
if (imsg->IDCMPWindow == gtwindow)
{
/* Filter the message and see if action is needed */
if (gtimsg = IGadTools->GT_FilterIMsg(imsg))
{
switch (gtimsg->Class)
{
/* Act depending on the message */
...
}
/* Clean up the filtered message. The return value is not needed */
/* since we already have a pointer to the original message. */
IGadTools->GT_PostFilterIMsg(gtimsg);
}
}
/* other stuff can go here */
IExec->ReplyMsg(imsg);
</syntaxhighlight>

You should not make any assumptions about the contents of the unfiltered IntuiMessage (imsg in the above example). Only two things are guaranteed: the unfiltered IntuiMessage must be replied to and the unfiltered IntuiMessage (if it produces anything when passed through GT_FilterIMsg()) will produce a meaningful GadTools IntuiMessage like those described in the section on the different kinds of gadgets. The relationship between the unfiltered and filtered messages are expected to change in the future. See the section on documented side-effects for more information.

==== DrawBevelBox() ====

A key visual signature shared by most GadTools gadgets is the raised or recessed beveled box imagery. Since the program may wish to create its own boxes to match, GadTools provides the DrawBevelBox() and DrawBevelBoxA() functions.

<syntaxhighlight lang="C" line>
VOID DrawBevelBoxA( struct RastPort *rport, LONG left, LONG top, LONG width, LONG height,
struct TagItem *taglist );
VOID DrawBevelBox ( struct RastPort *rport, LONG left, LONG top, LONG width, LONG height,
Tag tag1, ... );
</syntaxhighlight>

The rport argument is a pointer to the RastPort into which the box is to be rendered. The left, top, width and height arguments specify the dimensions of the desired box.

The tag arguments, tag1 or taglist, may be set as follows:

; GT_VisualInfo (APTR)
: The VisualInfo handle as returned by a prior call to GetVisualInfo(). This value is required.

; GTBB_Recessed (BOOL)
: A beveled box may either appear to be raised to signify an area of the window that is selectable or recessed to signify an area of the window in which clicking will have no effect. Set this boolean tag to TRUE to get a recessed box. Omit this tag entirely to get a raised box.

DrawBevelBox() is a rendering operation, not a gadget. This means that the program must refresh any beveled boxes rendered through this function if the window gets damaged.

=== Gadget Keyboard Equivalents ===

Often, users find it convenient to control gadgets using the keyboard. The keyboard equivalent will be an underscored character in the gadget label, for easy identification. At the present time, however, the application is still responsible for implementing the reaction to each keypress.

==== Denoting a Gadget's Keyboard Equivalent ====

In order to denote the key equivalent, the application may add a marker-symbol to the gadget label. This is done by placing the marker-symbol immediately before the character to be underscored. This symbol can be any character that is not used in the label. The underscore character, "_" is the recommended marker-symbol. So, for example, to mark the letter "F" as the keyboard equivalent for a button labelled "Select Font ...", create the gadget text:

<syntaxhighlight lang="C" line>
ng.ng_GadgetText = "Select _Font ...";
</syntaxhighlight>

To inform GadTools of the underscore in the label, pass the GA_Underscore tag to CreateGadget() or CreateGadgetA(). The data-value associated with this tag is a character, not a string, which is the marker-symbol used in the gadget label:

<syntaxhighlight lang="C" line>
GA_Underscore, '_', /* Note '_', not "_" !!! */
</syntaxhighlight>

GadTools will create a gadget label which consists of the text supplied with the marker-symbol removed and the character following the marker-symbol underscored.

The gadget's label would look something like:

Select Font ...

==== Implementing a Gadget's Keyboard Equivalent Behavior ====

Currently, GadTools does not process keyboard equivalents for gadgets. It is up to the application writer to implement the correct behavior, normally by calling GT_SetGadgetAttrs() on the appropriate gadget. For some kinds of gadget, the behavior should be the same regardless of whether the keyboard equivalent was pressed with or without the shift key. For other gadgets, shifted and unshifted keystrokes will have different, usually opposite, effects.

Here is the correct behavior for keyboard equivalents for each kind of GadTools gadget:

; Button Gadgets
: The keyboard equivalent should invoke the same function that clicking on the gadget does. There is currently no way to highlight the button visuals programmatically when accessing the button through a keyboard equivalent.

; Text-Entry and Number-Entry Gadgets
: The keyboard equivalent should activate the gadget so the user may type into it. Use Intuition's ActivateGadget() call.

; Checkbox Gadgets
: The keyboard equivalent should toggle the state of the checkbox. Use GT_SetGadgetAttrs() and the GTCB_Checked tag.

; Mutually-Exclusive Gadgets
: The unshifted keystroke should activate the next choice, wrapping around from the last to the first. The shifted keystroke should activate the previous choice, wrapping around from the first to the last. Use GT_SetGadgetAttrs() and the GTMX_Active tag.

; Cycle Gadgets
: The unshifted keystroke should activate the next choice, wrapping around from the last to the first. The shifted keystroke should activate the previous choice, wrapping around from the first to the last. Use GT_SetGadgetAttrs() and the GTCY_Active tag.

; Slider Gadgets
: The unshifted keystroke should increase the slider's level by one, stopping at the maximum, while the shifted keystroke should decrease the level by one, stopping at the minimum. Use GT_SetGadgetAttrs() and the GTSL_Level tag.

; Scroller Gadgets
: The unshifted keystroke should increase the scroller's top by one, stopping at the maximum, while the shifted keystroke should decrease the scroller's top by one, stopping at the minimum. Use GT_SetGadgetAttrs() and the GTSC_Top tag.

; Listview Gadgets
: The unshifted keystroke should cause the next entry in the list to become the selected one, stopping at the last entry, while the shifted keystroke should cause the previous entry in the list to become the selected one, stopping at the first entry. Use GT_SetGadgetAttrs() and the GTLV_Top and GTLV_Selected tags.

; Palette Gadgets
: The unshifted keystroke should select the next color, wrapping around from the last to the first. The shifted keystroke should activate the previous color, wrapping around from the first to the last. Use GT_SetGadgetAttrs() and the GTPA_Color tag.

; Text-Display and Number-Display Gadgets
: These kinds of GadTools gadget have no keyboard equivalents since they are not selectable.

; Generic Gadgets
: Define appropriate keyboard functions based on the kinds of keyboard behavior defined for other GadTools kinds.

=== Complete GadTools Gadget Example ===

Here's a working example showing how to set up and use a linked list of GadTools gadgets complete with keyboard shortcuts.

<syntaxhighlight lang="C" line>
/* gadtoolsgadgets.c
** Simple example of using a number of gadtools gadgets.
**
*/
#define INTUI_V36_NAMES_ONLY

#include <exec/types.h>
#include <intuition/intuition.h>
#include <intuition/gadgetclass.h>
#include <libraries/gadtools.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/graphics.h>
#include <proto/intuition.h>
#include <proto/gadtools.h>

/* Gadget defines of our choosing, to be used as GadgetID's,
** also used as the index into the gadget array my_gads[].
*/
#define MYGAD_SLIDER (0)
#define MYGAD_STRING1 (1)
#define MYGAD_STRING2 (2)
#define MYGAD_STRING3 (3)
#define MYGAD_BUTTON (4)

/* Range for the slider: */
#define SLIDER_MIN (1)
#define SLIDER_MAX (20)

struct TextAttr Topaz80 = { "topaz.font", 8, 0, 0, };

struct IntuitionIFace *IIntuition;
struct GraphicsIFace *IGraphics;
struct GadToolsIFace *IGadTools;

/* Print any error message. We could do more fancy handling (like
** an EasyRequest()), but this is only a demo.
*/
void errorMessage(STRPTR error)
{
if (error)
IDOS->Printf("Error: %s\n", error);
}

/*
** Function to handle a GADGETUP or GADGETDOWN event. For GadTools gadgets,
** it is possible to use this function to handle MOUSEMOVEs as well, with
** little or no work.
*/
VOID handleGadgetEvent(struct Window *win, struct Gadget *gad, UWORD code,
WORD *slider_level, struct Gadget *my_gads[])
{
switch (gad->GadgetID)
{
case MYGAD_SLIDER:
/* Sliders report their level in the IntuiMessage Code field: */
IDOS->Printf("Slider at level %ld\n", code);
*slider_level = code;
break;
case MYGAD_STRING1:
/* String gadgets report GADGETUP's */
IDOS->Printf("String gadget 1: '%s'.\n",
((struct StringInfo *)gad->SpecialInfo)->Buffer);
break;
case MYGAD_STRING2:
/* String gadgets report GADGETUP's */
IDOS->Printf("String gadget 2: '%s'.\n",
((struct StringInfo *)gad->SpecialInfo)->Buffer);
break;
case MYGAD_STRING3:
/* String gadgets report GADGETUP's */
IDOS->Printf("String gadget 3: '%s'.\n",
((struct StringInfo *)gad->SpecialInfo)->Buffer);
break;
case MYGAD_BUTTON:
/* Buttons report GADGETUP's (button resets slider to 10) */
IDOS->Printf("Button was pressed, slider reset to 10.\n");
*slider_level = 10;
IGadTools->GT_SetGadgetAttrs(my_gads[MYGAD_SLIDER], win, NULL,
GTSL_Level, *slider_level,
TAG_END);
break;
}
}

/*
** Function to handle vanilla keys.
*/
VOID handleVanillaKey(struct Window *win, UWORD code,
WORD *slider_level, struct Gadget *my_gads[])
{
switch (code)
{
case 'v':
/* increase slider level, but not past maximum */
if (++*slider_level > SLIDER_MAX)
*slider_level = SLIDER_MAX;
IGadTools->GT_SetGadgetAttrs(my_gads[MYGAD_SLIDER], win, NULL,
GTSL_Level, *slider_level,
TAG_END);
break;
case 'V':
/* decrease slider level, but not past minimum */
if (--*slider_level < SLIDER_MIN)
*slider_level = SLIDER_MIN;
IGadTools->GT_SetGadgetAttrs(my_gads[MYGAD_SLIDER], win, NULL,
GTSL_Level, *slider_level,
TAG_END);
break;
case 'c':
case 'C':
/* button resets slider to 10 */
*slider_level = 10;
IGadTools->GT_SetGadgetAttrs(my_gads[MYGAD_SLIDER], win, NULL,
GTSL_Level, *slider_level,
TAG_END);
break;
case 'f':
case 'F':
IIntuition->ActivateGadget(my_gads[MYGAD_STRING1], win, NULL);
break;
case 's':
case 'S':
IIntuition->ActivateGadget(my_gads[MYGAD_STRING2], win, NULL);
break;
case 't':
case 'T':
IIntuition->ActivateGadget(my_gads[MYGAD_STRING3], win, NULL);
break;
}
}

/*
** Here is where all the initialization and creation of GadTools gadgets
** take place. This function requires a pointer to a NULL-initialized
** gadget list pointer. It returns a pointer to the last created gadget,
** which can be checked for success/failure.
*/
struct Gadget *createAllGadgets(struct Gadget **glistptr, void *vi,
UWORD topborder, WORD slider_level, struct Gadget *my_gads[])
{
struct NewGadget ng;
struct Gadget *gad;

/* All the gadget creation calls accept a pointer to the previous gadget, and
** link the new gadget to that gadget's NextGadget field. Also, they exit
** gracefully, returning NULL, if any previous gadget was NULL. This limits
** the amount of checking for failure that is needed. You only need to check
** before you tweak any gadget structure or use any of its fields, and finally
** once at the end, before you add the gadgets.
*/

/* The following operation is required of any program that uses GadTools.
** It gives the toolkit a place to stuff context data.
*/
gad = IGadTools->CreateContext(glistptr);

/* Since the NewGadget structure is unmodified by any of the CreateGadget()
** calls, we need only change those fields which are different.
*/
ng.ng_LeftEdge = 140;
ng.ng_TopEdge = 20+topborder;
ng.ng_Width = 200;
ng.ng_Height = 12;
ng.ng_GadgetText = "_Volume: ";
ng.ng_TextAttr = &Topaz80;
ng.ng_VisualInfo = vi;
ng.ng_GadgetID = MYGAD_SLIDER;
ng.ng_Flags = NG_HIGHLABEL;

my_gads[MYGAD_SLIDER] = gad = IGadTools->CreateGadget(SLIDER_KIND, gad, &ng,
GTSL_Min, SLIDER_MIN,
GTSL_Max, SLIDER_MAX,
GTSL_Level, slider_level,
GTSL_LevelFormat, "%2ld",
GTSL_MaxLevelLen, 2,
GT_Underscore, '_',
TAG_END);

ng.ng_TopEdge += 20;
ng.ng_Height = 14;
ng.ng_GadgetText = "_First:";
ng.ng_GadgetID = MYGAD_STRING1;
my_gads[MYGAD_STRING1] = gad = IGadTools->CreateGadget(STRING_KIND, gad, &ng,
GTST_String, "Try pressing",
GTST_MaxChars, 50,
GT_Underscore, '_',
TAG_END);

ng.ng_TopEdge += 20;
ng.ng_GadgetText = "_Second:";
ng.ng_GadgetID = MYGAD_STRING2;
my_gads[MYGAD_STRING2] = gad = IGadTools->CreateGadget(STRING_KIND, gad, &ng,
GTST_String, "TAB or Shift-TAB",
GTST_MaxChars, 50,
GT_Underscore, '_',
TAG_END);

ng.ng_TopEdge += 20;
ng.ng_GadgetText = "_Third:";
ng.ng_GadgetID = MYGAD_STRING3;
my_gads[MYGAD_STRING3] = gad = IGadTools->CreateGadget(STRING_KIND, gad, &ng,
GTST_String, "To see what happens!",
GTST_MaxChars, 50,
GT_Underscore, '_',
TAG_END);

ng.ng_LeftEdge += 50;
ng.ng_TopEdge += 20;
ng.ng_Width = 100;
ng.ng_Height = 12;
ng.ng_GadgetText = "_Click Here";
ng.ng_GadgetID = MYGAD_BUTTON;
ng.ng_Flags = 0;
gad = IGadTools->CreateGadget(BUTTON_KIND, gad, &ng,
GT_Underscore, '_',
TAG_END);
return(gad);
}

/*
** Standard message handling loop with GadTools message handling functions
** used (GT_GetIMsg() and GT_ReplyIMsg()).
*/
VOID process_window_events(struct Window *mywin,
WORD *slider_level, struct Gadget *my_gads[])
{
struct IntuiMessage *imsg;
ULONG imsgClass;
UWORD imsgCode;
struct Gadget *gad;
BOOL terminated = FALSE;

while (!terminated)
{
Wait (1 << mywin->UserPort->mp_SigBit);

/* GT_GetIMsg() returns an IntuiMessage with more friendly information for
** complex gadget classes. Use it wherever you get IntuiMessages where
** using GadTools gadgets.
*/
while ((!terminated) &&
(imsg = IGadTools->GT_GetIMsg(mywin->UserPort)))
{
/* Presuming a gadget, of course, but no harm...
** Only dereference this value (gad) where the Class specifies
** that it is a gadget event.
*/
gad = (struct Gadget *)imsg->IAddress;

imsgClass = imsg->Class;
imsgCode = imsg->Code;

/* Use the toolkit message-replying function here... */
IGadTools->GT_ReplyIMsg(imsg);

switch (imsgClass)
{
/* --- WARNING --- WARNING --- WARNING --- WARNING --- WARNING ---
** GadTools puts the gadget address into IAddress of IDCMP_MOUSEMOVE
** messages. This is NOT true for standard Intuition messages,
** but is an added feature of GadTools.
*/
case IDCMP_GADGETDOWN:
case IDCMP_MOUSEMOVE:
case IDCMP_GADGETUP:
handleGadgetEvent(mywin, gad, imsgCode, slider_level, my_gads);
break;
case IDCMP_VANILLAKEY:
handleVanillaKey(mywin, imsgCode, slider_level, my_gads);
break;
case IDCMP_CLOSEWINDOW:
terminated = TRUE;
break;
case IDCMP_REFRESHWINDOW:
/* With GadTools, the application must use GT_BeginRefresh()
** where it would normally have used BeginRefresh()
*/
IGadTools->GT_BeginRefresh(mywin);
IGadTools->GT_EndRefresh(mywin, TRUE);
break;
}
}
}
}

/*
** Prepare for using GadTools, set up gadgets and open window.
** Clean up and when done or on error.
*/
VOID gadtoolsWindow(VOID)
{
struct TextFont *font;
struct Screen *mysc;
struct Window *mywin;
struct Gadget *glist, *my_gads[4];
void *vi;
WORD slider_level = 5;
UWORD topborder;

/* Open topaz 8 font, so we can be sure it's openable
** when we later set ng_TextAttr to &Topaz80:
*/
if (NULL == (font = IGraphics->OpenFont(&Topaz80)))
errorMessage( "Failed to open Topaz 80");
else
{
if (NULL == (mysc = IIntuition->LockPubScreen(NULL)))
errorMessage( "Couldn't lock default public screen");
else
{
if (NULL == (vi = IGadTools->GetVisualInfo(mysc, TAG_END)))
errorMessage( "GetVisualInfo() failed");
else
{
/* Here is how we can figure out ahead of time how tall the */
/* window's title bar will be: */
topborder = mysc->WBorTop + (mysc->Font->ta_YSize + 1);

if (NULL == createAllGadgets(&glist, vi, topborder,
slider_level, my_gads))
errorMessage( "createAllGadgets() failed");
else
{
if (NULL == (mywin = IIntuition->OpenWindowTags(NULL,
WA_Title, "GadTools Gadget Demo",
WA_Gadgets, glist, WA_AutoAdjust, TRUE,
WA_Width, 400, WA_MinWidth, 50,
WA_InnerHeight, 140, WA_MinHeight, 50,
WA_DragBar, TRUE, WA_DepthGadget, TRUE,
WA_Activate, TRUE, WA_CloseGadget, TRUE,
WA_SizeGadget, TRUE, WA_SimpleRefresh, TRUE,
WA_IDCMP, IDCMP_CLOSEWINDOW | IDCMP_REFRESHWINDOW |
IDCMP_VANILLAKEY | SLIDERIDCMP | STRINGIDCMP |
BUTTONIDCMP,
WA_PubScreen, mysc,
TAG_END)))
errorMessage( "OpenWindow() failed");
else
{
/* After window is open, gadgets must be refreshed with a
** call to the GadTools refresh window function.
*/
IGadTools->GT_RefreshWindow(mywin, NULL);

process_window_events(mywin, &slider_level, my_gads);

IIntuition->CloseWindow(mywin);
}
}
/* FreeGadgets() even if createAllGadgets() fails, as some
** of the gadgets may have been created...If glist is NULL
** then FreeGadgets() will do nothing.
*/
IGadTools->FreeGadgets(glist);
IGadTools->FreeVisualInfo(vi);
}
IIntuition->UnlockPubScreen(NULL, mysc);
}
IGraphics->CloseFont(font);
}
}

/*
** Open all libraries and run. Clean up when finished or on error..
*/
int main()
{
struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
if (IIntuition == NULL)
errorMessage( "Requires V50 intuition.library");
else
{
struct Library *GfxBase = IExec->OpenLibrary("graphics.library", 50);
IGraphics = (struct GraphicsIFace*)IExec->GetInterface(GfxBase, "main", 1, NULL);
if (IGraphics == NULL))
errorMessage( "Requires V50 graphics.library");
else
{
struct Library *GadToolsBase = IExec->OpenLibrary("gadtools.library", 50);
IGadTools = (struct GadToolsIFace*)IExec->GetInterface(GadToolsBase, "main", 1, NULL);
if (IGadTools == NULL)
errorMessage( "Requires V50 gadtools.library");
else
{
gadtoolsWindow();

IExec->DropInterface((struct Interface*)IGadTools);
IExec->CloseLibrary(GadToolsBase);
}
IExec->DropInterface((struct Interface*)IGraphics);
IExec->CloseLibrary(GfxBase);
}
IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);
}
return 0;
}
</syntaxhighlight>

=== Restrictions on GadTools Gadgets ===

There is a strict set of functions and operations that are permitted on GadTools gadgets. Even if a technique is discovered that works for a particular case, be warned that it cannot be guaranteed and should not be used. If the trick concocted only works most of the time, it may introduce subtle problems in the future.

Never selectively or forcibly refresh gadgets. The only gadget refresh that should ever be performed is the initial GT_RefreshWindow() after a window is opened with GadTools gadgets attached. It is also possible to add gadgets after the window is opened by calling AddGlist() and RefreshGlist() followed by GT_RefreshWindow(). These refresh functions should not be called at any other time.

GadTools gadgets may not overlap with each other, with other gadgets or with other imagery. Doing this to modify the gadget's appearance is not supported.

GadTools gadgets may not be selectively added or removed from a window. This has to do with the number of Intuition gadgets that each call to CreateGadget() produces and with refresh constraints.

Never use OnGadget() or OffGadget() or directly modify the GFLG_DISABLED Flags bit. The only approved way to disable or enable a gadget is to use GT_SetGadgetAttrs() and the GA_Disabled tag. Those kinds of GadTools gadgets that do not support GA_Disabled may not be disabled (for now).

The application should never write into any of the fields of the Gadget structure or any of the structures that hang off it, with the exception noted earlier for GENERIC_KIND gadgets. Avoid making assumptions about the contents of these fields unless they are explicitly programmer fields (GadgetID and UserData, for example) or if they are guaranteed meaningful (Left, Top, Width, Height, Flags). On occasion, the program is specifically invited to read a field, for example the StringInfo->Buffer field.

GadTools gadgets may not be made relative sized or relative positioned. This means that the gadget flags GFLG_RELWIDTH, GFLG_RELHEIGHT, GFLG_RELBOTTOM and GFLG_RELRIGHT may not be specified. The activation type of the gadget may not be modified (for example changing GACT_IMMEDIATE to GACT_RELVERIFY). The imagery or the highlighting method may not be changed.

These restrictions are not imposed without reason; subtle or blatant problems may arise now or in future versions of GadTools for programs that violate these guidelines.

=== Documented Side-Effects ===

There are certain aspects of the behavior of GadTools gadgets that should not be depended on. This will help current applications remain compatible with future releases of the GadTools library.

When using GT_FilterIMsg() and GT_PostFilterIMsg(), never make assumptions about the message before or after filtering. I.e., do not interpret the unfiltered message, assume that it will or will not result in certain kinds of filtered message or assume it will result in a consumed message (i.e., when GT_FilterIMsg() returns NULL).

IDCMP_INTUITICKS messages are consumed when a scroller's arrows are repeating. That is, IDCMP_INTUITICKS will not be received while the user is pressing a scroller arrows. Do not depend or rely on this side effect, though, it will not necessarily remain so in the future.

A single call to CreateGadget() may create one or more actual gadgets. These gadgets, along with the corresponding code in GadTools, define the behavior of the particular kind of GadTools gadget requested. Only the behavior of these gadgets is documented, the number or type of actual gadgets is subject to change. Always refer to the gadget pointer received from CreateGadget() when calling GT_SetGadgetAttrs(). Never refer to other gadgets created by GadTools, nor create code which depends on their number or form.

For text-display gadgets, the GTTX_CopyText tag does not cause the text to be copied when the text is later changed with GTTX_Text.

The PLACETEXT ng_Flags are currently ignored by GENERIC_KIND gadgets. However, this may not always be so.

All GadTools gadgets set GADTOOL_TYPE in the gadget's GadgetType field. Do not use this flag to identify GadTools gadgets, as this flag is not guaranteed to be set in the future.

The palette gadget subdivides its total area into the individual color squares. Do not assume that the subdivision algorithm won't change.