Topic : The ATARI Compendium
Author : Scott Sanders / JAY Software
Version : 1.25 (20/6/2003)
Subject : Documentation
Nodes : 1117
Index Size : 32614
HCP-Version : 6
Compiled on : Atari
@charset : UTF-8
@lang : en
@default :
@help : %About
@options : +g -i -t4 +y +z
@width : 100
View Ref-FileConventionsTypesettingThe following table displays a list of typesetting conventions used in this
book:
Style Meaning
Normal Text Standard body text.
Bold Text Bolded words are always title of a chapter
or its part.
Underlined Text Underlined text is used to represent variable names
like handle. In addition sections of this book like
AES Reference Manual will be in capitalized italic
text.
| Text between Vertical bars imply the absolute value of the variable
vertical bars | or expression within. For instance: | -2 | == | 2 |
( Number 1, Two numbers contained within parentheses and separated
Number 2 ) by a comma indicate a coordinate point X followed by Y
For instance: ( 100, 100 ).
Number1 ^ Number2 2 ^ 8 is the same as 2 to the power of 8.
FunctionsThe function references in this guide are designed in a compatible manner
for ease of reading. Each function is illustrated as follows (headings not
applicable for a particular function will be omitted):
objc_draw() Function Name
WORD objc_draw( tree, obj, depth, bx, by, bw, bh ) Definition
OBJECT *tree; Data Types
WORD obj, depth, bx, by, bw, bh;
Function Immediately following the definition, a brief summary of
the function will follow.
Opcode The opcode related to the function will be listed in
decimal and hexadecimal where appropriate.
Availability This section will indicate any special conditions that must
exist for this function to be present (i.e.: OS version,
presence of GDOS, etc.).
Parameters The meaning of each parameter to the function will be
explained here. If any data pointed to by parameters is
modified it will be noted here as well.
Binding This section will list a binding for the function in either
'C' format or assembly format, whichever is more
appropriate. Please note bindings were written with ease of
reading, not necessarily optimized code, in mind.
Return Value This section explains the return value of the function.
This covers only that value returned on the left side of
the function expression.
Version Notes Under this heading, any features of a function which are
only present under certain conditions are discussed.
Caveats Known bugs or abnormalities of a function are listed next
to this heading.
Comments Other useful information or hints are listed here.
See Also Functions which bear a relation to the current function or
which are codependent on one another are listed here.
Group Group in which certain function belongs to.
Data TypesWithin function definitions, several data types are referenced that vary from
compiler to compiler. The following provides a key to the data type used and
their actual definition. Other data types will contain a structure definition
or 'typedef' within the binding. Be aware that some compilers default to
16-bit integers while others use 32-bit integers.
Usage Synonyms Meaning
WORD short, int, 16-bit signed integer
short int
UWORD unsigned int, 16-bit unsigned integer
unsigned short,
unsigned short int
LONG long, int, long int 32-bit signed integer
ULONG unsigned long, 32-bit unsigned integer
unsigned int,
unsigned long int
VOID void This naming is used to denote a function
with no parameters or return value.
BOOLEAN bool, boolean, 16-bit signed integer valid only as TRUE
short, short int, (non-zero) or FALSE (0)
int
WORD * short *, int *, This is a pointer to a 16-bit signed
short int * integer.
UWORD * unsigned short *, This is a pointer to a 16-bit unsigned
unsigned int *, integer.
unsigned short int *
LONG * long *, int *, This is a pointer to a 32-bit signed
long int * integer.
ULONG * unsigned long *, This is a pointer to a 32-bit unsigned
unsigned int *, integer.
unsigned long int *
VOIDP void *, char * This represents a pointer to an undefined
memory type.
VOIDPP void **, char ** This represents a pointer to a pointer of
an undefined memory type.
char * None 8-bit character string buffer
BYTE, signed byte, signed 8-bit signed byte
CHAR char
UBYTE, unsigned byte, 8-bit unsigned byte
UCHAR unsigned char
fix31 None This type holds a 31-bit mantissa and sign
bit. The value represents the number
contained multiplied times 1/65536. For
a complete explanation see Chapter 7: VDI.
Numeric ValuesBecause different computer languages use different nomenclature to specify
numbers in different bases, you will come across numbers presented in a
variety of different ways within this book as follows:
Prefix Decimal Meaning
22 as an
Example
None 22 This number is shown in decimal (base 10) format. The
majority of numbers shown will be in this format for
simplicity.
0x 0x16 This number is shown in hexadecimal (base 16) format.
Function opcodes in assembly language and numbers
used as mask values will appear mostly in this
format.
$ $16 Same as above.
0 026 This number is shown in octal (base 8) format. Only
in extremely specialized cases will numbers by
represented in this manner.
% %00010110 This number is shownn in binary (base 2) format. Only
when dealing with hardware registers and in a few
other circumstances will numbers be represented in
this manner.
Constant DefinitionsModern programming practices dictate the use of named constants wherever
possible in place of 'raw' values. Take for example the following call to
Devconnect():
In 'C':
Devconnect( 3, 9, 0, 0, 1 );
In assembly language:
move.w #1,-(sp)
move.w #0,-(sp)
move.w #0,-(sp)
move.w #9,-(sp)
move.w #3,-(sp)
move.w #$8B,-(sp)
trap #14
lea 12(sp),sp
Calling the function in this format makes debugging and program maintenance
more difficult because the parameters' meanings are concealed by the numeric
assignments. The following code illustrates the preferred method of coding:
In 'C':
/* Extracted from TOSDEFS.H, included by TOS.H */
#define ADC 3
#define DMAREC 0x01
#define DAC 0x08
#define CLK_25M 0
#define CLK_COMPAT 0
#define NO_SHAKE 1
/* Program segment */
#include <TOS.H>
Devconnect( ADC, DMAREC|DAC, CLK_25M, CLK_COMPAT, NO_SHAKE );
In assembly language:
; Extracted from TOSDEFS.I
ADC EQU 3
DMAREC EQU $01
DAC EQU $08
CLK_25M EQU 0
CLK_COMPAT EQU 0
NO_SHAKE EQU 1
Devconnect EQU $8B
; Program Segment
INCLUDE "TOSDEFS.I"
move.w #NO_SHAKE, -(sp)
move.w #CLK_COMPAT,-(sp)
move.w #CLK_25M,-(sp)
move.w #DMAREC|DAC,-(sp)
move.w #ADC,-(sp)
move.w #Devconnect,-(sp)
trap #14
lea 12(sp),sp
Unfortunately, because many function call parameters do not have standard
definitions associated with them, programmers have had to create their
own, which in turn makes their programs less portable, or use the 'raw'
constants. In addition, some compilers do not use standardized definitions
at all.
To help alleviate these difficulties, this revision of the Compendium
contains named definitions for almost every possible function parameter.
These definitions come from the 'C' header files TOS.H and TOSDEFS.H or
the assembly include file TOSDEFS.I, both available on disk from SDS.
Every attempt has been made to ensure that these files compile with
development tools in the Lattice 'C', Pure 'C', and Alcyon 'C' packages.
Some modifications to these files may be necessary, however, due to the
peculiarities of some compilers.
The 'C' header files consist of two parts to improve portability between
compilers. The TOS.H file is a compiler dependent file used to bind the
operating system calls to definitions. This file, in turn, includes the file
TOSDEFS.H which should remain portable between compilers.
When choosing definitions for inclusion in the TOSDEFS files, names given
by Atari were given highest precedence followed by those assigned (and kept
consistent) by compiler manufacturers. Other definitions were created with
simplicity and consistency in mind.
Use of the given constants will increase program code readability and
provide for a higher level of portability between compilers.