This explains how the psx interacts with the bios and the CPU, among other very important things.
-----------------------------------------------------------------
Table of Contents
Chapter 1
Kernel Library (libapi)
1
Chapter 2
CD-ROM Library (libcd)
73
Chapter 2
Streaming Library (libcd)
103
Chapter 4
Controller Library (libetc)
119
Chapter 5
Basic Graphics Library (libgpu)
129
Chapter 6
Basic Geometry Library (libgte)
229
Chapter 7
Extended Graphics Library (libgs)
511
Chapter 8
Basic Sound Library (libspu)
597
Chapter 9
Extended Sound Library (libsnd)
665
Chapter 10
Data Processing Library (libpress)
763
Chapter 11
Memory Card Library (libcard)
777
Chapter 12
Link Cable Library (libcomb)
795
Chapter 13
Kernal Library (libc/libc2)
803
Chapter 14
Math library (libmath)
857
About this Manual
This manual is the Reference manual for release 3.0 of the OS Runtime Library. All 3.0 Library functions and structures are defined in the this volume of the PlayStation Developer Reference Series.
For information on the differences between the 2.0 and 3.0 runtime libraries, refer to Appendix C of the Library Overview manual.
Changes Since Last Release
This manual has been significantly expanded in content and altered in format since release 2.0 of the Runtime Library. There are new Libraries and many new and modified structures and functions in release 3.0 which are referenced in this manual.
Note the following new features in this manual:
* A new, detailed chapter table of contents now appears at the beginning of each chapter.
Related Documentation
This manual should be read in conjunction with the Library Overview, since it summarizes the use of the libraries.
The complete set of the Developer Reference Series includes the following:
* PlayStation OS Guide
* PlayStation Hardware Guide
* Psy-Q Development System
* CD Emulator
* CD Generator
* 3D Graphics Tool
* Sprite Editor
* Sound Artist Tool
Note that the Developer Support BBS posts late breaking developments regarding the Libraries and also provides notice of forthcoming documentation releases and upgrades.
Manual Structure
The Library Reference contains fourteen chapters providing general descriptions of each of the high level and low level runtime ibraries.
Chapter 1 Chapter 2 Chapter 3 Chapter 4 Chapter 5 Chapter 6 Chapter 7
describes the Kernel Library (libapi)
describes the CD-ROM Library (libcd) describes the Streaming Library (libcd) describes the Controller Library (libetc) describes the Basic Graphics Library (libgpu) describes the Basic Geometry Library (libgte) describes the Extended Graphics Library (libgs
Chapter 8 Chapter 9 Chapter 10 Chapter 11 Chapter 12 Chapter 13 Chapter 14
describes the Basic Sound Library (libspu describes the Extended Sound Library (libsnd describes the Data Processing Library (libpress) describes the Memory Card Library (libcard) describes the Link Cable Library (libcomb) describes the Kernal Library (libc/libc2) describes the Math library (libmath)
Typographical Conventions
Certain Typographic Conventions are used through out this manual to clarify the meaning of the text. The following details the specific conventions used to represent literals, arguments, keywords, etc.
The following conventions apply to all narrative text outside of the structure and function descriptions. Convention Meaning
| A revision bar. Indicates that information to the left or right of the bar has been changed or added since the last release.
courier Indicates literal program code.
Bold Indicates a document, chapter or section title. The following conventions apply within structure and function descriptions only:
Convention Meaning
Medium Bold Denotes structure or function types and names.
Italic Denotes function arguments and structure members.
{} Denotes the start and end of the member list in a structure declaration.
Order Information
Additional copies of this documentation can be ordered by contacting:
Sony Computer Entertainment of America 919 East Hillsdale Blvd., 2nd floor
Foster City, CA 94404
Tel (41 5)-655-8000
Chapter 1
Kernel Library (libapi)
This chapter describes the structures defined in the kernel library and the available functions.
Chapter 1: Kernel Library (libapi) Table of Contents
Structures
DIRENTRY
5
EvCB
6
EXEC
7
TCB
8
TCBH
9
ToT
10
Functions
cd
11
ChangeClearPAD
12
ChangeTh
13
close
14
CloseEvent
15
CloseTh
16
delete
17
DeliverEvent
18
DisableEvent
19
EnableEvent
20
EnterCriticalSection
21
Exception
22
Exec
23
ExitCriticalSection
24
firstfile
25
FlushCache
26
format
27
GetConf
28
GetCr
29
GetGp
30
GetRCnt
31
GetSp
32
GetSr
33
GetSysSp
34
InitHeap
35
InitPAD
36
ioctl
37
Krom2RawAdd
38
Load
39
LoadExec
40
LoadTest
41
lseek
42
nextfile
43
open
44
OpenEvent
45
OpenTh
46
read
47
rename
48
ResetRCnt
49
ReturnFromException
50
SetConf
51
SetMem
52
SetRCnt
53
SetSp
54
StartPAD
55
StartRCnt
56
StopPAD
57
StopRCnt
58
SwEnterCriticalSection
59
SwExitCriticalSection
60
SystemError
61
TestEvent
62
undelete
63
UnDeliverEvent
64
WaitEvent
65
write
66
_96_init
67
_96_remove
68
_boot
69
_get_errno
70
_get_error
71
DIRENTRY
Data structure of directory entries. Structure
struct DIRENTRY {
char name [20];
long attr;
long size;
struct DIRENTRY *next long head;
char system[8];
}
Arguments
name
attr
size
next
head
system
Explanation
FIlename
Attributes (dependent on file system) FIle size (in bytes)
Next file entry (for user)
Startingsector
Reserved by system
This structure stores information relating to files registered in the file system.
See also: firstfile (p. 25), nextfile (p. 43).
6 Kernal Library (libapi) Structures
EvCB
Event Control Block. Structure
struct EvCB {
unsigned long desc; long status;
long spec;
long mode;
(long *FHandler)(); long system[2];
};
Members
desc
status spec
mode FHandler system
Explanation
Cause descriptor
Status
Event type
Mode
Function type handler Reservation by system
Used for event management.
See also: Open Event (p, 45), GetConf (p. 28), SetConf (p. 51).
EXEC
The data structure of an execute file. Structure
struct EXEC { unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned
};
Members
long pc0;
long gp0;
long t_addr; long t_size; long d_addr; long d_size; long b_addr; long b_size; long s_addr; long s_size;
long sp, fp, gp, ret.base;
pc0
gp0
t_addr t-size
d_addr d_size b_addr b_size s_addr s_size
Explanation
Execution start address gp register initial value
Startingaddress of data section with text section + initial value Size of data with text section + initial value
Reserved by system Reserved by system
Data section start address without initial value
Data section size without initial value
Stack start address (specified by the user)
Stack size (specified by the user)
Used by Exec() function.
See also: Exec (p. 23).
8 Kernal Library (libapi) Structures
TCB
Task Control Block. Structure
struct TCB {
long status;
long mode;
unsigned long reg[NREGS]; long system[6];
}; Members
status Status
mode Mode
reg Register saving area (specified by register designation macro) system Reservation by system
Explanation
Data block where a context (the contents of the registers) is stored for thread management.
See also: Open Th (p. 46), ChangeTh (p. 13), GetConf (p. 28), SetConf (p. 51).
Runtime Library Release 3.0
TCBH
Task Execute Queue. Structure
struct TCBH {
struct TCB *entry; long flag;
};
Members
entry Pointer to execute TCB.
flag Flag (reserved by system).
Explanation
Used for thread management. The execute TCB is linked to entry.
See also: ChangeTh (p. 13).
10 Kernal Library (libapi) Structures
ToT
System Table Information. Structure
struct ToT {
unsigned long *head; long size;
};
Members
head System table start address
size System table size (in bytes)
Explanation
Table information which enables organized handling of to various system tables which are used by the kernel. The placement address is 0x00000100.
Runtime Library Release 3.0
Kernal Library (libapi) Functions 11
cd
Change default directory. Syntax
long cd (path) char *path;
Arguments
path Default directory path Explanation
Changes the default directory path for the file system. The file system is specified by the device name at the beginning of the path.
Return value
Returns "1" if it succeeds, and "0" otherwise.
Runtime Library Release 3.0
12 Kernal Library (libapi) Functions
ChangeClearPAD
Sets the control driver. Syntax
void ChangeClearPAD (val) long val;
Arguments
val Vertical retrace line interruption clear flag Explanation
This function specifies whether to complete interrupt processing in a control driver started by a vertical retrace line interrupt, or to pass processing to a lower priority interrupt module without completion. A val value of 1 specifies completion, while a val value of 0 specifies passing.
Return value None.
See also: StartPAD (p. 55), StopPAD (p. 57), StartCARD (Ch 12), StopCARD (Ch 12).
Runtime Library Release 3.0
ChangeTh
Changing a thread to be executed. Syntax
long ChangeTh (thread) unsigned long thread;
Arguments
thread Thread descriptor Explanation
Execution is transferred to the thread specified by thread. The current thread is saved in a TCB during execution of this function. It returns from this function when the thread is restored.
Return value
On success and re-execution, the function returns 1. On failure, it returns 0. The Return value on re-execution can be changed by any other thread.
Remarks
Before executing ChangeTh(), initialize TCB reg [R-SR] to the following:
1) the interrupt context is 0X404
2) the main flow is 0X401
See also: TCB structure (p.8), TCBH structure (p. 9), OpenTh (p. 46).
close
Closing a file. Syntax
long close (fd) unsigned long fd;
Arguments
fd File descriptor
Explanation
This function closes a file descriptor.
Return value
On success, the function returns fd. On failure, it returns -1.
See also: Open (p. 43).
CloseEvent
Closing an event. Syntax
long CloseEvent (event) unsigned long event;
Arguments
event Event descriptor
Explanation
Releases the EvCB specified by event. Return value
On success, the function returns 1. On failure, it returns 0. Remarks
To be executed in a critical section.
See also: OpenEvent (p. 44).
CloseTh
Closes a thread. Syntax
CloseTh (thread) unsigned long thread;
Arguments
thread Thread descriptor
Explanation
This function closes a thread and releases its TCB. Return value
On success, the function returns 1. On failure, it returns 0. Remarks
To be executed in a critical section.
See also: OpenTh (p. 45).
delete
Deletes a file. Syntax
long delete (name) char *name;
Arguments name Filename Explanation
Deletes the file specified by name.
Return value
Returns "1" if it succeeds, and "0" otherwise.
See also: undelete (p. 62).
DeliverEvent
Generates an event. Syntax
void DeliverEvent (ev1, ev2)
unsigned long ev1; unsigned long ev2;
Arguments
ev1 Cause descriptor
ev2 Event class
Explanation
This function delivers an event.
Return value
None.
Remarks
This function must be executed in a critical section.
See also: UnDeliverEvent (p. 64), OpenEvent (p. 45), TestEvent (p. 62).
DisableEvent
Disables an event. Syntax
long DisableEvent (event) unsigned long event;
Arguments
event Event descriptor Explanation
This function inhibits occurrence of an event specified by the descriptor event. Occurrence of an event during inhibition is ignored.
Return value
On success, the function returns 1. On failure, it returns 0.
See also: EnableEvent (p. 20).
EnableEvent
Enables occurrence of an event. Syntax
This function enables occurrence of an event specified by the descriptor event.
Return value
On success, the function returns 1. On failure, it returns 0.
See also: DisableEvent (p. 19), TestEvent (p. 62).
EnterCriticalSection
Enter a critical section.
Syntax
void EnterCriticalSection (void)
Arguments None.
Explanation
This function stops interrupts, and enters a critical section. This occurs immediately after kernel startup.
Return value None.
Remarks
Executes an internal system call and destroys the interrupt context.
See also: TCBH (p. 9), TCB (p. 8), ExitCriticalSection (p. 24).
Exception
Causes an interrupt. Syntax
void Exception (void)
Arguments None.
Explanation
This function causes an interrupt, and stores the current context in the execute TCB. It is also valid in a critical section.
Return value
None. Remarks
Executes an internal call and destroys the exception context.
See also: TCBH (p. 9), TCB (p. 8), ChangeTh (p. 13), ReturnFromException (p. 50).
Executes an execute file. Syntax
long Exec (exec, argc, argv) struct EXEC *exec;
long argc;
char *argv[];
Arguments
exec Execute file information
argc Number of arguments
argv Argument
Explanation
According to the execute file information specified by exec, this function executes a module already loaded in memory. If exec->s_addr is 0, neither stack nor frame pointer is set.
The function performs the following:
(1) A data section without initial values is cleared to zero.
(2) sp, fp, and gp are saved, and then initialized.
(fp is set to the same value as sp.)
(3) The arguments of main() are set (in the a0 and a1 registers).
(4) The execution start address is called.
(5) After a return is made, sp, fp, and gp are restored.
Return value
On success, the function returns 1. On failure, it returns 0.
Remarks To be executed in a critical section.
See also: EXEC (p. 7), Load (p. 39).
ExitCriticalSection
Exits critical section.
Syntax
void ExitCriticalSection (void)
Arguments None.
Explanation
This function enables interrupts, and exits from the critical section.
Return value
None. Remarks
Executes an internal system call
See also: TCBH (p. 9), TCB (p.
and destroys the interrupt context.
8), EnterCriticalSection (p. 21).
firstfile
Looks up the first file. Syntax
struct DIRENTRY *firstfile (name, dir) char *name;
struct DIRENTRY *dir;
Arguments
name Filename
dir Buffer holding information relating to the referenced file.
Explanation
Looks up the file corresponding to the filename pattern name, and stores data relating to this file in the directory dir.
Return value
Returns dir if it succeeds, and "0" otherwise. Remarks
The wildcard characters "?" (standing for any one character) and "*" (standing for a character string of any length) can be used in the filename pattern. Characters specified after "*" are ignored.
See also: DIRENTRY (p. 5), nextfile (p. 42).
26 Kernal Library (libapi) Functions
FlushCache
Flushing one cache. Syntax
void FlushCache (void)
Arguments None.
Explanation
Flushes one cache. The program code is executed when it is written to memory.
Return value None.
Remarks
To be executed in a critical section. Note also that it cannot change the contents of memory.
Runtime Library Release 3.0
format
Initializes file system. Syntax
Kernal Library (libapi) Functions 27
long format (fs) char *fs;
Arguments
fs File system name Explanation
Initializes file system fs. Return value
Returns "1" if it succeeds, and "0" otherwise.
Remarks This function is only effective on writeable file systems.
Runtime Library Release 3.0
28 Kernal Library (libapi) Functions
GetConf
Gets the kernel configuration. Syntax
void GetConf (ev, tcb, sp) unsigned long *ev; unsigned long *tcb; unsigned long *sp;
Arguments
ev Address for storing the number of event management block elements
tcb Address for storing the number of task management block elements
sp Address for storing the initial stack pointer value
Explanation
This function stores a system configuration parameter in an address given by a pointer as an argument.
Return value None.
See also: SetConf (p. 51).
Runtime Library Release 3.0
Kernal Library (libapi) Functions 29
GetCr
Gets a cause register value.
Syntax
unsigned long GetCr (void)
Arguments None.
Explanation This function gets the control register cause register value .
The meaning of each bit of the cause register as follows:
Bit Description
31-6 Reserved by the system
5-2 Exception code
0000 External interrupt
0001 Not used 0010 Not used 0011 Not used
0100 Address read error
0101 Address write error
0110 Command bus error
0111 Data bus error
1000 System call 1001 Break point
1010 Undefined command
1011 Co-processor not mounted
1100 Overflow
1-0 Reserved by the system
Return value
The current cause register value is returned.
See also: OpenTh (p. 46).
unsigned long GetGp (void)
Arguments None.
Explanation
This function gets a gp register value.
Return value
The current gp register value is returned.
See also: EXEC structure (p. 7), OpenTh (p. 46), Load (p. 39), Exec (p. 23).
Kernal Library (libapi) Functions 31
GetRCnt
Acquires a root counter. Syntax
long GetRCnt (spec) unsigned long spec;
Arguments
spec Root counter Explanation
Returns the current value of root counter spec.
Return value
On success, the function returns the 32-bit unsigned expanded counter value. On failure, it returns -1.
See also: SetRCnt (p. 53), StartRCnt (p. 56), StopRCnt (p. 58), ResetRCnt (p. 49).
Runtime Library Release 3.0
unsigned long GetSp (void)
Arguments None.
Explanation
This function gets an sp register value.
Return value
A current sp register value is returned.
See also: EXEC (p. 6), OpenTh (p. 45), Load (p. 38), Exec (p. 23).
GetSr
Gets a status register value.
Syntax
unsigned long GetSr (void)
Arguments None.
Explanation This function gets the control register status register value.
The meaning of each bit of the status register is as follows:
Bit
Description
31-28
Co-processor installation flag (1: Installed)
Bit 29 is GTE.
27-11
Reserved by the system
10
Always 1
9-3
Reserved by the system
2
Main flow interrupt
permission (1: Permission)
1
Reserved by the system
0
Interrupt ermission
(1: Permission)
Return value
The current status register value is returned.
See also: OpenTh (p. 45).
34 Kernal Library (libapi) Functions
GetSysSp
Gets a system stack.
Syntax
long GetSysSp (void)
Arguments None.
Explanation
This function acquires the highest address of a system stack area for event handler function execution.
The size of the stack area is 2 K-bytes.
Return value
Highest address of the system stack area
InitHeap
Initializes a heap area. Syntax
void InitHeap (head, size) void *head;
long size;
Arguments
head Heap start address
size Heap size (a multiple of 4, in bytes)
Explanation
This function initializes a group of standard function library memory control functions . After using this function, malloc(), etc. are usable.
There is an overhead so the entire size in bytes cannot be used.
Return value
None.
Remarks
To be executed in a critical section. If several executions of this function overlap, the memory control information previously held will be lost.
See also: malloc (see Ch 14).
36 Kernal Library (libapi) Functions
InitPAD
Initializes the controller. Syntax
void InitPAD (bufA, lenA, bufB, lenB) char *bufA, *bufB;
long lenA, lenB;
Arguments
bufA, bufB Incoming data buffers
lenA, lenB Length of incoming data buffers (in bytes)
Explanation
This function registers a receive data buffer for the controller. The format of received data is given in the Library Overview. ChangeClearPAD() is not executed internally.
Return value None.
See also: StartPAD (p. 55), StopPAD (p. 57), ChangeClearPAD (p. 12).
Runtime Library Release 3.0
ioctl
Controls devices. Syntax
long ioctl (fd, com, arg) unsigned long fd;
long com;
long arg;
Arguments
fd File descriptor
com Control command
arg Control command argument
Explanation
Executes all types of control commands on the device. Details of the commands and their arguments are given separately for each device.
Return value
Returns the value "1" if it succeeds and the value "0" otherwise.
See also: open (p. 43).
38 Kernal Library (libapi) Functions
Krom2RawAdd
Collects Kanji font pattern addresses. Syntax
unsigned long Krom2RawAdd (sjiscode) unsigned short sjiscode;
Arguments
sjiscode Shift JIS code Explanation
This function acquires the starting address in the kernel of the font pattern corresponding to the Kanji character specified by sjiscode.
Return value
The starting address of a Kanji font pattern is returned. If there is no font data corresponding to the specified Kanji character, a value of -1 is returned.
Runtime Library Release 3.0
Load
Loads an execute file. Syntax
long Load (name, exec) char *name;
struct EXEC *exec;
Arguments
name Filename
exec Execute file information
Explanation
This function reads the PS-X EXE format file name to the address specified by its internal header, and writes internal information to exec.
Return value
On success, the function returns 1. On failure, it returns 0.
See also: EXEC structure (p. 7), Exec (p.23).
LoadExec
Executes a file. Syntax
Void Load Exec (name, s_a ddr, s_size) char *name;
unsigned long s_addr;
unsigned long s_size;
Arguments
name PS-X EXE format execution file name (fewer than 19 characters) s_addr Stack area starting address
s_size Number of bytes in stack area
Explanation
This function calls Load() and Exec(), then reads a file name into memory and executes the file. s_addr and s_size are passed to Exec() and set by the structure EXEC.
Return value
None. There is no return value when the function executes normally.
See also: EXEC (p. 6), Load (p. 38), Exec (p. 23).
LoadTest
Load test. Syntax
long LoadTest (name, exec) char *name;
struct EXEC *exec;
Arguments
name Filename
exec Data in an execute file
Explanation
This function writes internal information from a PS-X EXE format file name to exec.
Return value
On success, the function returns the executione starting address. On failure, it returns 0.
See also: EXEC (p. 6), Load (p. 38).
lseek
Moves a file pointer. Syntax
long lseek (fd, offset, flag) unsigned long fd;
long offset;
long flag;
Arguments
fd File descriptor
offset Offset
flag See "Explanation".
Explanation
This function moves a file pointer to the device indicated by the descriptor fd. offset stands for the number of bytes to be moved. The starting point of the movement varies with the value of the flag. However, it does not apply to a tty driver. Any of the following can be designated as flag:
flag macro Operation
SEEK_SET Start of file
SEEK_CUR Current Position
Return value
On success, the function returns the current file pointer. On failure, it returns -1.
See also: open (p. 44), read (p. 47), write (p. 66).
nextfile
Looks up the next file. Syntax
struct DIRENTRY *nextfile (dir) struct DIRENTRY *dir;
Arguments
dir Buffer holding information relating to the referenced file. Explanation
This function continues the lookup under the same conditions as the function "firstfile()", executed immediately beforehand. If it finds the corresponding file, it stores information relating to this file in dir.
Return value
Returns dir if it succeeds, and "0" otherwise. Remarks
If the shell cover of the CD-ROM drive has been opened since the execution of the immediately preceding function "firstfile()", this function fails on execution, and reports that the file has not been found.
See also: DIRENTRY (p. 5), firstfile (p. 25).
open
Opens a file. Syntax
unsigned long open (devname, flag) char *devname;
unsigned long flag;
Arguments
devname Filename
flag Open mode
Explanation
This function opens a device for low-level input/output, and returns the descriptor. flag is dependent on the device. Common parts are as follows:
Macro Open mode
O_RDONLY O_WRONLY O_RDWR O_CREAT O_NOBUF O_NOWAIT
Read only Write only
Both read and write Create new file Non-buffer mode Asynchronous mode
Return value
On success, the function returns the descriptor. On failure, it returns -1.
See also: close (p.14).
OpenEvent
Opens an event. Syntax
unsigned long OpenEvent (desc, spec, mode, func) unsigned long desc;
long spec;
long mode;
long *func();
Arguments
desc Cause descriptor
spec Event type
mode Mode
func Pointer to the handler function
Explanation
This function secures the EvCB for an event with the descriptor desc and event class spec. Return value
On success, the function returns an event descriptor. On failure, it returns -1. Remarks
To be executed in a critical section.
See also: EvCB structure (p. 6), CloseEvent (p. 15), DeliverEvent (p.18).
OpenTh
Opens a thread. Syntax
unsigned long OpenTh (func, sp, gp) long (*func)();
unsigned long sp;
unsigned long gp;
Arguments
func Pointer to the execution start function
sp Stack pointer value
gp Global pointer value
Explanation
This function secures a TCB, and initializes it according to the arguments. This TCB can be executed using ChangeTh().
Return value
On success, the function returns the descriptor. On failure, it returns 1. Remarks
To be executed in a critical section.
See also: TCB structure (p. 8), CloseTh (p. 13).
read
Reads data from a file Syntax
long read (fd, buf, n) unsigned long fd; void *buf;
long n;
Arguments
fd File descriptor
buf Read buffer address
n Number of bytes to be read
Explanation
This function reads n bytes from the descriptor fd to the area specified by buf.
Return value
On normal termination, the function returns the actual number of bytes read into the area. Any other value returns -1.
See also: open (p. 44).
48 Kernal Library (libapi) Functions
rename
Changes a file name. Syntax
long rename (src dest) const char *src; const char *dest;
Arguments
src Old filename
dest New filename
Explanation
Changes the filename from src to dest. In both cases, the full path from the device name must be specified.
Return value
Returns "1" if it succeeds, and "0" otherwise. Remarks
This function is only effective on writeable file systems.
Runtime Library Release 3.0
ResetRCnt
Resets a root counter. Syntax
long ResetRCnt (spec) unsigned long spec;
Arguments
spec Specifies a root counter Explanation
This function resets a root counter spec.
Return value
On success, the function returns 1. On failure, it returns 0.
See also: SetRCnt (p. 53), GetRCnt (p. 31), StartRCnt (p. 56), StopRCnt (p. 58).
50 Kernal Library (libapi) Functions
ReturnFromException
Return from exception. Syntax
void ReturnFromException (void)
Arguments None.
Explanation
Accesses the exception context and returns from exception processing. It is used in an event handler or callback function.
Return value
None if the function is executed normally.
Runtime Library Release 3.0
Kernal Library (libapi) Functions 51
SetConf
Modifies the kernel configuration. Syntax
void SetConf (ev, tcb, sp) unsigned long ev; unsigned long tcb; unsigned long sp;
Arguments
ev Number of event management block elements
tcb Number of task management block elements
sp Initial stack pointer value
Explanation
This function modifies a system configuration parameter to reorganize the kernel. All the contents of event and task management blocks are destroyed. Registration of functions like callback and all patches to the kernel are invalid.
Return value None.
See also: GetContf (p. 27).
Runtime Library Release 3.0
52 Kernal Library (libapi) Functions
SetMem
Modifies the valid memory size. Syntax
void SetMem (n) long n;
Arguments
n Valid memory size (in megabytes) Explanation
This function changes the valid memory size to the value specified by the argument. n must be 2 (2 megabytes) or 8 (8 megabytes). Any values other than these are ignored.
Return value None.
Remarks
Memory access out of the valid range results in the generation of CPU exception irrespective of the mounted physical memory.
Runtime Library Release 3.0
Kernal Library (libapi) Functions 53
SetRCnt
Sets a root counter. Syntax
long SetRCnt (spec, target, mode) unsigned long spec;
unsigned short target;
long mode;
Arguments
spec Root counter specification target Target value
mode Mode
Explanation
Set the root counter in spec, the target value in target, and the mode in mode.
Return value
On success, the function returns 1. On failure, it returns 0.
See also: GetRConf (p. 31), StartRCnt (p. 56), StopRCnt (p. 58), ResetRCnt (p. 49).
Runtime Library Release 3.0
SetSp
Sets a stack pointer. Syntax
unsigned long SetSp (new-sp) unsigned long new-sp;
Arguments
new-sp value set in sp register Explanation
Sets new-sp in the sp register.
Return value
Returns the sp register value before modification.
See also: EXEC (p. 6), OpenTh (p. 45), Load (p. 38), Exec (p. 23).
Kernal Library (libapi) Functions 55
StartPAD
Starts reading the controller. Syntax
long StartPAD (void)
Arguments
None.
Explanation
Triggered by the interruption of a vertical retrace line, this function starts to read the controller. ChangeClearPAD (1) is executed internally.
Return value
On success, the function returns 1. On failure, it returns 0. Remarks
Interruption is permitted.
See also: InitPAD (p. 35), ChangeClearPAD (p. 12).
StartRCnt
Starting a root counter. Syntax
This function starts a root counter spec, and enables interrupts for that counter. If spec is 0, the function initializes all the root counters, and enables interrupts for all counters.
Return value
On success, the function returns 1. On failure, it returns 0.
See also: GetRCnt (p. 31), ResetRCnt (p. 49), SetRCnt (p. 53), StopRCnt (p. 58).
Kernal Library (libapi) Functions 57
StopPAD
Stops reading the controller. Syntax
void Stop PAD (void)
Arguments None.
Explanation
This function stops reading the controller. Interruption is not permitted. ChangeClearPAD (1) is executed internally.
Return value None.
See also: InitPAD (p. 55), ChangeClearPAD (p.12).
Runtime Library Release 3.0
StopRCnt
Stops a root counter. Syntax
This function stops a root counter spec.
Return value
On success, the function returns 1. On failure, it returns 0.
See also: StartRCnt (p. 56), SetRCnt (p. 53), ResetRCnt (p. 49), GetRCnt (p. 31).
Kernal Library (libapi) Functions 59
SwEnterCriticalSection
Suppressess interrupts. Syntax
void SwEnterCriticalSection (void)
Arguments None.
Explanation
This function suppresses interrupts. Because no system call interrupt is generated internally, this function can be invoked in event handling and callback functions. It must be executed in a critical section.
Return value None.
See also: EnterCriticalSection (p. 24), SwExitCriticalSection (p. 59).
Runtime Library Release 3.0
60 Kernal Library (libapi) Functions
SwExitCriticalSection
Permits interrupts. Syntax
void SwExitCriticalSection (void)
Arguments None.
Explanation
This function permits interrupts. Because no system call interrupt is generated internally, the function can be invoked in event handling and callback functions. It must be executed in a critical section.
Return value None.
See also: EnterCriticalSection (p. 21), SwExitCriticalSection (p. 59).
Runtime Library Release 3.0
Kernal Library (libapi) Functions 61
SystemError
Displays the system error screen. Syntax
void System Error (c, n) char c;
long n;
Arguments
c Error identification character (Alphabetic character)
n Error identification code (0 to 999)
Explanation
This function displays a detected system error forthe user (game player). In the PlayStation, exit() is called. Successful execution results in no return value.
Return value None.
Runtime Library Release 3.0
TestEvent
Testing an event. Syntax
long TestEvent (event) unsigned long event;
Arguments
event Event descriptor Explanation
This function checks to see whether or not the event specified by the descriptor event has occurred. If so, the function restores the event to its previous status.
Return value
If the event is found to have occurred, the function returns 1. Otherwise, it returns 0.
See also: DeliverEvent (p. 18), EnableEvent (p. 20), WaitEvent (p. 65).
undelete
Resurrect a file. Syntax
long undelete (name) char *name;
Arguments
name Filename
Explanation
Resurrects the previously deleted file specified by name.
Return value
Returns "1" if it succeeds, and "0" otherwise.
See also: delete (p. 17).
UnDeliverEvent
Cancelling event. Syntax
void UnDeliverEvent (ev1, ev2)
unsigned long ev1; unsigned long ev2;
Arguments
ev1 Cause descriptor
ev2 Event class
Explanation
This function cancels an event.
Return value
None.
Remarks
This function must be executed in a critical section.
See also: DeliverEvent (p. 18), EnableEvent (p. 20), OpenEvent (p. 44), TestEvent (p. 61), WaitEvent (p. 65), EnterCriticalSection (p. 21).
WaitEvent
Waiting for the occurrence of an event. Syntax
long WaitEvent (event) unsigned long event;
Arguments
event Event descriptor Explanation
This function waits until an event specified by the descriptor event occurs, and returns after restoring the event to its previous status.
Return value
On success, the function returns 1. Otherwise, it returns 0.
See also: TestEvent (p. 62).
write
fd File descriptor
buf Write buffer address
n Number of bytes to be written
Explanation
This function writes n bytes from the descriptor fd to the area specified by buf.
Return value
At normal termination, thisfunction returns the number of bytes actually written to the area. Any other result returns -1.
See also: open (p. 44).
_96_init
Installs the ISO-9660 file system.
Syntax
void _96_init (void)
Arguments None.
Explanation
This function installs the ISO-9660 file system driver that manages access to the CD-ROM in the kernel.
Return value
None.
See also: _96_remove (p. 68).
68 Kernal Library (libapi) Functions
_96_remove
Removes the ISO-9660 file system. Syntax
void _96_remove (void)
Arguments None.
Explanation
This function removes the ISO-9660 file system driver that manages access to the CD-ROM from the kernel.
Return value None.
See also: _96_init (p. 67).
Runtime Library Release 3.0
Kernal Library (libapi) Functions 69
_boot
Rebooting. Syntax
void _boot (void)
Arguments None.
Explanation
This function reboots the system. This is an interface used to develop demonstration programs. Do not use it for general title applications.
Return value None.
Runtime Library Release 3.0
70 Kernal Library (libapi) Functions
_get_errno
Collects the latest I/O error code. Syntax
long _get_errno (void)
Arguments None.
Explanation
This function collects the latest error code through all file descriptors. Error codes are defined in sys/errno.h.
Return value Error code
Runtime Library Release 3.0
Kernal Library (libapi) Functions 71
_get_error
Collects an error code for afile descriptor. Syntax
long _get_error (fd) unsigned long fd
Arguments
fd File descriptor Explanation
This function returns the code of the most recent error on the specified file descriptor. Error codes are defined in sys/errno.h.
Return value Error code.
Runtime Library Release 3.0
72 Kernal Library (libapi) Functions
Chapter 2
CD-ROM Library (libcd)
This chapter describes the structures and macro instructions defined in the CD-ROM library, and available functions. "libcd" provides a service for asynchronously controlling the PlayStation's built-in CD-ROM drive.
Chapter 2: CD-ROM Library (libcd) Table of Contents
Structures
CdlATV
77
CdlFILE
78
CdlLOC
79
Functions
CdComstr
80
CdControl
81
CdControlB
83
CdControlF
84
CdGetToc
85
CdInit
86
CdInitFileSystem
87
CdIntstr
88
CdIntToPos
89
CdMix
90
CdPosToInt
91
CdRead
92
CdRead2
93
CdReadCallback
93
CdReadSync
94
CdReady
95
CdReadyCallback
97
CdSearchFile
97
CdSetDebug
98
CdSync
100
CdSyncCallback
100
Audio attenuator. Structure
typedef struct {
unsigned char val0; unsigned char val1; unsigned char val2; unsigned char val3; } CdlATV;
Members
val0 CD (L) --> SPU (L) reduction
val1 CD (L) --> SPU (R) reduction
val2 CD (R) --> SPU (L) reduction
val3 CD (R) --> SPU (R) reduction
78 CD-ROM Library (libcd) Structures
CdlFILE
9660 File Descriptor. Structure
typedef struct { CdlLOC pos;
unsigned long size; char name[16];
} CdlFILE;
Members
pos File position
size File size
name File name
Explanation
Get position and size of ISO-9660 CD-ROM file.
Runtime Library Release 3.0
CD-ROM Location. Structure
typedef struct {
unsigned char minute; unsigned char second; unsigned char sector; unsigned char track; } CdlLOC;
Members
minute Minute
second Second
sector Sector
track Track number
Explanation
Structure for setting the position of the CD-ROM.
Remarks
The track member is not used at present.
CdComstr
Get character string corresponding to command code (for debugging). Syntax
char *CdComstr (com) unsigned char com;
Argument
code Command completion code Explanation
For debugging. Get corresponding character string from processing status code. For example, get the following character strings for these codes. For debugging.
Command Code Character String
CdlNop CdlSetloc CdlPlay CdlForward CdlBackword
"CdlNop" "CdlSetloc" "CdlPlay" "CdlForward" "CdlBackword"
Return value
Pointer to start of character string.
CdControl
Issue primitive command to CD-ROM system. Syntax
int CdControl (com,*param,*result) unsigned char com, *param, *result;
Argument
com Command code
param Command arguments
result Return value storage buffer (requires 8 bytes)
Explanation
Issues the primitive command com to the CD-ROM system. If the command takes an argument, CdControl() sets these arguments in param. Uses result to store the return value of the command in the specified buffer.
The stored contents of command (com), the arguments (param), and the return value (result) are listed below.
This function is a non-blocking function, so it is necessary to use CdSync to detect actual transfer termination.
Symbol
Code
CdlNop
0x01
CdlSetloc
0x02
CdlPlay
0x03
CdlForward
0x04
CdlBackword
0x05
CdlReadN
0x06
CdlStanby
0x07
CdlStop
0x08
CdlPause
0x09
CdlMute
0x0b
CdlDemute
0x0c
CdlSetfilter
0x0d
CdlSetmode
0x0e
CdlGetlocL
0x10
CdlGetlocP
0x11
CdlSeekL
0x15
CdlSeekP
0x16
CdlReadS
0x1b
CdlReset
0x1c
B: Blocking, N: Non-Blocking operation Table: Primitive command overview
Symbol
Parameter Type
Contents
CdlSetloc
|CdlLOC *
start sector location
CdlReadN
|CdlLOC *
start sector location
CdlReadS |CdlLOC start sector location
CdlPlay |CdlLOC start sector location
CdlSetfilter |CdlFILTER set ADCPM sector play
CdlSetmode |u_char set basic mode
Table: Primitive commands that take arguments and their arguments
Symbol Return values and locations of the bytes where they are stored
CdlNop CdlSetloc CdlPlay CdlForward CdlBackword CdlReadN CdlStanby CdlStop CdlPause CdlMute CdlDemute CdlSetfilter CdlSetmode CdlGetlocL CdlGetlocP CdlSeekL CdlSeekP CdlReadS CdlReset
0 1 2 3 4 5 6 7 status
status status status status status status status status status status status status
min sec sector mode file chan
track index min sec frame amina sec aframe status
status status status
Table: Return values of primitive commands
Return value
1 if the command is issued successfully. 0 if failed. Remarks
Set param to 0 for commands that do not require arguments. If result is set to 0, the return value is not stored.
CdControl B
Issue primitive command to CD-ROM system (Blocking-type function). Syntax
int CdControlB (com, *param,*result) unsigned char com, *param, *result;
Argument
com Command code
param Command arguments
result Return value storage buffer (requires 8 bytes)
Explanation
Issues the primitive command com to the CD-ROM system. If the command takes an argument, CdControlB() sets these arguments in param. Uses result to store the return value of the command in the specified buffer.
CdControlB() is identical to CdControl() except for the block function that waits to return until processing terminates.
For details, see the commands and arguments of CdControl(), and Vol. 1. Return value
1 if issued successfully. 0 if failed. Remarks
Set param to 0 for commands that do not require arguments. If result is set to 0, the return value is not stored.
CdControl F
Issue primitive command to CD-ROM system (highspeed type). Syntax
int CdControlF (com,*param) unsigned char com, *param;
Argument
com Command code (see separate item) param Argument for command
Explanation
Issues the primitive command com to the CD-ROM system. If the command takes an argument, CdControlF() sets these arguments in param. Uses result to store the return value of the command in the specified buffer.
CdControlF() is fast because it does no handshaking with the subsystem (it does not even wait for command acknowledgement (ACK)).
For details, see the commands and arguments of CdControl(), and Vol. 1.
Return value 1 if issued successfully. 0 if failed. Remarks
Set param to 0 for commands that do not require arguments. At present 1 is always returned, so "return value" has no significance.
CdGetToc
Read TOC. Syntax
CD-ROM Library (libcd) Functions 85
int CdGetToc (*loc) CdlLOC *loc;
Argument
loc Location table Explanation
Get starting position of each track in CD-ROM.
Return value Positive integer returns a track number. Anything else returns Error.
Remarks The maximum number of tracks is 100.
Runtime Library Release 3.0
86 CD-ROM Library (libcd) Functions
CdInit
Initializes CD-ROM system. Syntax
void CdInit (mode) CdInit mode;
Argument
mode Reset mode
Explanation
Resets CD-ROM subsystem to mode set by "mode"
Return value None.
Remarks At present the mode argument is not used.
Runtime Library Release 3.0
CD-ROM Library (libcd) Functions 87
CdInitFileSystem
Initializes CD-ROM file driver. Syntax
void CdInitFileSystem (int mode) int mode;
Argument
mode Reset mode
Explanation
Reset CD file system to the mode set by mode.
If the CD-ROM file is accessed using the open()/read()interface, this function must always be called.
Return value None
Remarks
At present the mode argument is not used.
Runtime Library Release 3.0
88 CD-ROM Library (libcd) Functions
CdIntstr
Get character string corresponding to command processing status (for debugging). Syntax
char *CdIntstr (intr) unsigned char intr;
Argument
intr Processing status code
Explanation
For debugging. Get character string corresponding to processing status code intr. For debugging.
Processing Status Character String
CdlNoIntr "CdlNoIntr"
CdlComplete "CdlComplete"
CdlDiskError "CdlDiskError"
Return value
Pointer to start of character string.
Runtime Library Release 3.0
CD-ROM Library (libcd) Functions 89
CdIntToPos
Get minute/second/sector from absolute sector number. Syntax
CdlLOC *CdIntToPos (i,*p) int i;
CdlLOC *p;
Argument
i Absolute sector number
p Minute and seconds,sectors storage buffer
Explanation Calculate value for minute/second/sector from absolute sector number
Return value Pointer to p.
Runtime Library Release 3.0
90 CD-ROM Library (libcd) Functions
CdMix
Set attenuator. Syntax
int CdMix (CdlATV *vol) CdlATV *vol;
Argument
vol Attenuator volume
Explanation
Set audio volume value for CD audio (CD-DA, ADPCM)
Return value Always returns 1.
Runtime Library Release 3.0
CD-ROM Library (libcd) Functions 91
Cd PosTo I nt
Get absolute sector number from minute/second/sector. Syntax
int CdPosToInt (*p) CdlLOC *p;
Argument
p Minute/second/sector storage buffer
Explanation Calculate value for absolute sector number from minutes/seconds/sectors increased by p.
Return value
Absolute sector number.
Runtime Library Release 3.0
92 CD-ROM Library (libcd) Functions
CdRead
Read multiple sectors. Syntax
int CdRead (sectors ,*buf ,mode) int sectors;
unsigned long *buf;
int mode;
Argument
sectors Read sector count
buf Read buffer
mode Subsystem mode
Explanation
Read sectors of data from CD-ROM, and fill buffers in main memory. The start position is the target position when CdlSeekL/CdlSetloc was last issued, or the next sector after the sector read by the last CdRead(). This is a non-blocking function, so in practice the actual transfer completionr needs to be detected by CdReadSync().
Return value
0 if command issue failed. 1 if command issue succeeded.
Runtime Library Release 3.0
CD-ROM Library (libcd) Functions 93
Cd Read 2
Start the read. Syntax
int CdRead2 (mode) int mode;
Argument
mode Subsystem mode Explanation
Seeks CD-ROM head in CdlSetloc position, and commences reading. Commences streaming in mode when CdlModeStream is added. If CdlModeRT is added in mode, commences play of ADPCM.
When you read data, you must code it with a user program that calls CdGetSector() at the same time that DataReady timing is done.
Return value
0 if command issue failed.
1 if command issue succeeded.
Runtime Library Release 3.0
CdReadCallback
Defines CdRead callback function. Syntax
unsigned long CdReadCallback (*func) void (*func)();
Argument
func Callback function address
Explanation
func defines the callback called when CdRead() completes. If func is set as 0, callback does not occur.
Return value
Address of previously set callback Remarks
While func is executing,subsequent drawing complete interrupts are masked. Therefore func needs to return as soon as the necessary processing is completed.
To return the original callback to its previous state, preserve the return value and when processing finishes, you must use the preserved value for reset.
Cd Read Sync
Await completion of CdRead. Syntax
int CdReadSync (mode ,*result) int mode;
unsigned char *result;
Argument
mode Await read completion.
result Status storage buffer of command most recently completed.
Explanation
Waits until reading from CdRead() finishes. mode specifies whether to wait for completion of reading, and returns.
Value Contents
0 waits for completing of read and returns
1 determines current status and promptly returns
Return value
Returns the values below.
Return value Contents
Positive integer number of sectors remaining
0 Completion
-1 Read error
CdReady
Wait for CD-ROM data to be ready. Syntax
int CdReady (mode,*result) int mode;
unsigned char *result;
Argument
mode Wait until data is prepared.
result Status storage buffer of command most recently completed.
Explanation
Data waits for preparation in the sector buffer. mode specifies whether to wait and return data preparation.
Value Contents
0 data waits until it can be prepared and returns
1 determines current status and promptly returns
Return value
Data preparation status is indicated by the following values:
Return value Meaning
CdlDataReady There is preparation-completed data
CdlDiskError Error detected
CdlNoIntr No preparation-completed data
CdReadyCallback
Define CdReady callback function. Syntax
unsigned long CdReadyCallback (*func) void (*func)();
Argument
func Callback function address Explanation
func defines the callback called when the data is ready. func is called at the point in time when the sector buffer data is determined. If func is set to 0, callback does not occur.
Return value
Address of previously set callback Remarks
While func is executing,subsequent drawing complete interrupts are masked. Therefore func needs to return as soon as the necessary processing is completed.
To return the original callback to its previous state, preserve the return value and when processing finishes, you must use the preserved value for reset.
CdSearchFile
Get location and size from CD-ROM file name. Syntax
CdlFILE *CdSearchFile (*fp,*name)
CdlFILE *fp; char *name;
Argument
fp CD-ROM file structure pointer
char File name
Explanation
Determine the absolute location (minutes and seconds, sectors)from the file name in the CD-ROM. Result is stored in fp.
Return value
Failure returns 0. Anything else returns a pointer to the CD-ROM file structure. Remarks
File name must be specified as an absolute path.
Location information on files in the same directory as files set with fp is cached in memory. Therefore if CdSearchFile() is performed on files in the same directory, access is fast the second and subsequent times.
CD-ROM Library (libcd) Functions 99
CdSetDebug
Set debug level. Syntax
int CdSetDebug (level) int level;
Argument
level Debug level Explanation
Set debug level for CD-ROM subsystem. The possible values of level are shown below.
Value Contents
0 No checks performed
1 Check primitive commands
2 Print execution status of primitive commands
Return value
Previously set debug mode.
Runtime Library Release 3.0
CdSync
Wait for completion of CD-ROM command. Syntax
int CdSync (mode,*result) int mode;
unsigned char *result;
Argument
mode Waits for command termination
result Status storage buffer of command most recently completed.
Explanation
Waits for actual termination of a command issued by CdControl(). mode specifies whether to wait and return command termination.
Value Contents
0 waits for command termination and returns
1 determines current status and promptly returns
Return value
Command execution status is indicated by the following values:
Return value Meaning
CdlComplete Command complete
CdlDiskError Error detected
CdlNoIntr Command is being executed
CD-ROM Library (libcd) Functions 101
CdSyncCallback
Define CdSync callback function. Syntax
unsigned long CdSyncCallback (*func) void (*func)() ;
Argument
func Callback function address
Explanation
func defines the callback called when command completes. If func is set to 0, callback does not occur.
Return value
Address of previously set callback. Remarks
While func is executing, subsequent drawing complete interrupts are masked. Therefore func needs to return as soon as the necessary processing is completed.
To return the original callback to its previous state, preserve the return value and when processing finishes, you must use the preserved value for reset.
Chapter 3
CD Streaming (libcd)
This chapter describes structures defined in the CD-ROM library (libcd) and the available functions. "libcd" assists in the continous retrieval of stored realtime data such as animation, sound, and vertex information from large capacity media like CD-ROMs.
Chapter 3: CD Streaming (libcd) Table of Contents
Structures
StHEADER
107
Functions
StCdInterrupt
108
StClearRing
109
StFreeRing
110
StGetNext
111
StSetChannel
111
StSetEmulate
113
StSetMask
114
StSetRing
115
StSetStream
116
St U n Set Rin g
116
CD Streaming (libcd) Structures 107
StHEADER
Sector header. Structure
typedef struct {
unsigned short id;
unsigned short type;
unsigned short secCount; unsigned short nSectors; unsigned long frameCount; unsigned long frameSize; unsigned short width;
unsigned short height;
} StHEADER;
Members
id
type secCount nSectors frameCount frameSize width
height
Explanation
Reserved by system
Data type (always 0x0 160)
Sector offset within 1 frame
Number of sectors comprising one frame Movie absolute frame number
Movie data size (in long words)
Movie horizontal size
Movie vertical size
Movie sector header.
If a header obtained with StGetNext() is written to this structure, the various items of information can be accessed through the structure members.
For details of information structure, refer to "Data Format" in volume 1.
108 CD Streaming (libcd) Functions
StCdInterrupt
Handler for interrupts from CD-ROM (internal function). Syntax
void StCdInterrupt (void)
Arguments None.
Explanation
This function is normally hooked to CD-ROM interrupts by StStartStream() and StStartEmulation(), and it is called automatically at interrupt generation, so it does not need to be called by the user. When used in24-bit mode, the interrupt just sets StCdInterFlag, so this function needs to be called by the application.
Return value None.
Runtime Library Release 3.0
CD Streaming (libcd) Functions 109
StClearRing
Flush ring buffer. Syntax
void StClearRing (void)
Arguments None.
Explanation
Flush ring buffer. Flushing the ring buffer when jumping tracks and so forth is effective in preventing excess frames from showing up.
Return value None.
Runtime Library Release 3.0
110 CD Streaming (libcd) Functions
StFreeRing
Release ring buffer. Syntax
unsigned long StFreeRing (base) unsigned long *base;
Arguments
base Starting address of user data area of released 1 frame
Explanation
The area obtained by StGetNext() is locked. StFreeRing() releases this locked region. The released region is the region for one frame's worth of data which is used as the base for the starting address of the user region. Linked sector header regions are also released.
If a region locked by StGetNext() is not released when its use ends, the ring buffer will soon overflow and streaming will come to a halt.
Return value
A return value of 0 indicates successful release. 1 denotes a failed release (for example, trying to release something that wasn't locked).
StGetNext
Get one frame of data. Syntax
unsigned long StGetNext (addr,header) unsigned long *addr;
unsigned long *header;
Arguments
addr User data region starting address for 1 frame of retrieved data
header Sector header region starting address for 1 frame of retrieved data
Explanation
This function gets one frame of ring buffer data. When StGetNext() is called, if the next 1 frame of data is ready in the ring buffer, the starting addresses of the user data and the sector header are stored in addr and header, and 0 is returned.
If the next frame of data is not ready, 1 is returned.
The region the data is taken from is locked until StFreeRing() is called, so it cannot be destroyed by new data.
The data region has a continuous address and the ring buffer does not loop in mid-data.
Return value
If 1 FRAME of data is taken from the ring buffer, 0 is returned. If it is not ready, 1 is returned.
112 CD Streaming (libcd) Functions
StSetChannel
Set streaming channel. Syntax
int StSetChannel (ch) unsigned long ch
Arguments
ch Playback channel Explanation
Sets streaming playback channel. ch sets the channel (0-31). The channel stores the STR data at the authoring level.
Return value
If the channel is set, return 0; otherwise, return 1.
Runtime Library Release 3.0
StSetEmulate
Set parameters for streaming emulation. Syntax
void StStartEmulate(addr,loc,start_frame,end_frame,f1,f 2) unsigned long *addr,loc,start_frame,end_frame;
int (*func1)(), (*func2)();
Arguments
addr loc start_frame end_frame func1 func2
Explanation
Emulation data starting address
Set color mode
Streaming start frame
Streaming end frame
Address of function called back for each 1 frame of data Address of function called back when streaming ends
Sets parameters for streaming emulation. Emulation means that CD-ROM data is put into memory in advance and data streaming is performed from memory, not from the CD-ROM, which provides only data-ready timing. In streaming emulation, play time is limited to a few seconds because of limits in memory capacity. Still, emulation is easier than using a CD-ROM emulator.
STR-format data needs to be loaded to addr in advance. See StSetStream() for details on other arguments. (loc is the same as mode.)
Return value None.
114 CD Streaming (libcd) Functions
StSetMask
Controls the playing of streaming. Syntax
void StSetMask (mask,start,end) unsigned long mask,start,end;
Arguments
mask Streaming play on/off
start StSetStream() start_frame
end StSetStream() end_frame
Explanation
Turns streaming play ON/OFF. There is no mechanical timing lag compared to CD-ROM drive pause and playback, and instant ON/OFF is possible.
Values that can be specified in mask are as follows.
Value Contents
0 play
1 pause
Resets start and end of SetStream() trigger frame values.
Return value None.
Runtime Library Release 3.0
StSetRing
Set ring buffer. Syntax
void StSetRing (ring_addr,ring_size) unsigned long *ring_addr;
unsigned long ring_size;
Arguments
ring_addr Ring buffer starting address
ring_size Ring buffer size (in sectors)
Explanation
Secure a ring buffer of a size specified by ring_size from ring_addr.
To use the Streaming Library, you must first call it.
Because only form-1 CD-ROM sectors are supported at is 2048 bytes.
It is necessary to secure this area in the main program.
an address specified by
present, one sector of data area
Return value None.
StSetStream
Set streaming parameters. Syntax
void StSetStream (mode,start_frame,end_frame,f1,f2) unsigned long mode,start_frame,end_frame;
int (*func1)(), (*func2)();
Arguments
mode start_frame end_frame
func 1: func2:
Explanation
Set color mode
Frame to start streaming
Frame to end streaming
Address of function called back for each 1 FRAME of data. Address of function called back when streaming ends.
Sets streaming parameters.
The specified values and contents of each argument are as follows: a) mode
Sets color mode. The values you may specify are as follows.
Value Contents
0 16 bit mode
1 24 bit mode
b) start_frame Specifies the frame number (stored in STR data) that starts streaming.
Streaming will not begin until this Streaming Library frame is reached. If you want to play the data starting in the middle, you must specify an appropriate frame number. When you specify 0, streaming commences no matter what the frame number is.
c) end_frame
Specifies the frame number (stored in STR data) that ends streaming. Streaming ends when this Streaming Library frame is reached. If you specify a number large enough, it plays the CD-ROM data to the end and termintes. When you specify 0, all the data is stored in the ring buffer and the function automatically terminates. This takes a large ring buffer, and the function is successful when streaming is from memory.
d) func1
Generates one frame's worth of data and specifies the address of the callback function called.
e) func2
Sets the address of the callback function called at the time streaming is completed. Return value
None.
Remarks
To correctly exit from a streaming application, the end of streaming should not be set by end_frame. Set end_frame to 0xffffffff, and code an appropriate endpoint from within the loop.
CD Streaming (libcd) Functions 117
StUnSetRing
Release interrupt used by streaming library. Syntax
void StUnSetRing (void)
Arguments None.
Explanation
Release two interrupt functions CdDataCallback() and CdReadyCallback() hooked by CDRead2(CdlModeStream) and return to initial state.
If the streaming library is not used when streaming ends and control transfers to another program, the interrupt hooks which call this function need to be returned to the initial state.
Return value None.
Runtime Library Release 3.0
Chapter 4
Controller Library (libetc)
This chapter describes structures defined in the "libetc" library and their common functions. "libetc" controls callbacks for low-level interrupt processing. Controller functions have been added.
Chapter 4: Controller Library (libetc) Table of Contents
Functions
CheckCallback
123
PadInit
PadRead
124
ResetCallback
126
StopCallback
127
Controller Library (libetc) Functions 123
CheckCallback
Determines whether a program is being executed in a callback.
Syntax
int CheckCallback()
Arguments None.
Explanation
Determines whether a program is being executed in a callback context or in a normal context.
Return value
Normal context returns 0. Callback context returns 1.
124 Controller Library (libetc) Functions
PadInit
Initializes a controller.
Syntax
void PadInit (mode)
Arguments
mode Controller type
Explanation
This function initializes connected controllers. The type of controller is specified by mode.
Return value
None.
Remarks
At present, only type 0 controllers are supported.
Controller Library (libetc) Functions 125
PadRead
Read data from the controller. Syntax
long PadRead (id) unsigned short id;
Argument
id Controller type Explanation
This function reads data from the controller specified by id. id is the controller number.
Return value
The return value is controller button status.
Remarks
Currently, id has no meaning.
Runtime Library Release 3.0
126 Controller Library (libetc) Functions
ResetCallback
Initializes all callbacks. Syntax
void ResetCallback()
Arguments None.
Explanation
Initializes all system callbacks. Sets all callback functions to 0 (unregistered), and after securing the interrupt context stack, sets up the environment for accepting interrupts.
Return value None.
Remarks
ResetCallback() must be called after program boot, before any other processing is performed.
The environment initialized by ResetCallback() will remain valid until StopCallback() is called.
It is acceptable to continuously call ResetCallback() without StopCallback(). However, the second and subsequent calls will be ignored.
Runtime Library Release 3.0
Controller Library (libetc) Functions 127
StopCallback
Stops all callbacks. Syntax
void StopCallback()
Arguments None.
Explanation
Stops all system callbacks.
Return value None
Remarks
Before terminating programs, StopCallback() must be called to disable all interrupts.
Runtime Library Release 3.0
128 Controller Library (libetc) Functions
Chapter 5
Basic Graphics Library (libgpu)
This chapter describes the structures and macro instructions defined in the fundamental graphics library, and available functions. "libgpu" is a low-level graphics library, closer to hardware. The triangles, squares, lines, and other basic units forming the foundation of 3-dimensional applications are handled with their GPU performance and flexibility intact.
Chapter 5: Basic Graphics Library (libgpu) Table of Contents
Structures
DISPENV
133
DRAW EN V
135
DR_AREA
137
DR_ENV
138
DR_MODE
139
DR_OFFSET
140
DR_TWIN
141
LINE_F2, LINE_F3, LINE_F4
142
LINE_G2, LINE_G3, LINE_G4
143
POLY_F3, POLY_F4
144
POLY_FT3, POLY_FT4
145
POLY_G3, POLY_G4
147
POLY_GT3, POLY_GT4
148
RECT
149
SPRT
150
SPRT_8, SPRT_16
151
TILE
152
TILE_1, TILE_8, TILE_16
153
TIM_IMAGE
154
TMD_PRIM
155
Functions
Add Prim
156
Add Prims
157
addVector
158
CatPrim
159
CheckPrim
160
ClearImage
161
ClearOTag
162
ClearOTagR
163
copyVector
164
DrawOTag
165
DrawSync
166
DrawSyncCallback
167
DumpClut
168
DumpDispEnv
169
DumpDrawEnv
170
DumpOTag
171
DumpTPage
172
FntFlush
173
FntLoad
174
FntOpen
175
FntPrint
176
GetClut
177
GetDispEnv
178
GetDrawEnv
179
GetTPage
180
KanjiFntFlush
181
KanjiFntOpen
182
KanjiFntPrint
183
LoadClut
184
LoadImage
185
LoadTPage
186
MoveImage
187
Next Prim
188
OpenTIM
189
OpenTMD
190
PutDispEnv
191
PutDrawEnv
192
ReadTIM
193
ReadTMD
194
ResetGraph
195
SetDefDispEnv
196
SetDefDrawEnv
197
SetDispMask
198
SetDrawArea
199
SetDrawEnv
200
SetDrawMode
201
SetDrawOffset
202
SetDumpFnt
203
SetGraphDebug
204
SetLineF2, SetLineF3, SetLineF4
205
SetLineG2, SetLineG3, SetLineG4
206
SetPolyF3, SetPolyF4
207
SetPolyFT3, SetPolyFT4
208
SetPolyG3, SetPolyG4
209
SetPolyGT3, SetPolyGT4
210
setRECT
211
setRGB0, setRGB1, setRGB2, setRGB3
212
SetSemiTrans
213
SetShadeTex
214
SetSprt8, SetSprt16, SetSprt
215
SetTexWindow
216
SetTile, SetTile1, SetTile8, SetTile16
217
setUV0, setUV3, setUV4
218
setUVWH
219
setVector
220
setWH
221
setXY0, set XY2, setXY3, setXY4
222
setXYWH
223
StoreImage
224
Term Prim
225
VSync
226
VSyncCallback
227
Display environment. Structure
struct DISPENV {
RECT disp;
RECT screen;
unsigned char isinter;
unsigned char isrgb24; unsigned char pad0, pad1; };
Members
disp This is the display area within the frame buffer. Specify the width one of the following: 256, 320, 368, 512, 640. Specify the area or 280.
Output screen display area. The screen area is calculated without value of disp, using the standard monitor screen upper left-hand and lower right-hand point y (256,240).
This is the interlace mode flag.
0 non-interlace
1 interlace
This is the 24-bit mode flag.
0 16-bit mode
1 24-bit mode Reserved by system.
Explanation
Specifies display parameters for screen display mode, frame buffer display value, and so on.
The following member names can be shared by primitives.
Member Type Content
tag unsigned long Hooking to next primitive (reserved)
code
r0, g0, b0
r1, g1, b1
r2, g2, b2
r3, g3, b3 x0, y0
x1, y1
x2, y2
x3, y3 u0, v0
u1, v1
u2, v2
u3, v3 tpage
unsigned char Primitive ID (reserved unsigned char Brightness values
unsigned short Vertex coordinates
unsigned short Texture coordinates
unsigned char Texture page ID
clut unsigned short CLUT ID (color-look-up-
table for 4 bit/8 bit mode only)
Display Mode Table
Drawing environment. Structure
struct DRAWENV {
RECT clip;
short ofs;[2]
RECT tw;
unsigned short tpage; unsigned char dtd;
unsigned char dfe;
unsigned char isbg;
unsigned char r0, g0, b0; DR ENV dr_env;
};
Members
clip Drawing area. Drawing is restricted to a short area specified by clip. Drawing is not performed outside the clipping area. (See Remarks 1, below.)
ofs Offset. Drawing commands use the added values of (ofs[0], ofs[1]) as an address and draw in the frame buffer. (See Remarks 2.)
tw Texture window. The short area texture pattern restricted by the texture page tw is used repeatedly.
tpage Initial value of texture page
dtd Dithering processing flag
0 off
1 on
dfe Drawing to display area flag
0: drawing to display area is blocked
1: drawing to display area is permitted
isbg Drawing area clear flag.
0: OFF 1: ON
Does not clear drawing area when drawing environment is set.
Paints entire clip area with brightness values (r0, g0, b0) when drawing
environment is set.
r0, g0, b0 Background color. Valid only when isbg is 1
dr env System reserved
Explanation
This sets basic drawing parameters, such as drawing offset and drawing clip area.
Remarks
*1 Graphics can be actually drawn in an area (0, 0) - (1023, 511) in the graphic space.
*2 The offset value and the address after the addition of the offset are wrapped around at (-1024, -1024) - (1023, 1023).
*3 The values which may be specified for the texture window are restricted to the following combinations:
tw.w, tw.x
tw.w 0 (=256) 16 32 64 128
tw.x 0 multiple multiple multiple multiple of 16
of 32 of 64 of 128
tw.h, tw.y
tw.h 0 (=256) 16 32 64 128
tw.y 0 multiple multiple multiple multiple of 16
of 32 of 64 of 128
Drawing area change primitives.
Structure
struct DR_ENV {
unsigned long tag;
unsigned long code[2]; };
Members
tag Hook to the next primitive (reserved)
code Primitive ID
Explanation
The DR AREA primitive modifies only the drawing area under the current drawing environment during drawing. The SetDrawArea() function is used to set contents.
DR_ENV
Drawing environment modification primitive. Structure
struct DR_ENV {
unsigned long *tag;
unsigned long code[15]; };
Members
tag Pointer to next primitive
code Reserved by system
Explanation
During drawing, this primitive forcibly changes the drawing environment from the drawing environment structure DRAWENV to the new drawing environment. The details can be set using the SetDrawEnv() function. Note that the definition of DR_ENV is different from that of DRAWENV.
Remarks
Specify the drawing environment using "DRAWENV", and the display environment using "DISPENV". However, parts of "DRAWENV" can be changed while drawing, using the "DR_MODE" primitive. The whole of "DRAWENV" can be changed while drawing, using the "DR_ENV" primitive.
Basic Graphics Library (libgpu) Structures 139
DR_MODE
Drawing mode modification primitive. Structure
typedef struct {
unsigned long tag;
unsigned long code[2]; } DR_MODE;
Members
tag Hook for next primitive (reserved)
code Primitive ID
Explanation
This primitive changes part (such as the current texture page or texture window) of the current drawing environment during drawing. Set the contents using the function "SetDrawMode()".
Runtime Library Release 3.0
140 Basic Graphics Library (libgpu) Structures
DR_OFFSET
Drawing offset modification primitives. Structure
typedef struct {
unsigned long tag;
unsigned long code[2]; } DR_OFFSET;
Members
tag Hook to the next primitive (reserved)
code Primitive ID
Explanation
OFFSET primitive modifies only the drawing offset under the current drawing environment during drawing. The SetDrawOffset() function is used to set contents.
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Structures 141
DR_TWIN
Texture window change primitives. Structure
typedef struct {
unsigned long *tag; unsigned long code[2]; } DR_TWIN;
Members
tag Hook to the next primitive (reserved)
code Primitive ID
Explanation
The DR_TWIN primitive modifies only the texture window under the current drawing environment during drawing. The SetDrawTexWindow() function is used to set contents.
Runtime Library Release 3.0
LINE_F2, LINE_F3, LINE_F4
Flat non-connecting line/ 1 connecting line/ 2 connecting lines. Structure
struct LINE_F2 { unsigned long *tag;
unsigned char r0, g0, b0, code;
short x0, y0; short x1, y1; };
struct LINE_F3 { unsigned long *tag;
unsigned char r0, g0, b0, code;
short x0, y0; short x1, y1; short x2, y2;
};
struct LINE_F4 { unsigned long *tag;
unsigned char r0, g0, b0, code;
short x0, y0; short x1, y1; short x2, y2; short x3, y3;
};
Member
tag
code
r0, g0, b0 x*, y*
Explanation
Hook to the next primitive (reserved) Primitive ID
Brightness value of straight line
Coordinate of vertices forming straight line
LINE_F2 draws a non-connecting line linking (x0, y0) - (x1, (r0, g0, b0).
LINE_F3 draws 2 connecting lines linking (x0, y0) - (x1, y1) value (r0, g0, b0).
LINE_F4 draws 3 connecting lines linking (x0, y0) - (x1, y1) brightness value (r0, g0, b0).
y1) with the brightness value
- (x2, y2) with the brightness
- (x2, y2) - (x3, y3), with the
LINE_G2, LINE_G3, LINE_G4
Gouraud-shaded non-connecting line/ 1 connecting line/ 2 connecting lines. Structure
struct LINE_G2 { unsigned long *tag;
unsigned char r0, g0, b0, code;
short x0, y0;
unsigned char r1, g1, b1, p1;
short x1, y1; };
struct LINE_G3 { unsigned long *tag;
unsigned char r0, g0, b0, code;
short x0, y0;
unsigned char r1, g1, b1, p1;
short x1, y1;
unsigned char r2, g2, b2, p2;
short x2, y2; };
struct LINE_G3 { unsigned long *tag;
unsigned char r0, g0, b0, code;
short x0, y0;
unsigned char r1, g1, b1, p1;
short x1, y1;
unsigned char r2, g2, b2, p2;
short x2, y2;
unsigned char r3, g3, b3, p3;
short x3, y3; };
Members
See the List of Members table for DISPENV (p. 133). Explanation
LINE_G2 draws non-connecting lines linking (x0, y0) - (x1, y1) in such a way that their vertices have the brightness values (r0, g0, b0) - (r1, g1, b1), and performs Gouraud shading at the same time.
LINE_G3 draws the connecting lines linking (x0, y0) - (x1, y1)- (x2, y2) in such a way that their vertices have the brightness values (r0, g0, b0) - (r1, g1, b1) - (r2, g2, b2), and performs Gouraud shading at the same time.
LINE_G4 draws connecting lines linking (x0, y0) - (x1, y1)- (x2, y2) - (x3, y3) in such a way that their vertices have the brightness values (r0, g0, b0) - (r1, g1, b1) - (r2, g2, b2) - (r3, g3, b3) and performs Gouraud shading at the same time.
POLY_F3, POLY_F4
Flat shaded triangle and quadrilateral primitives. Structure
struct POLY _F3 { unsigned long *tag;
unsigned char r0, g0, b0, code;
short x0, y0; short x1, y1; short x2, y2;
};
struct POLY_F4 { unsigned long *tag;
unsigned char r0, g0, b0, code;
short x0, y0; short x1, y1; short x2, y2; short x3, y3;
};
Members
See the List of Members table for DISPENV (p. 133). Explanation
POLY_F3 paints the area demarcated by (x0, y0) - (x1, y1) - (x2, y2) using brightness values of (ro, g0, b0).
POLY_F4 paints the area demarcated by (x0, y0) - (x1, y1) - (x3, y3) - (x2, y2) using brightness values of (ro, g0, b0).
The address where a picture is actually drawn is equivalent to the value of x0-x3 to which the offset value specified by the drawing environment is added. What is drawn is clipped according to the clip area (quadrilateral area) specified by the drawing environment.
Again, if the polygon has a width greater than 1024 and a height greater than 512, all of it will be clipped.
In the case of a quadrilateral primitive, the corners are specified in the order shown below. The same applies to designation of (u, v) for a texture map rectangle, and (r, g, b) for a Gouraud shaded rectangle.
(x0,y0)
(x2,y2) (x3,y3)
POLY_FT3, POLY_FT4
Flat texture mapped triangle and quadrilateral primitives. Structure
struct POLY_FT3 {
unsigned long *tag;
unsigned char r0, g0, b0, code;
short x0, y0;
unsigned char u0, v0; unsigned short clut; short x1, y1;
unsigned char u1, v1; unsigned short tpage; short x2, y2;
unsigned char u2, v2; unsigned short pad1; };
struct POLY_FT4 {
unsigned long *tag;
unsigned char r0, g0, b0, code;
short x0, y0;
unsigned char u0, v0; unsigned short clut; short x1, y1;
unsigned char u1, v1; unsigned short tpage; short x2, y2;
unsigned char u2, v2; unsigned short pad1; short x3, y3;
unsigned char u3, v3; unsigned short pad2; };
Members
See the List of Members table for DISPENV (p. 133). pad1 and pad2 are reserved by the system.
Explanation
POLY_FT3 draws an area demarcated by (x0, y0) - (x1, y1) - (x2, y2) while mapping the area demarcated by (u0, v0) - (u1, v1) - (u2, v2) in the texture pattern on the texture page tpage.
POLY_FT4 draws an area demarcated by (x0, y0) - (x1, y1) - (x3, y3) - (x2, y2) while mapping the area demarcated by (u0, v0) - (u1, v1) - (u3, v3) - (u2, v2) in the texture pattern on the texture page tpage.
The actual brightness value for drawn graphics are obtained by multiplying the brightness values from the texture pattern by the brightness values given by r0, g0, b0.
The texture coordinates are the coordinates (0 to 255) inside the texture page which correspond to the vertices of the triangle to be drawn. if the texture mode is 4-bit or 8-bit, the texture coordinates and the actual frame buffer address will not be 1-to-1.
Texture page ID is given to tpage. Using the GetTPage() function, the texture page ID is obtained from the address (x, y) of the buffer frame where the texture page is located.
A texture using CLUT gives CLUT ID to be set in clut. Using the GetClut() function, CLUT ID is obtained from the address (x, y) of the frame buffer where CLUT is located.
The size of the texture page which can be used by one drawing command is 256 x 256. One primitive can only use one texture page.
POLY_G3, POLY_G4
Gouraudshaded triangle and quadrilateral primitives. Structure
struct POLY_G3 { unsigned long *tag;
unsigned char r0, g0, b0, code;
short x0, y0;
unsigned char r1, g1, b1, pad1;
short x1, y1;
unsigned char r2, g2, b2, pad2;
short x2, y2; };
struct POLY_G4 { unsigned long *tag;
unsigned char r0, g0, b0, code;
short x0, y0;
unsigned char r1, g1, b1, pad1;
short x1, y1;
unsigned char r2, g2, b2, pad2;
short x2, y2;
unsigned char r3, g3, b3, pad3;
short x3, y3; };
Members
See the List of Members table for DISPENV (p. 133). pad 1, pad2, and pad3 are reserved by the system.
Explanation
When drawing while performing Gouraud shading, POLY_G3 paints the area demarcated by (x0, y0) - (x1, y1) - (x2, y2) so that vertex brightness values may be set to (r0, g0, b0) - (r1, g1, b1) - (r2, g2, b2).
When drawing while performing Gouraud shading, POLY_G4 paints the area demarcated by (x0, y0) - (x1, y1) - (x3, y3) - (x2, y2) so that vertex brightness may be set to (r0, g0, b0) - (r1, g1, b1) - (r3, g3, b3) - (r2, g2, b2).
The brightness of triangle-internal pixels is calculated by performing linear interpolation of the brightness values of the three vertices. (Gouraud shading).
POLY_GT3, POLY_GT4
Gouraud-shaded texture mapped triangle and quadrilateral primitives. Structure
struct POLY_GT3 {
unsigned long *tag;
unsigned char r0, g0, b0, code;
short x0, y0;
unsigned char u0, v0; unsigned short clut;
unsigned char r1, g1, b1, pad1;
short x1, y1;
unsigned char u1, v1; unsigned short tpage; unsigned char r2, g2, b2, pad2;
short x2, y2;
unsigned char u2, v2; unsigned char pad3; };
struct POLY_GT4 {
unsigned long *tag;
unsigned char r0, g0, b0, code;
short x0, y0;
unsigned char u0, v0; unsigned short clut; unsigned char r1, g1, b1, p1;
short x1, y1;
unsigned char u1, v1; unsigned short tpage; unsigned char r2, g2, b2, p2;
short x2, y2;
unsigned char u2, v2; unsigned char pad2; unsigned char r3, g3, b3, p3;
short x3, y3;
unsigned char u3, v3; unsigned char pad3; };
Members
See the List of Members table for DISPENV (p. 133). pad1, pad2, pad3 and pad4 are reserved by the system.
Explanation
POLY_GT3 draws a triangle performing texture mapping and Gouraud shading simultaneously.
POLY_GT4 draws a quadrilateral performing texture mapping and Gouraud shading simultaneously.
The actual brightness values for the picture are equal to the brightness values obtained from the texture pattern multiplied by the brightness values calculated by Gouraud shading.
Basic Graphics Library (libgpu) Structures 149
RECT
Frame buffer rectangular area. Structure
struct RECT {
short x, y;
short w, h; };
Members
x, y Top left coordinates of the rectangular area
w, h Width and height of the rectangular area
Explanation
This function specifies the area of the frame buffer to be accessed. Neither negative values, nor values exceeding the size of the frame buffer (1024 x 512) may be specified.
Runtime Library Release 3.0
150 Basic Graphics Library (libgpu) Structures
SPRT
Sprite of any desired size. Structure
struct SPRT {
unsigned long *tag;
unsigned char r0, g0, b0, code;
short x0, y0;
unsigned char u0, v0; unsigned short clut; short w, h;
}; Members
tag
r0, g0, b0 code
x0, y0
u0, v0
clut w, h
Explanation
Hook to next primitive (reserved)
Brightness values for sprite
Primitive code (reserved)
Position of sprite (top right coordinate)
Position of sprite texture within the texture page (top right coordinate). u0 should be an even number.
CLUT ID used (for 4-bit/8-bit mode only).
Width and height of sprite. w is an even number.
This draws a rectangular area with texture mapping. Drawing speed is faster than POLY_FT4 primitive.
Remarks
Only even numbers can be specified for u0 and w.
Because the sprite primitive has no member tpage, the texture page specified in the current drawing environment (current texture page) is used.
Basic Graphics Library (libgpu) Structures 151
SPRT_8, SPRT_16
8 x 8 and 16 x 16 fixed size Sprite. Structure
struct SPRT_1 6 {
unsigned long *tag;
unsigned char r0, g0, b0, code;
short x0, y0;
unsigned char u0, v0; unsigned short clut; };
struct SPRT_8 {
unsigned long *tag;
unsigned char r0, g0, b0, code;
short x0, y0;
unsigned char u0, v0; unsigned short clut; };
Members
See SPRT structure (p. Error! Bookmark not defined.). Explanation
This primitive draws a sprite with a fixed size of 8 x 8 or 16 x 16. The same result can be obtained if 8 and 16 are designated as the w and h members for the SPRT structure.
Runtime Library Release 3.0
152 Basic Graphics Library (libgpu) Structures
TILE
Tile Sprite of any desired size. Structure
struct TILE {
unsigned long *tag;
unsigned char r0, g0, b0, code; short x0, y0;
short w, h;
};
Members
See SPRT structure (p. 150). Explanation
The rectangle area is drawn using the same brightness values (r0, g0, b0). This is faster than the POLY_F4 primitive.
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Structures 153
TILE_1, TILE_8, TILE_16
1 x 1, 8 x 8, 16 x 16 fixed size tile Sprite. Structure
struct TILE_16 {
unsigned long *tag;
unsigned char r0, g0, b0, code; short x0, y0;
};
struct TILE_8{
unsigned long *tag;
unsigned char r0, g0, b0, code; short x0, y0;
};
struct TILE_1 {
unsigned long *tag;
unsigned char r0, g0, b0, code; short x0, y0;
};
Members
See SPRT structure (p. 150). Explanation
This primitive paints out an 8x8 or 16x16 area with the brightness value (r0, g0, b0). The effect is the same as when the values "8" and "16" are specified, respectively, for the members w and h of a TILE structure.
Runtime Library Release 3.0
154 Basic Graphics Library (libgpu) Structures
TIM_IMAGE
TIM format image data header. Structure
typedef struct { unsigned long RECT *crect; unsigned long RECT *prect; unsigned long
} TIM_IMAGE;
Members
mode crect caddr prect paddr
Explanation
TIM data header information acquired by the ReadTIM() function.
Remarks
crect and caddr are assigned a value of zero for TIM having no CULT.
Basic Graphics Library (libgpu) Structures 155
TMD_PRIM
TMD format model data header. Structure
typedef struct {
unsigned long id;
unsigned charr0, g0, b0, p0; unsigned char r1, g1, b1, p1; unsigned charr2, g2, b2, p2; unsigned charr3, g3, b3, p3; unsigned short tpage, clut;
unsigned charu0, v0, u1, v1; unsigned char u2, v2, u3, v3; SVECTOR x0, x1, x2, x3;
SVECTOR n0, n1, n2, n3; SVECTOR *v_ofs;
SVECTOR *n_ofs;
unsigned short vert0, vert1; unsigned short vert2, vert3; unsigned short norm0, norm1; unsigned short norm2, norm3;
} TMD_PRIM;
Members
id
r0, g0, b0,...r3, g3, b3 clut
tpage
u0, v0, u1, v1..u3, v3 x0, x1, x2, x3
n0, n1, n2, n3
v_ofs
n_ofs
vert0, vert1.. vert3
norm0, norm 1..norm3
TMD primitive ID
Brightness values of the vertices of a primitive
CLUT ID used by a primitive Texture page used by a primitive
Texture coordinates of the vertices of a primitive Three-dimensional coordinates of a primitive
Normal coordinates of a primitive Start coordinates of a vertex array Start coordinates of a normal array Offset to a vertex array
Offset to a vertex array
Explanation
Information on primitives constituting a TMD object. The information is acquired using the ReadTMD() function. x0, x1, x3, n0, n1,n3 are used for an independent vertex model. v_ofs, n_ofs and vert0,. .vert3, norm0.. .norm3 are used for a common vertex model.
Remarks
Some members have no meaning depending on the TMD primitive type.
AddPrim
Adding a primitive to OT table. Syntax
void Add Prim (ot, p) unsigned long *ot; unsigned long *p;
Arguments
ot Ordering table entry
p Registered primitive start address
Explanation
This function registers a primitive beginning with the address *p to the OT entry *ot in OT table. ot is an ordering table or pointer to another primitive.
Return value None.
Remarks
The same primitive may not be registered more than once in different entries of one OT.
Basic Graphics Library (libgpu) Functions 157
AddPrims
Registers the primitives to be drawn in OT. Syntax
void Add Prims (ot, ps, pe) unsigned long *ot; unsigned long*ps; unsigned long *pe;
Arguments
ot OT entry
ps Address of top primitive in primitive list
pe Address of last primitive in primitive list
Explanation
This function registers the primitive list starting at *ps in the entry *ot in the OT. The primitive is a list of primitives connected by AddPrim(), or a list created by the local ordering table.
Return value None.
Runtime Library Release 3.0
add Vector
Adds vectors.
Syntax addVector (v0, v1)
Arguments v0, v1 Pointers to vectors
Explanation
This macro adds v1 to the vector v0, and stores the result in v0.
Return value None.
Remarks
addVector() is a macro, so there is no dependence on the vector type.
Basic Graphics Library (libgpu) Functions 159
CatPrim
Concatenates a primitive list. Syntax
unsigned long *CatPrim (p0, p1) unsigned long *p0, *p1;
Arguments
p0, pl Start addresses of primitive to be concatenated Explanation
This function links the primitive p1 to the primitive p0.
Return value
Start address of p0. Remarks
AddPrim() adds a primitive to a primitive list. CatPrim() simply concatenates two primitives.
Runtime Library Release 3.0
160 Basic Graphics Library (libgpu) Functions
CheckPrim
Checking a value of each member of a primitive for coordination. Syntax
long CheckPrim (s, p) char *s;
unsigned long *p;
Arguments
s Optimal character string
p Primitive start address
Explanation
This function checks the conformity of each member of the primitive, as far as possible. If the contents do not conform, it prints the primitive continued in character string s. It does not correct the content.
Return value
Normal returns 0. Content does not match returns -1.
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Functions 161
ClearImage
Clears Frame Buffer at high speed. Syntax
int ClearImage (recp, r, g, b) RECT *recp;
unsigned char r, g, b;
Arguments
recp Rectangular area to be cleared
r, g, b Pixel values to be used for clearing
Explanation
Clears a rectangular area inside the Frame Buffer specified by recp at brightness values indicated by (r, g, b).
Return value
Number in the queue Remarks
Because this is a non-blocking function, the end of actual transfer must be detected using DrawSync(). The drawing area will not be affected by the drawing environment (clip/offset).
Runtime Library Release 3.0
162 Basic Graphics Library (libgpu) Functions
ClearOTag
Initializes OTs. Syntax
unsigned long *ClearOTag (ot, n) unsigned long *ot;
int n;
Arguments
ot OT starting pointer
n Number of entries in OT
Explanation
This function generates n + 1.
Return value None.
Remarks
number of OTs having the format of NextPrim (ot + i) == ot + i
When you want to execute the OT initialized by "ClearOTag()", execute "DrawOTag (ot)".
Basic Graphics Library (libgpu) Functions 163
ClearOTag R
Initializes reverse-order OT. Syntax
void ClearOTagR (ot, n) unsigned long *ot;
long n;
Arguments
ot Head pointer of OT
n Number of entries in OT
Explanation
This function generates n number of reverse-order OTs having the format of NextPrim (ot + i) == ot + i - 1.
Return value None.
Remarks
When you want to execute the OT initialized by"ClearOTagR()", execute "DrawOTag (ot+n-1)".
164 Basic Graphics Library (libgpu) Functions
copyVector
Copies vectors. Syntax
copyVector (vo,v1) Arguments
vo,v1 Vector pointer
Explanation Copies vector v0 to v1.
Remarks
copyVector is a macro, so there is no dependence on the vector type.
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Functions 165
D rawOTag
Drawing primitives registered in OT. Syntax
void DrawOTag (ot) unsigned long *ot;
Arguments
ot OT starting pointer Explanation
This function executes the primitives registered in the OT. Remarks
DrawOTag() is a non-block function. Therefore, termination of transfer must be detected using DrawSync().
Runtime Library Release 3.0
166 Basic Graphics Library (libgpu) Functions
DrawSync
Wait for all drawing to terminate. Syntax
long DrawSync (mode) long mode;
Arguments
The values which can be specified for mode are shown below.
Value Content
0 Wait for the termination of all non-block functions registered in the queue.
1 Find out and return the number of positions in the current queue.
Explanation
This function waits for drawing to terminate. Return value
The Return value is the number of positions in the execution queue. Remarks
If drawing takes an exceptionally long time (approximately 8 VSync) to complete, a time-out is generated, and drawing is automatically reset. In that case, the application will have a loop like the one below.
While ( DrawSync(1) != 0);
Basic Graphics Library (libgpu) Functions 167
DrawSyncCallback
Defining drawing synchronization callback function. Syntax
void DrawSyncCallback (func) void (*func)();
Arguments
func Callback function Explanation
This defines the callback when drawing is terminated. When all the requests registered in the queue have terminated, the function func is called. If "0" has been specified in func, the callback is not issued.
Return value None.
Remarks
Inside func, subsequent draw termination interrupts are masked. Accordingly, a return must be carried out as soon as func has terminated the necessary processing.
168 Basic Graphics Library (libgpu) Functions
DumpClut
Printing contents of "clut" member of primitive. Syntax
void DumpClut (clut) unsigned short clut;
Arguments
clut CLUT ID
Explanation
This function prints the CLUT ID contents.
Return value None.
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Functions 169
DumpDispEnv
Printing contents of display environment Structure. Syntax
void DumpDispEnv (env) DISPENV *env;
Arguments
env Display environment Explanation
This function prints the contents of the display environment structure.
Return value None.
Runtime Library Release 3.0
170 Basic Graphics Library (libgpu) Functions
DumpDrawEnv
Printing contents of drawing environment Structure. Syntax
void DumpDrawEnv (env) DRAWENV *env;
Arguments
env Drawing environment Explanation
This function prints the contents of the drawing environment structure.
Return value None.
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Functions 171
DumpOTag
Prints the primitives registered in OT. Syntax
void DumpOTag (ot) unsigned long *ot;
Arguments
ot OT starting pointer Explanation
This function prints the code field of the primitives registered in the OT
Return value None.
Runtime Library Release 3.0
172 Basic Graphics Library (libgpu) Functions
DumpTPage
Prints the contents of "tpage" member of primitive. Syntax
void DumpTPage (tpage) unsiged short tpage;
Arguments tpage texture page ID
Explanation This function prints the contents of the texture page ID.
Return value None.
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Functions 173
FntFlush
Drawing printstream contents. Syntax
unsigned long *FntFlush (id) long id;
Arguments
id Print stream ID
Explanation
This function draws the contents of the print stream in the frame buffer. In fact, it initializes and then draws the sprite primitive list corresponding to the length of the character string.
Return value
The return value is the starting pointer of the primitive list used to perform the drawing. Remarks
After the drawing has been done, the print stream contents are also flushed.
Runtime Library Release 3.0
174 Basic Graphics Library (libgpu) Functions
FntLoad
Transmits font pattern. Syntax
void FntLoad (tx, ty) long tx, ty
Arguments
tx, ty Font pattern frame buffer address Explanation
This function transmits the font pattern for debugging to the frame buffer. It loads the basic font pattern (4-bit texture 256 x 128) into the frame buffer and initializes all the print streams.
Return value None.
Remarks
FntLoad() must always be executed before FntOpen() and FntFlush(). The font area must not clash with the frame buffer area used by the application.
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Functions 175
FntOpen
Opening printstream. Syntax
long FntOpen (x, y, w, h, isbg, n) long x, y;
long w, h;
long isbg;
long n;
Arguments
x, y Display start location
w, h Display area
isbg Automatic clearing of background
0: Clear background to (0, 0, 0) when display is performed
1: Do not clear background to (0, 0, 0) when display is performed. n Maximum number of characters
Explanation
This function opens the stream for on-screen printing. After this, character strings up to n characters long can be drawn in the (x, y)- (x+w, y+h) rectangular area of the frame buffer, using FntPrint(). If "1" is specified for isbg, the background is cleared when a character string is drawn.
Return value
The return value is the stream ID. Remarks
Up to 4 streams can be opened at once. However, once a stream is opened, it cannot be closed until the next time FntLoad() is called.
Runtime Library Release 3.0
176 Basic Graphics Library (libgpu) Functions
FntPrint
Outputting to printstream. Syntax
long FntPrint (id, format, [arg]...) long id;
char *format;
Arguments
id Print stream ID format Print format
Explanation
This function sends the character string s to the print stream using the interface printf().
Return value
The return value is the number of characters in the stream.
Remarks
The character string is not actually displayed until FntFlush() has been executed.
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Functions 177
GetClut
Calculating the value of the "CLUT" member in a primitive. Syntax
unsigned short GetClut (x, y) long x, y;
Arguments
x, y Frame buffer address of CLUT
Explanation This function calculates and returns the texture CLUT ID.
Return value CLUT ID
Return value
The CLUT address is limited to multiples of 64 in the x direction.
Runtime Library Release 3.0
178 Basic Graphics Library (libgpu) Functions
GetDispEnv
Gets the current display environment. Syntax
DISPENV *GetDispEnv (env) DISPENV *env;
Arguments
env Display environment start address Explanation
This function stores the current display environment in the address specified by env.
Return value
The return value is a pointer to the display environment obtained by the function.
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Functions 179
GetDrawEnv
Gets the current drawing environment. Syntax
DRAWENV *GetDrawEnv (env) DRAWENV *env;
Arguments
env Drawing environment start address Explanation
This function stores the current drawing environment in the address specified by env.
Return value
The return value is a pointer to the drawing environment obtained.
Runtime Library Release 3.0
180 Basic Graphics Library (libgpu) Functions
GetTPage
Calculates the value of the member "tpage" in a primitive. Syntax
unsigned short GetTPage (tp, abr, x, y) long tp, abr, x, y;
Arguments
tp Texture mode
0: 4bitCLUT
1: 8bitCLUT
2: 16bitDirect
abr Semi-transparency rate
0: 0.5 x Back + 0.5 x Forward
1: 1 .0 x Back + 1 .0 x Forward
2: 1 .0 x Back - 1 .0 x Forward
3: 1 .0 x Back + 0.25 x Forward
x, y Texture page address
Explanation
This function calculates the texture page ID, and returns it.
The texture page address is limited to a multiple of 64 in the X direction and a multiple of 256 in the Y direction.
The values that may be specified for tp and abr are as follows.
tp Content
0 4-bit CLUT
1 8-bit CLUT
2 16-bit Direct
Content
0.5 x Back + 0.5 x Forward 1.0 x Back + 1.5 x Forward 1.0 x Back + 0.5 x Forward 1.0 x Back + -1.0 x Forward
Return value Texture page ID.
Remarks
The semitransparent rate is also effective for polygons on which texture mapping is not performed.
Basic Graphics Library (libgpu) Functions 181
KanjiFntFlush
Draws the contents of the print stream. Syntax
unsigned long *KanjiFntFlush(id) int id;
Argument
id Print stream ID
Explanation
Renders the contents of a print stream in the frame buffer. A list of polygon primitives corresponding to the length of character string s is initialized for drawing.
Return value
Start pointer of a primitive list used for drawing Remarks
The contents of a print stream are also flushed after the end of drawing.
Runtime Library Release 3.0
182 Basic Graphics Library (libgpu) Functions
Kanj i FntOpen
Open print stream. Syntax
int KanjiFntOpen( x, y, w, h, dx, dy, cx, cy, isbg, n) int x, y, w, h, dx, dy, cx, cy, isbg, n;
Arguments
x, y w, h dx, dy
cx, cy
isbg
n Explanation
Position of starting display
Display area
Kanji font pattern frame buffer address
Kanji clut frame buffer address
Automatic background clear
0 Clears the background to (0, 0, 0) during display.
1 Does not clear the background to (0, 0, 0) during display. Maximum number of characters
This function opens a stream for open screen print. Then, the KanjiFntPrint() function can be used to render a character string composed of up to n characters in the rectangular area of (x, y) and (x+w, y+h) on the frame buffer. With isbg assigned a value of one, the background is cleared when a character string is rendered.
Return value Stream ID.
Remarks
Up to eight streams can be opened at a time. The opened stream cannot be closed until the KanjiFntLoad() function is called. The kanji font area must not interfere in the frame buffer area used for applications.
Basic Graphics Library (libgpu) Functions 183
KanjiFntPrint
Output print stream. Syntax
int KanjiFntPrint (id, format, [arg]...) int id
char *format
Arguments
id Print stream ID
format Print format
Explanation
Sends SJIS full-size character string s to a print stream via the printf() interface. Return value
Character count in a stream.
Remarks
The kanji code must be SJIS. A character string can be composed of full- and half-size characters. But all characters are converted into full-size characters and displayed. No half-size kana characters are not supported. A character string is actually displayed when the KanjiFntFlush() function is executed.
Runtime Library Release 3.0
184 Basic Graphics Library (libgpu) Functions
LoadClut
Loads texture CLUT. Syntax
unsigned short LoadClut (col, x, y) unsigned long *col;
long x, y;
Arguments
col Texture color start address
x, y Destination start address
Explanation
This function loads texture color data (CLUT) in the main memory area starting at the address col into the frame buffer area starting at the address (x, y), and calculates the ID of the loaded texture CLUT.
Return value
The Return value is the CLUT ID for the loaded CLUT
Remarks
256 palette entries are always transmitted, even in 4-bit mode.
Runtime Library Release 3.0
Transfers data to a frame buffer. Syntax
void LoadImage (recp, p) RECT *recp;
unsigned long *p;
Arguments
recp Destination rectangular area
p Main memory address of source of transmission
Explanation
This function transfers the contents of memory from the address p to the rectangular area in the frame buffer specified by recp.
Return value None.
Remarks
Because LoadImage() is a non-block function, the transmission termination has to be detected by "DrawSync()".
The transfer areas at the source and destination are not affected by the drawing environment (clip, offset). The destination area must be located within a drawable area (0, 0) - (1023, 511).
186 Basic Graphics Library (libgpu) Functions
LoadTPage
Loads a texture page. Syntax
unsigned short LoadTPage (pix, tp, abr, x, y, w, h) unsigned long *pix;
int mt tp, abr, x, y, w, h;
Arguments
Texture pattern start address Transfer texture type Semi-transparency rate Destination frame buffer address Texture pattern size
Explanation
This function loads a texture pattern from the memory area starting at the address tex into the frame buffer area starting at the address (x, y), and calculates the texture page ID for the loaded texture pattern.
Return value
Texture page ID for the loaded texture pattern. Remarks
The texture pattern size is not the actual size of the transfer area in the frame buffer. The texture pattern size is net in pixels.
LoadTPage() starts from within LoadImage()
Transfers data between two frame buffers. Syntax
int MoveImage (rect, x, y) RECT *rect;
int x, y;
Arguments
rect Source rectangular area
x, y Top left extremity of the rectangular area which is the destination of the transmission
Explanation
The rectangular area of the frame buffer specified by rect is transmitted to the rectangular area of the same size which starts at (x, y).
The content at the source is preserved. If the source and destination areas are the same, normal operation is not guaranteed.
Return value
Number in the queue. Remarks
Because MoveImage() is a non-block function, the termination of the transmission has to be detected by DrawSync().
The transfer areas at the source and destination are not affected by the drawing environment (clip, offset). The destination area must be located within a drawable area (0, 0) - (1023, 511).
188 Basic Graphics Library (libgpu) Functions
NextPrim
Gets next primitive in primitive list. Syntax
unsigned long *NextPrim(p) unsigned long *p;
Arguments
p Start address of a primitive
Explanation This function returns a pointer to the next primitive in a primitive list.
Return value
Pointer to the next primitive.
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Functions 189
OpenTIM
Opens TIM data. Syntax
long OpenTIM (addr) unsigned long *addr;
Arguments
addr Main memory address to which the TIM has been loaded Explanation
This function opens the TIM. The TIM information in the TIM opened using ReadTIM() can then be read.
Return value
If it succeeds, "0" is returned. Any other value indicates failure. Remarks
Only one TIM can be opened at a time. An opened TIM is not closed until the next time OpenTIM() is called.
Runtime Library Release 3.0
190 Basic Graphics Library (libgpu) Functions
OpenTMD
Opens TMD data. Syntax
long OpenTMD (tmd, obj_no) unsigned long *tmd;
long obj_no;
Arguments
addr Main memory address to which TMD has been loaded obj_no Object number.
Explanation
This function opens the TMD of the object with the ordinal number obj_no. The primitive information in the TMD opened using ReadTMD can then be read.
Return value
Returns the number of polygons comprising the object as a positive integer. Returns a negative number if it fails.
Remarks
Only one TMD can be opened at a time. An opened TMD is not closed until the next time OpenTMD() is called.
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Functions 191
PutDispEnv
Sets the display environment. Syntax
DISPENV *PutDispEnv (env) DISPENV *env;
Arguments
env Display environment start address Explanation
This function sets a display environment according to information specified by env. The display environment is executed as soon as the function is called.
Return value
This is a pointer to the display environment which has been set. (If the setting failed, the Return value is "0".)
Runtime Library Release 3.0
192 Basic Graphics Library (libgpu) Functions
PutDrawEnv
Sets the drawing environment. Syntax
DRAWENV *PutDrawEnv (env) DRAWENV *env;
Arguments
env Drawing environment start address Explanation
Basic drawing parameters such as the drawing offset and the drawing clip area should be set in accordance with the setting specified in env.
Return value
This is a pointer to the drawing environment which has been set. (If setting failed, the Return value is "0".)
Remarks
The drawing environment specified using "PutDrawEnv()" is effective until the next time "PutDrawEnv()" is executed, or until the "DR_ENV" primitive is executed.
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Functions 193
ReadTI M
Produces TIM header. Syntax
ReadTIM
TIM_IMAGE *ReadTIM (timimg) TIM_IMAGE *timimg
Arguments
timimg TIM_IMAGE structure pointer Explanation
This function picks out one item of TIM header information and stores it in timimg. The contents of the structure TIM_IMAGE are as follows.
Return value
Returns the value of timing if succesful; returns 0 if it fails.
Runtime Library Release 3.0
194 Basic Graphics Library (libgpu) Functions
ReadTM D
Reads contents of TMD primitives. Syntax
TMD_PRIM *ReadTMD (tmdprim) TMD_PRIM *tmdprim;
Arguments
tmdprim Printer for TMD-PRIM structure. Explanation
This function picks out the TMD primitives in order, and stores them in tmdprim. Return value
Returns tmdprim if successful; 0 if fails. Remarks
The TMD type does not carry the restriction that all the members of the structure have to be effective.
Runtime Library Release 3.0
ResetGraph
Initializes drawing engine. Syntax
int ResetGraph (mode) int mode;
Arguments
mode Reset mode Explanation
This function resets the graphic system in mode specified by mode. Possible setting of more are listed below.
Mode
Operation
0
Complete reset. The drawing environment and display environment are
initialized.
1
Cancels the current drawing and flushes the command buffer.
3
Initializes while preserving the display environment only.
Return value None.
196 Basic Graphics Library (libgpu) Functions
SetDefDispEnv
Sets drawing environment structure members in the drawing area. Syntax
DISPENV*SetDispEnv (disp, x, y, w, h) DISPENV *disp;
int x, y;
int w, h;
Arguments
disp Display environment
x, y Upper left corner of display area
w, h Width and height of the display area
Explanation
This function sets drawing environment structure members using the point on the left top of the drawing area, and width and height of the drawing area.
Member
Content
Value
disp
screen
ininter
isrgb24
Display area
screen display area
Interlace flag
24-bit mode flag
(x, y, w, h)
240)
(0,
0
0
0)-(256,
Return value
The return value is the starting pointer of the display environment which has been set. Remarks
SetDefDispEnv() does not change the interior status of the graphics system simply by setting a value for the structure DISPENV. The parameters do not become effective until PutDispEnv() has been called.
SetDefDrawEnv
Setting standard drawing. Syntax
DRAWENV*SetDefDrawEnv (env, x, y, w, h) DRAWENV *env;
int x, y, w, h;
Arguments
draw Drawing environment
x, y Upper left corner of drawing area
w, h Width and height of drawing area
Explanation
This function sets standard drawing environment structure members judging from the point on the left top of the drawing area, and width and height of the drawing area. The default values are listed below.
Member Content Value
Return value
The return value is the starting pointer of the drawing environment which has been set. Remarks
SetDefDrawEnv() does not change the interior status of the graphics system simply by setting a value for the structure DRAWENV. The parameters do not become effective until PutDrawenv() has been called.
198 Basic Graphics Library (libgpu) Functions
SetDispMask
Sets and cancels display mask. Syntax
void SetDispMask (mask) int mask;
Arguments
mask Display mask Explanation
This function puts display mask into the status specified by mask. Any of the following can be designated as mask:
Mask Operation
0 Not displayed on screen
1 Displayed on screen
Return value None.
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Functions 199
Set D rawArea
Initializes the content of drawing area setting primitive. Syntax
void SetDrawArea (p, r) DR_AREA *p;
RECT *r;
Arguments
p Drawing area setting primitive
r Drawing area
Explanation
Initializes the drawing area setting primitive. By using AddPrim() to register an initialized drawing environment change primitive in OT, it is possible to change part of a drawing environment in the middle of drawing.
Return value None.
Runtime Library Release 3.0
200 Basic Graphics Library (libgpu) Functions
SetDrawEnv
Initializes the content of the drawing environment change primitive. Syntax
Explanation
This function initializes the drawing environment change primitive dr_env in one drawing environment env. Add Prim() allows the initialized drawing environment change primitive to change the drawing environment during drawing by registering it in OT.
Return value None.
Remarks
DRAWENV and DR_ENV retain the same information, but they have different expression formats. DRAWENV itself cannot be connected to the primitive list.
When the DR_ENV primitive is executed, the initial drawing environment is destroyed.
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Functions 201
SetDrawMode
Initializes the content of a drawing mode primitive. Syntax
void SetDrawMode (p, dfe, dtd, tpage, tw) DR_MODE *p;
int dfe, dth, tpage;
RECT *tw;
Arguments
p
dfe dtd tpage tw
Drawing mode primitive
Dither processing flag: 0: OFF, 1: ON
Flag for drawing to a display area 0: OFF, 1: ON Texture page
Texture window
Explanation
This function initializes the draw mode primitive. By registering the initialized primitive in OT using AddPrim(), part of the drawing environment can be changed while drawing.
dtd and dfe spcified values are listed below. If "0" is specified in tw, the texture window is not changed.
dtd Action
0 dither processing not performance
1 dither processing performance
dfe Action
0 no drawing in display area
1 drawing in display area
Return value None.
Runtime Library Release 3.0
202 Basic Graphics Library (libgpu) Functions
Set D rawOffset
Initializes the content of drawing offset setting primitive. Syntax
void SetDrawOffset (p, ofs) DR_OFFSET *p;
u_short *ofs;
Arguments
p Drawing offset setting primitive
ofs Drawing offset
Explanation
Initializes the drawing offset primitive. By using AddPrim() to register an initialized drawing environment change primitive in OT, it is possible to change part of a drawing environment in the middle of drawing.
Return value None.
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Functions 203
SetDumpFnt
Defines stream for onscreen dump. Syntax
void SetDumpFnt (id) long id;
Arguments
id Print stream ID
Explanation
This function sets the print stream for debug printing. The output of the debug printing functions can then be carried out in relation to the stream specified in id.
Return value None.
Remarks
The actual display is executed by the FntFlush() function.
Runtime Library Release 3.0
204 Basic Graphics Library (libgpu) Functions
SetGraphDebug
Sets debugging level. Syntax
void SetGraphDebug (level) int level;
Arguments
level Debugging level
Explanation
Set a debugging level for the graphics system. Any of the following can be designated as level:
Level Operation
0 No checks are performed. (Highest speed mode)
1 Checks coordinating registered and drawn primitives.
2 Registered and drawn primitives are dumped.
Return value None.
Runtime Library Release 3.0
SetLineF2, SetLineF3, SetLineF4
Initializes flat straight line drawing primitive. Syntax
Basic Graphics Library (libgpu) Functions 205
void SetLineF2 (p) LINE_F2 *p;
void SetLineF3 (p) LINE_F3 *p;
void SetLineF4 LINE_F4 *p;
Arguments
p Primitive start address Explanation
These functions initialize the primitives specified by p.
Return value None.
Runtime Library Release 3.0
206 Basic Graphics Library (libgpu) Functions
SetLineG2, SetLineG3, SetLineG4
Initializes Gouraud straight line drawing primitive. Syntax
void SetLineG2 (p) LINE_G2 *p;
void SetLineG3 (p) LINE_G3 *p;
void SetLineG4 (p) LINE_G4 *p;
Arguments
p Primitive start address Explanation
These functions initialize the primitives specified by p.
Return value None.
Runtime Library Release 3.0
SetPolyF3, SetPolyF4
Initializes POLY_F3 and POLY_F4 primitives. Syntax
Basic Graphics Library (libgpu) Functions 207
void SetPolyF3 (p) POLY_F3 *p;
void SetPolyF4 (p) POLY_F4 *p;
Arguments
p Primitive start address
Explanation These functions initialize the primitive specified by p.
Return value None.
Runtime Library Release 3.0
208 Basic Graphics Library (libgpu) Functions
SetPolyFT3, SetPolyFT4
Initializes POLY_FT3 and POLY_FT4 primitives. Syntax
void SetPolyFT3 (p) POLY_FT3 *p;
void SetPolyFT4 (p) POLY_FT4 *p;
Arguments
p Primitive start address
Explanation These functions initialize the primitive specified by p.
Return value None.
Runtime Library Release 3.0
SetPolyG3, SetPolyG4
Initializes POLY_G3 and POLY_G4 primitives. Syntax
Basic Graphics Library (libgpu) Functions 209
void SetPolyG3 (p) POLY_G3 *p;
void SetPolyG4 (p) POLY_G4 *p;
Arguments
p Primitive start address
Explanation These functions initialize the primitive specified by p.
Return value None.
Runtime Library Release 3.0
210 Basic Graphics Library (libgpu) Functions
SetPolyGT3, SetPolyGT4
Initializes POLY_GT3 and POLY_GT4 primitives. Syntax
void SetPolyGT3 (p) POLY_GT3 *p;
void SetPolyGT4 (p) POLY_GT4 *p;
Arguments
p Primitive start address
Explanation These functions initialize the primitive specified by p.
Return value None.
Runtime Library Release 3.0
setRECT
Set rectangular area. Syntax
Basic Graphics Library (libgpu) Functions 211
setRECT (r, x, y, w, h) Arguments
r Pointer to RECT structure
x, y Upper left point of rectangular area
w, h Size of rectangular area
Explanation
Sets the x, y, w, and h values of member r.
Return value None.
Runtime Library Release 3.0
setRGB0, setRGB1, setRGB2, setRGB3
Sets the RGB of a primitive. Syntax
setRGB0 (p, r0, g0, b0) setRGB1 (p, r1, g1, b1) setRGB2 (p, r2, g2, b2) setRGB3 (p, r3, g3, b3)
Arguments
p Primitive pointer
r, g, B RGB members of primitive.
Explanation
These macros set the values for the RGB members of the primitive p.
Return value
None.
Remarks
These are macros, so there is no dependence on the primitive type. Generation differs between
a) set RGB0 ((POLY_FT4*)p, r0, g0, b0)
b) set RGB0 ((POLY_FT4*)p, r0, g0, b0)
SetSem iTrans
Sets a primitive semi-transparent attribute. Syntax
void SetSemiTrans (p, abe) unsigned long *p;
long abe;
Arguments
p Primitive start address
abe Semi-transparent flag
0: semitransparent OFF 1: Semitransparent ON
Explanation
This function sets the "semi-transparent" attribute, in accordance with abe, for the drawing primitive specified by p. If "semitransparent" is ON, semitransparent pixels are drawn under the conditions given below.
Primitive Pixels subjected to semitransparent processing
POLY_FT3/POLY_FT4 POLY_GT3/POLY_GT4 SPRT/SPRT_8/SPRT_16
Pixels for which the topmost bit of the corresponding texture pixel is "1"
Other drawing primitives All Pixels
Return value None.
Remarks
Semi-transparent pixels are calculated from the foreground pixels Pf and background pixels Pb as follows:
P = F x Pf + B x Pb
The rate (F, B) of semi-transparency is designated by the member tpage in the primitive. Drawing speed is reduced because semi-transparency requires reading of background brightness values. Therefore, drawing of a primitive which need not be displayed semi-transparently should be always done with semi-transparent mode turned off.
SetShadeTex
Inhibiting shading function. Syntax
void SetShadeTex (p, tge) unsigned long *p;
long tge;
Arguments
p Primitive start address
tge Un-shaded flag
0: Shading is performed
1: Shading is not performed
Explanation
This function allows or inhibits the shading function, for the drawing primitive specified by p, in accordance with tge.
When texture and shading are both ON, each pixel in the polygon is calculated as shown below from the pixel value "T" of the corresponding texture pattern, and the brightness value "L" correspondong to the pixel value "T".
P = (T*L)/128
When "L" = 128, the brightness value of the texture pattern is drawn as it is. If the value results in an overflow, the pixel value is clipped to 255.
When tge = 1, the brightness value is not divided, and the texture pattern value is used, as it is, as the pixel value.
Return value None.
Remarks
This function cannot be used for primitives other than "POLY_FT3", "POLY_FT4", "SPRT", "SPRT_8", and "SPRT_16".
SetSprt8, SetSprt16, SetSprt
Initializes sprites, tile primitives. Syntax
void SetSprt8 (p) SPRT_8 *p;
void SetSprt16 (p) SPRT_16 *p;
void SetSprt (p) SPRT *p;
Arguments
p Primitive start address
Explanation
These functions initialize the primitives specified by p. Details are given below.
Function name
Sprite size
Primitive
SetSprt8
8 x 8
SPRT_8
SetSprt16
16 x 16
SPRT_16
SetSprt
Can be set at will using
SPRT
values of
members h, w.
(0 < h , 255, 0 < w < 255)
Return value
None. Remarks
The SPRT... primitives are faster than POLY_FT4. TILE is also faster than POLY_F4.
216 Basic Graphics Library (libgpu) Functions
SetTexWi nd ow
Initializes the content of a texture window primitive. Syntax
void SetTexWindow (p, tw) DR_TWIN *p
RECT *tw
Arguments
p Texture window primitive
tw Texture window
Explanation
Initializes the texture window primitive. By using AddPrim() to register an initialized drawing environment change primitive in OT, it is possible to change part of a drawing environment in the middle of drawing.
Return value None.
Runtime Library Release 3.0
SetTile, SetTile1, SetTile8, SetTile16
Initializes Sprite, tile primitives. Syntax
void SetTile (p) TILE *p;
void SetTile (p) TILE_1 *p;
void SetTile (p) TILE_8 *p;
void SetTile (p) TILE_16 *p;
Arguments
p Primitive start address.
Explanation
These functions initialize the primitives specified by p. Details are given below.
Function name
Tile size
Primitive size
SetTile1
1 x 1
TILE
SetTile8
8 x 8
TILE_1
SetTile16
8 x 8
TILE_8
SetTile
Can be set at will using
TILE_16
values of
members h, w.
(0 < h , 255, 0 < w < 255)
Return value
None. Remarks
The SPRT... primitives are faster than POLY_FT4. TILE is also faster than POLY_F4.
218 Basic Graphics Library (libgpu) Functions
setUV0, setUV3, setUV4
Sets UV of a primitive. Syntax
setUV0 (p, u0, v0)
setUV3 (p, u0, v0, u1, v1, u2, v2)
setUV4 (p, u0, v0, u1, v1, u2, v2, u3, v3)
Arguments
p Primitive pointer.
u, v UV members of primitive.
Explanation
This macros set the values for the UV members of the primitive p.
Return value
None.
Remarks
This is a macro, so there is no dependence on the primitive type.
setUVWH
Sets UV members of 4-point specification primitive. Syntax
setUVWH (p, u0, v0, w, h)
Arguments
p Primitive pointer.
u0, v0 Upper left corner of primitive texture w, h Width and height of primitive texture.
Explanation
This macro sets the coordinates of a rectangle having diagonals (u0, v0)- (u0+w, v0+h) in the members (u0, v0)... (u3, v3) of the primitive.
Return value None.
Remarks
These are macros, so there is no dependence on the primitive type. However, they cannot be used on sprite primitives.
220 Basic Graphics Library (libgpu) Functions
setVector
Setting a vector value. Syntax
setVector (v, x, y, z) Arguments
v Pointer to a vector x, y, z Coordinate values
Explanation
Sets the (x, y, z) value for VECTOR/SVECTOR.
Return value None.
Remarks
setVector() is not dependent on vector format because it is a macro instruction. Operation differs between:
a) setVector ( (SVECTOR*)v, x, y, z)
b) setVector ( (VECTOR *)v, x, y, z)
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Functions 221
setWH
Setting values of members "w" and "h" of primitive "p". Syntax
setWH (p, w, h) Arguments
p Primitive pointer.
w, h Width and height of primitive.
Explanation
This macro specifies w and h for a primitive having the members w and h.
Return value None.
Remarks
This is a macro, so there is no dependence on the vector type. However, it cannot be used on primitives lacking the members w and h.
Runtime Library Release 3.0
222 Basic Graphics Library (libgpu) Functions
setXY0, set XY2, setXY3, setXY4
Setting the XY member of a primitive. Syntax
setXY0 (p, x0, y0)
setXY2 (p, x0, y0, x1, y1)
setXY3 (p, x0, y0, x1, y1, x2, y2)
setXY4 (p, x0, y0, x1, y1, x2, y2, x3, y3)
Arguments
p Primitive pointer
x, y XY members of primitive
Explanation
These macros set the values for the XY members of the primitive.
Return value None.
Remarks
These are macros, so there is no dependence on the primitive type.
Runtime Library Release 3.0
Basic Graphics Library (libgpu) Functions 223
setXYWH
Setting the XY member of a four-point primitive. Syntax
setXYWH (p, x0, y0, w, h) Arguments
p Primitive pointer.
x0, y0 Upper left corner of primitive. w, h Width and height of primitive.
Explanation
This macro sets the coordinates of a rectangle having diagonals (x0, y0) - (x0 +w, y0 + h) in the members (x0, y0)... (x3, y3) of the primitive.
Return value None.
Remarks
This is a macro, so there is no dependence on the primitive type. However, it cannot be used on sprite primitives.
Runtime Library Release 3.0
224 Basic Graphics Library (libgpu) Functions
StoreImage
Transferring data from a frame buffer. Syntax
int StoreImage (recp, p) RECT *recp;
unsigned long *p;
Arguments
recp Destination rectangular area
p Main memory address of destination of transmission
Explanation
This function transfers the rectangular area in the frame buffer specified by recp to the contiguous area in main memory at address p.
Return value
Number in the queue. Remarks
Because StoreImage() is detected by DrawSync(). The transfer areas at the environment (clip, offset) (1023, 511).
a non-block function, the transmission termination has to be
source and destination are not affected by the drawing
. The source area must be located within a drawable area (0, 0) -
Basic Graphics Library (libgpu) Functions 225
TermPrim
Terminating a primitive list. Syntax
void TermPrim (p) unsigned long *p;
Arguments
p Start address of a primitive
Explanation This function cuts off a primitive list after p, and terminates it forcibly.
Return value None.
Runtime Library Release 3.0
VSync
Waiting for vertical sync. Syntax
int VSync(mode) int mode;
Arguments mode Mode Explanation
This function waits for vertical sync according to mode specified as Mode. The values that may be be designated as mode are listed below.
Mode Operation
0 Blocks until vertical sync is generated
1 Returns time elapsed from the point in time VSync() is last called in horizontal sync units
n (n>1) Blocks from the point in time VSync() is last called until n number of vertical syncs are generated.
-n (n>0) Returns absolute time after program boot in vertical sync interval units.
Return value
Mode value is as listed below.
Mode Return value
mode>=0 Time elapsed from the point in time that Vsync() is last called (horizontal blanking units)
mode<0 Time elapsed after program boot (vertical blanking units)
Remarks
To prevent deadlocks, when VSync() blocks for an especially long time (about 4 VSync), a time out is produced. In that case, use VSync(-1), and block with the application.
Basic Graphics Library (libgpu) Functions 227
VSyncCallback
Defines a vertical synchronization callback function. Syntax
void VSyncCallback (func) void (*func)();
Arguments
func Callback function
Explanation
Calls the function "func" at the start of vertical retrace line space. If "0" is specified for func, no callback occurs.
Return value None.
Remarks
Subsequent interrupts will be masked inside func. Therefore, it is necessary to return quickly after performing necessary processes using func.
Runtime Library Release 3.0
Chapter 6
Fundamental Geometry Library (libgte)
This chaper describes structures defined in the extended graphics library (libgs) and the available functions. "libgs" is a high-level graphics library that uses libgpu and libgte. Three-dimensional functionality such as light source calculations, transparency conversions, and point-of-view specification have been added and there is support for such two-dimensional functions as basic point and line figure drawing, Sprite and BG drawing, and attribute control.
Chapter 6: Fundamental Geometry (libgte) Table of Contents
Structures
CRVECTOR3
255
CRVECTOR4
256
CVECTOR
257
DIVPOLYGON3
258
DIVPOLYGON4
259
DVECTOR
260
EVECTOR
261
MATRIX
262
POL3
263
POL4
264
RVECTOR
265
SPOL
266
SVECTOR
267
TMESH
268
VECTOR
269
Functions
ApplyMatrix
270
ApplyMatrixLV
271
ApplyMatrixSV
272
ApplyRotMatrix
273
AverageZ3
274
AverageZ4
275
catan
276
ccos
277
Clip3F
278
Clip3FP
279
Clip3FT
280
Clip3FTP
281
Clip3G
282
Clip3GP
283
Clip3GT
284
Clip3GTP
285
Clip4F
286
Clip4FP
287
Clip4FT
288
Clip4FTP
289
Clip4G
290
Clip4GP
291
Clip4GT
292
Clip4GTP
293
cln
294
ColorCol
295
ColorDpq
296
ColorMatCol
297
ColorMatDpq
298
CompMatrix
299
csin
300
csqrt
301
DivideF3
302
DivideF4
303
DivideFT3
304
DivideFT4
305
DivideG3
306
DivideG4
307
DivideGT3
308
DivideGT4
309
DpqColor
310
DpqColor3
311
DpqColorLight
312
GsPrstF3L, GsPrstF3LFG, GsPrstF3NL, GsPrstNF3
313
GsPrstF4L, GsPrstF4LFG, GsPrstF4NL, GsPrstNF4
314
GsPrstG3L, GsPrstG3LFG, GsPrstG3NL, GsPrstNG3
315
GsPrstG4L, GsPrstG4LFG, GsPrstG4NL, GsPrstNG4
316
GsPrstTF3L, GsPrstTF3LFG, GsPrstTF3NL, GsPrstTNF3
317
GsPrstTF4L, GsPrstTF4LFG, GsPrstTF4NL, GsPrstTNF4
318
GsPrstTG3L, GsPrstTG3LFG, GsPrstTG3NL, GsPrstTNG3
319
GsPrstTG4L, GsPrstTG4LFG, GsPrstTG4NL, GsPrstTNG4
320
GsTMDdivF3L, GsTMDdivF3LFG, GsTMDdivF3NL, GsTMDdivNF3
321
GsTMDdivF4L, GsTMDdivF4LFG, GsTMDdivF4NL, GsTMDdivNF4
323
GsTMDdivG3L, GsTMDdivG3LFG, GsTMDdivG3NL, GsTMDdivNG3
325
GsTMDdivG4L, GsTMDdivG4LFG, GsTMDdivG4N, GsTMDdivNG4
327
GsTMDdivTF3L, GsTMDdivTF3LFG, GsTMDdivTF3NL, GsTMDdivTNF3
329
GsTMDdivTF4L, GsTMDdivTF4LFG, GsTMDdivTF4NL, GsTMDdivTNF4
331
GsTMDdivTG3L, GsTMDdivTG3LFG, GsTMDdivTG3NL, GsTMDdivTNG3
333
GsTMDdivTG4L, GsTMDdivTG4LFG, GsTMDdivTG4NL, GsTMDdivTNG4
335
GsTMDfastF3L, GsTMDfastF3LFG, GsTMDfastF3NL, GsTMDfastNF3
337
GsTMDfastF4L, GsTMDfastF4LFG, GsTMDfastF4NL, GsTMDfastNF4
338
GsTMDfastG3L, GsTMDfastG3LFG, GsTMDfastG3NL, GsTMDfastNG3
339
GsTMDfastG4L, GsTMDfastG4LFG, GsTMDfastG4NL, GsTMDfastNG4
340
GsTMDfastTF3L, GsTMDfastTF3LFG, GsTMDfastTF3NL, GsTMDfastTNF3
341
GsTMDfastTF4L, GsTMDfastTF4LFG, GsTMDfastTF4NL, GsTMDfastTNF4
342
GsTMDfastTG3L, GsTMDfastTG3LFG, GsTMDfastTG3NL, GsTMDfastTNG3
343
GsTMDfastTG4L, GsTMDfastTG4LFG, GsTMDfastTG4NL, GsTMDfastTNG4
344
gteMIMefunc
345
InitClip
346
InitGeom
347
Intpl
348
InvSquareRoot
349
LightColor
350
LoadAverage0
351
LoadAverage12
352
LoadAverageByte
353
LoadAverageCol
354
LoadAverageShort0
355
LoadAverageShort12
356
LocalLight
357
Lzc
358
MulMatrix
359
MulMatrix0
360
MulMatrix2
361
MulRotMatrix
362
MulRotMatrix0
363
NormalClip
364
NormalColor
365
NormalColor3
366
NormalColor3_nom
367
NormalColorCol
368
NormalColorCol3
369
NormalColorCol3_nom
370
NormalColorCol_nom
370
NormalColorDpq
371
NormalColorDpq3
373
NormalColorDpq3_nom
374
NormalColorDpq_nom
374
NormalColor_nom
376
OuterProduct0
377
OuterProduct12
379
PopMatrix
380
PushMatrix
381
ratan2
382
rcos
383
RCpolyF3
384
253
RCpolyF4
385
RCpolyFT3
386
RCpolyFT4
387
RCpolyG3
388
RCpolyG4
389
RCpolyGT3
390
RCpolyGT4
391
ReadColorMatrix
392
ReadGeomOffset
393
ReadGeomScreen
394
ReadLightMatrix
395
ReadRGBfifo
396
ReadRotMatrix
397
ReadSXSYfifo
398
ReadSZfifo3
399
ReadSZfifo4
400
RotAverage3
401
RotAverage3_nom
402
RotAverage4
402
RotAverageNclip3
404
RotAverageNclip3_nom
405
RotAverageNclip4
406
RotAverageNclipColorCol3
407
RotAverageNclipColorCol3_nom
408
RotAverageNclipColorDpq3
410
RotAverageNclipColorDpq3_nom
411
RotColorDpq
411
RotColorDpq3
414
RotColorDpq3_nom
415
RotColorDpq_nom
416
RotColorMatDpq
416
Rot Matrix
418
RotMatrixC
419
Rot MatrixX
420
Rot MatrixY
421
Rot MatrixYXZ
422
Rot MatrixZ
423
RotMeshH
424
Rot Nclip3
425
RotNclip3_nom
426
Rot Nclip4
427
RotPMD_F3
428
RotPMD_F4
429
RotPMD_FT3
430
RotPMD_FT4
431
RotPMD_G3
432
RotPMD_G4
433
RotPMD_GT3
434
RotPMD_GT4
435
RotPMD_SV_F3
436
RotPMD_SV_F4
437
RotPMD_SV_FT3
438
RotPMD_SV_FT4
439
RotPMD_SV_G3
440
RotPMD_SV_G4
441
RotPMD_SV_GT3
442
RotPMD_SV_GT4
443
RotRMD_F3
444
RotRMD_F4
445
RotRMD_FT3
446
RotRMD_FT4
447
RotRMD_G3
448
RotRMD_G4
449
RotRMD_GT3
450
RotRMD_GT4
451
RotRMD_SV_F3
452
RotRMD_SV_F4
453
RotRMD_SV_FT3
454
RotRMD_SV_FT4
455
RotRMD_SV_G3
456
RotRMD_SV_G4
457
RotRMD_SV_GT3
458
RotRMD_SV_GT4
459
RotSMD_F3
460
RotSMD_F4
461
RotSMD_FT3
462
RotSMD_FT4
463
RotSMD_G3
464
RotSMD_G4
465
RotSMD_GT3
466
RotSMD_GT4
467
RotSMD_SV_F3
468
RotSMD_SV_F4
469
RotSMD_SV_FT3
470
RotSMD_SV_FT4
471
RotSMD_SV_G3
472
RotSMD_SV_G4
473
RotSMD_SV_GT3
474
RotSMD_SV_GT4
475
RotTrans
476
RotTransPers
477
RotTransPers3
478
RotTransPers3N
479
RotTransPers3_nom
479
RotTransPers4
480
RotTransPers4_nom
482
RotTransPersN
483
RotTransPers_nom
484
RotTrans_nom
485
rsin
485
ScaleMatrix
487
ScaleMatrixL
488
SetBackColor
489
SetColorMatrix
490
SetFarColor
491
SetFogFar
492
SetFogNear
493
SetGeomOffset
494
SetGeomScreen
495
SetLightMatrix
496
SetMulMatrix
497
SetRGBcd
498
SetRotMatrix
499
SetTransMatrix
500
Square0
501
Square12
502
SquareRoot0
503
SquareRoot12
504
SubPol3
505
SubPol4
506
TransMatrix
507
TransposeMatrix
508
VectorNormal
509
VectorNormalS
510
CRVECTOR3
Triangular recursive vector data. Structure
typedef struct {
RVECTOR r01, r12, r20; RVECTOR *r0, *r1, *r2; unsigned long *rtn;
} CRVECTOR3;
Members
r01, r12, r20 Division vertex vector data
r0, r1, r2 Division vertex vector data
rtn Return address for assembler
CRVECTOR4
Quadrilateral recursive vector data. Structure
typedef struct {
RVECTOR r01, r02, r3 1, r32, rc; RVECTOR *r0, *r1, *r2, *r3; unsigned long *rtn;
} CRVECTOR4;
Members
r01,
r02, r31, r32, rc
Division vertex vector data
*r0,
*r1, *r2, *r3
Division vertex vector data
*rtn
Return address for assembler
CVECTOR
Character vector. Structure
typedef struct {
unsigned char r, g, b, cd; };
Members
r, g, b Color palette cd GPU code
DIVPOLYGON3
Triangular division buffer. Structure
Number of divisions
Clip area specification (display screen resolution)
CLUT
Texture page Code + RGB color
Pointer to OT
Division vertex vector data
Triangular recursive vector data
Basic Geometry Library (libgte) Structures 259
DIVPOLYGON4
Quadrilateral recursive vector data. Structure
typedef struct {
unsigned long ndiv;
unsigned long pih, piv; unsigned short clut, tpage; CVECTOR rgbc;
unsigned long *ot;
RVECTOR r0, r1, r2, r3; CRVECTOR4 cr[5];
} DIVPOLYGON4;
Members
ndiv
pih, piv
clut
tpage
rgbc
*ot
r0, r1, r2, r3 cr
Number of divisions
Clip area specification (display screen's resolution)
CLUT
Texture page Code + RGB color
Pointer to OT
Division vertex vector data
Quadrilateral recursive vector data
Runtime Library Release 3.0
DVECTOR
2D vector. Structure
typedef struct { short vx, vy; } DVECTOR;
Members
vx, vy Vector coordinates
EVECTOR
Clip vector data. Structure
typedef struct { SVECTOR v; VECTOR sxyz; DVECTOR sxy; CVECTOR rgb; short txuv, pad; long chx, chy;
} EVECTOR;
Members
v
sxyz sxy rgb
txuv, pad chx, chy
Local object 3D vertex Screen 3D vertex Screen 2D vertex Color palette
Texture mapping data Clip area data
MATRIX
Matrix. Structure
struct MATRIX { short m [3][3]; long t [3];
};
Members
m matrix
y vector
POL3
Triangle polygon. Structure
struct POL3 {
short sxy [3][2]; short sz [3][2]; short uv [3][2]; short rgb [3][3]; short code;
};
Members
Screen coordinates Screen coordinates Texture coordinates RGB value
Code
264 Basic Geometry Library (libgte) Structures
POL4
Four-sided polygon. Structure
struct POL4 {
short sxy [4][2]; short sz [4][2]; short uv [4][2]; short rgb [4][3]; short code;
};
Members
sxy sz
uv
rgb code
Screen coordinates Screen coordinates Texture coordinates RGB value
Code
Runtime Library Release 3.0
RVECTOR
Division vertex vector data. Structure
typedef struct { SVECTOR v; unsigned char uv [2];
unsigned short pad;
CVECTOR c; DVECTOR sxy; unsigned long sz;
} RVECTOR;
Members
Local object 3D vertex Texture mapping data Vertex color palette Screen 2D vertex
Clip Z-data
266 Basic Geometry Library (libgte) Structures
SPOL
Vertex information. Structure
struct SPOL { short xy [3]; short uv [2]; short rgb [3];
};
Members
xy XY coordinates
uv UV coordinates
rgb RGB value
SVECTOR
Short vector. Structure
struct SVECTOR { short vx, vy;
short vz, pad; };
Members
vx, vy, vz Vector coordinates
pad System reserved
268 Basic Geometry Library (libgte) Structures
TMESH
Triangle mesh. Structure
struct TMESH { SVECTOR *v; SVECTOR *n; SVECTOR *u; CVECTOR *c; unsigned long len;
};
Members
v n
u c len
Pointer to vertex string Pointer to normal string Pointer to texture string Pointer to RGB string Mesh length
Runtime Library Release 3.0
VECTOR
Vector. Structure
struct VECTOR {
long vx, vy, vz, pad; };
Members
vx, vy, vz Vector coordinates
pad System reserved
ApplyMatrix
Multiplication of a vector by a matrix. Syntax
VECTOR* ApplyMatrix (m, v0, v1) MATRIX *m;
SVECTOR *v0;
VECTOR *v1;
Arguments
m Matrix to be multiplied (input)
v0 Short vector (input)
v1 Vector (output)
Explanation
This function multiplies the matrix m by the short vector v0 beginning with the rightmost end. The result is saved in the vector v1.
The argument format is as follows: m -> m [i][j]: (1, 3, 12) v0 -> vx, vy, vz: (1, 15, 0) v1 -> vx, vy, vz: (1, 31, 0)
Return value
This function returns v1. Remarks
The function destroys the constant rotation matrix.
Basic Geometry Library (libgte) Functions 271
ApplyMatrixLV
Multiply a vector by a matrix. Syntax
VECTOR* ApplyMatrixLV (m, v0, v1) MATRIX *m;
VECTOR *v0, *v1;
Arguments
m Matrix to be multiplied (input)
v0 Vector (input)
v1 Vector (output)
Explanation
This function destroys the rotation matrix.
This function multiplies matrix m by vector v0 beginning from the rightmost end. The result is saved in vector v1.
m -> m [i][j] : (1, 3, 12)
v0 -> vx, vy, vz : (1, 31, 0) v1 -> vx, vy, vz : (1, 31, 0)
Return value
v1
Remarks
This function destroys the rotation matrix.
ApplyMatrixSV
Multiply a vector by a matrix. Syntax
SVECTOR* ApplyMatrix (m, v0, v1) MATRIX *m;
SVECTOR *v0, *v1;
Arguments
m Matrix to be multiplied (input)
v0 Short vector (input)
v1 Short vector (output)
Explanation
This function multiplies matrix m by short vector v0 beginning at the rightmost end. The result is saved in the short vector v1.
m -> m [i][j] : (1, 3, 12)
v0 -> vx, vy, vz : (1, 15, 0) v1 -> vx, vy, vz : (1, 15, 0)
Return value
v1 Remarks
This function destroys the rotation matrix.
Basic Geometry Library (libgte) Functions 273
ApplyRotMatrix
Multiply a vector by a constant rotation matrix. Syntax
VECTOR* ApplyRotMatrix (v0, v1) SVECTOR *v0;
VECTOR *v1;
Arguments
v0 Short vector (input)
v1 Vector (output)
Explanation
This function multiplies a constant rotation matrix by short vector v0 beginning at the rightmost end. The result is saved in vector v1.
v0 -> vx, vy, vz : (1, 15, 0) v1 -> vx, vy, vz : (1, 31, 0)
Return value v1
Runtime Library Release 3.0
274 Basic Geometry Library (libgte) Functions
AverageZ3
Average of three values. Syntax
long AverageZ3 (sz0, sz1, sz2) long sz0, sz1, sz2;
Arguments
sz0, sz1, sz2 Input values Explanation
This function calculates an average of three values sz0, sz1, and sz2.
The argument format is as follows:
sz0, sz1, sz2 : (0, 16, 0)
Return value : (0, 16, 0)
Return value
Average of 1/4 of three values sz0, sz1, and sz2.
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 275
AverageZ4
Average of four values. Syntax
long AverageZ4 (sz0, sz1, sz2, sz3) long sz0, sz1, sz2, sz3;
Arguments
sz0, sz1, sz2, sz3 Input values
Explanation This function calculates an average of four values sz0, sz1, sz2, and sz3.
The argument format is as follows:
sz0, sz1, sz2, sz3 : (0, 16, 0)
Return value : (0, 16, 0)
Return value
Average of 1/4 of four values sz0, sz1, sz2, and sz3.
Runtime Library Release 3.0
276 Basic Geometry Library (libgte) Functions
catan
Syntax
long catan (a) long a;
Arguments
a Value Explanation
This function uses Playstation format (where 4096 = 360 degrees) to find the arctan (between - 90 and +90 degrees) of a.
The argument format is as follows:
a: (1, 19, 12)
return value: Playstation format (4096 = 360 degrees)
Return value atan (a)
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 277
ccos
Syntax
long ccos (a) long a;
Arguments
a Angle (in Playstation format)
Explanation
Find the cosine function of the angle (in Playstation format) (4096 = 360 degrees) using fixed point math (where 4096 = 1.0).
The argument format is as follows:
a : Playstation format (4096 = 360 degrees) return value : (1, 19, 12)
Return value
cos (a)
Runtime Library Release 3.0
Three-vertex clipping (without perspective transformation). Syntax
long Clip3F (v0, v1, v2, evmx) SVECTOR *v0, *v1, *v2;
EVECTOR **evmx;
Arguments
v0, v1, v2 Vertex coordinate vector (input)
evmx Pointer arrays for clip vector data (20,output)
Explanation
This function clips six surfaces of a triangle having vertices v0, v1, and v2, and defined by InitClip(), and angle information is stored in evmx. The output number of vertices is returned.
Effective output clip vector data:
evmx[i] -> v Local Object 3D Vertex
evmx[i] -> sxyz Screen 3D Vertex
evmx[i] -> chx chx = vz* (hw/2)/h
evmx[i] -> chy chy = vz* (vw/2)/h
This function reserves the pointer arrays (20 pointer arrays = 80 bytes), including the work area.
Return value
Output number of vertices.
Basic Geometry Library (libgte) Functions 279
Clip3FP
Three-vertex (triangle) clipping (with perspective transformation). Syntax
long Clip3FP (v0, v1, v2, evmx) SVECTOR *v0, *v1, *v2;
EVECTOR **evmx;
Arguments
v0, v1, v2 Vertex coordinate vector (input)
evmx Pointer arrays (for clip vector data (20, output)
Explanation
This function clips six surfaces of a triangle having vertices v0, v1, and v2, and defined by InitClip(). Angle information is stored in evmx. The output number of vertices is returned.
Effective output clip vector data:
evmx[i] -> v evmx[i] -> sxyz evmx[i] -> sxyz.pad evmx[i] -> sxy evmx[i] -> chx evmx[i] -> chy
Local Object 3D Vertex
Screen 3D Vertex
FOG effect interpolation value (p) Screen 2D Vertex chx = vz* (hw/2)/h chy = vz* (vw/2)/h
This function reserves the pointer arrays (20 pointer arrays = 80 bytes), including the work area.
Return value
Output number of vertices
Three-vertex clipping (without perspective transformation). Syntax
long Clip3FT (v0, v1, v2, uv0, uv1, uv2, evmx) SVECTOR *v0, *v1, *
short *uv0, *uv1, *uv2;
EVECTOR **evmx;
Arguments
v0, v1, v2 Vertex coordinate vector (input)
uv0, uv1, uv2 Texture coordinate vector (input)
evmx Pointer arrays for clip vector data (20, output)
Explanation
This function clips six surfaces of a triangle having vertices v0, v1, and v2, and defined by InitClip(). Angle information is stored in evmx. The output number of vertices is returned.
Effective output clip vector data:
evmx[i] -> v evmx[i] -> sxyz evmx[i] -> txuv evmx[i] -> chx evmx[i] -> chy
Local Object 3D Vertex Screen 3D Vertex Texture Mapping Vertex chx = vz* (hw/2)/h
chy = vz* (vw/2)/h
This function reserves the pointer arrays (20 pointer arrays = 80 bytes), including the work area.
Return value
Output number of vertices
Basic Geometry Library (libgte) Functions 281
Clip3FTP
Three-vertex clipping (with perspective transformation). Syntax
long Clip3FTP (v0, v1, v2, uv0, uv1, uv2, evmx) SVECTOR *v0, *v1, *v2;
short *uv0, *uv1, *uv2;
EVECTOR **evmx;
Arguments
v0, v1, v2 Vertex coordinate vector (input)
uv0, uv1, uv2 Texture coordinate vector (input)
evmx Pointer arrays for clip vector data (20, output)
Explanation
This function clips six surfaces of a triangle having vertices v0, v1, and v2, and defined by InitClip(). Angle information is stored in evmx. The output number of vertices is returned.
Effective output clip vector data:
evmx[i] -> v evmx[i] -> sxyz evmx[i] -> sxyz.pad evmx[i] -> sxy evmx[i] -> txuv evmx[i] -> chx evmx[i] -> chy
Object (Local) 3D Vertex
Screen 3D Vertex
FOG effect interpolation value (p)
Screen 2D Vertex Texture Mapping Data chx = vz* (hw/2)/h chy = vz* (vw/2)/h
This function reserves the pointer arrays (20 pointer arrays = 80 bytes), including the work area.
Return value
Output number of vertices
Runtime Library Release 3.0
Three-vertex clipping (without perspective transformation). Syntax
long Clip3G (v0, v1, v2, rgb0, rgb1, rgb2, evmx) SVECTOR *v0, *v1, *v2;
CVECTOR *rgb0, *rgb1, *rgb2;
EVECTOR **evmx;
Arguments
v0, v1, v2 Vertex coordinate vector (input)
rgb0, rgb1, rgb2 Vertex color data (input)
evmx Pointer arrays for clip vector data (20, output)
Explanation
This function clips six surfaces of a triangle having vertices v0, v1, and v2, and defined by InitClip(). Angle information is stored in evmx. The output number of vertices is returned.
Effective output clip vector data:
evmx[i] -> v evmx[i] -> sxyz evmx[i] -> rgb evmx[i] -> chx evmx[i] -> chy
Local Object 3D Vertex Screen 3D Vertex Vertex Color Data chx = vz* (hw/2)/h chy = vz* (vw/2)/h
This function reserves the pointer arrays (20 pointer arrays = 80 bytes), including the work area.
Return value
Output number of vertices
Three-vertex clipping (with perspective transformation). Syntax
long Clip3GP (v0, v1, v2, rgb0, rgb1, rgb2, evmx) SVECTOR *v0, *v1, *v2;
CVECTOR *rgb0, *rgb1, *rgb2;
EVECTOR **evmx; data
Arguments
v0, v1, v2 Vertex coordinate vector (input)
rgb0, rgb1, rgb2 Vertex color data (input)
evmx Pointer arrays for clip vector data (20, output)
Explanation
This function clips six surfaces of a triangle having vertices v0, v1, and v2, and defined by InitClip(). Angle information is stored in evmx. The output number of vertices is returned.
Effective output clip vector data:
evmx[i] -> v evmx[i] -> sxyz evmx[i] -> sxyz.pad evmx[i] -> sxy evmx[i] -> rgb evmx[i] -> chx evmx[i] -> chy
Local Object3D Vertex
Screen 3D Vertex
FOG effect interpolation value (p) Screen 2D Vertex Vertex Color Data chx = vz* (hw/2)/h chy = vz* (vw/2)/h
This function reserves the pointer arrays (20 pointer arrays = 80 bytes), including the work area.
Return value
Output number of vertices
Three-vertex clipping (without perspective transformation). Syntax
long Clip3GT (v0, v1, v2, uv0, uv1, uv2, rgb0, rgb1, rgb2, evmx) SVECTOR *v0, *v1, *v2;
short *uv0, *uv1, *uv2;
CVECTOR *rgb0, *rgb1, *rgb2;
EVECTOR **evmx; data
Arguments
v0, v1, v2
uv0, uv1, uv2 rgb0, rgb1, rgb2 evmx
Explanation
Vertex coordinate vector (input)
Texture coordinate vector (input)
Vertex color data (input)
Pointer arrays for clip vector data (20, output)
This function clips six surfaces of a triangle having vertices v0, v1, and v2, and defined by InitClip(). Angle information is stored in evmx. The output number of vertices is returned.
Effective output clip vector data:
evmx[i] -> v evmx[i] -> sxyz evmx[i] -> rgb evmx[i] -> txuv evmx[i] -> chx evmx[i] -> chy
Local Object3D Vertex Screen 3D Vertex Vertex Color Data Texture Mapping Data chx = vz* (hw/2)/h chy = vz* (vw/2)/h
This function reserves the pointer arrays (20 pointer arrays = 80 bytes), including the work area.
Return value
Output number of vertices
Three-vertex clipping (with perspective transformation). Syntax
long Clip3GTP (v0, v1, v2, uv0, uv1, uv2, rgb0, rgb1, rgb2, evmx) SVECTOR *v0, *v1, *v2;
short *uv0, *uv1, *uv2;
CVECTOR *rgb0, *rgb1, *rgb2;
EVECTOR **evmx; data
Arguments
v0, v1, v2
uv0, uv1, uv2 rgb0, rgb1, rgb2 evmx
Vertex coordinate vector (input)
Texture coordinate vector (input)
Vertex color data (input)
Pointer arrays for clip vector data (20, output)
Explanation
This function clips six surfaces of a triangle having vertices v0, v1, and v2, and defined by InitClip(). Angle information is stored in evmx. The output number of vertices is returned.
Effective output clip vector data:
evmx[i] -> v evmx[i] -> sxyz evmx[i] -> sxyz.pad evmx[i] -> sxy evmx[i] -> rgb evmx[i] -> txuv evmx[i] -> chx evmx[i] -> chy
Local Object 3D Vertex
Screen 3D Vertex
Fog effect interpolation value (p) Screen 2D Vertex Vertex Color Data Texture Mapping Data chx = vz* (hw/2)/h chy = vz* (vw/2)/h
This function reserves the pointer arrays (20 pointer arrays = 80 bytes), including the work area.
Return value
Output number of vertices
Four-vertex clipping (without perspective transformation). Syntax
long Clip4F (v0, v1, v2, v3, evmx) SVECTOR *v0, *v1, *v2, *v3; EVECTOR **evmx;
Arguments
v0, v1, v2, v3 Vertex coordinate vector (input)
evmx Pointer arrays for clip vector data (20, output)
Explanation
This function clips six surfaces of a quadrilateral (linked triangle) having vertices v0, v1, and v2, and defined by InitClip(). Angle information is stored in evmx. The output number of vertices is returned.
Effective output clip vector data:
evmx[i] -> v Local Object 3D Vertex
evmx[i] -> sxyz Screen 3D Vertex
evmx[i] -> chx chx = vz* (hw/2)/h
evmx[i] -> chy chy = vz* (vw/2)/h
This function reserves the pointer arrays (20 pointer arrays = 80 bytes), including the work area.
Return value
Output number of vertices
Four-vertex clipping (with perspective transformation). Syntax
long Clip4FP (v0, v1, v2, v3, evmx) SVECTOR *v0, *v1, *v2, *v3;
EVECTOR **evmx;
Arguments
v0, v1, v2, v3 Vertex coordinate vector (input)
evmx Pointer arrays for clip vector data (20, output)
Explanation
This function clips six surfaces of a quadrilateral (linked triangle) having vertices v0, v1, and v2, and defined by InitClip(). Angle information is stored in evmx. The output number of vertices is returned.
Effective output clip vector data:
evmx[i] -> v evmx[i] -> sxyz evmx[i] -> sxyz.pad evmx[i] -> sxy evmx[i] -> chx evmx[i] -> chy
Local Object 3D Vertex
Screen 3D Vertex
FOG effect interpolation value (p) Screen 2D Vertex chx = vz* (hw/2)/h chy = vz* (vw/2)/h
This function reserves the pointer arrays (20 pointer arrays = 80 bytes), including the work area.
Return value
Output number of vertices
Four-vertex clipping (without perspective transformation). Syntax
long Clip4FT (v0, v1, v2, v3, uv0, uv1, uv2, uv3, evmx)
SVECTOR *v0, *v1, *v2, *v3; short *uv0, *uv1, *uv2, *uv3; EVECTOR **evmx;
Arguments
v0, v1, v2, v3 Vertex coordinate vector (input)
uv0, uv1, uv2, uv3 Texture coordinate vector (input)
evmx Pointer arrays for clip vector data (20, output)
Explanation
This function clips six surfaces of a quadrilateral (linked triangle) having vertices v0, v1, and v2, and defined by InitClip(). Angle information is stored in evmx. The output number of vertices is returned.
Effective output clip vector data:
evmx[i] -> v evmx[i] -> sxyz evmx[i] -> txuv evmx[i] -> chx evmx[i] -> chy
Local Object 3D Vertex Screen 3D Vertex Texture Mapping Data chx = vz* (hw/2)/h chy = vz* (vw/2)/h
This function reserves the pointer arrays (20 pointer arrays = 80 bytes), including the work area.
Return value
Output number of vertices
Four-vertex clipping (with perspective transformation). Syntax
long Clip4FTP (v0, v1, v2, v3, uv0, uv1, uv2, uv3, evmx) SVECTOR *v0, *v1, *v2, *v3;
short *uv0, *uv1, *uv2, *uv3;
EVECTOR **evmx;
Arguments
v0, v1, v2, v3 Vertex coordinate vector (input)
uv0, uv1, uv2, uv3 Texture coordinate vector (input)
evmx Pointer arrays for clip vector data (20, output)
Explanation
This function clips six surfaces of a quadrilateral (linked triangle) having vertices v0, v1, and v2, and defined by InitClip(). Angle information is stored in evmx. The output number of vertices is returned.
Effective output clip vector data:
evmx[i] -> v evmx[i] -> sxyz evmx[i] -> sxyz.pad evmx[i] -> sxy evmx[i] -> txuv evmx[i] -> chx evmx[i] -> chy
Local Object 3D Vertex
Screen 3D Vertex
interpolation value (p) FOG effect Screen 2D Vertex Texture Mapping Data chx = vz* (hw/2)/h chy = vz* (vw/2)/h
This function reserves the pointer arrays (20 pointer arrays = 80 bytes), including the work area.
Return value
Output number of vertices
Four-vertex clipping (without perspective transformation). Syntax
long Clip4G (v0, v1, v2, v3, rgb0, rgb1, rgb2, rgb3, evmx) SVECTOR *v0, *v1, *v2, *v3;
CVECTOR *rgb0, *rgb 1, *rgb2, *rgb3;
EVECTOR **evmx;
Arguments
v0, v1, v2, v3 Vertex coordinate vector (input)
rgb0, rgb 1, rgb2, rgb3 Vertex color data (input)
evmx Pointer arrays for clip vector data (20, output)
Explanation
This function clips six surfaces of a quadrilateral (linked triangle) having vertices v0, v1, and v2, and defined by InitClip(). Angle information is stored in evmx. The output number of vertices is returned.
Effective output clip vector data:
evmx[i] -> v evmx[i] -> sxyz evmx[i] -> rgb evmx[i] -> chx evmx[i] -> chy
Local Object 3D Vertex Screen 3D Vertex Vertex Color Data chx = vz* (hw/2)/h chy = vz* (vw/2)/h
This function reserves the pointer arrays (20 pointer arrays = 80 bytes), including the work area.
Return value
Output number of vertices
Four-vertex clipping (with perspective transformation). Syntax
long Clip4GP (v0, v1, v2, v3, rgb0, rgb1, rgb2, rgb3, evmx) SVECTOR *v0, *v1, *v2, *v3;
CVECTOR *rgb0, *rgb 1, *rgb2, *rgb3;
EVECTOR **evmx;
Arguments
v0, v1, v2, v3 Vertex coordinate vector (input)
rgb0, rgb 1, rgb2, rgb3 Vertex color data (input)
evmx Pointer arrays for clip vector data (20, output)
Explanation
This function clips six surfaces of a quadrilateral (linked triangle) having vertices v0, v1, and v2, and defined by InitClip(). Angle information is stored in evmx. The output number of vertices is returned.
Effective output clip vector data:
evmx[i] -> v evmx[i] -> sxyz evmx[i] -> sxyz.pad evmx[i] -> sxy evmx[i] -> rgb evmx[i] -> chx evmx[i] -> chy
Local Object 3D Vertex
Screen 3D Vertex
interpolation value (p) for FOG effect Screen 2D Vertex Vertex Color Data chx = vz* (hw/2)/h chy = vz* (vw/2)/h
This function reserves the pointer arrays (20 pointer arrays = 80 bytes), including the work area.
Return value
Output number of vertices
Four-vertex clipping (without perspective transformation). Syntax
long Clip4GT (v0, v1, v2, v3, uv0, uv1, uv2, uv3, rgb0, rgb1, rgb2, rgb3, evmx)
SVECTOR *v0, *v1, *v2, *v3; short *uv0, *uv1, *uv2, *uv3; CVECTOR *rgb0, *rgb 1, *rgb2, *rgb3;
EVECTOR **evmx;
Arguments
v0, v1, v2, v3
uv0, uv1, uv2, uv3 rgb0, rgb 1, rgb2, rgb3 evmx
Vertex coordinate vector (input)
Texture coordinate vector (input)
Vertex color data (input)
Pointer arrays for clip vector data (20, output)
Explanation
This function clips six surfaces of a quadrilateral (linked triangle) having vertices v0, v1, and v2, and defined by InitClip(). Angle information is stored in evmx. The output number of vertices is returned.
Effective output clip vector data:
evmx[i] -> v evmx[i] -> sxyz evmx[i] -> rgb evmx[i] -> txuv evmx[i] -> chx evmx[i] -> chy
Local Object 3D Vertex Screen 3D Vertex Vertex Color Data Texture Mapping Data chx = vz* (hw/2)/h chy = vz* (vw/2)/h
This function reserves the pointer arrays (20 pointer arrays = 80 bytes), including the work area.
Return value
Output number of vertices
Four-vertex clipping (with perspective transformation). Syntax
long Clip4GTP (v0, v1, v2, v3, uv0, uv1, uv2, uv3, rgb0, rgb1, rgb2, rgb3, evmx)
SVECTOR *v0, *v1, *v2, *v3; short *uv0, *uv1, *uv2, *uv3; CVECTOR *rgb0, *rgb 1, *rgb2, *rgb3;
EVECTOR **evmx;
Arguments
v0, v1, v2, v3
uv0, uv1, uv2, uv3 rgb0, rgb 1, rgb2, rgb3 evmx
Vertex coordinate vector (input)
Texture coordinate vector (input)
Vertex color data (input)
Pointer arrays for clip vector data (20, output)
Explanation
This function clips six surfaces of a quadrilateral (linked triangle) having vertices v0, v1, and v2, and defined by InitClip(). Angle information is stored in evmx. The output number of vertices is returned.
Effective output clip vector data:
evmx[i] -> v evmx[i] -> sxyz evmx[i] -> sxyz.pad evmx[i] -> sxy evmx[i] -> rgb evmx[i] -> txuv evmx[i] -> chx evmx[i] -> chy
Local Object 3D Vertex
Screen 3D Vertex
Fog effect interpolation value (p) Screen 2D Vertex Vertex Color Data Texture Mapping Data chx = vz* (hw/2)/h chy = vz* (vw/2)/h
This function reserves the pointer arrays (20 pointer arrays = 80 bytes), including the work area.
Return value
Output number of vertices
294 Basic Geometry Library (libgte) Functions
cln
Syntax
long cln (a) long a;
Arguments
a Value
Explanation This function uses fixed point math (where 4096 = 1 .0) to find the fixed point natural logarithm. Argument format is as follows:
a : (1, 19, 12)
return value : (1, 19, 12)
Return value ln (a)
Runtime Library Release 3.0
ColorCol
Finds a local color from a local light vector. Syntax
Basic Geometry Library (libgte) Functions 295
void ColorCol (v0, v1, v2) VECTOR *v0; CVECTOR *v1; CVECTOR *v2;
Arguments
v0 Local light vector (input)
v1 Primary color vector (input)
v2 Color vector (output)
Explanation This function calculates the following: LC = BK + LCM*v0
v2 = v1*LC (product of multiplication) The argument format is as follows: v0 -> vx, vy, vz : (1, 19, 12)
v1 -> r, g, b: (0, 8, 0)
v2 -> r, g, b: (0, 8, 0)
Return value None.
Runtime Library Release 3.0
ColorDpq
Finds a local color from a local light vector, and performs depth queuing. Syntax
void ColorDpq (v0, v1, p, v2)
VECTOR *v0; CVECTOR *v1; long p;
CVECTOR *v2;
Arguments
v0 Local light vector (input)
v1 Primary color vector (input)
p Interpolation value (input)
v2 Color vector (output)
Explanation
This function calculates the following: LC = BK+LCM*v0
v2=p*v1*LC + (1-p)*FC
v1 * LC is the product of multiplication. The argument format is as follows:
v0 -> vx, vy, vz vl -> r, g, b
p
v2 -> r, g, b
Return value None.
: (1, 19, 12) : (0, 8, 0) : (0, 20, 12) : (0, 8, 0)
ColorMatCol
Finds a color. Syntax
void ColorMatCol (v0, v1, v2, matc)
SVECTOR *v0; CVECTOR *v1; CVECTOR *v2; long matc;
Arguments
v0 Normal vector (input)
v1 Primary color vector (input)
v2 Color vector (output)
matc Material (output)
Explanation
This function performs the following calculations: LLV = LLM*v0
LLV = LLV^ (2^matc)
LC = BK + LCM*LLV
v2 = v1*LC (separate multiplications)
The argument format is as follows:
v0 -> vx, vy, vz : (1, 3, 12)
v1 -> r, g, b
v2 -> r, g, b matc
Return value None.
: (0, 8, 0) : (0, 8, 0) : (0, 32, 0)
ColorMatDpq
Depth queuing. Syntax
void ColorMatDpq (v0, v1, p, v2, matc) SVECTOR *v0;
CVECTOR *v1; long p;
CVECTOR *v2; long matc;
Arguments
Normal vector (input) Primary color vector (input) Interpolation value (output) Color vector (output) Material (output)
Explanation
This function performs the following calculations:
LLV = LLM*v0
LLV = LLV^ (2^matc) LC = BK + LCM*LLV
v2 = p*v1*LC + (1-p)*FC
v1*LC is the product of separate multiplications.
The argument format is as follows:
v0 -> vx, vy, vz
v1 -> r, g, b
p
v2 -> r, g, b matc
Return value None.
: (1, 3, 12) : (0, 8, 0)
: (0, 20, 12) : (0, 8, 0) : (0, 32, 0)
CompMatrix
Make a composite coordinate transformation matrix. Syntax
MATRIX* CompMatrix (m0, m1, m2) MATRIX *m0, *m1, *m2;
Arguments
m0, m1 Matrix (input)
m2 Matrix (output)
Explanation
This function makes a composite coordinate transformation matrix that includes parallel translation.
[m2 -> m] = [m0 -> m] * [m1 -> m]
(m2 -> t) = [m0 -> m] * (m1 -> t) + (m0 -> t)
However, the values of the elements of m1 -> t should be in the range (-2^1 5, 2^1 5).
<Argument format> m0 -> m[i][j] : (1, 3, 12) m0 -> t[i] : (1, 31, 0)
m1 -> m[i][j] : (1, 3, 12)
m1 -> t[i] : (1, 15, 0)
m2 -> m[i][j] : (1, 3, 12)
m2 -> t[i] : (1, 31, 0) Return value
m2 Remarks
This function destroys a constant rotation matrix.
300 Basic Geometry Library (libgte) Functions
csin
Syntax
long csin (a) long a;
Arguments
a Angle (in Playstation format)
Explanation
Find the sine function of the angle (in Playstation format) (4096 = 360 degrees) using fixed point math (where 4096 = 1.0).
The argument format is as follows:
a : Playstation-format (4096 = 360 degrees) return value : (1, 19, 12)
Return value sin (a)
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 301
csqrt
Syntax
long csqrt (a) long a;
Arguments
a Value Explanation
This function uses fixed point math (where 4096 = 1 .0) to find the fixed point square root.
This function is the same as the SquareRoot12 function except that it requires a smaller table memory area.
The argument format is as follows: a: (1, 19, 12)
return value : (1, 19, 12)
Return value sqrt (a)
Runtime Library Release 3.0
Division of flat triangle. Syntax
u_long *DivideF3 (v0, v1, v2, rgbc, s, ot, divp) SVECTOR *v0, *v1, *v2;
CVECTOR *rgbc;
POLY_F3 *s;
u_long *ot;
DIVPOLYGON3 *divp;
Arguments
v0, v1, v2 rgbc
s
ot
divp
Explanation
Vertex coordinate vectors (input) Color vector + code (input) GPU packet buffer address OT entry
Division work area (input)
This is a flat triangle division program. It divides a flat triangle (POLY_F3) indicated by the vertex coordinate vectors and color vector based on the divp -> ndiv value, and registers the result to OT.
The divp -> ndiv values and division format are shown below:
ndiv value processing
1 2x2 division
2 4x4 division
3 8x8 division
4 16 x 16 division
5 32 x 32 division
Return value
Updated GPU packet buffer address. Remarks
You must set divp -> ndiv (number of divisions) and divp -> pih.piv (display screen (clipping) resolution) beforehand.
Division of flat quadrilateral. Syntax
u_long *DivideF4 (v0, v1, v2, v3, rgbc, s, ot, divp) SVECTOR *v0, *v1, *v2, *v3;
CVECTOR *rgbc;
POLY_F4 *s;
u_long *ot;
DIVPOLYGON4 *divp;
Arguments
v0, v1, v2, v3 rgbc
s
ot
divp
Explanation
Vertex coordinate vectors (input) Color vector + code (input) GPU packet buffer address OT entry
Division work area (input)
This is a flat quadrilateral division program. It divides a flat quadrilateral (POLY_F4) indicated by the vertex coordinate vectors and color vector based on the divp -> ndiv value and registers the result to OT.
The divp -> ndiv values and division format are shown below:
ndiv value processing
1 2x2 division
2 4x4 division
3 8x8 division
4 16 x 16 division
5 32 x 32 division
Return value
Updated GPU packet buffer address. Remarks
You must set divp -> ndiv (number of divisions) and divp -> pih.piv (display screen (clipping) resolution) beforehand.
Division of flat textured triangle. Syntax
u_long *DivideFT3 (v0, v1, v2, uv0, uv1, uv2, rgbc, s, ot, divp) SVECTOR *v0, *v1, *v2;
u_long *uv0, *uv1, *uv2;
CVECTOR *rgbc;
POLY_FT3 *s;
u_long *ot;
DIVPOLYGON3 *divp;
Arguments
v0, v1, v2 uv0, uv1, uv2
Vertex coordinate vectors (input) Texture coordinate vector (input) v0+clut, uv1:uv1+tpage (uv0) Color vector +code (input)
GPU packet buffer address OT entry
Division work area (input)
rgbc s
ot
divp
Explanation
This is the flat textured triangle division program. It divides a flat textured triangle (POLY_FT3) indicated by the vertex coordinate vectors, texture coordinate vector, and color vector based on the divp -> ndiv value and registers the result to OT.
The divp -> ndiv values and division format are shown below:
ndiv value processing
1 2x2 division
2 4x4 division
3 8x8 division
4 16 x 16 division
5 32 x 32 division
Return value
Updated GPU packet buffer address. Remarks
You must set divp -> ndiv (number of divisions) and divp -> pih.piv (display screen (clipping) resolution) beforehand.
Division of flat textured quadrilateral. Syntax
u_long *DivideFT4 (v0, v1, v2, v3, uv0, uv1, uv2, uv3, rgbc, s, ot, divp) SVECTOR *v0, *v1, *v2, *v3;
u_long *uv0, *uv1, *uv2, *uv3;
CVECTOR *rgbc;
POLY_FT4 *s;
u_long *ot;
DIVPOLYGON4 *divp;
Arguments
v0, v1, v2, v3 Vertex coordinate vectors (input) uv0, uv1, uv2, uv3 Texture coordinate vector (input) uv0:uv0+clut, uv1:uv1+tpage
rgbc Color vector + code (input)
s GPU packet buffer address
ot OT entry
divp Division work area (input)
Explanation
This is the flat textured quadrilateral division program. It divides a flat textured quadrilateral (POLY_FT4) indicated by the vertex coordinate vectors, texture coordinate vector, and color vector based on the divp -> ndiv value and registers the result to OT.
The divp -> ndiv values and division format are shown below:
ndiv value processing
1 2x2 division
2 4x4 division
3 8x8 division
4 16 x 16 division
5 32 x 32 division
Return value
Updated GPU packet buffer address. Remarks
You must set divp -> ndiv (number of divisions) and divp -> pih.piv (display screen (clipping) resolution) beforehand.
Division of Gouraud triangle. Syntax
u_long *DivideG3 (v0, v1, v2, rgb0, rgb1, rgb2, s, ot, divp) SVECTOR *v0, *v1, *v2;
CVECTOR *rgb0, *rgb 1, *rgb2;
POLY_G3 *s;
u_long *ot;
DIVPOLYGON3 *divp;
Arguments
v0, v1, v2 Vertex coordinate vectors (input)
rgb0, rgb1, rgb2 Color vector (input) rgb0:rgb0+code
s GPU packet buffer address
ot OT entry
divp Division work area (input)
Explanation
This is a Gouraud-shaded triangle division program. It divides a Gouraud-shaded (POLY_G3) triangle indicated by the vertex coordinate vectors and color vector based on the divp -> ndiv value and registers the result to OT.
The divp -> ndiv values and division format are shown below:
ndiv value processing
1 2x2 division
2 4x4 division
3 8x8 division
4 16 x 16 division
5 32 x 32 division
Return value
Updated GPU packet buffer address. Remarks
You must set divp -> ndiv (number of divisions) and divp -> pih.piv (display screen (clipping) resolution) beforehand.
Division of Gouraud-shaded quadrilateral. Syntax
u_long *DivideG4 (v0, v1, v2, v3, rgb0, rgb1, rgb2, rgb3, s, ot, divp) SVECTOR *v0, *v1, *v2, *v3;
CVECTOR *rgb0, *rgb 1, *rgb2, *rgb3;
POLY_G4 *s;
u_long *ot;
DIVPOLYGON4 *divp;
Arguments
v0, v1, v2, v3 Vertex coordinate vectors (input) rgb0, rgb1, rgb2, rgb3
color vector (input)
rgb0:rgb0+code
s GPU packet buffer address
ot OT entry
divp Division work area (input)
Explanation
This is the Gouraud-shaded quadrilateral division program. It divides a Gouraud-shaded quadrilateral (POLY_G4) indicated by the vertex coordinate vectors and color vector based on the divp -> ndiv value and registers the result to OT.
The divp -> ndiv values and division format are shown below:
ndiv value processing
1 2x2 division
2 4x4 division
3 8x8 division
4 16 x 16 division
5 32 x 32 division
Return value
Updated GPU packet buffer address. Remarks
You must set divp -> ndiv (number of divisions) and divp -> pih.piv (display screen (clipping) resolution) beforehand.
308 Basic Geometry Library (libgte) Functions
DivideGT3
Division of Gouraud-shaded, textured triangle. Syntax
u_long *DivideGT3 (v0, v1, v2, uv0, uv1, uv2, rgb0, rgb1, rgb2, s, ot, divp) SVECTOR *v0, *v1, *v2;
u_long *uv0, *uv1, *uv2;
CVECTOR *rgb0, *rgb 1, *rgb2;
POLY_GT3 *s;
u_long *ot;
DIVPOLYGON3 *divp;
Arguments
v0, v1, v2 uv0, uv1, uv2
rgb0, rgb1, rgb2 rgb0:rgb0+code s
ot
divp
Explanation
Vertex coordinate vectors (input) Texture coordinate vector (input) uv0:uv0+clut, uv1:uv1+tpage Color vector (input)
GPU packet buffer address OT entry
Division work area (input)
This is the Gouraud-shaded textured triangle division program. It divides a Gouraud-shaded textured triangle (POLY_GT3) indicated by the vertex coordinate vectors, texture coordinate vector, and color vector based on the divp -> ndiv value and registers the result to OT.
The divp -> ndiv values and division format are shown below:
ndiv value processing
1 2x2 division
2 4x4 division
3 8x8 division
4 16 x 16 division
5 32 x 32 division
Return value
Updated GPU packet buffer address. Remarks
You must set divp -> ndiv (number of divisions) and divp -> pih.piv (display screen (clipping) resolution) beforehand.
Division of Gouraud-shaded textured quadrilateral. Syntax
u_long *DivideGT4 (v0, v1, v2, v3, uv0, uv1, uv2, uv3, rgb0, rgb1, rgb2, rgb3, s, ot, divp) SVECTOR *v0, *v1, *v2, *v3;
u_long *uv0, *uv1, *uv2, *uv3;
CVECTOR *rgb0, *rgb 1, *rgb2, *rgb3;
POLY_GT4 *s;
u_long *ot;
DIVPOLYGON4 *divp;
Arguments
v0, v1, v2, v3 Vertex coordinate vectors (input)
uv0, uv1, uv2, uv3 Texture coordinate vector (input) uv0:uv0+clut, uv1:uv1+tpage
rgb0, rgb1, rgb2, rgb3 Color vector (input)
rgb0:rgb0+code
s GPU packet buffer address
ot OT entry
divp Division work area (input)
Explanation
This is the Gouraud-shaded textured quadrilateral division program. It divides a Gouraudshaded textured quadrilateral (POLY_GT4) indicated by the vertex coordinate vectors, texture coordinate vector, and color vector based on the divp -> ndiv value and registers the result to OT.
The divp -> ndiv values and division format are shown below:
ndiv value processing
1 2x2 division
2 4x4 division
3 8x8 division
4 16 x 16 division
5 32 x 32 division
Return value
Updated GPU packet buffer address. Remarks
You must set divp -> ndiv (number of divisions) and divp -> pih.piv (display screen (clipping) resolution) beforehand.
310 Basic Geometry Library (libgte) Functions
DpqColor
Interpolation of a primary color vector and far color. Syntax
void DpqColor (v0, p, v1) CVECTOR *v0; long p;
CVECTOR *v1;
Arguments
v0 Primary color vector (input)
p Interpolation value (input)
v1 Primary color vector (input)
Explanation
This function calculates v1=p*v0+ (1-p)*FC. The argument format is as follows:
v0 -> r, g, b : (0, 8, 0)
p : (0, 20, 12) v1 -> r, g, b : (0, 8, 0)
Return value None.
Runtime Library Release 3.0
DpqColor3
Interpolation of three primary color vectors and far color. Syntax
Basic Geometry Library (libgte) Functions 311
void DpqColor3 (v0, v1, v2, p, v3, v4, v5)
CVECTOR *v0, *v1, *v2; long p;
CVECTOR *v3, *v4, *v5;
Arguments
v0, v1, v2 Primary color vectors (input)
p Interpolation value (input)
v3, v4, v5 Color vectors (output)
Explanation
This function calculates:
v3 = p* (v0)+ (1-p) * FC.
v4 = p* (v1)+ (1-p) * FC.
v5 = p* (v2)+ (1-p) * FC.
The argument format is follows:
v0, v1, v2 -> r, g, b : (0, 8, 0)
p : (0, 20, 12)
v3, v4, v5 -> r, g, b : (0, 8, 0)
Return value
None.
Runtime Library Release 3.0
DpqColorLight
Interpolation of the product from the multiplication of a local color vector by primary color vector, and far color.
Syntax
void DpqColorLight (v0, v1, p, v2)
SVECTOR *v0; CVECTOR *v1; long p;
CVECTOR *v2;
Arguments
v0 Local color vector (input)
v1 Primary color vector (input)
p Interpolation value (input)
v2 Color vector (output)
Explanation
This function calculates v2 = p*(v1*v0) + (1-p)*FC. v1*v0 are separate multiplication products. The argument format is as follows:
v0 -> vx, vy, vz : (1, 3, 12)
v1 -> r, g, b : (0, 8, 0)
p : (0, 20, 12)
v2 -> r, g, b : (0, 8, 0)
Return value
None.
GsPrstF3L, GsPrstF3LFG, GsPrstF3NL, GsPrstNF3
TMD data flat triangle processing.
GsPrstF3L: flat triangle (light source calculation)
GsPrstF3LFG: flat triangle (light source calculation + FOG) GsPrstF3NL: flat triangle (without light source calculation) GsPrstNF3: flat triangle (without light source calculation)
Syntax
u_long *GsPrstF3L (primtop, vertop, nortop, s, n, shift, otp) u_long *GsPrstF3LFG (primtop, vertop, nortop, s, n, shift, otp) u_long *GsPrstF3NL (primtop, vertop, nortop, s, n, shift, otp) u_long *GsPrstNF3 (primtop, vertop, s, n, shift, otp) TMD_P_F3 *primtop;
(TMD_P_NF3 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_F3 *s;
u_long n;
u_long shift;
GsOT *otp;
Arguments primtop
vertop
nortop
s n shift
otp
Explanation
This function performs coordinate transformation, perspective transformation, normal line clipping, and light source calculation (GsPrstF3L(), Gs PrstF3LFG()), for n (number of) flat triangles linked to the TMD file, completes the GPU packet in the buffer, and links to OT.
Two packets per polygon are preset in the buffer. (see libgs: PresetObject) See libgs in Vol. 1 for details.
Return value
Updated GPU packet buffer address.
GsPrstF4L, GsPrstF4LFG, GsPrstF4NL, GsPrstNF4
TMD data flat quadrilateral processing
GsPrstF4L: flat rectangle (light source calculation)
GsPrstF4LFG: flat rectangle (light source calculation + FOG) GsPrstF4NL: flat rectangle (without light source calculation) GsPrstNF4: flat rectangle (without light source calculation)
Syntax
u_long *GsPrstF4L (primtop, vertop, nortop, s, n, shift, otp) u_long *GsPrstF4LFG (primtop, vertop, nortop, s, n, shift, otp) u_long *GsPrstF4NL (primtop, vertop, nortop, s, n, shift, otp) u_long *GsPrstNF4 (primtop, vertop, s, n, shift, otp) TMD_P_F4 *primtop;
(TMD_P_NF4 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_F4 *s;
u_long n;
u_long shift;
GsOT *otp;
Arguments primtop
vertop
nortop
s n shift
otp
Explanation
This function performs coordinate transformation, perspective transformation, normal line clipping, and light source calculation (GsPrstF4L(), Gs PrstF4LFG()), for n (number of) flat rectangles linked to the TMD file, completes the GPU packet in the buffer, and links to OT.
Two packets per polygon are preset in the buffer (see libgs: GsPresetObject). See libgs in Vol. 1 for details.
Return value
Updated GPU packet buffer address.
GsPrstG3L, GsPrstG3LFG, GsPrstG3NL, GsPrstNG3
TMD data Gouraud-shaded, triangle processing.
GsPrstG3L: Gouraud triangle (light source calculation) GsPrstG3LFG: Gouraud triangle (light source calculation + FOG) GsPrstG3NL: Gouraud triangle (without light source calculation) GsPrstNG3: Gouraud triangle (without light source calculation)
Syntax
u_long *GsPrstG3L (primtop, vertop, nortop, s, n, shift, otp) u_long *GsPrstG3LFG (primtop, vertop, nortop, s, n, shift, otp) u_long *GsPrstG3NL (primtop, vertop, nortop, s, n, shift, otp) u_long *GsPrstNG3 (primtop, vertop, s, n, shift, otp)
TMD_P_G3 *primtop;
(TMD_P_NG3 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_G3 *s;
u_long n;
u_long shift;
GsOT *otp;
Arguments primtop
vertop
nortop
s n shift
otp
Explanation
This function performs coordinate transformation, perspective transformation, normal line clipping, and light source calculation (GsPrstG3L(), Gs PrstG3LFG()), for n (number of) Gouraud triangles linked to the TMD file, completes the GPU packet in the buffer, and links to OT.
Two packets per polygon are preset in the buffer. (see libgs: GsPresetObject)
See libgs in Vol. 1 for details.
Return value
Updated GPU packet buffer address.
GsPrstG4L, GsPrstG4LFG, GsPrstG4NL, GsPrstNG4
TMD data Gouraud-shaded, quadrilateral processing.
GsPrstG4L: Gouraud rectangle (light source calculation) GsPrstG4LFG: Gouraud rectangle (light source calculation + FOG) GsPrstG4NL: Gouraud rectangle (without light source calculation) GsPrstNG4: Gouraud rectangle (without light source calculation)
Syntax
u_long *GsPrstG4L (primtop, vertop, nortop, s, n, shift, otp)
u_long *GsPrstG4LFG (primtop, vertop, nortop, s, n, shift, otp)
u_long *GsPrstG4NL (primtop, vertop, nortop, s, n, shift, otp)
u_long *GsPrstNG4 (primtop, vertop, s, n, shift, otp)
TMD_P_G4 *primtop;
(TMD_P_NG4 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_G4 *s; u_long n; u_long shift; GsOT *otp;
Arguments primtop
vertop
nortop
s n shift
otp
Explanation
This function performs coordinate transformation, perspective transformation, normal line clipping, and light source calculation (GsPrstG4L(), Gs PrstG4LFG()), for n (number of) Gouraud rectangles linked to the TMD file, completes the GPU packet in the buffer, and links to OT.
Two packets per polygon are preset in the buffer. (see libgs: GsPresetObject) See libgs in Vol. 1 for details.
Return value
Updated GPU packet buffer address.
GsPrstTF3L, GsPrstTF3LFG, GsPrstTF3NL, GsPrstTNF3
TMD data flat, textured triangle processing.
GsPrstTF3L: flat textured triangle (light source calculation) GsPrstTF3LFG: flat textured triangle (light source calculation + FOG) GsPrstTF3NL: flat textured triangle (without light source calculation) GsPrstTNF3: flat textured triangle (without light source calculation)
Syntax
u_long *GsPrstTF3L (primtop, vertop, nortop, s, n, shift, otp)
u_long *GsPrstTF3LFG (primtop, vertop, nortop, s, n, shift, otp)
u_long *GsPrstTF3NL (primtop, vertop, nortop, s, n, shift, otp)
u_long *GsPrstTNF3 (primtop, vertop, s, n, shift, otp)
TM D_P_TF3 *primtop;
(TMD_P_TNF3 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_FT3 *s; u_long n; u_long shift; GsOT *otp;
Arguments primtop
vertop
nortop
s n shift
otp
Explanation
This function performs coordinate transformation, perspective transformation, normal line clipping, and light source calculation (GsPrstTF3L(), Gs PrstTF3LFG()), for n (number of) flat textured triangles linked to the TMD file, completes the GPU packet in the buffer, and links to OT.
Two packets per polygon are preset in the buffer (see libgs: GsPresetObject). See libgs in Vol. 1 for details.
Return value
Updated GPU packet buffer address.
GsPrstTF4L, GsPrstTF4LFG, GsPrstTF4NL, GsPrstTNF4
TMD data flat, textured quadrilateral processing.
GsPrstTF4L: flat textured rectangle (light source calculation) GsPrstTF4LFG: flat textured rectangle (light source calculation + FOG) GsPrstTF4NL: flat textured rectangle (without light source
calculation)
GsPrstTNF4: flat textured rectangle (without light source calculation)
Syntax
u_long *GsPrstTF4L (primtop, vertop, nortop, s, n, shift, otp)
u_long *GsPrstTF4LFG (primtop, vertop, nortop, s, n, shift, otp)
u_long *GsPrstTF4NL (primtop, vertop, nortop, s, n, shift, otp)
u_long *GsPrstTNF4 (primtop, vertop, s, n, shift, otp)
TM D_P_TF4 *primtop;
(TMD_P_TNF4 *primtop;
SVECTOR *vertop;
SVECTOR *nortop;
POLY_FT4 *s; u_long n; u_long shift; GsOT *otp;
Arguments primtop
vertop
nortop
s n shift
otp
Explanation
This function performs coordinate transformation, perspective transformation, normal line clipping, and light source calculation GsPrstTF4L(), Gs PrstTF4LFG()), for n (number of) flat textured rectangles linked to the TMD file, completes the GPU packet in the buffer, and links to OT.
Two packets per polygon are preset in the buffer (see libgs: GsPresetObject). See libgs in Vol. 1 for details.
Return value
Updated GPU packet buffer address.
GsPrstTG3L, GsPrstTG3LFG, GsPrstTG3NL, GsPrstTNG3
TMD data Gouraud-shaded, textured triangle processing.
GsPrstTG3L: Gouraud texture triangle (light source calculation) GsPrstTG3LFG: Gouraud texture triangle (light source calculation + FOG) GsPrstTG3NL: Gouraud texture triangle (without light source calculation) GsPrstTNG3: Gouraud texture triangle (without light source calculation)
Syntax
u_long *GsPrstTG3L (primtop, vertop, nortop, s, n, shift, otp)
u_long *GsPrstTG3LFG (primtop, vertop, nortop, s, n, shift, otp)
u_long *GsPrstTG3NL (primtop, vertop, nortop, s, n, shift, otp)
u_long *GsPrstTNG3 (primtop, vertop, s, n, shift, otp)
TMD_P_TG3 *primtop;
(TMD_P_TNG3 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_GT3 *s; u_long n; u_long shift; GsOT *otp;
Arguments primtop
vertop
nortop
s n shift
otp
Explanation
This function performs coordinate transformation, perspective transformation, normal line clipping, and light source calculation (GsPrstTG3L(), Gs PrstTG3LFG()), for n (number of) Gouraud texture triangles linked to the TMD file, completes the GPU packet in the buffer, and links to OT.
Two packets per polygon are preset in the buffer (see libgs: GsPresetObject). See libgs in Vol. 1 for details.
Return value
Updated GPU packet buffer address.
GsPrstTG4L, GsPrstTG4LFG, GsPrstTG4NL, GsPrstTNG4
TMD data Gouraud-shaded, textured quadrilateral processing. GsPrstTG4L: Gouraud texture rectangle (light source calculation) GsPrstTG4LFG: Gouraud texture rectangle (light source calculation + FOG) GsPrstTG4NL: Gouraud texture rectangle (without light source calculation) GsPrstTNG4: Gouraud texture rectangle (without light source calculation)
Syntax
u_long *GsPrstTG4L (primtop, vertop, nortop, s, n, shift, otp)
u_long *GsPrstTG4LFG (primtop, vertop, nortop, s, n, shift, otp)
u_long *GsPrstTG4NL (primtop, vertop, nortop, s, n, shift, otp)
u_long *GsPrstTNG4 (primtop, vertop, s, n, shift, otp)
TMD_P_TG4 *primtop;
(TMD_P_TNG4 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_GT4 *s; u_long n; u_long shift; GsOT *otp;
Arguments primtop
vertop
nortop
s n shift
otp
Explanation
This function performs coordinate transformation, perspective transformation, normal line clipping, and light source calculation (GsPrstTG4L(), Gs PrstTG4LFG()), for n (number of) Gouraud texture rectangles linked to the TMD file, completes the GPU packet in the buffer, and links to OT.
Two packets per polygon are preset in the buffer (see libgs: GsPresetObject). See libgs in Vol. 1 for details.
Return value
Updated GPU packet buffer address.
GsTMDdivF3L, GsTMDdivF3LFG, GsTMDdivF3NL, GsTMDdivNF3
TMD data flat triangle processing.
GsTMDdivF3L: flat triangle (light source calculation) GsTMDdivF3LFG: flat triangle (light source calculation + FOG) GsTMDdivF3NL: flat triangle (without light source calculation) GsTMDdivNF3: flat triangle (without light source calculation)
Syntax
u_long *GsTMDdivF3L (primtop, vertop, nortop, s, n, shift, otp, divp)
u_long *GsTMDdivF3LFG (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivF3NL (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivNF3 (primtop, vertop, s, n, shift, otp, divp)
TMD_P_F3 *primtop; (TMD_P_NF3 *primtop;) SVECTOR *vertop; SVECTOR *nortop; POLY_F3 *s;
u_long n;
u_long shift;
GsOT *otp;
DIVPOLYGON3 *divp;
Arguments primtop
vertop
nortop
s n shift
otp
divp
Explanation
For n (number of) flat triangles linked to the TMD file, this function divides polygons based on the divp -> ndiv value, performs coordinate transformation, perspective transformation, normal line clipping, display screen clipping, and light source calculation (GsTMDdivF3L(), Gs TMDdivF3LFG()), for the divided polygons, and then completes the GPU packet in the buffer and links to OT.
The divp -> ndiv values and division format are shown below:
ndiv value processing
1 2x2 division
2 4x4 division
3 8x8 division
4 16 x 16 division
5 32 x 32 division
Return value
Updated GPU packet buffer address.
Remarks
You must set divp -> ndiv (number of divisions) and divp -> pih.piv (display screen (clipping) resolution) beforehand.
GsTMDdivF4L, GsTMDdivF4LFG, GsTMDdivF4NL, GsTMDdivNF4
TMD data flat quadrilateral processing.
GsTMDdivF4L: flat rectangle (light source calculation) GsTMDdivF4LFG: flat rectangle (light source calculation + FOG) GsTMDdivF4NL: flat rectangle (without light source calculation) GsTMDdivNF4: flat rectangle (without light source calculation)
Syntax
u_long *GsTMDdivF4L (primtop, vertop, nortop, s, n, shift, otp, divp)
u_long *GsTMDdivF4LFG (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivF4NL (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivNF4 (primtop, vertop, s, n, shift, otp, divp)
TMD_P_F4 *primtop; (TMD_P_NF4 *primtop;) SVECTOR *vertop; SVECTOR *nortop; POLY_F4 *s;
u_long n;
u_long shift;
GsOT *otp;
DIVPOLYGON4 *divp;
Arguments primtop
vertop
nortop
s n shift
otp
divp
Explanation
For n (number of) flat rectangles linked to the TMD file, this function divides polygons based on the divp -> ndiv value, performs coordinate transformation, perspective transformation, normal line clipping, display screen clipping, and light source calculation (GsTMDdivF4L(), Gs TMDdivF4LFG()), for the divided polygons, and then completes the GPU packet in the buffer and links to OT.
The divp -> ndiv values and division format are shown below:
ndiv value processing
1 2x2 division
2 4x4 division
3 8x8 division
4 16 x 16 division
5 32 x 32 division
Return value
Updated GPU packet buffer address.
Remarks
You must set divp -> ndiv (number of divisions) and divp -> pih.piv (display screen (clipping) resolution) beforehand.
GsTMDdivG3L, GsTMDdivG3LFG, GsTMDdivG3NL, GsTMDdivNG3
TMD data Gouraud-shaded, triangle processing.
GsTMDdivG3L: Gouraud triangle (light source calculation) GsTMDdivG3LFG: Gouraud triangle (light source calculation + FOG) GsTMDdivG3NL: Gouraud triangle (without light source calculation) GsTMDdivNG3: Gouraud triangle (without light source calculation)
Syntax
u_long *GsTMDdivG3L (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivG3LFG (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivG3NL (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivNG3 (primtop, vertop, s, n, shift, otp, divp) TMD_P_G3 *primtop;
(TMD_P_NG3 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_G3 *s;
u_long n;
u_long shift;
GsOT *otp;
DIVPOLYGON3 *divp;
Arguments primtop
vertop
nortop
s n shift
otp
divp
Explanation
For n (number of) Gouraud triangles linked to the TMD file, this function divides polygons based on the divp -> ndiv value, performs coordinate transformation, perspective transformation, normal line clipping, display screen clipping, and light source calculation (GsTMDdivG3L(), Gs TMDdivG3LFG()), for the divided polygons, and then completes the GPU packet in the buffer and links to OT.
The divp -> ndiv values and division format are shown below:
ndiv value processing
1 2x2 division
2 4x4 division
3 8x8 division
4 16 x 16 division
5 32 x 32 division
Return value
Updated GPU packet buffer address.
Remarks
You must set divp -> ndiv (number of divisions) and divp -> pih.piv (display screen (clipping) resolution) beforehand.
Basic Geometry Library (libgte) Functions 327
GsTMDdivG4L, GsTMDdivG4LFG, GsTMDdivG4N, GsTMDdivNG4
TMD data Gouraud-shaded, quadrilateral processing.
GsTMDdivG4L: Gouraud rectangle (light source calculation) GsTMDdivG4LFG: Gouraud rectangle (light source calculation + FOG) GsTMDdivG4NL: Gouraud rectangle (without light source calculation) GsTMDdivNG4: Gouraud rectangle (without light source calculation)
Syntax
u_long *GsTMDdivG4L (primtop, vertop, nortop, s, n, shift, otp, divp)
u_long *GsTMDdivG4LFG (primtop, vertop, nortop, s, n, shift, otp, divp)
u_long *GsTMDdivG4NL (primtop, vertop, nortop, s, n, shift, otp, divp)
u_long *GsTMDdivNG4 (primtop, vertop, s, n, shift, otp, divp)
TMD_P_G4 *primtop;
(TMD_P_NG4 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_G4 *s; u_long n;
u_long shift; GsOT *otp; DIVPOLYGON4 *divp;
Arguments
primtop
vertop
nortop
s n shift
otp
divp
Explanation
Top address of TMD PRIMITIVE
In GsTMDdivNG4(), a packet without a normal line
Top address of TMD VERTEX
Top address of TMD NORMAL
GPU packet buffer address
Number of target polygons
Specifies which bit of Z value to shift to right when assigning OT. Pointer to OT
Division work area
For n (number of) Gouraud rectangles linked to the TMD file, this function divides polygons based on the divp -> ndiv value, performs coordinate transformation, perspective transformation, normal line clipping, display screen clipping, and light source calculation (GsTMDdivG4L(), Gs TMDdivG4LFG()), for the divided polygons, and then completes the GPU packet in the buffer and links to OT.
The divp -> ndiv values and division format are shown below:
ndiv value processing
1 2x2 division
2 4x4 division
3 8x8 division
4 16 x 16 division
5 32 x 32 division
Return value
Updated GPU packet buffer address.
Remarks
You must set divp -> ndiv (number of divisions) and divp -> pih.piv (display screen (clipping) resolution) beforehand.
Basic Geometry Library (libgte) Functions 329
GsTMDdivTF3L, GsTMDdivTF3LFG, GsTMDdivTF3NL, GsTMDdivTNF3
TMD data flat, textured triangle processing.
GsTMDdivTF3L: flat textured triangle (light source calculation) GsTMDdivTF3LFG: flat textured triangle (light source calculation + FOG) GsTMDdivTF3NL: flat textured triangle (without light source calculation) GsTMDdivTNF3: flat textured triangle (without light source calculation)
Syntax
u_long *GsTMDdivTF3L (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivTF3LFG (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivTF3NL (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivTNF3 (primtop, vertop, s, n, shift, otp, divp) TM D_P_TF3 *primtop;
(TMD_P_TNF3 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_FT3 *s;
u_long n;
u_long shift;
GsOT *otp;
DIVPOLYGON3 *divp;
Arguments
primtop
vertop
nortop
s n shift
otp
divp
Explanation
Top address of TMD PRIMITIVE
In GsTMDdivTNF3(), a packet without a normal line
Top address of TMD VERTEX
Top address of TMD NORMAL
GPU packet buffer address
Number of target polygons
Specifies which bit of Z value to shift to right when assigning OT. Pointer to OT
Division work area
For n (number of) flat textured triangles linked to the TMD file, this function divides polygons based on the divp -> ndiv value, performs coordinate transformation, perspective transformation, normal line clipping, display screen clipping, and light source calculation (GsTMDdivTF3L(), Gs TMDdivTF3LFG()), for the divided polygons, and then completes the GPU packet in the buffer and links to OT.
The divp -> ndiv values and division format are shown below:
ndiv value processing
1 2x2 division
2 4x4 division
3 8x8 division
4 16 x 16 division
5 32 x 32 division
Return value
Updated GPU packet buffer address.
Remarks
You must set divp -> ndiv (number of divisions) and divp -> pih.piv (display screen (clipping) resolution) beforehand.
Basic Geometry Library (libgte) Functions 331
GsTMDdivTF4L, GsTMDdivTF4LFG, GsTMDdivTF4NL, GsTMDdivTNF4
TMD data flat, textured quadrilateral processing.
GsTMDdivTF4L: flat textured rectangle (light source calculation) GsTMDdivTF4LFG: flat textured rectangle (light source calculation + FOG) GsTMDdivTF4NL: flat textured rectangle (without light source calculation) GsTMDdivTNF4: flat textured rectangle (without light source calculation)
Syntax
u_long *GsTMDdivTF4L (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivTF4LFG (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivTF4NL (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivTNF4 (primtop, vertop, s, n, shift, otp, divp) TM D_P_TF4 *primtop;
(TMD_P_TNF4 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_FT4 *s;
u_long n;
u_long shift;
GsOT *otp;
DIVPOLYGON4 *divp;
Arguments
primtop
vertop
nortop
s n shift
otp
divp
Explanation
Top address of TMD PRIMITIVE
In GsTMDdivTNF4(), a packet without a normal line
Top address of TMD VERTEX
Top address of TMD NORMAL
GPU packet buffer address
Number of target polygons
Specifies which bit of Z value to shift to right when assigning OT. Pointer to OT
Division work area
For n (number of) flat textured rectangles linked to the TMD file, this function divides polygons based on the divp -> ndiv value, performs coordinate transformation, perspective transformation, normal line clipping, display screen clipping, and light source calculation (GsTMDdivTF4L(), Gs TMDdivTF4LFG()), for the divided polygons, and then completes the GPU packet in the buffer and links to OT.
The divp -> ndiv values and division format are shown below:
ndiv value processing
1 2x2 division
2 4x4 division
3 8x8 division
4 16 x 16 division
5 32 x 32 division
Return value
Updated GPU packet buffer address. CAUTION
Remarks
You must set divp -> ndiv (number of divisions) and divp -> pih.piv (display screen (clipping) resolution) beforehand.
Basic Geometry Library (libgte) Functions 333
GsTMDdivTG3L, GsTMDdivTG3LFG, GsTMDdivTG3NL, GsTMDdivTNG3
TMD data Gouraud-shaded, textured triangle processing.
GsTMDdivTG3L: Gouraud texture triangle (light source calculation) GsTMDdivTG3LFG: Gouraud texture triangle (light source calculation + FOG) GsTMDdivTG3NL: Gouraud texture triangle (without light source calculation) GsTMDdivTNG3: Gouraud texture triangle (without light source calculation)
Syntax
u_long *GsTMDdivTG3L (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivTG3LFG (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivTG3NL (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivTNG3 (primtop, vertop, s, n, shift, otp, divp) TMD_P_TG3 *primtop;
(TMD_P_TNG3 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_GT3 *s;
u_long n;
u_long shift;
GsOT *otp;
DIVPOLYGON3 *divp;
Arguments
primtop
vertop
nortop
s n shift
otp
divp
Explanation
Top address of TMD PRIMITIVE
In GsTMDdivTNG3(), a packet without a normal line
Top address of TMD VERTEX
Top address of TMD NORMAL
GPU packet buffer address
Number of target polygons
Specifies which bit of Z value to shift to right when assigning OT. Pointer to OT
Division work area
For n (number of) Gouraud texture triangles linked to the TMD file, this function divides polygons based on the divp -> ndiv value, performs coordinate transformation, perspective transformation, normal line clipping, display screen clipping, and light source calculation (GsTMDdivTG3L(), Gs TMDdivTG3LFG()), for the divided polygons, and then completes the GPU packet in the buffer and links to OT.
The divp -> ndiv values and division format are shown below:
ndiv value processing
1 2x2 division
2 4x4 division
3 8x8 division
4 16 x 16 division
5 32 x 32 division
Return value
Updated GPU packet buffer address.
Remarks
You must set divp -> ndiv (number of divisions) and divp -> pih.piv (display screen (clipping) resolution) beforehand.
Basic Geometry Library (libgte) Functions 335
GsTMDdivTG4L, GsTMDdivTG4LFG, GsTMDdivTG4NL, GsTMDdivTNG4
TMD data Gouraud-shaded, textured quadrilateral processing.
GsTMDdivTG4L: Gouraud texture rectangle (light source calculation) GsTMDdivTG4LFG: Gouraud texture rectangle (light source calculation + FOG) GsTMDdivTG4NL: Gouraud texture rectangle (without light source calculation) GsTMDdivTNG4: Gouraud texture rectangle (without light source calculation)
Syntax
u_long *GsTMDdivTG4L (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivTG4LFG (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivTG4NL (primtop, vertop, nortop, s, n, shift, otp, divp) u_long *GsTMDdivTNG4 (primtop, vertop, s, n, shift, otp, divp) TMD_P_TG4 *primtop;
(TMD_P_TNG4 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_GT4 *s;
u_long n;
u_long shift;
GsOT *otp;
DIVPOLYGON4 *divp;
Arguments
primtop
vertop
nortop
s n shift
otp
divp
Explanation
Top address of TMD PRIMITIVE
In GsTMDdivTNG4(), a packet without a normal line
Top address of TMD VERTEX
Top address of TMD NORMAL
GPU packet buffer address
Number of target polygons
Specifies which bit of Z value to shift to right when assigning OT. Pointer to OT
Division work area
For n (number of) Gouraud texture rectangles linked to the TMD file, this function divides polygons based on the divp -> ndiv value, performs coordinate transformation, perspective transformation, normal line clipping, display screen clipping, and light source calculation (GsTMDdivTG4L(), Gs TMDdivTG4LFG()), for the divided polygons, and then completes the GPU packet in the buffer and links to OT.
The divp -> ndiv values and division format are shown below:
ndiv value processing
1 2x2 division
2 4x4 division
3 8x8 division
4 16 x 16 division
5 32 x 32 division
Return value
Updated GPU packet buffer address.
Remarks
You must set divp -> ndiv (number of divisions) and divp -> pih.piv (display screen (clipping) resolution) beforehand.
GsTMDfastF3L, GsTMDfastF3LFG, GsTMDfastF3NL, GsTMDfastNF3
TMD data flat triangle processing.
GsTMDfastF3L: flat triangle (light source calculation) GsTMDfastF3LFG: flat triangle (light source calculation + FOG) GsTMDfastF3NL: flat triangle (without light source calculation) GsTMDfastNF3: flat triangle (without light source calculation)
Syntax
u_long *GsTMDfastF3L (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastF3LFG (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastF3NL (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastNF3 (primtop, vertop, s, n, shift, otp) TMD_P_F3 *primtop;
(TMD_P_NF3 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_F3 *s;
u_long n;
u_long shift;
GsOT *otp;
Arguments primtop
vertop
nortop
s n shift
otp
Explanation
This function performs coordinate transformation, perspective transformation, normal line clipping, and light source calculation (GsTMDfastF3L(), GsTMDfastF3LFG()), for n (number of) flat triangles linked to the TMD file, completes the GPU packet in the buffer, and links to OT.
See libgs in Vol. 1 for details.
Return value
Updated GPU packet buffer address.
GsTMDfastF4L, GsTMDfastF4LFG, GsTMDfastF4NL, GsTMDfastNF4
TMD data flat quadrilateral processing.
GsTMDfastF4L: flat rectangle (light source calculation) GsTMDfastF4LFG: flat rectangle (light source calculation + FOG) GsTMDfastF4NL: flat rectangle (without light source calculation) GsTMDfastNF4: flat rectangle (without light source calculation)
Syntax
u_long *GsTMDfastF4L (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastF4LFG (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastF4NL (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastNF4 (primtop, vertop, s, n, shift, otp) TMD_P_F4 *primtop;
(TMD_P_NF4 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_F4 *s;
u_long n;
u_long shift;
GsOT *otp;
Arguments primtop
vertop
nortop
s n shift
otp
Explanation
This function performs coordinate transformation, perspective transformation, normal line clipping, and light source calculation(GsTMDfastF4L(), GsTMDfastF4LFG()), for n (number of) flat rectangles linked to the TMD file, completes the GPU packet in the buffer, and links to OT.
See libgs in Vol. 1 for details.
Return value
Updated GPU packet buffer address.
GsTMDfastG3L, GsTMDfastG3LFG, GsTMDfastG3NL, GsTMDfastNG3
TMD data Gouraud-shaded, triangle processing.
GsTMDfastG3L: Gouraud triangle (light source calculation) GsTMDfastG3LFG: Gouraud triangle (light source calculation + FOG) GsTMDfastG3NL: Gouraud triangle (without light source calculation) GsTMDfastNG3: Gouraud triangle (without light source calculation)
Syntax
u_long *GsTMDfastG3L (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastG3LFG (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastG3NL (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastNG3 (primtop, vertop, s, n, shift, otp) TMD_P_G3 *primtop;
(TMD_P_NG3 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_G3 *s;
u_long n;
u_long shift;
GsOT *otp;
Arguments primtop
vertop
nortop
s n shift
otp
Explanation
This function performs coordinate transformation, perspective transformation, normal line clipping, and light source calculation(GsTMDfastG3L(), GsTMDfastG3LFG()), for n (number of) Gouraud triangles linked to the TMD file, completes the GPU packet in the buffer, and links to OT.
See libgs in Vol. 1 for details.
Return value
Updated GPU packet buffer address.
GsTMDfastG4L, GsTMDfastG4LFG, GsTMDfastG4NL, GsTMDfastNG4
TMD data Gouraud-shaded, quadrilateral processing.
GsTMDfastG4L: Gouraud rectangle (light source calculation) GsTMDfastG4LFG: Gouraud rectangle (light source calculation + FOG) GsTMDfastG4NL: Gouraud rectangle (without light source calculation) GsTMDfastNG4: Gouraud rectangle (without light source calculation)
Syntax
u_long *GsTMDfastG4L (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastG4LFG (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastG4NL (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastNG4 (primtop, vertop, s, n, shift, otp) TMD_P_G4 *primtop;
(TMD_P_NG4 *primtop
SVECTOR *vertop;
SVECTOR *nortop;
POLY_G4 *s;
u_long n;
u_long shift;
GsOT *otp;
Arguments primtop
vertop
nortop
s n shift
otp
Explanation
This function performs coordinate transformation, perspective transformation, normal line clipping, and light source calculation(GsTMDfastG4L(), GsTMDfastG4LFG()), for n (number of) Gouraud rectangles linked to the TMD file, completes the GPU packet in the buffer, and links to OT.
See libgs in Vol. 1 for details.
Return value
Updated GPU packet buffer address.
GsTMDfastTF3L, GsTMDfastTF3LFG, GsTMDfastTF3NL, GsTMDfastTNF3
TMD data flat, textured triangle processing.
GsTMDfastTF3L: flat textured triangle (light source calculation) GsTMDfastTF3LFG: flat textured triangle (light source calculation + FOG) GsTMDfastTF3NL: flat textured triangle (without light source calculation) GsTMDfastTNF3: flat textured triangle (without light source calculation)
Syntax
u_long *GsTMDfastTF3L (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastTF3LFG (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastTF3NL (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastTNF3 (primtop, vertop, s, n, shift, otp) TM D_P_TF3 *primtop;
(TMD_P_TNF3 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_FT3 *s;
u_long n;
u_long shift;
GsOT *otp;
Arguments primtop
vertop
nortop
s n shift
otp
Explanation
This function performs coordinate transformation, perspective transformation, normal line clipping, and light source calculation (GsTMDfastTF3L(), GsTMDfastTF3LFG()), for n (number of) flat textured triangles linked to the TMD file, completes the GPU packet in the buffer, and links to OT.
See libgs in Vol. 1 for details.
Return value
Updated GPU packet buffer address.
GsTMDfastTF4L, GsTMDfastTF4LFG, GsTMDfastTF4NL, GsTMDfastTNF4
TMD data flat, textured quadrilateral processing.
GsTMDfastTF4L: flat textured rectangle (light source calculation) GsTMDfastTF4LFG: flat textured rectangle (light source calculation + FOG) GsTMDfastTF4NL: flat textured rectangle (without light source calculation) GsTMDfastTNF4: flat textured rectangle (without light source calculation)
Syntax
u_long *GsTMDfastTF4L (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastTF4LFG (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastTF4NL (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastTNF4 (primtop, vertop, s, n, shift, otp) TM D_P_TF4 *primtop;
(TMD_P_TNF4 *primtop;
SVECTOR *vertop;
SVECTOR *nortop;
POLY_FT4 *s;
u_long n;
u_long shift;
GsOT *otp;
Arguments primtop
vertop
nortop
s n shift
otp
Explanation
This function performs coordinate transformation, perspective transformation, normal line clipping, and light source calculation (GsTMDfastTF4L(), GsTMDfastTF4LFG()), for n (number of) flat textured rectangles linked to the TMD file, completes the GPU packet in the buffer, and links to OT.
See libgs in Vol. 1 for details.
Return value
Updated GPU packet buffer address.
GsTMDfastTG3L, GsTMDfastTG3LFG, GsTMDfastTG3NL, GsTMDfastTNG3
TMD data Gouraud-shaded, textured triangle processing.
GsTMDfastTG3L: Gouraud texture triangle (light source calculation) GsTMDfastTG3LFG: Gouraud texture triangle (light source calculation + FOG) GsTMDfastTG3NL: Gouraud texture triangle (without light source calculation) GsTMDfastTNG3: Gouraud texture triangle (without light source calculation)
Syntax
u_long *GsTMDfastTG3L (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastTG3LFG (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastTG3NL (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastTNG3 (primtop, vertop, s, n, shift, otp) TMD_P_TG3 *primtop;
(TMD_P_TNG3 *primtop
SVECTOR *vertop;
SVECTOR *nortop;
POLY_GT3 *s;
u_long n;
u_long shift;
GsOT *otp;
Arguments primtop
vertop
nortop
s n shift
otp
Explanation
This function performs coordinate transformation, perspective transformation, normal line clipping, and light source calculation (GsTMDfastTG3L() and GsTMDfast TG3LFG()), for n (number of) Gouraud texture triangles linked to the TMD file, completes the GPU packet in the buffer, and links to OT.
See libgs in Vol. 1 for details.
Return value
Updated GPU packet buffer address.
GsTM DfastTG4L, GsTM DfastTG4LFG, GsTM DfastTG4N L, GsTM DfastTNG4
TMD data Gouraud-shaded, textured quadrilateral processing.
GsTMDfastTG4L: Gouraud texture rectangle (light source calculation) GsTMDfastTG4LFG: Gouraud texture rectangle (light source calculation + FOG) GsTMDfastTG4NL: Gouraud texture rectangle (without light source calculation) GsTMDfastTNG4: Gouraud texture rectangle (without light source calculation)
Syntax
u_long *GsTMDfastTG4L (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastTG4LFG (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastTG4NL (primtop, vertop, nortop, s, n, shift, otp) u_long *GsTMDfastTNG4 (primtop, vertop, s, n, shift, otp) TMD_P_TG4 *primtop;
(TMD_P_TNG4 *primtop;)
SVECTOR *vertop;
SVECTOR *nortop;
POLY_GT4 *s;
u_long n;
u_long shift;
GsOT *otp;
Arguments primtop
vertop
nortop
s n shift
otp
Explanation
This function performs coordinate transformation, perspective transformation, normal line clipping, and light source calculation (GsTMDfastTG4L() and GsTMDfast TG4 LFG()), for n (number of) Gouraud texture rectangles linked to the TMD file, completes the GPU packet in the buffer, and links to OT.
See libgs in Vol. 1 for details.
Return value
Updated GPU packet buffer address.
gteMIMefunc
Adding a vertex data array to a differential data array multiplied by a coefficient. Syntax
void gteMIMefunc (otp, dfp, n, p)
SVECTOR *otp; SVECTOR *dfp; long n;
long p;
Arguments
otp Pointer to a vertex array
dfp Pointer to a differential array
n Number of vertex (differential) data
p Weight (control) coefficient: (1, 19, 12)
Explanation
Executes calculation of multiple interpolations using vertex data array and difference data array. The argument format is as follows.
p : (1, 19, 12)
otp, dfp optional
It operates at high speed in a similar way to the program given in the example below.
void gteMIMefunc (otp, dfp, n, p)
SVECTOR *otp, *dfp;
long n, p;
{
int i;
for (i = 0; i<n; i++) {
(otp+i)->x+=((int) ((dfp+i)->x)*p)>>12; (otp+i)->y+=((int) ((dfp+i)->y)*p)>>12; (otp+i)->z+=((int) ((dfp+i)->z)*p)>>12;
}
}
Return value
None.
346 Basic Geometry Library (libgte) Functions
InitClip
Initialize clipping parameter. Syntax
void InitClip (evbfad, hw, vw, h, near, far) EVECTOR *evb fad;
long hw, vw;
long h;
long near, far;
Arguments
evbfad
hw, vw h
near, far
Explanation
Addresses of (16) clip vector data arrays hw: Window width, vw: Window height Projection distance from view point to screen near: NearClip position, far: FarClip position
This function sets parameters used for clipping.
The clip vector data array evbfad reserves 16 data arrays (176 words or 704 bytes).
Return value None.
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 347
InitGeom
Initialization of geometry transformation engine. Syntax
void InitGeom (void)
Arguments None.
Explanation
This function initializes GTE. It is called when the basic geometry library is used.
Return value None.
Runtime Library Release 3.0
Intpl
Interpolation of a vector and far color. Syntax
void Intpl (v0, p, v1)
SVECTOR *v0; long p;
CVECTOR *v1;
Arguments
v0 Vector (input)
p Interpolation value (input)
v1 Vector (output)
Explanation
This function calculates v1 = p * v0 + (1 -p) * FC. The argument format is as follows:
v0 -> vx, vy, vz : (1, 3, 12)
p : (0, 20, 12)
v1 -> r, g, b: (0, 8, 0)
Return value
None.
InvSquareRoot
1/square root. Syntax
Basic Geometry Library (libgte) Functions 349
void InvSquareRoot (a, b, c) long a;
long *b; long *c;
Arguments
a Value
b Address where a mantissa will be stored
c Address where an exponent will be stored
Explanation
The function returns 1/square root of a value a. The argument format is as follows:
a : (0, 32, 0)
b : (0, 20, 12)
c : (0, 32, 0)
Return value None.
Runtime Library Release 3.0
350 Basic Geometry Library (libgte) Functions
LightColor
Coordinate transformation using the local color matrix. Syntax
void LightColor (v0, v1) SVECTOR *v0; VECTOR *v1;
Arguments
v0 Vector (input)
v1 Vector (output)
Explanation
This function calculates v1=LCM*v0. A limiter works on negative components of v1 when 0 is reached. The argument format is as follows:
v0 -> vx, vy, vz : (1, 3, 12) v1 -> vx, vy, vz : (0, 20, 12)
Return value None.
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 351
LoadAverage0
Weighted average of two vectors. Syntax
void LoadAverage0 (v0, v1, p0, p1, v2) VECTOR *v0, *v1;
long p0, p1;
VECTOR *v2;
Arguments
v0, v1 Vectors (input) p0, p1 Weights (input) v2 Vector (output)
Explanation
This function returns the weighted average of two vectors v0 and v1 in v2 using weights of p0 and p1.
The argument format is as follows:
v0, v1 -> vx, vy, vz : (1, 31, 0) p0, p1 : (1, 15, 0)
v2 -> vx, vy, vz : (1, 46, 0)
Return value None.
Runtime Library Release 3.0
352 Basic Geometry Library (libgte) Functions
LoadAverage12
Weighted average of two vectors. Syntax
void LoadAverage12 (v0, v1, p0, p1, v2) VECTOR *v0, *v1;
long p0, p1;
VECTOR *v2;
Arguments
v0, v1 Vectors (input) p0, p1 Weights (input) v2 Vector (output)
Explanation
This function finds the weighted average of two vectors v0 and v1 using weights of p0 and p1 after division by 4096 (1 in fixed point format) the results are returned in v2.
The argument format is as follows:
v0, v1 -> vx, vy, vz : (1, 31, 0) p0, p1 : (1, 3, 12)
v2 -> vx, vy, vz : (1, 31, 0)
Return value None.
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 353
LoadAve rage Byte
Find weighted average of two vectors. Syntax
void LoadAverageByte (v0, v1, p0, p1, v2) unsigned char v0[2], v1[2];
long p0, p1;
unsigned char v2[2];
Arguments
v0, v1 p0, p1 v2
Explanation
Vector (input) Weights (input) Vector (output)
This function finds the weighted average of two vectors v0 and v1 using weights p0 and p1. The result is returned in v2 after division by 4096.
The argument format is as follows:
v0[i], v1[i] : (0, 8, 0)
p0, p1 : (1, 3, 12)
v2[i] : (0, 8, 0)
Return value
None.
354 Basic Geometry Library (libgte) Functions
LoadAverageCol
Find weighted average of two vectors. Syntax
void LoadAverageCol (v0, v1, p0, p1, v2) unsigned char v0[3], v1[3];
long p0, p1;
unsigned char v2[3];
Arguments
v0, v1 p0, p1 v2
Explanation
Vectors (input) Weights (input) Vector (output)
This function finds the weighted average of two vectors v0 and v1 using weights p0 and p1. The result is returned in v2 after division by 4096.
The argument format is as follows:
v0[i], v1[i] : (0, 8, 0)
p0, p1 : (1, 3, 12)
v2[i] : (0, 8, 0)
Return value
None.
Basic Geometry Library (libgte) Functions 355
LoadAverageShort0
Weighted average of two vectors. Syntax
void LoadAverageShort0 (v0, v1, p0, p1, v2) SVECTOR *v0, *v1;
long p0, p1;
SVECTOR *v2;
Arguments
v0, v1 Vectors (input) p0, p1 Weights (input) v2 Vector (output)
Explanation
This function returns the weighted average of two vectors v0 and v1 in v2 using weights of p0 and p1.
The argument format is as follows:
v0, v1 -> vx, vy, vz : (1, 15, 0) p0, p1 : (1, 15, 0)
v2 -> vx, vy, vz : (1, 30, 0)
Return value None.
Runtime Library Release 3.0
356 Basic Geometry Library (libgte) Functions
LoadAverageShort12
Weighted average of two vectors. Syntax
void LoadAverageShort12 (v0, v1, p0, p1, v2) SVECTOR *v0, v1;
long p0, p1;
SVECTOR *v2;
Arguments
v0, v1 Vectors (input) p0, p1 Weights (input) v2 Vector (output)
Explanation
This function finds the weighted average of two vectors v0 and v1 using weights of p0 and p1 after division by 4096 (1 in fixed point format) the results are returned to v2.
The argument format is as follows:
v0, v1 -> vx, vy, vz : (1, 15, 0) p0, p1 : (1, 3, 12)
v2 -> vx, vy, vz : (1, 15, 0)
Return value None.
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 357
LocalLight
Coordinate transformation using the local light matrix. Syntax
void LocalLight (v0, v1) SVECTOR *v0; VECTOR *v1;
Arguments
v0 Vector (input)
v1 Vector (output)
Explanation
This function calculates v1=LLM*v0. A limiter works on negative components of v1 when 0 is reached. The argument format is as follows:
v0 -> vx, vy, vz: (1, 3, 12) v1 -> vx, vy, vz: (0, 20, 12)
Return value None.
Runtime Library Release 3.0
Returning a leading zero count (LZC). Syntax
long Lzc (data) long data;
Arguments
data Value
Explanation
This function calculates the leading zero count given by data. In short, when the data is displayed as binary, a value identical to MSB returns a number of bits from MSB.
The argument format is as follows: data : (1, 31, 0)
Return value : (1, 31, 0)
Return value
Returns the value of LZC.
MulMatrix
Multiplication of two matrices. Syntax
MATRIX *MulMatrix (m0, m1) MATRIX *m0, *m1;
Arguments
m0, m1 Input/output matrices
Explanation
This function multiplies two matrices. The result is saved in m0. The argument format is as follows:
m0, m1 -> m[i][j]: (1, 3, 12) Return value
This function returns m0. Remarks
The function destroys the constant rotation matrix.
MulMatrix0
Multiplication of two matrices. Syntax
MATRIX *MulMatrix0 (m0, m1, m2) MATRIX *m0, *m1;
MATRIX *m2;
Arguments
m0, m1 m2
Explanation
This function multiplies two matrices m0 and m1. The argument format is as follows:
m0, m1, m2 -> m[i][j] : (1, 3, 12)
Return value
This function returns m2. Remarks
The function destroys the constant rotation matrix.
MulMatrix2
Multiplication of two matrices. Syntax
MATRIX *MulMatrix2 (m0, m1) MATRIX *m0, *m1;
Arguments
m0, m1 Input/output matrices
Explanation
This function multiplies two matrices. The result is saved in m1. The argument format is as follows:
m0, m1 -> m[i][j]: (1, 3, 12) Return value
This function returns m1. Remarks
The function destroys the constant rotation matrix.
362 Basic Geometry Library (libgte) Functions
MulRotMatrix
Multiply a constant rotation matrix by a matrix. Syntax
MATRIX* MulRotMatrix (m0) MATRIX *m0;
Arguments
m0 Input/output matrix
Explanation This function multiplies a constant rotation matrix by a matrix. It stores the value in m0.
The argument format is as follows: m0, m1 -> m[i][j] : (1, 3, 12)
Return value Returns m0.
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 363
MulRotMatrix0
Multiply a constant rotation matrix by a matrix. Syntax
MATRIX* MulRotMatrix0 (m0, m1) MATRIX *m0;
MATRIX *m1;
Arguments
m0 Input matrix
m1 Output matrix
Explanation This function multiplies a constant rotation matrix by matrix m0. The result is saved in m1.
The argument format is as follows: m0, m1 -> m[i][j] : (1, 3, 12)
Return value Returns m1.
Runtime Library Release 3.0
364 Basic Geometry Library (libgte) Functions
NormalClip
Outer product of three points. Syntax
long NormalClip (sxy0, sxy1, sxy2) long sxy0, sxy1, sxy2;
Arguments
sxy0, sxy1, sxy2 Vertex coordinates (upper position 16-bit is y coordinate and lower position 16-bit is x coordinate)
Explanation
This function returns the outer product for a triangle formed by three points (sx0, sy0), (sx1, sy1), and (sx2, sy2).
If the triangle is defined clockwise as seen from the visual point (on the negative end of the Z-axis), the value is positive (provided that the positive end of the X-axis is facing right, and that the positive end of the Y-axis is facing down).
The argument format is as follows:
sxy0, sxy1, sxy2: y (1, 15, 0), x (1, 15, 0)
Return value
The function returns the outer product for the triangle formed by three points (sx0, sy0), (sx1, sy1), and (sx2, sy2).
sx1-sx0, sy1 -sy0 sx2-sx0, sy2-sy0
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 365
NormalColor
Finds a local color from a normal vector. Syntax
void NormalColor (v0, v1) SVECTOR *v0; CVECTOR *v1;
Arguments
v0 Normal vector (input)
v1 Color vector (output)
Explanation
This function calculates LLV=LLM*v0, v1=BK+LCM*LLV. The argument format is as follows: v0 -> vx, vy, vz : (1, 3, 12)
vl -> r, g, b : (0, 8, 0)
Return value None.
Runtime Library Release 3.0
366 Basic Geometry Library (libgte) Functions
NormalColor3
Finds three local colors from three normal vectors. Syntax
void NormalColor3 (v0, v1, v2, v3, v4, v5) SVECTOR *v0, *v1, *v2; CVECTOR *v3, *v4, *v5;
Arguments
v0, v1, v2 Normal vectors (input)
v3, v4, v5 Color vectors (output)
Explanation
This function calculates
(LLV0, LLV1, LLV2) = LLM * (v0, v1, v2)
(v3, v4, v5) = BK +LCM * (LLV0, LLV1, LLV2) The argument format is as follows:
v0, v1, v2 -> vx, vy, vz : (1, 3, 12)
v3, v4, v5 -> r, g, b : (0, 8, 0)
Return value None.
Runtime Library Release 3.0
NormalColor3_nom
Find three local colors from three normal vectors. Syntax
Basic Geometry Library (libgte) Functions 367
void NormalColor3_nom (v0, v1, v2) SVECTOR *v0, *v1, *v2;
Arguments
v0, v1, v2 Normal vector (input) Explanation
Perform calculations as below:
(LLV0, LLV1, LLV2) = LLM* (v0, v1, v2)
(v3, v4, v5) = BK + LCM* (LLV0, LLV1, LLV2)
Return value None.
Remarks (v3, v4, v5) is read by macro read_rgb_fifo.
The argument format is as follows: v0, v1, v2 vx, vy, vz : (1, 3, 12) v3, v4, v5 r, g, b : (0, 8, 0)
Runtime Library Release 3.0
368 Basic Geometry Library (libgte) Functions
NormalColorCol
Finds a local color from a normal vector. Syntax
void NormalColorCol (v0, v1, v2) SVECTOR *v0;
CVECTOR *v1; CVECTOR *v2;
Arguments
v0 Normal vector (input)
v1 Primary color vector (input)
v2 Color vector (output)
Explanation This function calculates the following: LLV=LLM*v0
LC = BK + LCM * LLV
v2 = v1 * LC (separate multiplication) The argument format is as follows: v0 -> vx, vy, vz : (1, 3, 12)
v1 -> r, g, b: (0, 8, 0)
v2 -> r, g, b: (0, 8, 0)
Return value None.
Runtime Library Release 3.0
NormalColorCol3
Finds a local color from three normal vectors. Syntax
void NormalColorCol3 (v0, v1, v2, v3, v4, v5, v6) SVECTOR *v0, *v1, *v2; CVECTOR *v3;
CVECTOR *v4, *v5, *v6;
Arguments
v0, v1, v2 v3
v4, v5, v6
Explanation
Normal vectors
Primary color vector (input) Color vectors (output)
This function calculates the following:
(LLV0, LLV1, VVL2)=LLM* (v0, v1, v2)
(LC0, LC1, LC2) = BK + LCM * (LLV0, LLV1, LLV2)
(v4, v5, v6) = v3 * (LC0, LC1, LC2) (separate multiplication) The argument format is as follows:
v0, v1, v2 -> vx, vy, vz : (1, 3, 12)
v3 -> r, g, b: (0, 8, 0)
v4, v5, v6 -> r, g, b : (0, 8, 0)
Return value None.
370 Basic Geometry Library (libgte) Functions
NormalColorCol3_nom
Find a local color from three normal vectors. Syntax
void NormalColorCol3_nom (v0, v1, v2, v3) SVECTOR *v0, *v1, *v2;
CVECTOR *v3;
Arguments
v0, v1, v2 Normal vector (input)
v3 Primary color vector (input)
Explanation
Perform calculations as below.
(LLV0, LLV1, LLV2) = LLM* (v0, v1, v2)
(LC0, LC1, LC2) = BK + LCM* (LLV0, LLV1, LLV2)
(v4, v5, v6) = v3* (LC0, LC1, LC2) (separate multiplications)
The argument format is as follows:
v0, v1, v2 -> vx, vy, vz : (1, 3, 12) v3 -> r, g, b : (0, 8, 0)
v4, v5, v6 -> r, g, b : (0, 8, 0)
Return value None.
Remarks
(v4, v5, v6) is read by macro read_rgb_fifo.
Runtime Library Release 3.0
NormalColorCol_nom
Find a local color from a normal vector. Syntax
void NormalColorCol_nom (v0, v1)
SVECTOR *v0; CVECTOR *v1;
Arguments
v0 Normal vector (input)
v1 Primary color vector (input)
Explanation
Perform calculations as below.
LLV = LLM*v0
LC = BK + LCM*LLV
v2 = v1*LC (separate multiplications) The argument format is as follows:
v0 -> vx, vy, vz : (1, 3, 12)
v1 -> r, g, b : (0, 8, 0)
v2 -> r, g, b : (0, 8, 0)
Return value
None.
Remarks
(v2 -> r, v2 -> g, v2 -> b) is read by macro read_rgb2.
372 Basic Geometry Library (libgte) Functions
NormalColorDpq
Finds a local color from a normal vector and performs depth queuing. Syntax
void NormalColorDpq (v0, v1, p, v2) SVECTOR *v0;
CVECTOR *v1; long p;
CVECTOR *v2;
Arguments
v0 Normal vector (input)
v1 Primary color vector (input)
p Interpolation value (input)
v2 Color vector (output)
Explanation
This function calculates the following: LLV=LLM*v0
LC = BK +LCM*LLV
v2 = (1-p)*(v1*LC)+p*FC
The argument format is as follows: v0 -> vx, vy, vz : (1, 3, 12) vl -> r, g, b : (0, 8, 0) p : (0, 20, 12) v2 -> r, g, b: (0, 8, 0)
Return value None.
Runtime Library Release 3.0
NormalColorDpq3
Finds local color from three normal vectors, and performs depth queuing. Syntax
void NormalColorDpq3 (v0, v1, v2, v3, p, v4, v5, v6)
SVECTOR *v0, *v1, *v2; CVECTOR *v3;
long p;
CVECTOR *v4, *v5, *v6;
Arguments
v0, v1, v2 v3
p
v4, v5, v6
Explanation
Normal vectors (input)
Primary color vector (input) Interpolation value (input) Color vectors (output)
This function calculates the following:
(LLV0, LLV1, LLV2) = LLM * (v0, v1, v2)
(LC0, LC1, LC2) = BK + LCM * (LLV0, LLV1, LLV2)
(v4, v5, v6) = p * (v3 * (LC0, LC1, LC2)) + (1 -p) * FC
v3 * (LC0, LC1, LC2) is the product of separate multiplications. The argument format is as follows:
v0, v1, v2 -> vx, vy, vz: (1, 3, 12)
v3 -> r, g, b : (0, 8, 0)
p : (0, 20, 12)
v4, v5, v6 -> r, g, b) : (0, 8, 0)
Return value
None.
NormalColorDpq3_nom
Find a local color from three normal vectors and perform depth queuing. Syntax
void NormalColorDpq3_nom (v0, v1, v2, v3, p) SVECTOR *v0, *v1, *v2;
CVECTOR *v3;
long p;
Arguments
v0, v1, v2 Normal vector (input)
v3 Primary color vector (input)
p Interpolation value (input)
Explanation
Perform calculations as below.
(LLV0, LLV1, LLV2) = LLM* (v0, v1, v2)
(LC0, LC1, LC2) = BK + LCM* (LLV0, LLV1, LLV2) (v4, v5, v6) = p * v3 * (LC0, LC1, LC2) + (1-p) * FC The argument format is as follows:
v0, v1, v2 -> vx, vy, vz : (1, 3, 12)
v3 -> r, g, b : (0, 8, 0)
p : (0, 20, 12)
v4, v5, v6 -> r, g, b : (0, 8, 0)
Return value
None.
Remarks
(v4, v5, v6) is read by macro read_rgb_fifo.
NormalColorDpq3_nom
Find a local color from three normal vectors and perform depth queuing. Syntax
void NormalColorDpq3_nom (v0, v1, v2, v3, p) SVECTOR *v0, *v1, *v2;
CVECTOR *v3;
long p;
Arguments
v0, v1, v2 Normal vector (input)
v3 Primary color vector (input)
p Interpolation value (input)
Explanation
Perform calculations as below.
(LLV0, LLV1, LLV2) = LLM* (v0, v1, v2)
(LC0, LC1, LC2) = BK + LCM* (LLV0, LLV1, LLV2) (v4, v5, v6) = p * v3 * (LC0, LC1, LC2) + (1-p) * FC The argument format is as follows:
v0, v1, v2 -> vx, vy, vz : (1, 3, 12)
v3 -> r, g, b : (0, 8, 0)
p : (0, 20, 12)
v4, v5, v6 -> r, g, b : (0, 8, 0)
Return value
None.
Remarks
(v4, v5, v6) is read by macro read_rgb_fifo.
NormalColorDpq_nom
Find a local color from a normal vector and perform depth queuing. Syntax
void NormalColorDpq_nom (v0, v1, p)
SVECTOR *v0; CVECTOR *v1; long p;
Arguments
v0 Normal vector (input)
v1 Primary color vector (input)
p Interpolation value (input)
Explanation Perform calculations as below.
LLV = LLM*v0
LC = BK + LCM*LLV
v2 = (1-p) * (v1*LC) + p*FC
v1*LC indicates separate multiplications. The argument format is as follows:
v0 -> vx, vy, vz : (1, 3, 12)
v1 -> r, g, b : (0, 8, 0)
p : (0, 20, 12)
v2 -> r, g, b : (0, 8, 0)
Return value
None.
Remarks
(v2 -> r, v2 -> g, v2 -> b) is read by macro read_rgb2.
NormalColor_nom
Find a local color from a normal vector. Syntax
Basic Geometry Library (libgte) Functions 377
void NormalColor_nom (v0) SVECTOR *v0;
Arguments
v0 Normal vector (input) Explanation
Perform calculations as below. LLV = LLM*v0
v1 = BK + LCM*LLV
The argument format is as follows: v0 -> vx, vy, vz : (1, 3, 12)
v1 -> r, g, b : (0, 8, 0)
Return value None.
Remarks
(v1 -> r, v1 -> g, v1 -> b) is read by macro read_rgb2.
Runtime Library Release 3.0
378 Basic Geometry Library (libgte) Functions
OuterProduct0
Outer product of two vectors. Syntax
void OuterProduct0 (v0, v1, v2) VECTOR *v0, *v1;
VECTOR *v2;
Arguments
v0, v1 Vectors (input) v2 Vector (output)
Explanation
This function returns the outer product vector of two vectors v0 and v1 to v2. The argument format is as follows:
v0, v1 -> vx, vy, vz : (1, 31, 0)
v2 -> vx, vy, vz : (1, 31, 0)
Return value None.
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 379
OuterProduct12
Outer product of two vectors. Syntax
void OuterProduct12 (v0, v1, v2) VECTOR *v0, *v1;
VECTOR *v2;
Arguments
v0, v1 Vectors (input) v2 Vector (output)
Explanation
This function returns the outer product vector of two vectors, v0 and v1, to v2. The argument format is as follows:
v0, v1, v2 -> vx, vy, vz: (1, 19, 12)
Return value None.
Runtime Library Release 3.0
380 Basic Geometry Library (libgte) Functions
PopMatrix
Resets a constant rotation matrix from a stack. Syntax
void PopMatrix (void)
Arguments None.
Explanation This function resets a constant rotation matrix from a stack.
Return value None.
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 381
PushMatrix
Saving a constant rotation matrix in a stack. Syntax
void PushMatrix (void)
Arguments None.
Explanation
This function saves a constant rotation matrix on a stack. The stack has 20 slots.
Return value None.
Runtime Library Release 3.0
382 Basic Geometry Library (libgte) Functions
ratan2
Arctan. Syntax
long ratan2 (y, x) long y, x;
Arguments
y, x Value
Explanation
This function uses Playstation format (4096 = 360 degrees) to finish the y/x arctan function (-180 degrees and +180 degrees).
The argument format is as follows:
(x, y) : (1, 31, 0)
return value : Playstation format (4096 = 360 degrees)
Return value
This function returns the y/x arctan function (atan2 (y,x)). Remarks
The return value is incorrect if either x or y is -2147483648 (0x80000000 = long negative's maximum value).
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 383
rcos
Syntax
long rcos (a) long int a;
Arguments
a Angle (in Playstation format)
Explanation
Finds the cosine function of the angle (in Playstation format) (4096=360 degrees) using fixed-point math (where 4096=1.0).
The argument format is as follows:
a : Playstation format (4096=360 degrees) return value : (1, 19, 12)
Return value
cos (a)
Runtime Library Release 3.0
RCpolyF3
Division of flat triangle. Syntax
u_long *RCpolyF3 (s, divp) POLY_F3 *s;
DIVPOLYGON3 *divp;
Arguments
s GPU packet buffer address
divp Division work area
Explanation
This is a recursive program for division of flat triangles (POLY_F3). You must set the data below in the division work area.
u_long ndiv; /* Number of divisions */
u_long pih, piv; /* Display screen resolution (for clipping) */
u_short clut, tpage; /* CBA & TSB */ CVECTOR rgbc; /* color vector (+code) */
u_long *ot; /* OT entry */ RVECTOR r0, r1, r2;
/* Division vertex vector data (See RVECTOR)*/
/* 2D and 3D texture coordinates and color for each vertex */
divp -> cr[0].r0 = &divp -> r0; divp -> cr[0].r1 = &divp -> r1; divp -> cr[0].r2 = &divp -> r2;
Return value
Updated GPU packet buffer address.
RCpolyF4
Division of flat quadrilateral. Syntax
u_long *RCpolyF4 (s, divp) POLY_F4 *s;
DIVPOLYGON4 *divp;
Arguments
s GPU packet buffer address
divp Division work area
Explanation
This is a recursive program for division of flat quadrilaterals (POLY_F4). You must set the data below in the division work area.
u_long ndiv; /* Number of divisions */
u_long pih, piv; /* Display screen resolution (for clipping) */
u_short clut, tpage; /* CBA & TSB */ CVECTOR rgbc; /* color vector (+code) */
u_long *ot; /* OT entry */ RVECTOR r0, r1, r2, r3;
/* Division vertex vector data (See RVECTOR)*/
/* 2D and 3D texture coordinates and color for each vertex */
divp -> cr[0].r0 = &divp -> r0; divp -> cr[0].r1 = &divp -> r1; divp -> cr[0].r2 = &divp -> r2; divp -> cr[0].r3 = &divp -> r3;
Return value
Updated GPU packet buffer address.
RCpolyFT3
Division of flat, textured triangle. Syntax
u_long * RCpolyFT3 (s, divp) POLY_FT3 *s;
DIVPOLYGON3 *divp;
Arguments
s GPU packet buffer address
divp Division work area
Explanation
This is a recursive program for division of flat, textured triangles (POLY_FT3). You must set the data below in the division work area.
u_long ndiv; /* Number of divisions */
u_long pih, piv; /* Display screen resolution (for clipping) */ u_short clut, tpage; /* CBA & TSB */
CVECTOR rgbc; /* color vector (+code) */
u_long *ot; /* OT entry */ RVECTOR r0, r1, r2;
/* Division vertex vector data (See RVECTOR)*/
/* 2D and 3D texture coordinates and color for each vertex */
divp -> cr[0].r0 = &divp -> r0; divp -> cr[0].r1 = &divp -> r1; divp -> cr[0].r2 = &divp -> r2;
Return value
Updated GPU packet buffer address.
RCpolyFT4
Division of flat, textured quadrilateral. Syntax
u_long * RCpolyFT4 (s, divp) POLY_FT4 *s;
DIVPOLYGON4 *divp;
Arguments
s GPU packet buffer address
divp Division work area
Explanation
This is a recursive program for division of flat , textured quadrilaterals (POLY_FT4). You must set the data below in the division work area.
u_long ndiv /* Number of divisions */
u_long pih, piv; /* Display screen resolution (for clipping) */ u_short clut, tpage; /* CBA & TSB */
CVECTOR rgbc; /* color vector (+code) */
u_long *ot; /* OT entry */ RVECTOR r0, r1, r2, r3;
/* Division vertex vector data (See RVECTOR)*/
/* 2D and 3D texture coordinates and color for each vertex */
divp -> cr[0].r0 = &divp -> r0; divp -> cr[0].r1 = &divp -> r1; divp -> cr[0].r2 = &divp -> r2; divp -> cr[0].r3 = &divp -> r3;
Return value
Updated GPU packet buffer address.
RCpolyG3
Division of Gouraud-shaded triangle. Syntax
u_long * RCpolyG3 (s, divp) POLY_G3 *s;
DIVPOLYGON3 *divp;
Arguments
s GPU packet buffer address
divp Division work area
Explanation
This is a recursive program for division of Gouraud-shaded triangles (POLY_G3). You must set the data below in the division work area.
u_long ndiv; /* Number of divisions */
u_long pih, piv; /* Display screen resolution (for clipping) */
u_short clut, tpage; /* CBA & TSB */ CVECTOR rgbc; /* color vector (+code) */
u_long *ot; /* OT entry */ RVECTOR r0, r1, r2;
/* Division vertex vector data (See RVECTOR)*/
/* 2D and 3D texture coordinates and color for each vertex */
divp -> cr[0].r0 = &divp -> r0; divp -> cr[0].r1 = &divp -> r1; divp -> cr[0].r2 = &divp -> r2;
Return value
Updated GPU packet buffer address.
RCpolyG4
Division of Gouraud-shaded quadrilateral. Syntax
u_long * RCpolyG4 (s, divp) POLY_G4 *s;
DIVPOLYGON4 *divp;
Arguments
s GPU packet buffer address
divp Division work area
Explanation
This is a recursive program for division of Gouraud-shaded quadrilaterals (POLY_G4). You must set the data below in the division work area.
u_long ndiv; /* Number of divisions */
u_long pih, piv; /* Display screen resolution (for clipping) */
u_short clut, tpage; /* CBA & TSB */ CVECTOR rgbc; /* color vector (+code) */
u_long *ot; /* OT entry */ RVECTOR r0, r1, r2, r3;
/* Division vertex vector data (See RVECTOR)*/
/* 2D and 3D texture coordinates and color for each vertex */
divp -> cr[0].r0 = &divp -> r0; divp -> cr[0].r1 = &divp -> r1; divp -> cr[0].r2 = &divp -> r2; divp -> cr[0].r3 = &divp -> r3;
Return value
Updated GPU packet buffer address.
RCpolyGT3
Division of Gouraud-textured triangle. Syntax
u_long * RCpolyGT3 (s, divp) POLY_GT3 *s;
DIVPOLYGON3 *divp;
Arguments
s GPU packet buffer address
divp Division work area
Explanation
This is a recursive program for division of Gouraud-shaded, textured triangles (POLY_GT3). You must set the data below in the division work area.
u_long ndiv; /* Number of divisions */
u_long pih, piv /* Display screen resolution (for clipping) */
u_short clut, tpage; /* CBA & TSB */ CVECTOR rgbc; /* color vector (+code) */
u_long *ot; /* OT entry */ RVECTOR r0, r1, r2;
/* Division vertex vector data (See RVECTOR)*/
/* 2D and 3D texture coordinates and color for each vertex */
divp -> cr[0].r0 = &divp -> r0; divp -> cr[0].r1 = &divp -> r1; divp -> cr[0].r2 = &divp -> r2;
Return value
Updated GPU packet buffer address.
RCpolyGT4
Division of Gouraud-textured quadrilateral. Syntax
u_long * RCpolyGT4 (s, divp) POLY_GT4 *s;
DIVPOLYGON4 *divp;
Arguments
s GPU packet buffer address
divp Division work area
Explanation
This is a recursive program for division of Gouraud-shaded, textured quadrilaterals (POLY_GT4). You must set the data below in the division work area.
u_long ndiv; /* Number of divisions */
u_long pih, piv; /* Display screen resolution (for clipping) */
u_short clut, tpage; /* CBA & TSB */ CVECTOR rgbc; /* color vector (+code) */
u_long *ot; /* OT entry */ RVECTOR r0, r1, r2, r3;
/* Division vertex vector data (See RVECTOR)*/
/* 2D and 3D texture coordinates and color for each vertex */
divp -> cr[0].r0 = &divp -> r0; divp -> cr[0].r1 = &divp -> r1; divp -> cr[0].r2 = &divp -> r2; divp -> cr[0].r3 = &divp -> r3;
Return value
Updated GPU packet buffer address.
392 Basic Geometry Library (libgte) Functions
ReadColorMatrix
Reading a local color matrix. Syntax
void ReadColorMatrix (m) MATRIX *m;
Arguments
m Matrix (input) Explanation
This function reads the current local color matrix, and saves it in m. The argument format is as follows:
m -> m[i][j]: (1, 3, 12)
Return value None.
Runtime Library Release 3.0
ReadGeomOffset
Read GTE offset value. Syntax
Basic Geometry Library (libgte) Functions 393
void ReadGeomOffset (ofx, ofy) long *ofx, *ofy;
Arguments
ofx Offset X coordinate
ofy Offset Y coordinate
Explanation This function reads the GTE offset value. The argument format is as follows:
ofx, ofy : (0, 32, 0)
Return value None.
Runtime Library Release 3.0
394 Basic Geometry Library (libgte) Functions
ReadGeomScreen
Read distance from view point to screen. Syntax
long ReadGeomScreen (void)
Arguments None.
Explanation This function reads the distance h from the view point (eye) to the screen.
The argument format is as follows: return value : (0, 32, 0)
Return value h value
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 395
ReadLightMatrix
Reading a local light matrix. Syntax
void Read LightMatrix (m) MATRIX *m;
Arguments
m Matrix (input)
Explanation This function reads the current local light matrix, and saves it in m.
The argument format is as follows: m -> m[i][j]: (1, 3, 12)
Return value None.
Runtime Library Release 3.0
396 Basic Geometry Library (libgte) Functions
Read RG Bfifo
Reading RGBcd values. Syntax
void Read RGBfifo (v0, vl, v2) CVECTOR *v0, *v1, *v2;
Arguments
v0, v1, v2 Vectors (output) Explanation
This function stores the RGBcd0, RGBcd1, and RGBcd2 values in v0, v1, and v2. The argument format is as follows:
v0, v1, v2 -> r, g, b, cd: (0, 8, 0)
Return value None.
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 397
Read RotMatrix
Reads a constant rotation matrix. Syntax
void Read RotMatrix (m) MATRIX *m;
Arguments
m Matrix (output)
Explanation
This function reads the current rotation matrix, and saves it in m. The argument format is as follows:
m -> m[i][j]: (1, 3, 12) m -> t[i]: (1, 31, 0)
Return value None.
Runtime Library Release 3.0
398 Basic Geometry Library (libgte) Functions
ReadSXSYfifo
Reads SXSY values. Syntax
void ReadSXSYfifo (sxy0, sxy1, sxy2) long *sxy0, *sxy1, *sxy2;
Arguments
sxy0, sxy1, sxy2 Addresses where SZ values are stored Explanation
This function stores the sx0, sy0, sx1, sy1, sx2, and sy2 values in sxy0, sxy1, and sxy2. The argument format is as follows:
(sxy0, sxy1, sxy2): (1, 15, 0)
Return value None.
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 399
ReadSZfifo3
Reads SZ values. Syntax
void ReadSZfifo3 (sz0, sz1, sz2) long *sz0, *sz1, *sz2;
Arguments
sz0, sz1, sz2 Addresses where SZ values are stored Explanation
This function stores the SZ0, SZ1, and SZ2 values in sz0, sz1, and sz2. The argument format is as follows:
(sz0, sz1, sz2): (0, 16, 0)
Return value None.
Runtime Library Release 3.0
400 Basic Geometry Library (libgte) Functions
ReadSZfifo4
Reads SZ values. Syntax
void Read SZfifo4 (szx, sz0, sz1, sz2) long *szx, *sz0, *sz1, *sz2;
Arguments
szx, sz0, sz1, sz2 Addresses where SZ values are stored Explanation
This function stores the SZX, SZ0, SZ1, and SZ2 values in szx, sz0, sz1, and sz2. The argument format is as follows:
(szx, sz0, sz1, sz2): (0, 16, 0)
Return value None.
Runtime Library Release 3.0
RotAverage3
Perform coordinate transformation for 3 points and perspective transformation, and find an interpolation value and an average of Z values for depth queuing.
Syntax
long RotAverage3 (v0, v1, v2, sxy0, sxy1, sxy2, p, flag) SVECTOR *v0, *v1, *v2;
long *sxy0, *sxy1, *sxy2;
long *p;
long * flag;
Arguments
v0, v1, v2
sxy0, sxy1, sxy2 p
flag
Explanation
Vectors (input)
Address where the coordinates will be stored Address where the interpolation value will be stored Address where a flag will be stored
This function performs a coordinate transformation of the local vectors v0, v1, and v2 using a rotation matrix, and performs perspective transformation. Then, it returns three screen coordinates in sxy0, sxy1, and sxy2. It also, returns to p an interpolation value for depth queuing for v2.
The argument format is as follows:
v0, v1, v2 -> vx, vy, vz: (1, 15, 0)
sxy0, sxy1, sxy2 : (1, 15, 0), (1, 15, 0)
p : (0, 20, 12)
flag : (0, 32, 0)
Return value : (0, 32, 0)
Return value
1/4 (OTZ value) average of three screen coordinate Z values.
RotAverage3_nom
Perform coordinate transformation and perspective transformation for three points and find interpolation value for depth queuing and an average of Z values.
Syntax
void RotAverage3_nom (v0, v1, v2) SVECTOR *v0, *v1, *v2;
Arguments
v0, v1, v2 Vectors (input) Explanation
After using a rotation matrix to perform coordinate transformation for local coordinate vectors v0, v1, and v2, this function performs perspective transformation and stores the following values in one GTE internal register:
* three screen coordinates (sx0, sy0, sz0), (sx1, sy1, sz1), (sx2, sy2, sz2)
* the interpolation value p for depth queuing corresponding to v2
* an average of Z values (otz) for the three screen coordinates Argument format and data formats are as follows:
v0, v1, v2 -> vx, vy, sx0, sy0, sz0
sx1, sy1, sz1
sx2, sy2, sz2 p
flag
Return value None.
Remarks
vz : (1, 15, 0)
: (1, 15, 0), (1, 15, 0), (0, 16, 0) : (1, 15, 0), (1, 15, 0), (0, 16, 0) : (1, 15, 0), (1, 15, 0), (0, 16, 0) : (0, 20, 12)
: (0, 32, 0)
Values are returned by macro. A flag is returned in v0.
value read macro
(sz0, sz1, sz2) read_sz_fifo3
((sx0, sy0), (sx1, sy1), (sx2, sy2)) read_sxsy_fifo3
p read_p
otz read_otz.
RotAverage4
Perform coordinate transformation for 3 points and perspective transformation, and find an interpolation value and an average of Z values for depth queuing.
Syntax
long RotAverage4 (v0, v1, v2, v3, sxy0, sxy1, sxy2, sxy3, p, flag) SVECTOR *v0, *v1, *v2, *v3;
long *sxy0, *sxy1, *sxy2, *sxy3;
long *p;
long * flag;
Arguments
v0, v1, v2, v3
sxy0, sxy1, sxy2, sxy3 p
flag
Vectors (input)
Address where the coordinates will be stored Address where the interpolation value will be stored Address where a flag will be stored
Explanation
This function performs coordinate transformation of the four points v0, v1, v2, and v3 using a rotation matrix, and performs perspective transformation. Then, it returns four screen coordinates to sxy0, sxy1, sxy2, and sxy3. It also returns an interpolation value for depth queuing for v2 to p.
The argument format is as follows:
v0, v1, v2, v3 -> vx, vy, vz: (1, 15, 0)
sxy0, sxy1, sxy2, sxy3 : (1, 15, 0), (1, 15, 0)
p : (0, 20, 12)
flag : (0, 32, 0)
Return value
1/4 (OTZ value) average of four screen coordinate Z values.
RotAverageNclip3
Perform coordinate transformation and perspective transformation for three points, and find an interpolation value, average of Z values, and outer product.
Syntax
long RotAverageNclip3 (v0, v1, v2, sxy0, sxy1, sxy2, p, otz, flag) SVECTOR *v0, *v1, *v2;
long *sxy0, *sxy1, *sxy2;
long *p;
long *otz;
long * flag;
Arguments
v0, v1, v2
sxy0, sxy1, sxy2 p
otz
flag
Explanation
Vectors (input)
Address where coordinates will be stored
Address where an interpolation value will be stored Address where an OTZ value will be stored Address where a flag will be stored
This function performs perspective transformation after coordinate transformation of three points v0, v1, and v2 using a rotation matrix, and returns three screen coordinates to sxy0, sxy1, and sxy2. It also returns an interpolation value for depth queuing for v2 to p, and returns 1/4 of the average of Z values of the screen coordinates for v2 to otz.
The argument format is as follows:
v0, v1, v2 -> vx, vy, vz: (1, 15, 0)
sxy0, sxy1, sxy2 : (1, 15, 0), (1, 15, 0)
p : (0, 20, 12)
otz : (0, 32, 0)
flag : (0, 32, 0) Return value
Outer product of (sx0, sy0), (sx1, sy1), (sx2, sy2). Remarks
When the return value is negative, SX, SY, etc. are incorrect. When SX and SY are required, use RotAverage3().
RotAverageNclip3_nom
Peform coordinate transformation and perspective transformation for three points, then find an interpolation value, an average of Z values, and an outer product value.
Syntax
void RotAverageNclip3_nom (v0, v1, v2) SVECTOR *v0, *v1, *v2;
Arguments
v0, v1, v2 Vectors (input) Explanation
After using a rotation matrix to perform coordinate transformation for local coordinate vectors v0, v1, and v2, this function performs perspective transformation and maintains the following values in a GTE internal register:
* three screen coordinates (sx0, sy0, sz0), (sx1, sy1, sz1), (sx2, sy2, sz2)
* the interpolation value p for depth queuing corresponding to v2
* an average of Z values (otz) for the three screen coordinates
* an outer product value (opz) for (sx0, sy0), (sx1, sy1), and (sx2, sy2) in a GTE internal register.
Argument format and data formats are as follows:
Values are returned by macro. A flag is returned in v0.
value read macro
(sz0, sz1, sz2)
((sx0, sy0), (sx1, sy1), (sx2, sy2)) p
otz
opz
read_sz_fifo3 read_sxsy_fifo3 read_p
read_otz. read_opz
RotAverageNclip4
Perform coordinate transformation and perspective transformation for four points, and find an interpolation value, average of Z values, and outer product.
Syntax
long RotAverageNclip4 (v0, v1, v2, v3, sxy0, sxy1, sxy2, sxy3, p, otz, flag) SVECTOR *v0, *v1, *v2, *v3;
long *sxy0, *sxy1, *sxy2, *sxy3;
long *p;
long *otz;
long * flag;
Arguments
v0, v1, v2, v3
sxy0, sxy1, sxy2, sxy3 p
otz
flag
Explanation
Vectors (input)
Address where coordinates will be stored
Address where an interpolation value will be stored Address where an OTZ value will be stored Address where a flag will be stored
This function performs perspective transformation after coordinate transformation of four points v0, v1, v2, and v3 using a rotation matrix, and returns three screen coordinates to sxy0, sxy1, sxy2, and sxy3. It also returns an interpolation value for depth queuing for v3 to p, and returns 1/4 of the average of four Z values of the screen coordinates for v3 to otz.
The argument format is as follows:
v0, v1, v2, v3 -> vx, vy, vz : (1, 15, 0)
sxy0, sxy1, sxy2, sxy3 : (1, 15, 0), (1, 15, 0)
p : (0, 20, 12)
otz : (0, 32, 0)
flag : (0, 32, 0)
Return value Outer product of (sx0, sy0), (sx1, sy1), (sx2, sy2).
Remarks
When the return value is negative, SX, SY, etc., are incorrect. When SX and SY are required, use RotAverage4().
RotAverageNclipColorCol3
Find a color by performing coordinate transformation for three points and perspective transformation.
Syntax
long RotAverageNclipColorCol3 (v0, v1, v2, v3, v4, v5, v6, sxy0, sxy1, sxy2, v7, v8, v9, otz,
flag)
SVECTOR *v0, *v1, *v2; SVECTOR *v3, *v4, *v5; CVECTOR *v6;
long *sxy0, *sxy1, *sxy2; CVECTOR *v7, *v8, *v9; long *otz;
long * flag;
Arguments
v0, v1, v2 v3, v4, v5 v6
sxy0, sxy1, sxy2 v7, v8, v9 otz
flag
Explanation
Vectors (input)
Normal vectors (input)
Primary color vector (input)
Address where coordinate values will be stored Color vectors (output)
Address where an OTZ value will be stored Address where a flag will be stored
This function performs perspective transformation after performing coordinate transformation for three points v0, v1, and v2 using a rotation matrix, and returns screen coordinates to sxy0, sxy1, and sxy2.The remaining values are calculated as follows:
(LLV0, LLV1, LLV2) = LLM* (v3, v4, v5)
(LC0, LC1, LC2) = BK + LCM*(LLV0, LLV1, LLV2)
(v7, v8, v9) = v6*(LC0, LC1, LC2)
(separate multiplications)
The function also returns an average of Z values of three screen coordinates to otz. The argument format is as follows:
v0, v1, v2 -> vx, vy, vz: (1, 15, 0) v3, v4, v5 -> vx, vy, vz: (1, 3, 12)
v6 -> r, g, b : (0, 8, 0)
sxy0, sxy1, sxy2 : (1, 15, 0), (1, 15, 0)
v7, v8, v9 -> r, g, b : (0, 8, 0)
otz : (0, 32, 0)
flag : (0, 32, 0)
Return value Outer product of (sx0, sy0), (sx1, sy1), (sx2, sy2)
Remarks When the return value is negative, SX, SY, etc., are incorrect.
RotAverageNclipColorCol3_nom
Perform coordinate transformation and perspective transformation, then find color. Syntax
void RotAverageNclipColorCol3_nom (v0, v1, v2, v3, v4, v5, v6)
SVECTOR *v0, *v1, *v2; SVECTOR *v3, *v4, *v5; CVECTOR *v6;
Arguments
v0, v1, v2 Vectors (input)
v3, v4, v5 Normal vectors (input)
v6 Primary color vector (input)
Explanation
After performing coordinate transformation for local coordinate vectors v0, v1, and v2 using a rotation matrix, this function performs perspective transformation and maintains the following values in a GTE internal register:
* stores three screen coordinates (sx0, sy0, sz0), (sx1, sy1, sz1), (sx2, sy2, sz2)
* an average of Z values (otz) for the three screen coordinates
* an outer product value (opz) for (sx0, sy0), (sx1, sy1), (sx2, sy2)
(LLV0, LLV1, LLV2) = LLM* (v3, v4, v5)
(LC0, LC1, LC2) = BK + LCM* (LLV0, LLV1, LLV2)
(v7, v8, v9) = v6* (LC0, LC1, LC2) (separate multiplications)
Argument format and data formats are as follows:
v0, v1, v2 -> vx, vy, vz : (1, 15, 0) v3, v4, v5 -> vx, vy, vz : (1, 3, 12)
sx0, sy0, sz0 : (1,
15, 0), (1,
15, 0), (0,
16, 0)
sx1, sy1, sz1 : (1,
15, 0), (1,
15, 0), (0,
16, 0)
sx2, sy2, sz2 : (1,
15, 0), (1,
15, 0), (0,
16, 0)
v6 -> r, g, b : (0, 8, 0)
v7, v8, v9 -> r, g, b : (0, 8, 0) otz : (0, 32, 0)
flag : (0, 32, 0)
Return value None.
Remarks
Values are read by macros as shown below. A flag is returned in v0.
value read macro
(sz0, sz1, sz2) read_sz_fifo3
((sx0, sy0), (sx1, sy1), (sx2, sy2)) read_sxsy_fifo3
((r0, g0, b0), (r1, g1, b1), (r2, g2, b2)) read_rgb_fifo
p read_p
otz read_otz
opz read_opz
RotAverageNclipColorDpq3
Coordinate transformation for three points, perspective transformation, and depth queuing. Syntax
long RotAverageNclipColorDpq3 (v0, v1, v2, v3, v4, v5, v6, sxy0, sxy1, sxy2,
v7, v8, v9, otz, flag)
SVECTOR *v0, *v1, *v2; SVECTOR *v3, *v4, *v5; CVECTOR *v6;
long *sxy0, *sxy1, *sxy2; CVECTOR *v7, *v8, *v9; long *otz;
long * flag;
Arguments
v0, v1, v2 v3, v4, v5 v6
sxy0, sxy1, sxy2 v7, v8, v9 otz
flag
Explanation
Vectors (input)
Normal vectors (input)
Primary color vector (input)
Address where coordinate values will be stored Color vectors (output)
Address where an OTZ value will be stored Address where a flag will be stored
This function performs perspective transformation after performing coordinate transformation for three points v0, v1, and v2 using a rotation matrix, and returns screen coordinates to sxy0, sxy1, and sxy2. The function uses the interpolation value p for depth queuing; p is found by the following calculations:
(LLV0, LLV1, LLV2) = LLM* (v3, v4, v5)
(LC0, LC1, LC2) = BK + LCM* (LLV0, LLV1, LLV2)
(v7, v8, v9) = p*(v6* (LC0, LC1, LC2) + (1-p))*FC
VC*( LC0, LC1, LC2) indicates the products of separate multiplications.
The function also returns an average of the Z values of the three screen coordinates to otz. The argument format is as follows:
v0, v1, v2 -> vx, vy, vz: (1, 15, 0) v3, v4, v5 -> vx, vy, vz: (1, 3, 12)
v6 -> r, g, b : (0, 8, 0)
sxy0, sxy1, sxy2 : (1, 15, 0), (1, 15, 0)
v7, v8, v9 -> r, g, b : (0, 8, 0)
otz : (0, 32, 0)
flag : (0, 32, 0)
Return value Outer product of (sx0, sy0), (sx1, sy1), (sx2, sy2)
Remarks When the return value is negative, SX, SY, etc. are incorrect.
RotAverageNclipColorDpq3_nom
Perform coordinate transformation, perspective transformation, and depth queuing. Syntax
void RotAverageNclipColorDpq3_nom (v0, v1, v2, v3, v4, v5, v6)
SVECTOR *v0, *v1, *v2; SVECTOR *v3, *v4, *v5; CVECTOR *v6;
Arguments
v0, v1, v2 Vectors (input)
v3, v4, v5 Normal vectors (input)
v6 Primary color vector (input)
Explanation
After performing coordinate transformation for local coordinate vectors v0, v1, and v2 using a rotation matrix, this function performs perspective transformation and maintains the following values in a GTE internal register:
* three screen coordinates (sx0, sy0, sz0), (sx1, sy1, sz1), (sx2, sy2, and sz2)
* an average of Z values (otz) for the three screen coordinates
* an outer product value (opz) for (sx0, sy0), (sx1, sy1), (sx2, sy2) The interpolation value p for depth queuing is calculated as follows. (LLV0, LLV1, LLV2) = LLM* (v3, v4, v5)
(LC0, LC1, LC2) = BK + LCM* (LLV0, LLV1, LLV2)
(v7, v8, v9) = p*v6* (LC0, LC1, LC2) + (1-p)*FC
v6* (LC0, LC1, LC2) indicates separate multiplications Argument format and data formats are as follows:
v0, v1, v2 -> vx, vy, vz : (1, 15, 0)
v3, v4, v5 -> vx, vy, vz : (1, 3, 12)
v6 -> r, g, b : (0, 8, 0)
sx0, sy0, sz0 : (1,
15, 0), (1,
15, 0), (0,
16, 0)
sx1, sy1, sz1 : (1,
15, 0), (1,
15, 0), (0,
16, 0)
sx2, sy2, sz2 : (1,
15, 0), (1,
15, 0), (0,
16, 0)
v7, v8, v9 -> r, g, b : (0, 8, 0) otz : (0, 32, 0)
flag : (0, 32, 0)
Return value None.
Remarks
Values are read by macro as shown below. A flag is returned in v0.
value read macro
412 Basic Geometry Library (libgte) Functions
(sz0, sz1, sz2)
((sx0, sy0), (sx1, sy1), (sx2, sy2)) ((r0, g0, b0), (r1, g1, b1), (r2, g2, b2) p
otz
opz
read_sz_fifo3 read_sxsy_fifo3 read_rgb_fifo read_p
read_otz
read_opz
Runtime Library Release 3.0
RotColorDpq
Coordinate transformation, perspective transformation, and depth queuing. Syntax
long RotColorDpq (v0, v1, v2, sxy, v3, flag)
SVECTOR *v0; SVECTOR *v1; CVECTOR *v2; long *sxy;
CVECTOR *v3; long * flag;
Arguments
Vector (input)
Normal vector (input) Primary color vector (input)
Address where coordinate values will be stored Color vector (output)
Address where a flag will be stored
Explanation
This function performs perspective transformation after performing coordinate transformation for the point v0 using a rotation matrix, and returns screen coordinates to sxy. The function uses the interpolation value p for depth queuing, which is found by the following calculations:
LLV = LLM*v1
LC=BK + LCM*LLV
v3=p*(v2*LC) + (1-p)*FC
v2*LC indicates the products of separate multiplications The argument format is as follows:
v0 -> vx, vy, vz
v1 -> vx, vy, vz
v2 -> r, g, b sxy
v3 -> r, g, b flag
Return value
: (1, 15, 0) : (1, 3, 12) : (0, 8, 0)
: (1, 15, 0), (1, 15, 0) : (0, 8, 0)
: (0, 32, 0)
1/4 of the Z component sz of screen coordinates
RotColorDpq3
Coordinate transformation for three points, perspective transformation, and depth queuing. Syntax
long RotColorDpq3 (v0, v1, v2, v3, v4, v5, v6, sxy0, sxy1, sxy2, v7, v8, v9, flag)
SVECTOR *v0, *v1, *v2; SVECTOR *v3, *v4, *v5; CVECTOR *v6;
long *sxy0, *sxy1, *sxy2; CVECTOR *v7, *v8, *v9; long * flag;
Arguments
v0, v1, v2 v3, v4, v5 v6
sxy0, sxy1, sxy2 v7, v8, v9 flag
Explanation
Vectors (input)
Normal vectors (input)
Primary color vector (input)
Address where coordinate values will be stored Color vectors (output)
Address where a flag will be stored
This function performs perspective transformation after performing coordinate transformation for three points v0, v1, and v2 using a rotation matrix, and returns screen coordinates to sxy0, sxy1, and sxy2. The function uses the interpolation value p for depth queuing, which is found by the following calculations:
LLV0, LLV1, LLV2) = LLM* (v3, v4, v5)
(LC0, LC1, LC2) = BK + LCM* (LLV0, LLV1, LLV2)
(v7, v8, v9) = p*(v6* (LC0, LC1, LC2)) + (1-p)*FC
Note that v6*(LC0, LC1, LC2) indicates the products of separate multiplications. The argument format is as follows:
v0, v1, v2 -> vx, vy, vz : (1, 15, 0)
v3, v4, v5 -> vx, vy, vz : (1, 3, 12)
v6 -> r, g, b: (0, 8, 0)
sxy0, sxy1, sxy2: (1, 15, 0), (1, 15, 0)
v7, v8, v9 -> r, g, b : (0, 8, 0)
flag: (0, 32, 0)
Return value
1/4 of the Z component sz of screen coordinates.
RotColorDpq3_nom
Perform coordinate transformation, perspective transformation, and depth queuing for three points.
Syntax
long RotColorDpq3_nom (v0, v1, v2, v3, v4, v5, v6)
SVECTOR *v0, *v1, *v2; SVECTOR *v3, *v4, *v5; CVECTOR *v6;
Arguments
v0, v1, v2 Vectors (input)
v3, v4, v5 Normal vectors (input)
v6 Primary color vector (input)
Explanation
After performing coordinate transformation for points v0, v1, and v2 using a rotation matrix, this function performs perspective transformation and stores the three screen coordinates (sx0, sy0, sz0, ), (sx1, sy1, sz1, ) and (sx2, sy2, sz2) in a GTE internal register.
The interpolation value p for depth queuing is used in calculations as shown below. The found color vectors are stored in an internal register.
(LLV0, LLV1, LLV2) = LLM* (v3, v4, v5)
(LC0, LC1, LC2) = BK + LCM* (LLV0, LLV1, LLV2)
(v7, v8, v9) = p*v6* (LC0, LC1, LC2) + (1-p)*FC
v6* (LC0, LC1, LC2) indicates the products of separate multiplications Argument format and data formats are as follows:
v0, v1, v2 -> vx, vy, vz v3, v4, v5 -> vx, vy, vz v6 -> r, g, b
sxy0, sxy1, sxy2
v7, v8, v9 -> r, g, b flag
Return value None.
Remarks
: (1, 15, 0) : (1, 3, 12) : (0, 8, 0)
: (1, 15, 0), (1, 15, 0) : (0, 8, 0)
: (0, 32, 0)
Values are returned by macro. A flag is returned in v0.
value read macro
(sz0, sz1, sz2) read_sz_fifo3
((sx0, sy0), (sx1, sy1), (sx2, sy2)) read_sxsy_fifo3
p read_p
v7, v8, v9 read_rgb_fifo
RotColorDpq_nom
Perform coordinate transformation, perspective transformation, and depth queuing. Syntax
void RotColorDpq_nom (v0, v1, v2)
SVECTOR *v0; SVECTOR *v1; CVECTOR *v2;
Arguments
v0 Vectors (input)
v1 Normal vector (input)
v2 Primary color vector (input)
Explanation
After performing coordinate transformation for point v0 using a rotation matrix, this function performs perspective transformation and stores the screen coordinates (sx, sy, sz) in a GTE internal register.
The interpolation value p for depth queuing is used in calculations as shown below, and color vector v3 is stored in an internal register.
LLV = LLM*v1
LC = BK + LCM*LLV
v3 = p*(v2*LC) + (1-p)*FC
v2*LC indicates separate multiplications
Arguments and internal data formats are as follows:
v0 -> vx, vy, vz : (1, 15, 0)
v1 -> vx, vy, vz : (1, 3, 12)
sx, sy, sz : (1, 15, 0), (1, 15, 0), (0, 16, 0)
v2 -> r, g, b : (0, 8, 0)
v3 -> r, g, b : (0, 8, 0)
flag : (0, 32, 0)
Return value
None.
Remarks A flag is returned in v0. Values are read by macros.
value sz
(sx, sy) p
v3
read macro
read_sz2, read_sxsy2, read_p
read_rgb2.
RotColorMatDpq
Coordinate transformation, perspective transformation, and depth queuing. Syntax
long RotColorMatDpq (v0, v1, v2, sxy, v3, matc, flag)
SVECTOR *v0; SVECTOR *v1; SVECTOR *v2; long *sxy;
CVECTOR *v3; long matc;
long flag;
Arguments
Vector (input)
Normal vector (input) Primary color vector (input)
Address where coordinate values will be stored Color vector (output)
Material (input)
Address where a flag will be stored
Explanation
This function performs perspective transformation after performing coordinate transformation for the point v0 using a rotation matrix, and returns screen coordinates in sxy. The function uses the interpolation value p, found by the following calculations, for depth queuing.
LLV = LLM*v1
LLV = LLV^ (2^matc) LC = BK + LCM*LLV
v3 = p*(v2*LC) + (1-p)*FC
(v2*LC) indicates separate multiplications
The argument format is as follows:
v0 -> vx, vy, vz : (1, 15, 0)
v1 -> vx, vy, vz : (1, 3, 12)
v2 -> r, g, b: (0, 8, 0) sxy : (1, 15, 0), (1, 15, 0)
v3 -> r, g, b: (0, 8, 0) matc : (0, 32, 0) flag: (0, 32, 0)
Return value
1/4 of the Z component sz of screen coordinates.
RotMatrix
Finds a rotation matrix from a rotation angle. Syntax
MATRIX * RotMatrix (r, m) SVECTOR *r;
MATRIX *m;
Arguments
r Rotation angle (input)
m Rotation matrix (output)
Explanation
This function generates a rotation queue from the rotation angle (r[0], r[1], r[2]) in matrix m. A value of 4096 represents 360 degrees; and in matrices, 4096 represents 1 .0.
The argument format is as follows: m -> m[i][j]: (1, 3, 12)
r -> vx, vy, vz: (1, 3, 12)
(where, 1 .0 stands for 360 degrees)
Return value
This function returns m. Remarks
The matrix is obtained by doing the following multiplication. In a coordinate conversion function (such as RotTransPers) for GTE, a vector is multiplied beginning with the rightmost end. So, it is rotated around the Z-, Y-, and X-axes.
-1,
0,
0
c1,
0
s1
c2
-s2 0
0,
c0,
-s0
0
1
0
s2
c2 0
0,
s0,
c0
-s1
0
c1
0
0 1
* c0=cos (r[0]), s0=sin (r[0]) c1=cos (r[1]), s1=sin (r[1]) c2=cos (r[2]), s2=sin (r[2])
Basic Geometry Library (libgte) Functions 419
RotMatrixC
Finds a rotation matrix from a rotation angle. Syntax
MATRIX * RotMatrixC (r, m) SVECTOR *r;
MATRIX *m;
Arguments
r Rotation angle (input)
m Rotation matrix (output)
Explanation Same as RotMatrix()
Return value
This function returns m. Remarks
This function requires a smaller table memory area than RotMatrix(), but its speed is lower.
Runtime Library Release 3.0
RotMatrixX
Finds a rotation matrix around the X axis. Syntax
MATRIX* RotMatrixX (r, m) long r;
MATRIX *m;
Arguments
r Rotation angle (input)
m Rotation matrix (output)
Explanation
This function generates a rotation queue in matrix m as the product of a rotation matrix around the X axis at rotation angle r. A value of 4096 represents a rotation angle of 360 degrees and as a matrix element, 4096 represents 1 .0.
The argument format is as follows:
m -> m[i][j] : (1, 3, 12)
r : (1, 3, 12) (360 degrees represents 1 .0)
Return value
m
Remarks
The matrix is described below.
0 1, 0,
m 0, c, -s
c 0, s,
Where c = cos (r), s = sin (r)
RotMatrixY
Find a rotation matrix around the Y axis. Syntax
MATRIX* RotMatrixY (r, m) long r;
MATRIX *m;
Arguments
r Rotation angle (input)
m Rotation matrix (input/output)
Explanation
This function generates a rotation queue in matrix m as the product of a rotation matrix around the Y axis at rotation angle r. A value of 4096 represents a rotation angle of 360 degrees and as a matrix element, 4096 represents 1 .0.
The argument format is as follows:
m -> m[i][j] : (1, 3, 12)
r : (1, 3, 12) (360 degrees represents 1 .0)
Return value
m
Remarks
The matrix is described below.
c, 0, -s
m 0, 1, 0
c s, 0,
Where c = cos (r), s = sin (r)
RotMatrixYXZ
Finds a rotation matrix from a rotation angle. Syntax
MATRIX* RotMatrixYXZ (r, m) SVECTOR *r;
MATRIX *m;
Arguments
r Rotation angle (input)
m Rotation matrix (output)
Explanation
This function generates a rotation queue in matrix m from the rotation angle (r[0], r[1], r[2]). A value of 4096 represents a rotation angle of 360 degrees, and as a matrix element, 4096 represents 1 .0.
The argument format is as follows:
m -> m[i][j] : (1, 3, 12)
r -> vx, vy, vz : (1, 3, 12) (360 degrees represents 1 .0)
Return value
m
Remarks
The matrix is found by performing the following multiplication. In GTE's coordinate transformation functions (such as RotTransPers()) a vector is multiplied beginning with the rightmost end. This produces rotation around the Z axis, Y axis, and X axis.
c1,
0,
s1
1, 0,
0
c2,
-s2, 0
0,
1,
0
0, c0,
-s0
s2,
c2, 0
-s1,
0,
c1
0, s0,
c0
0,
0, 1
Where c0 = cos (r[0]), s0 = sin (r[0])
c1 = cos (r[1]), s1 = sin (r[1])
c2 = cos (r[2]), s2 = sin (r[2])
RotMatrixZ
Finds a rotation matrix around the Z axis. Syntax
MATRIX* RotMatrixZ (r, m) long r;
MATRIX *m;
Arguments
r Rotation angle input
m Rotation matrix output
Explanation
This function generates a rotation queue in matrix m as the product of a rotation matrix around the Z axis at rotation angle r. A value of 4096 represents a rotation angle of 360 degrees and as a matrix element, 4096 represents 1 .0.
The argument format is as follows: m -> m[i][j] : (1, 3, 12)
r : (1, 3, 12) (360 degrees represent 1 .0)
Return value
m
Remarks The matrix is described below. [ c, -s, 0]*m
[ s, c, 0]
[ 0, 0, 1]
0 c, -s,
m s, c, 0 1 0, 0,
Where c = cos (r), s = sin (r)
RotMesh H
Performs coordinate transformation and perspective transformation. Syntax
void RotMeshH (Yheight, Vo, sz, flag, Xoffset, Zoffset, m, n, base) short *Yheight;
DVECTOR *Vo;
unsigned short *sz; unsigned short * flag; short Xoffset, Zoffset; short m, n;
DVECTOR *base;
Arguments
Yheight
Vo
sz
flag
Xoffset, Zoffset m, n
base
Explanation
Vertex Y coordinate (input) Screen coordinate (output) SZ value (output)
Flag (output)
Offsets for X and Z (input) Number of vertices (input) Base address
This function performs coordinate transformation and perspective transformation for the number of quadrilateral mesh vertices indicated by m x n.
Arguments and internal data format are as follows:
*Yheight
Vo -> vx, vy
sz
flag
Xoffset, Zoffset m, n
base
Return value None.
Remarks
The flag must normally be set between bit 27 and bit 12 of the 32-bit flag.
RotNclip3
Perform coordinate transformation and perspective transformation for three points, and find an interpolation value and outer product for depth queuing.
Syntax
long RotNclip3 (v0, v1, v2, sxy0, sxy1, sxy2, p, otz, flag) SVECTOR *v0, *v1, *v2;
long *sxy0, *sxy1, *sxy2;
long *p;
long *otz;
long * flag;
Arguments
v0, v1, v2
sxy0, sxy1, sxy2 p
otz
flag
Explanation
Vectors (input)
Address where coordinates will be stored
Address where an interpolation value will be stored Address where an OTZ value will be stored Address where a flag will be stored
This function performs perspective transformation after coordinate transformation of three points v0, v1, and v2 using a rotation matrix, and returns three screen coordinates to sxy0, sxy1, and sxy2. It also returns an interpolation value for depth queuing for v2 to p, and returns 1/4 of the Z value of the screen coordinates for v2 to otz.
The argument format is as follows:
v0, v1, v2 -> vx, vy, vz: (1, 15, 0)
sxy0, sxy1, sxy2
: (1, 15, 0), (1,
15, 0)
p
: (0, 20, 12)
otz
: (0, 32, 0)
flag
: (0, 32, 0)
Return value
Outer product of (sx0, sy0), (sx1, sy1), (sx2, sy2) Remarks
When the return value is negative, SX, SY, etc. are incorrect. When SX and SY are needed, use RotTransPer3().
RotNclip3_nom
Perform coordinate transformation and perspective transformation, then find interpolation value for depth queuing and an outer product value.
Syntax
void RotNclip3_nom (v0, v1, v2) SVECTOR *v0, *v1, *v2;
Arguments
v0, v1, v2 Vectors (input) Explanation
After using a rotation matrix to perform coordinate transformation for local coordinate vectors v0, v1, and v2, this function performs perspective transformation and stores the following in the GTE internal register:
* three screen coordinates (sx0, sy0, sz0), (sx1, sy1, sz1), (sx2, sy2, sz2)
* the interpolation value p for depth queuing corresponding to v2
* an outer product value (opz) for (sx0, sy0), (sx1, sy1), (sx2, sy2) Arguments and data formats are as follows:
v0, v1, v2 -> vx, vy, vz sx0, sy0, sz0
sx1, sy1, sz1
sx2, sy2, sz2 p
otz
flag
Return value None.
Remarks
: (1, 15, 0)
: (1, 15, 0), (1, 15, 0), (0, 16, 0) : (1, 15, 0), (1, 15, 0), (0, 16, 0) : (1, 15, 0), (1, 15, 0), (0, 16, 0) : (0, 20, 12)
: (0, 32, 0)
: (0, 32, 0)
Values are read by macro. A flag is returned in v0.
value read macro
(sz0, sz1, sz2) read_sz_fifo3 ((sx0, sy0), (sx1, sy1), (sx2, sy2)) read_sxsy_fifo3
p read_p
opz read_opz.
RotNclip4
Perform coordinate transformation and perspective transformation for four points, and find an interpolation value and outer product for depth queuing.
Syntax
long RotNclip4 (v0, v1, v2, v3, sxy0, sxy1, sxy2, sxy3, p, otz, flag) SVECTOR *v0, *v1, *v2, *v3;
long *sxy0, *sxy1, *sxy2, *sxy3;
long *p;
long *otz;
long * flag;
Arguments
v0, v1, v2, v3
sxy0, sxy1, sxy2, sxy3 p
otz
flag
Explanation
Vectors (input)
Address where coordinates will be stored
Address where an interpolation value will be stored Address where an OTZ value will be stored Address where a flag will be stored
This function performs perspective transformation after coordinate transformation of four points v0, v1, v2, and v3 using a rotation matrix, and returns four screen coordinates to sxy0, sxy1, sxy2, and sxy3. It also returns an interpolation value for depth queuing for v3 to p, and returns 1/4 of the Z value of the screen coordinates for v2 to otz.
The argument format is as follows: v0, v1, v2, v3 -> vx, vy, vz sxy0, sxy1, sxy2, sxy3
p
otz
flag
Return Value
: (1, 15, 0)
: (1, 15, 0), (1, 15, 0) : (0, 20, 12) : (0, 32, 0) : (0, 32, 0)
Outer product of (sx0, sy0), (sx1, sy1), (sx2, sy2) Remarks
When the return value is negative, SX, SY, etc. are incorrect. When SX and SY are required, use RotTransPer4().
RotPM D_F3
Independent vertex POLY_F3-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotPMD_F3 (pa, ot, otlen, id, backc)
long *pa;
unsigned long *ot; int otlen, id, backc;
Arguments
pa
ot
otlen
id
backc
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits)
Double buffer ID
Normal line clipping ON/OFF (0: ON)
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the independent vertex flat three-sided polygon-type (POLY_F3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked.
Return value
None.
RotPM D_F4
Independent vertex POLY_F4-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotPMD_F4 (pa, ot, otlen, id, backc) long *pa;
u_long *ot;
int otlen;
int id;
int backc;
Arguments
pa
ot
otlen
id
backc
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits)
Double buffer ID
Normal line clipping ON/OFF (0: ON)
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the independent vertex flat four-sided polygon-type (POLY_F4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked.
Return value
None.
RotPM D_FT3
Independent vertex POLY_FT3-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotPMD_FT3 (pa, ot, otlen, id, backc) long *pa;
u_long *ot;
int otlen;
int id;
int backc;
Arguments
pa
ot
otlen
id
backc
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits)
Double buffer ID
Normal line clipping ON/OFF (0: ON)
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the independent vertex flat, textured three-sided polygon-type (POLY_FT3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked.
Return value
None.
RotPM D_FT4
Independent vertex POLY_FT4-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotPMD_FT4 (pa, ot, otlen, id, backc) long *pa;
u_long *ot;
int otlen;
int id;
int backc;
Arguments
pa
ot
otlen
id
backc
Explanation
Top address of PRIMITIVE Gp Top address of OT
Length of OT (number of bits)
Double buffer ID
Backface clip ON/OFF flag (0 = ON)
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the independent vertex flat, textured four-sided polygon-type (POLY_FT4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked.
Return value
None.
RotPM D_G3
Independent vertex POLY_G3-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotPMD_G3 (pa, ot, otlen, id, backc)
long *pa; u_long *ot; int otlen; int id;
int backc;
Arguments
pa
ot
otlen
id
backc
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits)
Double buffer ID
Normal line clipping ON/OFF (0: ON)
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the independent vertex Gouraud-shaded three-sided polygon-type (POLY_G3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked.
Return value
None.
RotPM D_G4
Independent vertex POLY_G4-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotPMD_G4 (pa, ot, otlen, id, backc) long *pa;
u_long *ot;
int otlen;
int id;
int backc;
Arguments
pa
ot
otlen
id
backc
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits)
Double buffer ID
Normal line clipping ON/OFF (0: ON)
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the independent vertex Gouraud-shaded four-sided polygon-type (POLY_G4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked.
Return value
None.
RotPM D_GT3
Independent vertex POLY_GT3-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotPMD_GT3 (pa, ot, otlen, id, backc) long *pa;
u_long *ot;
int otlen;
int id;
int backc;
Arguments
pa
ot
otlen
id
backc
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits)
Double buffer ID
Normal line clipping ON/OFF (0: ON)
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the independent vertex Gouraud-shaded, textured three-sided polygon-type (POLY_GT3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked.
Return value
None.
RotPM D_GT4
Independent vertex POLY_GT4-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotPMD_GT4 (pa, ot, otlen, id, backc) long *pa;
u_long *ot;
int otlen;
int id;
int backc;
Arguments
pa
ot
otlen
id
backc
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits)
Double buffer ID
Normal line clipping ON/OFF (0: ON)
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the independent vertex Gouraud-shaded, textured four-sided polygon-type (POLY_GT4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked.
Return value
None.
RotPM D_SV_F3
Shared vertex POLY_F3-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotPMD_SV_F3 (pa, va, ot, otlen, id, backc)
long *pa; long *va; u_long *ot; int otlen; int id;
int backc;
Arguments
pa va ot otlen
id backc
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits)
Double buffer ID
Normal line clipping ON/OFF (0: ON)
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the shared vertex flat three-sided polygon-type (POLY_F3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked.
Return value
None.
RotPM D_SV_F4
Shared vertex POLY_F4-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotPMD_SV_F4 (pa, va, ot, otlen, id, backc) long *pa;
long *va;
u_long *ot;
int otlen;
int id;
int backc;
Arguments
pa va ot otlen
id backc
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits)
Double buffer ID
Normal line clipping ON/OFF (0: ON)
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the shared vertex flat four-sided polygon-type (POLY_F4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked.
Return value
None.
RotPM D_SV_FT3
Shared vertex POLY_FT3-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotPMD_SV_FT3 (pa, va, ot, otlen, id, backc)
long *pa; long *va; u_long *ot; int otlen; int id;
int backc;
Arguments
pa va ot otlen
id backc
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits)
Double buffer ID
Normal line clipping ON/OFF (0: ON)
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the shared vertex flat, textured three-sided polygon-type (POLY_FT3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked.
Return value
None.
RotPM D_SV_FT4
Shared vertex POLY_FT4-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotPMD_SV_FT4 (pa, va, ot, otlen, id, backc)
long *pa; long *va; u_long *ot; int otlen; int id;
int backc;
Arguments
pa va ot otlen
id backc
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits)
Double buffer ID
Normal line clipping ON/OFF (0: ON)
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the shared vertex flat, textured four-sided polygon-type (POLY_FT4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked.
Return value
None.
RotPM D_SV_G3
Shared vertex POLY_G3-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotPMD_SV_G3 (pa, va, ot, otlen, id, backc)
long *pa; long *va; u_long *ot; int otlen; int id;
int backc;
Arguments
pa va ot otlen
id backc
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits)
Double buffer ID
Normal line clipping ON/OFF (0: ON)
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the shared vertex Gouraud-shaded three-sided polygon-type (POLY_G3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked.
Return value
None.
RotPM D_SV_G4
Shared vertex POLY_G4-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotPMD_SV_G4 (pa, va, ot, otlen, id, backc)
long *pa; long *va; u_long *ot; int otlen; int id;
int backc;
Arguments
pa va ot otlen
id backc
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits)
Double buffer ID
Normal line clipping ON/OFF (0: ON)
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the shared vertex Gouraud-shaded four-sided polygon-type (POLY_G4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked.
Return value
None.
RotPM D_SV_GT3
Shared vertex POLY_GT3-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotPMD_SV_GT3 (pa, va, ot, otlen, id, backc)
long *pa; long *va; u_long *ot; int otlen; int id;
int backc;
Arguments
pa va ot otlen
id backc
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits)
Double buffer ID
Normal line clipping ON/OFF (0: ON)
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the shared vertex Gouraud-shaded, textured three-sided polygon-type (POLY_GT3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked.
Return value
None.
RotPM D_SV_GT4
Shared vertex POLY_GT4-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotPMD_SV_GT4 (pa, va, ot, otlen, id, backc) long *pa;
long *va;
u_long *ot;
int otlen;
int id;
int backc;
Arguments
pa va ot otlen
id backc
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits)
Double buffer ID
Normal line clipping ON/OFF (0: ON)
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the shared vertex flat four-sided polygon-type (POLY_GT4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked.
Return value
None.
RotRM D_F3
Independent vertex POLY_F3-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotRMD_F3 (pa, ot, otlen, id) long *pa;
u_long *ot;
int otlen;
int id;
Arguments
pa
ot
otlen id
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the independent vertex flat three-sided polygon-type (POLY_F3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. No normal line clipping is performed.
Return value None.
RotRM D_F4
Independent vertex POLY_F4-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotRMD_F4 (pa, ot, otlen, id)
long *pa; u_long *ot; int otlen; int id;
Arguments
pa
ot
otlen id
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the independent vertex flat four-sided polygon-type (POLY_F4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. No normal line clipping is performed.
Return value None.
RotRM D_FT3
Independent vertex POLY_FT3-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotRMD_FT3 (pa, ot, otlen, id) long *pa;
u_long *ot;
int otlen;
int id;
Arguments
pa
ot
otlen id
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the independent vertex flat, textured three-sided polygon-type (POLY_FT3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. No normal line clipping is performed.
Return value None.
RotRM D_FT4
Independent vertex POLY_FT4-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotRMD_FT4 (pa, ot, otlen, id) long *pa;
u_long *ot;
int otlen;
int id;
Arguments
pa
ot
otlen id
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the independent vertex flat, textured four-sided polygon-type (POLY_FT4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. No normal line clipping is performed.
Return value None.
RotRM D_G3
Independent vertex POLY_G3-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotRMD_G3 (pa, ot, otlen, id) long *pa;
u_long *ot;
int otlen;
int id;
Arguments
pa
ot
otlen id
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the independent vertex Gouraud-shaded three-sided polygon-type (POLY_G3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. No normal line clipping is performed.
Return value None.
RotRM D_G4
Independent vertex POLY_G4-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotRMD_G4 (pa, ot, otlen, id) long *pa;
u_long *ot;
int otlen;
int id;
Arguments
pa
ot
otlen id
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the independent vertex Gouraud-shaded four-sided polygon-type (POLY_G4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. No normal line clipping is performed.
Return value None.
RotRM D_GT3
Independent vertex POLY_GT3-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotRMD_GT3 (pa, ot, otlen, id) long *pa;
u_long *ot;
int otlen;
int id;
Arguments
pa
ot
otlen id
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the independent vertex Gouraud-shaded, textured three-sided polygon-type (POLY_GT3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. No normal line clipping is performed.
Return value None.
RotRM D_GT4
Independent vertex POLY_GT4-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotRMD_GT4 (pa, ot, otlen, id) long *pa;
u_long *ot;
int otlen;
int id;
Arguments
pa
ot
otlen id
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the independent vertex Gouraud-shaded, textured four-sided polygon-type (POLY_GT4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. No normal line clipping is performed.
Return value None.
RotRM D_SV_F3
Shared vertex POLY_F3-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotRMD_SV_F3 (pa, va, ot, otlen, id)
long *pa; long *va; u_long *ot; int otlen; int id;
Arguments
pa va ot otlen
id
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the shared vertex flat three-sided polygon-type (POLY_F3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. No normal line clipping is performed.
Return value None.
RotRM D_SV_F4
Shared vertex POLY_F4-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotRMD_SV_F4 (pa, va, ot, otlen, id)
long *pa; long *va; u_long *ot; int otlen; int id;
Arguments
pa va ot otlen
id
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the shared vertex flat four-sided polygon-type (POLY_F4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. No normal line clipping is performed.
Return value None.
RotRM D_SV_FT3
Shared vertex POLY_FT3-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotRMD_SV_FT3 (pa, va, ot, otlen, id)
long *pa; long *va; u_long *ot; int otlen; int id;
Arguments
pa va ot otlen
id
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the shared vertex flat, textured three-sided polygon-type (POLY_FT3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. No normal line clipping is performed.
Return value None.
RotRM D_SV_FT4
Shared vertex POLY_FT4-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotRMD_SV_FT4 (pa, va, ot, otlen, id)
long *pa; long *va; u_long *ot; int otlen; int id;
Arguments
pa va ot otlen
id
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the shared vertex flat, textured four-sided polygon-type (POLY_FT4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. No normal line clipping is performed.
Return value None.
RotRM D_SV_G3
Shared vertex POLY_G3-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotRMD_SV_G3 (pa, va, ot, otlen, id)
long *pa; long *va; u_long *ot; int otlen; int id;
Arguments
pa va ot otlen
id
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the shared vertex Gouraud-shaded three-sided polygon-type (POLY_G3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. No normal line clipping is performed.
Return value None.
RotRM D_SV_G4
Shared vertex POLY_G4-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotRMD_SV_G4 (pa, va, ot, otlen, id)
long *pa; long *va; u_long *ot; int otlen; int id;
Arguments
pa va ot otlen
id
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the shared vertex Gouraud-shaded four-sided polygon-type (POLY_G4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. No normal line clipping is performed.
Return value None.
RotRM D_SV_GT3
Shared vertex POLY_GT3-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotRMD_SV_GT3 (pa, va, ot, otlen, id)
long *pa; long *va; u_long *ot; int otlen; int id;
Arguments
pa va ot otlen
id
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the shared vertex Gouraud-shaded, textured three-sided polygon-type (POLY_GT3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. No normal line clipping is performed.
Return value None.
RotRM D_SV_GT4
Shared vertex POLY_GT4-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotRMD_SV_GT4 (pa, va, ot, otlen, id)
long *pa; long *va; u_long *ot; int otlen; int id;
Arguments
pa va ot otlen
id
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the shared vertex Gouraud-shaded, textured four-sided polygon-type (POLY_GT4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. No normal line clipping is performed.
Return value None.
RotSM D_F3
Independent vertex POLY_F3-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotSMD_F3 (pa, ot, otlen, id)
long *pa; u_long *ot;
int otlen; int id;
Arguments
pa
ot
otlen id
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the independent vertex flat three-sided polygon-type (POLY_F3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. Normal line clipping must be performed.
Return value None.
RotSM D_F4
Independent vertex POLY_F4-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotSMD_F4 (pa, ot, otlen, id)
long *pa; u_long *ot;
int otlen; int id;
Arguments
pa
ot
otlen id
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the independent vertex flat four-sided polygon-type (POLY_F4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. Normal line clipping must be performed.
Return value None.
RotSM D_FT3
Independent vertex POLY_FT3-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotSMD_FT3 (pa, ot, otlen, id) long *pa;
u_long *ot;
int otlen;
int id;
Arguments
pa
ot
otlen id
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the independent vertex flat three-sided polygon-type (POLY_FT3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. Normal line clipping must be performed.
Return value None.
RotSM D_FT4
Independent vertex POLY_FT4-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotSMD_FT4 (pa, ot, otlen, id) long *pa;
u_long *ot;
int otlen;
int id;
Arguments
pa
ot
otlen id
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the independent vertex flat four-sided polygon-type (POLY_FT4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. Normal line clipping must be performed.
Return value None.
RotSM D_G3
Independent vertex POLY_G3-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotSMD_G3 (pa, ot, otlen, id) long *pa;
u_long *ot;
int otlen;
int id;
Arguments
pa
ot
otlen id
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the independent vertex flat three-sided polygon-type (POLY_G3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. Normal line clipping must be performed.
Return value None.
RotSM D_G4
Independent vertex POLY_G4-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotSMD_G4 (pa, ot, otlen, id) long *pa;
u_long *ot;
int otlen;
int id;
Arguments
pa
ot
otlen id
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the independent vertex flat four-sided polygon-type (POLY_G4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. Normal line clipping must be performed.
Return value None.
RotSM D_GT3
Independent vertex POLY_GT3-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotSMD_GT3 (pa, ot, otlen, id) long *pa;
u_long *ot;
int otlen;
int id;
Arguments
pa
ot
otlen id
Explanation
Starting address of PRIMITIVE Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the independent vertex flat three-sided polygon-type (POLY_GT3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. Normal line clipping must be performed.
Return value None.
RotSM D_GT4
Independent vertex POLY_GT4-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotSMD_GT4 (pa, ot, otlen, id) long *pa;
u_long *ot;
int otlen;
int id;
Arguments
pa
ot
otlen id
Explanation
Top address of PRIMITIVE Gp Top address of OT
Length (number of bits) of OT Double buffer ID
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the independent vertex flat four-sided polygon-type (POLY_GT4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. Normal line clipping must be performed.
Return value None.
RotSM D_SV_F3
Shared vertex POLY_F3-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotSMD_SV_F3 (pa, va, ot, otlen, id)
long *pa; long *va; u_long *ot; int otlen; int id;
Arguments
pa va ot otlen
id
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the shared vertex flat three-sided polygon-type (POLY_F3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. Normal line clipping must be performed.
Return value None.
RotSM D_SV_F4
Shared vertex POLY_F4-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotSMD_SV_F4 (pa, va, ot, otlen, id)
long *pa; long *va; u_long *ot; int otlen; int id;
Arguments
pa va ot otlen
id
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the shared vertex flat four-sided polygon-type (POLY_F4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. Normal line clipping must be performed.
Return value None.
RotSM D_SV_FT3
Shared vertex POLY_FT3-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotSMD_SV_FT3 (pa, va, ot, otlen, id)
long *pa; long *va; u_long *ot; int otlen; int id;
Arguments
pa va ot otlen
id
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the shared vertex flat, textured three-sided polygon-type (POLY_FT3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. Normal line clipping must be performed.
Return value None.
RotSM D_SV_FT4
Shared vertex POLY_FT4-type PM D data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotSMD_SV_FT4 (pa, va, ot, otlen, id)
long *pa; long *va; u_long *ot; int otlen; int id;
Arguments
pa va ot otlen
id
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the shared vertex flat, textured four-sided polygon-type (POLY_FT4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. Normal line clipping must be performed.
Return value None.
RotSM D_SV_G3
Shared vertex POLY_G3-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotSMD_SV_G3 (pa, va, ot, otlen, id)
long *pa; long *va; u_long *ot; int otlen; int id;
Arguments
pa va ot otlen
id
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the shared vertex Gouraud-shaded three-sided polygon-type (POLY_G3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. Normal line clipping must be performed.
Return value None.
RotSM D_SV_G4
Shared vertex POLY_G4-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotSMD_SV_G4 (pa, va, ot, otlen, id)
long *pa; long *va; u_long *ot; int otlen; int id;
Arguments
pa va ot otlen
id
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the shared vertex Gouraud-shaded four-sided polygon-type (POLY_G4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. Normal line clipping must be performed.
Return value None.
RotSM D_SV_GT3
Shared vertex POLY_GT3-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotSMD_SV_GT3 (pa, va, ot, otlen, id)
long *pa; long *va; u_long *ot; int otlen; int id;
Arguments
pa va ot otlen
id
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all three-sided polygons included in the shared vertex Gouraud-shaded, textured three-sided polygon-type (POLY_GT3) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. Normal line clipping must be performed.
Return value None.
RotSM D_SV_GT4
Shared vertex POLY_GT4-type PMD data coordinate transformation/perspective transformation/link to OT.
Syntax
void RotSMD_SV_GT4 (pa, va, ot, otlen, id)
long *pa; long *va; u_long *ot; int otlen; int id;
Arguments
pa va ot otlen
id
Explanation
Starting address of PRIMITIVE Gp Starting address of VERTEX Gp Starting address of OT
Length of OT (number of bits) Double buffer ID
This function performs coordinate transformations and perspective transformations on all four-sided polygons included in the shared vertex Gouraud-shaded, textured four-sided polygon-type (POLY_GT4) PRIMITIVE Gp, then completes the GPU packet and links it to OT.
Only polygons with an SZ value within the range [h/2, 2^1 6] may be linked. Normal line clipping must be performed.
Return value None.
RotTrans
Perform coordinate transformation using a rotation matrix. Syntax
void RotTrans (v0, v1, flag) SVECTOR *v0;
VECTOR *v1;
long * flag;
Arguments
v0 Vector (input)
v1 Vector (output)
flag Address where a flag is stored
Explanation
This function calculates v1=RTM*v0. The argument format is as follows:
v0 -> vx, vy, vz v1 -> vx, vy, vz flag
Return value None.
Basic Geometry Library (libgte) Functions 477
RotTransPers
Performs coordinate and perspective transformation. Syntax
long RotTransPers (vo, sxy, p, flag) SVECTOR *v0;
long *sxy;
long *p;
long * flag;
Arguments
v0 Vertex coordinate vector (input)
sxy Address where the screen coordinates are stored
p Address where the interpolated value is stored
flag Address where a flag is stored
Explanation
After converting the coordinate vector v0 with a rotation matrix, the function performs perspective transformation, and returns screen coordinates sx, sy. It also returns an interpolated value for depth queuing in p.
The argument format is as follows:
v0 -> vx, vy, vz : (1, 15, 0)
sxy : (1, 15, 0), (1, 15, 0)
p : (0, 20, 12)
flag : (0, 32, 0)
Return value
1/4 of the screen coordinate Z component sz.
Runtime Library Release 3.0
RotTransPers3
Perform coordinate transformation of three vertices and perspective transformation. Syntax
long RotTransPers3 (v0, v1, v2, sxy0, sxy1, sxy2, p, flag) SVECTOR *v0, *v1, *v2;
long *sxy0, *sxy1, *sxy2;
long *p;
long * flag;
Arguments
v0, v1, v2
sxy0, sxy1, sxy2 p
flag
Vertex coordinate vectors
Addresses where the screen coordinates are stored Address where the interpolated value is stored Address where a flag is stored
Explanation
After transforming the three coordinate vectors v0, v1, and v2 using a rotation matrix, the function performs perspective transformation, and returns three screen coordinates sxy0, sxy1, and sxy2. It also returns to p an interpolated value for depth queuing corresponding to v2. The argument format is as follows:
v0, v1, v2 -> vx, vy, vz: (1, 15, 0)
sxy0, sxy1, sxy2 : (1, 15, 0), (1, 15, 0)
p : (0, 20, 12)
flag : (0, 32, 0)
Return value
1/4 of the screen coordinate Z component sz corresponding to v2.
RotTransPers3N
Perform coordinate transformation and perspective transformation. Syntax
void RotTransPers3N (v0, v1, sz, flag, n)
SVECTOR *v0; DVECTOR *v1; unsigned short *sz;
unsigned short * flag;
long n;
Arguments
Vertex coordinate vector (input) Vertex coordinate vector (output) SZ value (output)
Flag (output)
Number of vertices (output)
Explanation This function executes the RotTransPers3() function for the number of triangles specified by n. Arguments and internal data formats are as follows:
v0 -> vx, vy, vz : (1, 15, 0) v1 -> vx, vy : (1, 15, 0)
sz : (0, 16, 0)
flag : (0, 16, 0)
Return value None.
Remarks
The flag must normally be set between bits 27 and 12 of the 32-bit flag.
RotTransPers3_nom
Perform coordinate transformation and perspective transformation for three vertices. Syntax
void RotTransPers3_nom (v0, v1, v2) SVECTOR *v0, *v1, *v2;
Arguments
v0, v1, v2 Vertex coordinate vector (input) Explanation
After performing coordinate transformation for three coordinate vectors v0, v1, and v2 using a rotation matrix, this function performs perspective transformation and maintains the following values in a GTE register:
* three screen coordinates (sx0, sy0, sz0), (sx1, sy1, sz1), (sx2, sy2, sz2)
* the depth queue interpolation value that corresponds to v2 Arguments and internal data formats are as follows:
v0, v1, v2 -> vx, vy, sx0, sy0, sz0
sx1, sy1, sz1
sx2, sy2, sz2 p
flag
Return value None.
Remarks
vz: (1, 15, 0)
: (1, 15, 0), (1, 15, 0), (0, 16, 0) : (1, 15, 0), (1, 15, 0), (0, 16, 0) : (1, 15, 0), (1, 15, 0), (0, 16, 0) : (0, 20, 12)
: (0, 32, 0)
Values are read by macros as shown below.
value read macro
(sz0, sz1, sz2) read_sz_fifo3 ((sx0, sy0), (sx1, sy1), (sx2, sy2)) read_sxsy_fifo3
p read_p
flag read_flag
RotTransPers4
Perform coordinate transformation and perspective transformation for 4 vertices. Syntax
long RotTransPers4 (v0, v1, v2, v3, sxy0, sxyl, sxy2, sxy3, p, flag) SVECTOR *v0, *v1, *v2, *v3;
long *sxy0, *sxy1, *sxy2, *sxy3;
long *p;
long * flag;
Arguments
v0, v1, v2, v3
sxy0, sxy1, sxy2, sxy3 p
flag
Vectors (input)
Addresses where the screen coordinates are stored Address where the interpolated value is stored Address where the flag is stored
Explanation
After transforming the four coordinate vectors v0, v1, v2, and v3 using a rotation matrix, the function performs perspective transformation, and returns four screen coordinates sxy0, sxy1, sxy2, and sxy3. It also returns an interpolated value for depth queuing to p corresponding to v3.The argument format is as follows:
v0, v1, v2, v3 -> vx, vy, vz sxy0, sxy1, sxy2, sxy3 p
flag
Return value
: (1, 15, 0)
: (1, 15, 0), (1, 15, 0) : (0, 20, 12) : (0, 32, 0)
1/4 of the Z component sz of the screen coordinates corresponding to v3.
RotTransPers4_nom
Perform coordinate transformation and perspective transformation for three vertices. Syntax
void RotTransPers4_nom (v0, v1, v2, v3) SVECTOR *v0, *v1, *v2, *v3;
Arguments
v0, v1, v2, v3 Vertex coordinate vectors (input) Explanation
After performing coordinate transformation for four coordinate vectors v0, v1, v2, and v3 using a rotation matrix, this function performs perspective transformation and maintains the following values in a GTE internal register:
* screen coordinates (sz0), (sx1, sy1, sz1), (sx2, sy2, sz2), (sx3, sy3, sz3)
* the depth queue interpolation value that corresponds to v3 Arguments and internal data formats are as follows:
v0, v1, v2 -> vx, vy, vz: (1, 15, 0)
sx0, sy0, sz0
sx1, sy1, sz1
sx2, sy2, sz2
sx3, sy3, sz3 p
flag
Return value Flag
Remarks
: (1, 15, 0), (1, 15, 0), (0, 16, 0) : (1, 15, 0), (1, 15, 0), (0, 16, 0) : (1, 15, 0), (1, 15, 0), (0, 16, 0) : (1, 15, 0), (1, 15, 0), (0, 16, 0) : (0, 20, 12)
: (0, 32, 0)
Values are read by macros as shown below.
(sx0, sy0) is returned in register v1. A flag is returned in register v0.
value read macro
(sz0, sz1, sz2, sz3) read_sz_fifo4
((sx1, sy1), (sx2, sy2), (sx3, sy3)) read_sxsy_fifo3
p read_p
RotTransPersN
Perform coordinate transformation and perspective transformation. Syntax
void RotTransPersN (v0, v1, sz, flag, n)
SVECTOR *v0; DVECTOR *v1; unsigned short *sz;
unsigned short * flag;
long n;
Arguments
Vertex coordinate vector (input) Vertex coordinate vector (output) SZ value (output)
Flag (output)
Number of vertices (output)
Explanation
This function performs the RotTransPers() function for the number of vertices specified by n.
The arguments and internal data formats are as follows:
v0 -> vx, vy, vz : (1, 15, 0)
v1 -> vx, vy : (1, 15, 0)
sz : (0, 16, 0) flag : (0, 16, 0)
Return value
None.
Remarks
The flag must normally be set between bits 27 and 12 of the 32-bit flag.
RotTransPers_nom
Perform coordinate transformation and perspective transformation. Syntax
void RotTransPers_nom (v0) SVECTOR *v0;
Arguments
v0 Vertex coordinate vector (input) Explanation
After performing coordinate transformation for coordinate vector v0 using a rotation matrix, this function performs perspective transformation and stores screen coordinates sx, sy, and sz and the interpolation value p for depth queue in the GTE internal register.
v0 -> vx, vy, vz : (1, 15, 0)
sx : (1, 15, 0) sy : (1, 15, 0) sz : (0, 16, 0) p : (0, 20, 12) flag : (0, 32, 0)
Return value None.
Remarks
Values are read by macros as shown below.
value read macro
sz read_sz2,
(sx, sy) read_sxsy2,
p read_p
flag read_flag
RotTrans_nom
Perform coordinate transformation using rotation matrix. Syntax
void RotTrans_nom (v0) SVECTOR *v0;
Arguments
v0 Vector (input)
Explanation
v1 = RTM*v0
Calculates arguments and data formats as follows:
v0 -> vx, vy, vz v1 -> vx, vy, vz flag
Return value None.
Remarks
Values are read by macros as shown below.
value read macro
(v1 -> vx, v1 -> vy, v1 -> vz) read_mt, flag read_flag.
486 Basic Geometry Library (libgte) Functions
rsin
Sine. Syntax
long rsin (a) long int a;
Arguments
a Angle (in Playstation format)
Explanation
Finds the sine function of the angle (in Playstation format) (4096=360 degrees) using fixed-point math (where 4096=1.0).
The argument format is as follows:
a : Playstation format (4096 = 360 degrees) return value : (1, 19, 12)
Return value sin (a)
Runtime Library Release 3.0
ScaleMatrix
Scales a matrix. Syntax
MATRIX *ScaleMatrix (m, v)
MATRIX *m; VECTOR *v;
Arguments
m Matrix (output)
v Scale vector (input)
Explanation
This function scales m by v. The components of v are fixed point decimals in which 1 .0 represents 4096.The argument format is as follows:
m -> m[i][j]: (1, 3, 12)
v -> vx, vy, vz: (1, 3, 12) Return value
The function returns m.
Remarks If:
m =
a00,
a01,
a02
a10,
a11,
a12
a20,
a21,
a22
v =
Then:
m =
[sx,
sy,
sz]
a01 * sy,
a02 * sz
a00 * sx,
a10 * sx,
a20 * sx,
a11 * sy,
a21 * sy,
a12 * sz
a22 * sz
488 Basic Geometry Library (libgte) Functions
ScaleMatrixL
Scales a matrix. Syntax
MATRIX* ScaleMatrixL (m, v) MATRIX *m;
VECTOR *v;
Arguments
m Matrix (output)
v Scale vector (input)
Explanation
This function scales matrix m by v. The elements of v are fixed point numbers in which 4096 represents a value of 1 .0.
The argument format is as follows:
m -> m[i][j] : (1, 3, 12)
v -> vx, vy, vz : (1, 3, 12)
If:
m =
a00,
a01,
a02
a10,
a11,
a1 2
a20,
a21,
a22
Then:
v =
m =
[sx,
a00
sy,
sx,
sz]
a01
sx,
a02
sx
a10
sy,
a11
sy,
a12
sy
a20
sz,
a21
sz,
a22
sz
Return value m
Basic Geometry Library (libgte) Functions 489
SetBackColor
Setting back color vectors. Syntax
void SetBackColor (rbk, gbk, bbk) long rbk, gbk, bbk;
Arguments
rbk, gbk, bbk Vectors (input)
Explanation This function sets the back color vectors (rbk, gbk, bbk). Color values are in the range 0 to 255.
The argument format is as follows: (rbk, gbk, bbk): (0, 32, 0)
Return value None.
Runtime Library Release 3.0
490 Basic Geometry Library (libgte) Functions
SetColorMatrix
Sets a local color matrix. Syntax
void SetColorMatrix (m) MATRIX *m;
Arguments
m Matrix (input) Explanation
This function sets a local color matrix specified by m. The argument format is as follows: m -> m[i][j] : (1, 3, 12)
Return value None.
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 491
SetFarColor
Sets far color vectors. Syntax
void SetFarColor (rfc, gfc, bfc) long rfc, gfc, bfc;
Arguments
rfc, gvc, bfc Vectors (input) Explanation
This function sets the far color vectors (rfc, gfc, bfc). Color values are in the range 0 to 255.The argument format is as follows:
(rfc, gfc, bfc): (0, 32, 0)
Return value None.
Runtime Library Release 3.0
492 Basic Geometry Library (libgte) Functions
SetFog Far
Sets a fog parameter. Syntax
void SetFogFar (a, h) long a, h;
Arguments
a Z value
h Distance
Explanation
When the distance between the visual point and screen is h, a defines the Z value at which the fog is 100%. A Z value which makes fog 0% is automatically set to 0.2*a. a should satisfy 0<a<65536.
The argument format is as follows:
a : (0, 32, 0)
h : (0, 32, 0)
Return value None.
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 493
SetFog Near
Sets a fog parameter. Syntax
void SetFogNear (a, h) long a, h;
Arguments
a Z value
h Distance
Explanation
When the distance between the visual point and screen is h, a defines the Z value at which the fog is 0%. A Z value which makes fog 100% is automatically set to 5*a. a should satisfy 0<a<65536*0.2.
The argument format is as follows:
a : (0, 32, 0) h : (0, 32, 0)
Return value None.
Runtime Library Release 3.0
494 Basic Geometry Library (libgte) Functions
SetGeomOffset
Sets offset values. Syntax
void SetGeomOffset (ofx, ofy) long ofx, ofy;
Arguments
ofx, ofy Offset input values
Explanation This function sets the offset values (ofx, ofy).
The argument format is as follows: ofx, ofy: (1, 31, 0)
Return value None.
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 495
SetGeomScreen
Sets the projection. Syntax
void SetGeomScreen (h) long h;
Arguments
h Distance
Explanation This function sets the distance h (projection) from a visual point (the eye) to the screen. The argument format is as follows:
h: (0, 32, 0)
Return value None.
Runtime Library Release 3.0
496 Basic Geometry Library (libgte) Functions
SetLightMatrix
Sets a local light matrix. Syntax
void SetLightMatrix (m) MATRIX *m;
Arguments
m Matrix (input) Explanation
This function sets a local light matrix specified by m. The argument format is as follows: m -> m[i][j]: (1, 3, 12)
Return value None.
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 497
SetM ul Matrix
Multiplies two matricies and sets one rotation matrix. Syntax
MATRIX *SetMulMatrix (m0, m1) MATRIX *m0, *m1;
Arguments
m0, m1 Input matricies Explanation
Multiplies two matricies and stores that value in one constant rotation matrix. The argument format is as follows:
m0, m1 -> m[i][j] : (1, 3, 12)
Return value Returns m0.
Runtime Library Release 3.0
498 Basic Geometry Library (libgte) Functions
SetRG Bcd
Set primary color vector and GPU code. Syntax
void SetRGBcd (v) CVECTOR *v;
Arguments
v Color vector and GPU code input: Explanation
This function sets the primary color vector and GPU code v.
The argument format is as follows: v -> r, g, b, cd : (0, 8, 0)
Return value None.
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 499
SetRotMatrix
Sets a constant rotation matrix. Syntax
void SetRotMatrix (m) MATRIX *m;
Arguments
m Matrix (input)
Explanation
This function sets a 3x3 follows:
m -> m[i][j]: (1, 3, 12)
matrix m as a constant rotation matrix. The argument format is as
Return value None.
Runtime Library Release 3.0
500 Basic Geometry Library (libgte) Functions
SetTransMatrix
Setting a constant parallel transfer vector. Syntax
void SetTransMatrix (m) MATRIX *m;
Arguments
m Matrix (input)
Explanation
This function sets a constant parallel transfer vector specified by m. The argument format is as follows:
m -> t[i]: (1, 31, 0)
Return value None.
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 501
Square0
Squaring a vector. Syntax
void Square0 (v0, v1) VECTOR *v0; VECTOR *v1;
Arguments
v0 Vector (L1, L2, L3) (input)
v1 Vector (L1^2, L2^2, L3^2) (output)
Explanation
This function returns a vector, obtained by squaring each term of the vector v0, to v1. The argument format is as follows:
v0 -> vx, vy, vz : (1, 31, 0) v1 -> vx, vy, vz : (1, 31, 0)
Return value Returns v1.
Runtime Library Release 3.0
502 Basic Geometry Library (libgte) Functions
Square12
Squaring a vector. Syntax
void Square12 (v0, v1)
VECTOR *v0; VECTOR *v1;
Arguments
v0 Vector (L1, L2, L3) (input)
v1 Vector (L1^2, L2^2, L3^2) (output)
Explanation
This function returns a vector, obtained by dividing the square of each term of the vector v0 by 4096, to v1. The argument format is as follows:
v0 -> vx, vy, vz : (1, 19, 12) v1 -> vx, vy, vz : (1, 19, 12)
Return value Returns v1.
Runtime Library Release 3.0
SquareRoot0
Square root. Syntax
long SquareRoot0 (a) long a;
Arguments
a Value
Explanation This function returns the square root of a value a. The argument format is as follows:
a : (0, 32, 0)
Return value : (0, 32, 0)
Return value
Returns the square root of a.
SquareRoot12
Square root. Syntax
long SquareRoot12 (a) long a;
Arguments
a Value
Explanation
This function returns the square root of a value a, which has (0, 20, 12) format, in (0, 20, 12) format.
The argument format is as follows:
a : (0, 20, 12)
Return value : (0, 20, 12)
Return value
Square root of a.
SubPol3
Subdividing a triangle. Syntax
void SubPol3 (p, sp, ndiv) POL3 *p;
SPOL *sp;
int ndiv;
Arguments
p 3-vertex polygon
sp Subdivision vertex array
ndiv Number after subdivision 0: None; 1: 2x2; 2: 4x4
Explanation
This function subdivides a three-sided polygon p by the number 2**ndiv, and returns the subdivision vertex coordinates, texture coordinates, and RGB to a triangle in an array indicated by sp. See the figure below:
The argument format is as follows:
p -> sxy p -> sz p -> uv p -> rgb p -> code sp -> xy sp -> uv sp -> rgb
Return value None.
: (1, 15, 0), (1, 15, 0) : (0, 16, 0)
: (1, 15, 0), (1, 15, 0)
: (0, 8, 0), (0, 8, 0), (0, 8, 0) : (0, 32, 0)
: (1, 15, 0), (1, 15, 0) : (1, 15, 0), (1, 15, 0)
: (0, 8, 0), (0, 8, 0), (0, 8, 0)
SubPol4
Subdividing a quadrangle. Syntax
void SubPol4 (p, sp, ndiv) POL4 *p;
SPOL *sp;
int ndiv;
Arguments
p 4-vertex polygon
sp Subdivision vertex array
ndiv Number after subdivision 0: None; 1: 2x2; 2: 4x4
Explanation
This function subdivides a four-sided polygon p by the number 2**ndiv, and returns the subdivision vertex coordinates, texture coordinates, and RGB to an array indicated by sp. See the figure below:
p[0] p[1] sp[0] sp[1] sp[2]
p[2] p[3]
: (1, 15, 0), (1, 15, 0) : (0, 16, 0)
: (1, 15, 0), (1, 15, 0)
: (0, 8, 0), (0, 8, 0), (0, 8, 0) : (0, 32, 0)
: (1, 15, 0), (1, 15, 0) : (1, 15, 0), (1, 15, 0)
: (0, 8, 0), (0, 8, 0), (0, 8, 0)
Return value None.
TransMatrix
Sets the amount of parallel transfer. Syntax
MATRIX *TransMatrix (m, v)
MATRIX *m; VECTOR *v;
Arguments
m Matrix (output)
v Transfer vector (input)
Explanation
This function gives an amount of parallel transfer expressed by v to the matrix m. The argument format is as follows:
m -> m[i][j]
: (1, 3, 12)
m -> t[i]
: (1, 31, 0)
v -> vx, vy, vz
: (1, 31, 0)
Return value
This function returns m.
508 Basic Geometry Library (libgte) Functions
TransposeMatrix
Transposes a matrix Syntax
MATRIX *TransposeMatrix (m0, m1) MATRIX *m0, *m1;
Arguments
m0 Matrix (input)
m1 Matrix (output)
Explanation
Transposes matrix m0 into m1.
The argument format is as follows: m0 -> m[i][j] : (1, 3, 12)
m1 -> m[i][j] : (1, 3, 12)
Return value Returns m1.
Runtime Library Release 3.0
Basic Geometry Library (libgte) Functions 509
VectorNormal
Normalize a vector. Syntax
void VectorNormal (v0, v1) VECTOR *v0; VECTOR *v1;
Arguments
v0 Vector (input)
v1 Vector (output)
Explanation
This function normalizes a vector v0 and returns the result in v1. The argument format is as follows:
v0 -> vx, vy, vz : (1, 31, 0)
v1 -> vx, vy, vz : (1, 19, 12)
Return value
Sum of squared v0 elements
Runtime Library Release 3.0
510 Basic Geometry Library (libgte) Functions
VectorNormalS
Normalize a vector. Syntax
long VectorNormalS (v0, v1) VECTOR *v0;
SVECTOR *v1;
Arguments
v0 v1
Explanation
This function normalizes a vector v0 and returns the result in v1.
The argument format is as follows: v0 -> vx, vy, vz : (1, 31, 0) v1 -> vx, vy, vz : (1, 3, 12)
Return value
Sum of squared v0 elements Remarks
The calculation will be incorrect if the sum of the squared elements of v0 exceeds 2^31-1.
Chapter 7
Extended Graphics Library (libgs)
This chapter describes structures defined in the extended graphics library (libgs) and the available functions. "libgs" is a high-level graphics library that uses libgpu and libgte. Three-dimensional functionality such as light source calculations, perspective transformations, and point-of-view specification have been added. There is also support for such two-dimensional functions as basic point and line figure drawing, Sprite and BG drawing, and attribute control.
Chapter 7: Additional Graphics Library (libgs) Table of Contents
Structures
GsBG
515
GsBOXF
516
GsCELL
517
GsCOORDINATE2
517
GsDOBJ2
519
GsDOBJ3
521
GsDOBJ5
522
GsFOGPARAM
524
GsF_LIGHT
525
GsGLINE
526
GsIMAGE
527
GsLINE
528
GsMAP
529
GsOBJTABLE2
530
GsOT
531
GsOT_TAG
532
GsRVIEW2
533
GsSPRITE
534
GsVIEW2
537
Functions
GsClearOt
538
GsClearVcount
539
GsCreateNewObj2
540
GsCutOt
541
GsDefDispBuffer
542
GsDrawOt
543
GsGetActiveBuffer
544
GsGetLs
545
GsGetLw
546
GsGetLws
547
GsGetTimInfo
548
GsGetVcount
549
GsGetWorkBase
550
GsInit3D
551
GsInitCoordinate2
552
GsInitFixBg16, GsInitFixBg32
553
GsInitGraph
553
GsInitObjTable2
555
GsInitVcount
556
GsLinkObject3
557
GsLinkObject4
558
GsLinkObject5
559
GsMapModelingData
560
GsMulCoord2
561
GsMulCoord3
562
GsPresetObject
563
GsRemoveObj2
564
GsSearchObjByID2
565
GsSearchTmdByID
566
GsSetAmbient
567
GsSetClip
568
GsSetClip2
569
GsSetClip2D
569
GsSetDrawBuffClip
571
GsSetDrawBuffOffset
572
GsSetFlatLight
573
GsSetFogParam
574
GsSetLightMatrix
575
GsSetLightMode
576
GsSetLsMatrix
577
GsSetOffset
578
GsSetProjection
578
GsSetRefView2
580
GsSetTodFrame2
581
GsSetTodPacket2
582
GsSetWorkBase
583
GsSortBg, GsSortFastBg
584
GsSortFixBg16, GsSortFixBg32
585
GsSortBoxFill
586
GsSortClear
587
GsSortLine, GsSortGLine
588
GsSortObject3
589
GsSortObject4
590
GsSortObject5
591
GsSortOt
592
GsSortPoly
593
GsSortSprite, GsSortFastSprite, GsSortFlipSprite
594
GsSwapDispBuffer
595
Extended Graphics Library (libgs) Structures 515
BG (background surface) handler. Structure
struct GsBG {
unsigned long attribute;
short x, y;
short w, h;
short scrollx, scroly; unsigned char r, g, b; GsMAP *map;
short mx, my;
short scalex, scaley; long rotate;
};
Members
attribute
x, y
w, h
scrollx, scrolly r, g, b
map
mx, my
scalex, scaley rotate
Explanation
Attribute
Top left point display position BG display size
x and y scroll values
Display brightness is set in r, g, b. (Normal brightness is 128.) Pointer to map data
Rotation and enlargement central point coordinates
Scale values in x and y directions Rotation angle (4096 = 1 degree)
BG (background) draws a large rectangle based on GsMAP data on a combination of small rectangles defined by GsCELL data. There is a GsBg for each BG. BG may be manipulated via GsBG.
To register GsBg in the ordering table, use GsSortBg().
(x, y) specifies the screen display position.
(w, h) specifies BG display size in pixels, and is not dependent on cell size or map size.
If the display area is larger than the map, the content of the map is repeatedly displayed. (Tiling function)
(scrollx, scroly) specifies offset from the map display position in dots.
(r, g, b) specifies brightness values. The range is 0 to 255. 128 is the brightness of the original pattern; 255 doubles the brightness.map is a pointer to the map data of the GsMAP format.
(map) specifies the starting address of map data with a pointer to GsMAP format map data.
(mx, my) specify rotation and enlargement central coordinates as relative coordinates. The top left point of the BG is the point of origin. For example, if rotation is around the center of the BG, specify w/2 and h/2.
(scalex, scaley) specifies enlargement/reduction values in the x and y directions. These values are expressed in units of 4096, which stands for 1 .0 (i.e. is the same size as 1 .0). You can set these values up to 8 times the original size.
(rotate) specifies a rotation angle around the z-axis (4096 = 1 degree). For (attribute), see the description in GsSPRITE.
516 Extended Graphics Library (libgs) Structures
GsBOXF
Rectangle handler. Structure
struct GsBOXF {
unsigned long attribute; short x, y;
unsigned short w, h; unsigned char r, g, b; };
Members
attribute Attribute (see GsLINE attributes) x, y Display position (top left point)
w, h Size of rectangle (width, height) r, g, b Drawing color
Explanation
GsBOXF is a structure used to draw a rectangle in a single color. To register GsBOXF in the ordering table, the GsSortBoxFill() function is used.
Runtime Library Release 3.0
GsCELL
Cells constituting BG. Structure
struct GsCELL {
unsigned short u, v; unsigned short cba; unsigned short flag; unsigned short tpage; };
Members
cba CLUT ID
tpage Texture page number
u Offset (X-direction) within the page
v Offset (Y-direction) within the page
Explanation
GsCell is a structure containing data on cells that comprise BG, allocated as an array in memory.
cba is data that displays the position within the frame buffer of a CLUT corresponding to the cell, as follows.
Bit Value
Bit 0-5 X position of CLUT/1 6
Bit 6-15 Y position of CLUT
tpage is a page number that indicates the position of a Sprite pattern within a frame buffer.
(u, v) specifies the position of the Sprite pattern corresponding to the cell in terms of offset within the page specified by tpage.
flag specifies option information for performing drawing. The meaning of each bit is as shown below.
Bit Value
Bit 0 Vertical flip (0: no flip; 1: flip)
Bit 1 Horizontal flip (0: no flip; 1: flip)
GsCOORDINATE2
Matrix type coordinate system. Structure
struct GsCOORDINATE2 { unsigned long flg;
MATRIX coord;
MATRIX workm;
GsCOORD2PARM *param; GsCOORDINATE2 * super; GsCOORDINATE2 *sub; };
Members
flg Flag indicating whether coord was rewritten
coord Matrix
workm Result of multiplication from this coordinate system to the WORLD coordinate system
param Pointer for scale, rotation, and transfer parameters
super Pointer to superior coordinates
sub Not in current use
Explanation
GsCOORDINATE2 has superior coordinates and is defined by the matrix type coord.
workm retains the result of multiplication of matrices performed by the GsGetLw() and GsGetLs() functions in each node of GsCOORDINATE2 using the WORLD coordinates.
flg is referenced to omit calculations for a node for which calculations were already made, during GsGetLw() calculations. 1 means the flage is set, 0 clears the flag. The programmer must clear this flag when he has changed coord. If you neglect to clear it, the GsGetLw() and GsGetLs() functions will fail to execute normally.
param is used for setting coord values with layout tools.
Remarks
param may be freely used if TOD animation is not used.
GsDOBJ2
Used by the three-dimensional object handler GsCOORDINATE2. Structure
struct GsDOBJ2 {
unsigned long attribute; GsCOORDINATE2 *coord2; unsigned long *tmd;
unsigned long id;
};
Members
attribute Object attribute (32-bit)
coord2 Pointer to a local coordinate system
tmd Pointer to modelling data
id Reserved by the layout tool
Explanation
There is a GsDOBJ2 for each object of a three dimensional model; GsDOBJ2 structures may be used to manipulate the 3-dimensional model.
Use GsLinkObject4() is to link GsDOBJ2 to TMD file modelling data.
You can use GsDOBJ2 to access TMD data linked by GsLinkObject4(). Use GsSortObject4() to register GsDOBJ2 in the ordering table.
coord2 is a pointer to a coordinate system unique to an object. The location, inclination, and size of the object is reflected in a matrix set in the coordinate system to point to coord2.
tmd retains the starting address of TMD modelling data stored in memory. tmd is calculated and set using GsLinkObject4().
attribute is 32-bit; various display attributes are set here. An explanation of each bit follows. (a) Material attenuation (bit 0-2) (not currently supported)
This sets the relationship between the normal gradient and brightness attenuation when light source calculation is performed. This takes a value of 0-3. With 0 there is no attenuation; the steepest attenuation is with 3. This parameter can be used to display an object's material quality. In general, making the attenuation steep produces a metallic quality.
Note the following points.
(1) If the material attenuation value is high, calculation takes longer and the processing requires a lot of resources.
(2) This parameter is invalid In lighting mode unless material ON is set. (b)lighting mode (bit 3-5)
This sets the light source calculation formula. It takes a value of 0-3. The values are as listed below.
Bit 5, the highest ranking bit, is a switch to validate the lighting mode set by GsSetLightMode().
Value Operation
0 normal mode without fog or material attenuation. This is the fastest mode and calculation takes least time.
1 fog only mode. The fog parameter is GsFOGPARAM; set the parameter with GsSetFogParam().
2 material attenuation only mode. The amount of attenuation is set by the material attenuation bit. Not currently supported.
3 applies both fog and material attenuation. Not currently supported.
Table: Lighting modes
(c) Light source calculation ON/OFF switch (bit 6)
This bit is used when light source calculation is not performed. When light source calculation is removed, a texture-mapped polygon is displayed in the original texture color. An unmapped polygon is displayed in the modelling data color.
(d)semi-transparency rate (bit 28-29)
When semi-transparency is set to ON with bit 30, the semi-transparency rate sets the pixel-blending formula.
Value Processing
0 normal semi-transparency processing
1 pixel addition
2 50% addition
3 pixel subtraction
Table: Semi-transparency rate
(e) Semi-transparency ON/OFF (bit 30) This sets semi-transparency ON/OFF.
This bit must be used with the uppermost bit (STP bit) of the texture color field (texture pattern when direct and CLUT color field when indexed) to set semi-transparency,. Also, the semi-transparency and non-transparency of each pixel unit may be controlled using this STP bit.
(f) Display ON/OFF (bit 31) This turns display ON and OFF.
GsDOBJ3
Used by the three-dimensional object handler PMD FORMAT. Structure
struct GsDOBJ3 { unsigned long attribute; GsCOORDINATE2 *coord2;
unsigned long *pmd; unsigned long *base; unsigned long *sv; unsigned long id;
};
Members
attribute coord2
pmd base sv
id
Explanation
Object attribute (32-bit)
Pointer to a local coordinate system Pointer to modelling data (PMD FORMAT) Object base address
Shared vertex base address
Reserved by the layout tool
There is a GsDOBJ3 for each object of a 3-dimensional model; GsDOBJ3 structures may be used to manipulate the 3-dimensional model.
Use GsLinkObject3() to link GsDOBJ3 to PMD file modelling data.
You can use GsDOBJ3 to access PMD data linked by GsLinkObject3(). Use GsSortObject3() to register GsDOBJ3 in the ordering table.
coord2 is a pointer to a coordinate system unique to an object. The location, inclination, and size of the object is reflected in a matrix set in the coordinate system to point to coord2.
pmd retains the starting address of PMD modelling data stored in memory. pmd is calculated and set using GsLinkObject3().
attribute is 32-bit; various display attributes are set here. Only the attribute shown below is currently available. (a) Display ON/OFF (bit 31)
This turns display ON and OFF.
Remarks
id is not used unless the layout function is used.
GsDOBJ5
Used by the three-dimensional object handler GsSortObject5. Structure
struct GsDOBJ5 {
unsigned long attribute; GsCOORDINATE2 *coord2; unsigned long *tmd;
unsigned long *packet; unsigned long id;
};
Members
attribute coord2 tmd
packet id
Explanation
Object attribute (32-bit)
Pointer to local coordinate system Pointer to modelling data
Pointer to preset packet area Reserved by the layout tool
There is a GsDOBJ5 for each object of a 3-dimensional model; GsDOBJ5 structures may be used to manipulate the 3-dimensional model.
Use GsLinkObject5() to link GsDOBJ5 to TMD file modelling data.
You can use GsDOBJ5 to access TMD data linked by GsLinkObject5(). Use GsSortObject5() to register GsDOBJ5 in the ordering table.
coord2 is a pointer to a coordinate system unique to an object. The location, inclination, and size of the object is reflected in a matrix set in the coordinate system to point to coord2.
tmd retains the starting address of TMD modelling data stored in memory. tmd is calculated and set using GsLinkObject5().
packet retains the starting address of a preset packet copied into memory. A preset packet is copied by GsPresetObject(), and is set in a GsDOBJ5 packet.
attribute is 32-bit; various display attributes are set here. An explanation of each bit follows. (a) Material attenuation (bit 0-2) (not currently supported)
This sets the relationship between the normal gradient and brightness attenuation when light source calculation is performed. This takes a value of 0-3. With 0 there is no attenuation; the steepest attenuation is with 3. This parameter can be used to display an object's material quality. In general, making the attenuation steep produces a metallic quality.
Note the following points.
(1) If the material attenuation value is high, calculation takes longer and the processing requires a lot of resources.
(2) This parameter is invalid In lighting mode unless material ON is set. (b)lighting mode (bit 3-5)
This sets the light source calculation formula. It takes a value of 0-3. The values are as listed below.
Bit 5, the highest ranking bit, is a switch to validate the lighting mode set by GsSetLightMode().
Value Operation
0 normal mode without fog or material attenuation. This is the fastest mode and calculation takes least time.
1 fog only mode. The fog parameter is GsFOGPARAM; set the parameter with GsSetFogParam().
2 material attenuation only mode. The amount of attenuation is set by the material attenuation bit. Not currently supported.
3 applies both fog and material attenuation. Not currently supported.
Table: Lighting modes
(c) Light source calculation ON/OFF switch (bit 6)
This bit is used when light source calculation is not performed. When light source calculation is removed, a texture-mapped polygon is displayed in the original texture color. An unmapped polygon is displayed in the modelling data color.
(d)Display ON/OFF (bit 31)
This turns display ON and OFF.
Remarks
id is not used unless the layout function is used.
524 Extended Graphics Library (libgs) Structures
GsFOGPARAM
Fog (depth cue) information. Structure
struct GsFOGPARAM { short dqa;
long dqb;
unsigned char rfc, gfc, bfc; };
Members
dqa dqb
rfc, gfc, bfc Explanation
Parameter for the degree of merging due to depth Parameter for the degree of merging due to depth
For the meaning of these parameters, see the description of "FOG" in "FUNDAMENTAL GEOMETRY LIBRARY Part 1". Background colors
dqa and dqb are background color attenuation coefficients. They can be calculated using the following formulas:
DQA = -df * 4096/64/h DQB = 1.25 * 4096 * 4096
df is the distance where the attenuation coefficient is "1"; that is, the distance from the viewpoint to where the background colors are completely blended.
"h" indicates a projection, or a distance from the visual point to the screen.
Extended Graphics Library (libgs) Structures 525
GsF_LIG HT
Parallel light source. Structure
struct GsF_LIGHT { long vx, vy, vz;
unsigned char r, g, b; };
Members
vx, vy, vz Directional vectors for light source
r, g, b Light colors
Explanation
GsF_LIGHT holds parallel light source information, and is set in the system by the GsSetFlatLight() function. Up to three parallel light sources may be set at the same time.
The light source directional vector is specified by (vx, vy, vz). It is unnecessary for the programmer to perform normalization because the system does it. A polygon whose normal vectors are opposite to these directional vectors is exposed to the strongest light.
Light source colors are set in 8 bits by (r, g, b).
Runtime Library Release 3.0
526 Extended Graphics Library (libgs) Structures
GsGLINE
Straight line handler with gradation. Structure
struct GsLINE {
unsigned long attribute; short x0, y0;
short x1, y1;
unsigned char r0, g0, b0; unsigned char r1, g1, b1; };
Members
attribute Attribute (see GsLINE attributes) x0, y0 Drawing start point position x1, y1 Drawing end point position r0, g0, b0 Drawing colors of start point r1, g1, b1 Drawing colors of end point
Explanation
GsGLINE is a structure used to draw straight lines with gradation. It is the same as GsLINE except that drawing colors for the starting point and end point may be specified separately.
Runtime Library Release 3.0
Extended Graphics Library (libgs) Structures 527
GsIMAGE
Information on image data composition. Structure
struct GsIMAGE {
short pmode;
short px, py;
unsigned short pw, ph; unsigned long *pixel; short cx, cy;
unsigned short cw, ch; unsigned long * clut; };
Members
pmode Pixel mode
0: 4-bit CLUT
1: 8-bit CLUT
2: 16-bit DIRECT
3: 24-bit DIRECT
4: Coexistence of multiple modes
px, py Pixel data storage location
pw, ph Pixel data width and height
pixel pointer to pixel data
cx, cy CLUT data storage location
cw, ch CLUT data width and height
clut pointer to CLUT data
Explanation
A structure in which TIM format data information is stored by the GsGetTimInfo() function.
Runtime Library Release 3.0
528 Extended Graphics Library (libgs) Structures
GsLINE
Straight line handler. Structure
struct GsLINE {
unsigned long attribute;
short x0, y0; short x1, y1; unsigned char r, g, b;
}
Members
attribute Attribute
28-29: Semi-transparency rate
0 50% x Back + 50% x Line
1 100% x Back + 100% x Line
2 100% x Back + 50% x Line
3 100% x Back - 100% x Line
30: Semi-transparency ON/OFF
0: Semi-transparency OFF
1: Semi-transparency ON
31:0: Displayed 1: Not displayed
x0, y0 Drawing start point position
x1, y1 Drawing end point position
r, g, b Drawing color
Explanation
GsLINE is a structure for drawing straight lines. Use GsSortLine() to register a GsLINE in the ordering table.
"attribute" is 32 bits, and sets various attributes for display. (a) Semi-transparency rate (bit 28-29)
If semi-transparency is turned on using bit 30, bits 28 and 29 are used to set the pixel blending method.
(b)Semi-transparency ON/OFF (bit 30)
This bit turns semi-transparency ON and OFF. (c)Display ON/OFF (bit 31)
Runtime Library Release 3.0
Map comprising BG. Structure
struct GsMAP {
unsigned char celw, cellh; unsigned short ncellw, ncelh; GsCELL * base;
unsigned short *index;
};
Members
celv, celh ncellw, ncellh
Cell size (0 is treated as 256.) Size of BG (in cells)
(Not displayed if w or h is 0.) Pointer to GsCELL structure array Pointer to cell information
base index
Explanation
GsMAP is map data used to compose BG from GsCELL. Map data are managed by cell index array information.
cellw, cellh specify the size of one cell in pixels. Note that one BG is made up of cells of the same size.
ncellw and ncellh set the size of the BG map in cells.
base sets the starting address of the GsCELL array. index sets the starting address of the cell data table. Cell data is a list of index values (whose number is equivalent to ncellw * ncellh) for the arrays specified by base. If the index value is 0xffff, it is thought of as indicating NULL cell (transparent cell).
530 Extended Graphics Library (libgs) Structures
GsOBJTABLE2
Object table information. Structure
struct GsDOBJTABLE2 { GsDOBJ2 *top;
int nobj;
int maxnobj;
};
Members
top pointer to object array
maxobj size of object array
nobj number of valid objects in array
Explanation
When the three-dimensional animation function group is used, a three-dimensional object must be in the array in order to give effect to the object ID number specification. This array is called an object table. GsOBJTABLE2 contains information relating to the object table.
top is a pointer to the GsDOBJ2 array, within which the three-dimensional object managed by ID is created. The GsDOBJ2 array must be allocated prior to object table initialization.
maxobj is the size of array indicated by top; its value must be greater than the maximum value of the object handled.
nobj is the number of valid objects within the array. GsOBJTABLE2 is initialized by GsInitObjTable2().
Runtime Library Release 3.0
Ordering table header. Structure
struct GsOT {
unsigned short length;
GsOT_TAG *org; unsigned short offset;
unsigned short point;
GsOT_TAG *tag; };
Members
length Bit length of OT
org Start address of GsOT_TAG table
offset OT screen coordinate system Z-axis offset
point OT screen coordinate system Z-axis typical value
tag Pointer to GsOT_TAG currently located at the start
Explanation
GsOT is the ordering table header supported by libgs. This header has pointers to the ordering table org and tag; org and tag are initialized together by the function GsClearOt().
The GsDrawOt() function draws the ordering table indicated by tag. The value of tag is changed by the GsSortClear() or GsSortOt() function. org always preserves the start of the ordering table.
Length sets the size of the ordering table to values from 1-14. If the value "1" is specified, org points to a GsOT_TAG array running from 0~1. If the value "14" is specified, org points to a GsOT_TAG array running from 0~16384.
The GsClearOt() function initializes memory from org through to the size indicated by length. Note that memory will be destroyed if the size of the GsOT_TAG array pointed to by org is greater than that specified by length.
"point" is used by the GsSortOt() function in the sorting of ordering tables.
The ordering table Z-axis offset is set by "offset". For example, if offset = 256, the start of the ordering table is Z = 256. (Not yet supported.)
Remarks
length and org values should be set first. The other members are set by the GsClearOt() function.
See also: GsClearOt (p. 538), GsDrawOt (p. 543), GsSortOt (p. 592), GsCutOt(541).
532 Extended Graphics Library (libgs) Structures
GsOT_TAG
Ordering table unit. Structure
struct GsOT_TAG { unsigned p : 24;
unsigned char num : 8; };
Members
p OT ring pointer
num Number of words in a packet
Explanation
Ordering table arrays follow the order of GsOT_TAG arrays. The ordering table has a list structure that points at addresses in order. p may indicate the LS 24 bits in a 32-bit address.
Allocate a GsOT_TAG array having GsOT members and size length when loading the ordering table into memory.
Runtime Library Release 3.0
GsRVIEW2
Viewpoint position (Reference type). Structure
struct GsRVIEW2 { long vpx, vpy, vpz long vpx, vpy, vpz long rz
GsCOORDINATE2 * super
};
Members
vpx, vpy, vpz viewpoint coordinates
vrx, vry, vrz reference point coordinates
rz viewpoint twist
super pointer to the coordinate system that sets the viewpoint (GsCOORDINATE2type)
Explanation
GsVIEW2 holds viewpoint information, and is set in libgs by the GsSetRefView2() function.
The viewpoint coordinates in the coordinate system displayed by Super are set in (vpx, vpy, vpz).
The reference point coordinates in the coordinate system displayed by Super are set in (vrx, vry, vrz).
When the z axis a vector from the viewpoint to the reference point, rz specifies the screen inclination against the z axis in fixed decimal format, with 4096 set to one degree.
Viewpoint and reference point coordinate systems are set in super. As an example of using this function, an airplane cockpit view can be realized simply by setting super to the airplane coordinate system.
GsSPR ITE
Sprite handler. Structure
struct GsSPRITE {
unsigned long attribute; short x, y;
unsigned short w, h; unsigned short tpage; unsigned char u, v;
short cx, cy;
unsigned char r, g, b; short mx, my;
short scalex, scaley; long rotate;
}
Members
attribute
x, y
w, h
tpage u, v
cx, cy r, g, b
mx, my scalex, scaley rotate
32 bits; see listing below.
Display position of the top left point Width and height of the Sprite (Not displayed if w or h is 0.)
Sprite pattern texture page number Sprite pattern offset within the page Sprite CLUT address
Display brightness is set in r, g, b. (Normal brightness is 128.)
Rotation and enlargement central point coordinates Scale values in x and y directions Rotation angle (4096 = 1 degree)
6: Brightness adjustment
0: OFF 1: ON
22: Vertical flip
0: not flipped
1: flipped
23: Horizontal flip
0: not flipped
1: flipped
24-25: Sprite pattern bit mode 0: 4-bit CLUT
1: 8-bit CLUT
2: 15-bit Direct
27: Rotation, enlargement, and reduction functions 0: ON1: OFF
28-29: Semi-transparency rate 0: 50% x Back + 50% x Sprite
1: 100% x Back + 100% x Sprite
2: 100% x Back + 50% x Sprite
3: 100% x Back - 100% x Sprite
30: Semi-transparency ON/OFF 0: Semi-transparency OFF
1: Semi-transparency ON
31: 0: Displayed 1: Not displayed NOTE: Bit 26 is not supported as yet.
Explanation
GsSPRITE is a structure used to display a Sprite. This structure makes it possible to manipulate each Sprite via its parameters.
To register a GsSPRITE in the ordering table, use GsFlipSprite(), GsSortSprite(), or GsSortFastSprite().
(x, y) specifies the screen display position. (mx, my) specifies the point in the Sprite pattern used as the display position in GsSortSprite(); in GsSortFastSprite(), the point at the top left of the Sprite is used as the display position.
(w, h) specifies the width and height of the Sprite in pixels.
tpage specifies the texture page number (0-3 1) of the Sprite pattern.
(u, v) specifies the offset within the page from the top left point of the Sprite pattern. The range that may be specified is (0, 0) - (255, 255).
(cx, cy) specifies the starting position of CLUT (color palette) as a VRAM address. (Valid for 4-bit/8-bit mode only)
(r, g, b) specifies brightness values. The range is 0 to 255. 128 is the brightness of the original pattern; 255 doubles the brightness.
(mx, my) specify rotation and enlargement central coordinates as relative coordinates. The top left point of the Sprite is the point of origin. For example, if rotation is around the center of the Sprite, specify w/2 and h/2.
(scalex, scaley) specifies enlargement/reduction values in the x and y directions. These values are expressed in units of 4096, which stands for 1 .0 (i.e. is the same size as 1 .0). You can set these values up to 8 times the original size.
(rotate) sets rotation around the z-axis according to fixed-decimal format, in which 4096 is 1 degree.
attribute is 32 bits, and sets various attributes for display. An explanation of each bit follows. (a) Brightness adjustment ON/OFF switch (bit 6)
This bit sets Sprite pattern pixel colors according to (r, g, b) values. If this bit is set to 1, brightness is not adjusted, and (r, g, b) values are ignored.
(b)Vertical flipping, horizontal flipping (bits 22-23) Sets Sprite pattern flipping display.
(c)Color mode (bits 24-25)
A Sprite pattern has 4-bit mode and 8-bit mode, both of which use the color table, and 15-bit mode, which directly displays colors. These bits are used to select any of these modes.
(d)Rotation enlargement/reduction function (bit 27)
This bit turns on or off the Sprite enlargement function. If rotation or enlargement of the Sprite is not needed, this bit should be set to OFF for high speed processing.
GsSortFastSprite() and GsSortFlipSprite() ignore this bit and always set the enlargement function to off.
(e)Semi-transparency rate (bits 28-29)
If semi-transparency was turned on using bit 30, bits 28 and 29 are used to set the pixel blending method.
0 is for ordinary semi-transparency processing, 1 is for pixel addition, 2 is for 50% addition, and 3 is for pixel subtraction.
(f) Semi-transparency ON/OFF (bit 30)
This bit turns semi-transparency ON and OFF.
To select semi-transparency, this bit should be set, and at the same time the texture color field (colors in the texture pattern for direct, CLUT color field for indexed) must be set. Use of the STP bit allows control of the semi-transparency/opacity of each bit.
(g)Display ON/OFF (bit 31)
This bit is used to turn Sprite display ON or OFF.
GsVI EW2
Viewpoint position (matrix type). Structure
struct GsVIEW2 {
MATRIX view;
GsCOORDINATE *super };
Members
view matrix used to change from superior coordinates to viewpoint coordinates
super pointer to the coordinate system that sets viewpoint
Explanation
This sets the viewpoint coordinate system. It specifies the matrix used by view to change from superior coordinates to viewpoint coordinates.
The function that sets GsVIEW2 is GsSetView2().
538 Extended Graphics Library (libgs) Functions
GsClearOt
Initializes OT. Syntax
void GsClearOt (offset, point, otp) unsigned short offset;
unsigned short point;
GsOT *otp;
Arguments
offset Ordering table offset value
point Ordering table typical value Z
otp Pointer to ordering table
Explanation This function initializes the ordering table specified by otp.
offset is the value of Z at the start of the ordering table.
point is "Z", referenced when incorporating that ordering table into another ordering table. To specify the size to be cleared, the length of OT must first be specified.
Return value None.
Runtime Library Release 3.0
GsClearVcount
Clears vertical retrace counter. Syntax
Extended Graphics Library (libgs) Functions 539
void GsClearVcount (void)
Arguments None.
Explanation
This function clears the vertical retrace counter.
Return value None.
Runtime Library Release 3.0
GsCreateNewObj2
Creates a new object. Syntax
Creates an object that has the ID number specified by id in the object table. The superior coordinate system is WORLD and attribute is set to 0.
Return value
Returns a pointer to the object created. NULL is returned if it fails to create the object.
Extended Graphics Library (libgs) Functions 541
GsCutOt
OT separation. Syntax
GsOT *GsCutOt (ot_src, ot_dest) GsOt *ot_src;
GsOt *ot_dest;
Arguments
ot_src Pointer to old OT ot_dest Pointer to new OT
Explanation
This function extracts the drawing commands registered in the OT given by ot_src for separation from the old OT, and insertion in ot_dest.
The ot_dest tag stores a pointer to the separated drawing command. ot_src length is 0, while tag is set to NULL.
After the function call, ot_dest can be used to access OT, even though ot_src has been cleared.
Return value
ot_dest starting address.
Runtime Library Release 3.0
GsDefDispBuffer
Defines double buffers. Syntax
void GsDefDisp Buffer (x0, y0, x1, y1)
int x0, y0; int x1, y1;
Arguments
x0, y0 Buffer 0 origin point (top left point)
x1, y1 Buffer 1 origin point (top left point)
Explanation
This function defines double buffers.
(x0, y0) and (x1, y1) specify frame buffer coordinate values. The default is that buffer 0 is designated by (0, 0) and buffer 1 is designated by (0, y_res), where y_res is the vertical resolution specified by GsInitGraph().
If (x0, y0) and (x1, y1) are specified as the same coordinates, the double buffers are released. However, double-buffer swapping of even-numbered and odd-numbered fields is performed automatically when (x0, y0) and (x1, y1) are specified as the same coordinates in interlace mode.
The GsSwapDispBuffer() function is used to swap double buffers. The double buffer is implemented by the GPU/GTE offset. Set the libgpu or libgte offset with GsInitGraph(). When using the libgpu offset, coordinate values based on the coordinate system using the upper left point in the double buffer as the origin will be created in the packet (add the offset at the time of drawing, not at the time of packet preparation).
Return value None.
GsDrawOt
Drawing for a drawing command allocated to OT. Syntax
void GsDrawOt (otp) GsOT *otp;
Arguments
otp Pointer to OT Explanation
This function starts execution of a drawing command registered in OT, specified by otp. Because drawing processing is performed in the background, GsDrawOt() returns immediately.
Return value None.
Remarks
This function does not execute correctly when GPU drawing is in progress, so it is necessary to call this function after terminating drawing using ResetGraph (1).
544 Extended Graphics Library (libgs) Functions
GsGetActiveBuffer
Gets a buffer number during drawing. Syntax
int GsGetActiveBuffer (void)
Arguments None.
Explanation
This function gets a double buffer index. Index values are either 0 or 1.
By entering indexes in the external variables, PSDBASEX[] and PSDBASEY[], it is possible to determine the two-dimensional address of the double buffer origin point (top left coordinates) in the frame buffer.
Return value
Index of a double buffer (0 for buffer 0, and 1 for buffer 1)
Runtime Library Release 3.0
GsGetLs
Calculating a local screen matrix. Syntax
void GsGetLs (coord, m) GsCOORDINATE2 *coord; MATRIX *m;
Arguments
coord Local coordinates m Matrix
Explanation
This function calculates a local screen perspective transformation matrix from coord in the matrix-type coordinate system GsCOORDINATE2 specified by an argument, and stores the result in the MATRIX-type structure m.
For high speed operation, the function retains the result of calculation at each node of the hierarchical coordinate system. When the next GsGetLs() function is called, calculation up to the node to which no changes have been made is omitted. This is controlled by a GsCOORDINATE2 member flag (libgs replaces 1 in flags already calculated by GsCOORDINATE2).
If the contents of a superior node is changed, the effect on a subordinate node is handled by libgs, so it is not necessary to clear the flags of all subordinate nodes of the changed superior node.
Return value None.
546 Extended Graphics Library (libgs) Functions
GsGetLw
Calculating a local world matrix. Syntax
void GsGetLw (coord, m) GsCOORDINATE2 *coord; MATRIX *m;
Arguments
coord Local coordinate system m Matrix
Explanation
This function calculates a local world perspective transformation matrix from coord in the matrix-type coordinate system GsCOORDINATE2 specified by an argument, and stores the result in the MATRIX-type structure m.
For high speed operation, the function retains the result of calculation at each node of the hierarchical coordinate system. When the next GsGetLw() function is called, calculation up to the node to which no changes have been made is omitted. This is controlled by a GsCOORDINATE2 member flag (libgs replaces 1 in flags already calculated by GsCOORDINATE2).
If the contents of a superior node is changed, the effect on a subordinate node is handled by libgs, so it is not necessary to clear the flags of all subordinate nodes of the changed superior node.
Return value None.
Runtime Library Release 3.0
Extended Graphics Library (libgs) Functions 547
GsGetLws
Calculates local world and local screen matrices. Syntax
void GsGetLws (coord2, lw, ls) GsCOORDINATE2 *coord2; MATRIX *lw, *ls;
Arguments
coord2 Pointer to local coordinates
lw Matrix that stores the local world coordinates
ls Matrix that stores the local screen coordinates
Explanation
GsGetLws() calculates local world and local screen coordinates. This function is faster than calling GsGetLw() followed by calling GsGetLs(). Light source source calculations are performed at the time of application execution. When you use GsSet LightMatrix(), it is valid because you calculate the LW matrix.
Return value None
Runtime Library Release 3.0
548 Extended Graphics Library (libgs) Functions
GsGetTimInfo
Finds TIM format header. Syntax
void GsGetTim Info (tim, im) unsigned long *tim;
GsIMAGE *im;
Arguments
tim Pointer to TIM data
im Pointer to an image Structure
Explanation
TIM format data specified by the argument tim is stored in im.
Return value None.
Runtime Library Release 3.0
GsGetVcount
Gets the value of the vertical retrace counter. Syntax
Extended Graphics Library (libgs) Functions 549
long GsGetVcount (void)
Arguments None.
Explanation
Obtains the value of the vertical retrace counter.
Return value
Value of the vertical retrace counter
Runtime Library Release 3.0
550 Extended Graphics Library (libgs) Functions
GsGetWorkBase
Gets address for storing current drawing commands. Syntax
PACKET *GsGetWorkBase (void)
Arguments None.
Explanation
This function obtains an address for generating the current drawing primitive packet. Obtains an address from an unused area.
Return value
Address to prepare the next drawing primitive packet.
Runtime Library Release 3.0
Extended Graphics Library (libgs) Functions 551
GsInit3D
Initializes the graphics system. Syntax
void GsInit3D(void)
Arguments None.
Explanation
This function initializes the libgs three-dimensional graphics system. You must initialize the three-dimensional system using GsInit3D first, before you use three-dimensional processing functions such as(GsSetRefView), GsInitCoordinate2(), and GsSortObject().
GsInit3D performs the following:
(1)Moves the screen origin point to the center of the screen (2)Sets the light source default to LIGHT_NORMAL
Return value None.
Runtime Library Release 3.0
552 Extended Graphics Library (libgs) Functions
GsInitCoordinate2
Initializes a local coordinate system (for use by GsCOORDINATE2). Syntax
void GsInitCoordinate2 (super, base) GsCOORDINATE2 * super; GsCOORDINATE2 * base;
Arguments
super Pointer to a superior coordinate system
base Pointer to a coordinate system (to be initialized)
Explanation
base->coord is indicated in the coordinate system by a single determinant, base->super is indicated with an argument, and both are initialized.
Return value None.
Runtime Library Release 3.0
GsInitFixBg16, GsInitFixBg32
High-speed BG work area initialization Syntax
void GsInitFixBg16 (bg, work); GsBG *bg;
unsigned long *work;
void GsInitFixBg32 (bg, work); GsBG *bg;
unsigned long *work;
Arguments
bg Pointer to GsBG
work Pointer to work area (primitive area)
Explanation
This function initializes the work area used by the functions GsSortFixBg16() and GsSortFixBg32. The size of the array differs with the screen mode as follows.
size (in longg units)=(((ScreenW/CellW+1 )*(ScreenH/CellH+1 +1 )*6+4)*2+2) Screen H: screen height in dots (240/480)
ScreenW: screen width in dots (256/320/384/512/640)
CellH: cell height (in pixels)
CellW: cell width (in pixels)
Executing GsInitFixBg16()/GsInitFixBg32() once is sufficient; you need not execute it for every frame.
Return value None.
554 Extended Graphics Library (libgs) Functions
GsInitGraph
Initializes the graphics system. Syntax
void GsInitGraph (x_res, y_res, int1, dither, vram)
int x_res; int y_res; int int1;
int dither; int vram;
Arguments
x_res Horizontal resolution (256/320/384/512/640)
y_res Vertical resolution (240/480)
intl Interlace display flag (bit 0)
0: Non-interlace 2: Interlace
Double buffer offset mode (bit 2)
0: GTE offset 2: GPU offset
dither Dither ON/OFF during drawing
0: OFF 1: ON vram VRAM mode
0: 16-bit 1: 24-bit
Explanation
This function resets "gpu", and initializes the libgs graphics system.
libgpu settings recognize the global variables GsDISPENV and GsDRAWENV, so the programmer can reference libgpu settings and changes.
x_res specificies horizontal resolution (256/320/384/512/640), y_res vertical resolution, and bit 0 of int1 sets interlace/non-interlace display. A vertical 480-line interlace is only effective when used in conjunction with a VGA monitor. Note that even when interlace is 240 lines, the top and bottom eight lines cannot usually be seen on domestic televisions.
The default offset mode of bit2 of int1 is determined by whether the double-buffer offset is a GTE or GPU offset. Since the double buffer offset values in the packet realized by the GPU are not added, this is the easier to handle alternative.
In 24bit mode only memory image display is possible, and no polygons can be drawn
Graphics system initialization includes GsIDMATRIX and GsIDMATRIX2 initialization, so Gs library functions do not perform normally after GsInitGraph() is called.
Return value None.
GsInitObjTable2
Initializes the object table. Syntax
void GsInitObjTable2 (obj_tbl, obj_area, obj_coord, obj_cparam, nobj) GsOBJTABLE2 *obj_tbl;
GsDOBJ2 *obj_area;
GsCOORDINATE2 *obj_coord;
GsCOORD2PARAM *obj_cparam;
long nobj;
Arguments
obj_tbl obj_area obj_coord obj_cparam nobj
Explanation
pointer to an object table
pointer to a GsDOBJ2 array
pointer to a GsCOORDINATE2 array pointer to a GsCOORD2PARAM array maximum object number (size of array)
Carries out initialization of the object table displayed by obj_tbl and also carries out initialization of three-dimensional objects within the array of GsDOBJ2, which is indicated by obj_area. The following parameters are set for initialized objects.
ID number GsOBJ_UNDEF ( = 0xFFFFFFFF)
parent object WORLD ( = 0)
TMD address 0
coordinate system a factor of same order in the array which is indicated by obj_coord
Because each of the objects managed by ID has an object system, it prepares the arrays of GsCOORDINATE2 and GsCOORD2PARAM which are the same size as obj_tbl, and the initialization is carried out in such a way that each same order factor responds.
Return value
None.
556 Extended Graphics Library (libgs) Functions
GsInitVcount
Initializes vertical retrace counter. Syntax
void GsInitVcount(void)
Arguments None.
Explanation
This function initializes the vertical retrace counter, and starts it.
Return value None.
Runtime Library Release 3.0
Extended Graphics Library (libgs) Functions 557
GsLinkObject3
Links an object with PMD data (For GsSortObject3). Syntax
void GsLinkObject3 (pmd, obj_base) unsigned long *pmd;
GsDOBJ3 *obj_base;
Arguments
pmd Starting address of the PMD data to be linked
obj_base Array of the object structure to be linked
Explanation
Links GsDOBJ3 object structure to all objects contained in the PMD data, so that the PMD format three-dimensional object modelled can be handled by GsDOBJ3.
Return value None
Remarks
Unlike GsLinkObject4(), it is not possible to select and link an object included in the PMD data. All objects contained in pmd will be linked to the object handler array beginning with obj_base.
Runtime Library Release 3.0
GsLinkObject4
Links an object to TMD data (For GsSortObject4). Syntax
void GsLinkObject4 (tmd, obj_base, n) unsigned long *tmd;
GsDOBJ2 *obj_base;
unsigned long n;
Arguments
tmd Starting address of the TMD data to be linked
obj_base Array of the object structure to be linked
n Index of the object to be linked
Explanation
Links GsDOBJ2 object structure to the n-th object of the TMD data so that the TMD format three-dimensional object modelled can be handled by GsDOBJ2.
Return value None
Remarks
An object linked using GsLinkObject4() uses GsSortObject4() to created a packet.
Extended Graphics Library (libgs) Functions 559
GsLinkObject5
Links an object to TMD data (For GsSortObject5). Syntax
void GsLinkObject5 (tmd, obj_base, n) unsigned long *tmd; [
GsDOBJ5 *obj_base;
unsigned long n;
Arguments
tmd Starting address of the TMD data to be linked
obj_base Array of the object structure to be linked
n Index of the object to be linked
Explanation
Links GsDOBJ5 object structure to the n-th object of the TMD data so that the TMD format three-dimensional object modelled can be handled by GsDOBJ5.
Return value None
Runtime Library Release 3.0
GsMapModelingData
Maps TMD data to real addresses. Syntax
void GsMapModelingData (p) unsigned long *p;
Arguments
p Starting address of TMD data
Explanation TMD data includes a portion to be referenced by a pointer.
During preparation of TMD data, the offset addresses from the start of the TMD data are stored because the memory area into which they will be loaded is not known. The GsMapModelingData() function converts offset addresses into real addresses. To use a TMD file, it is essential to perform conversion into real addresses.
Return value
None. Remarks
A flag is set in the TMD data whose offset addresses have been converted into real addresses. So, no side effect occurs even if GsMapModelingData() is called again.
Extended Graphics Library (libgs) Functions 561
GsMulCoord2
MATRIX multiplication. Syntax
void GsMulCoord2 (m1, m2) MATRIX *m1, *m2
Arguments m1, m2 Matrix Explanation
This function multiplies MATRIX m2 by the translation matrix. The results are stored in m2. m2 = m1 x m2
Return value None.
Runtime Library Release 3.0
562 Extended Graphics Library (libgs) Functions
GsMulCoord3
MATRIX multiplication. Syntax
void GsMulCoord3 (m1, m2) MATRIX *m1, *m2
Arguments m1, m2 Matrix Explanation
This function multiplies MATRIX m1 by the translation matrix. The results are stored in m2. m2 = m1 x m2
Return value None.
Runtime Library Release 3.0
Extended Graphics Library (libgs) Functions 563
GsPresetObject
Creates a preset packet for a GsDOBJ5-type object. Syntax
unsigned long *GsPresetObject (objp, addr) GsDOBJ5 *objp;
unsigned long *addr;
Arguments
objp Pointer to the object to be preset
addr Starting address of the area in which the preset packet is to be prepared.
Explanation
Presetting refers to the advance preparation of polygons of all objects as packets. The areas that need not be rewritten (e.g., U and V of texture) for each frame will not be rewritten, thus ensuring high speed.
The return value of GsPresetObject points to the address next to the last preset address, so when presetting the next object, preserve the return value and pass it as an argument of the next GsPresetObject(). The return value will indicate how large an area must be allocated for the preset area.
A GsDOBJ5 type object pointer is exclusively used for presetting.
Return value
Pointer that indicates the next to the last preset address
Runtime Library Release 3.0
564 Extended Graphics Library (libgs) Functions
GsRemoveObj2
Deletes an object. Syntax
GsDOBJ2 *GsRemoveObj2 (table, id) GsOBJTABLE2 *table;
unsigned long id;
Arguments
table Pointer to the object table
id ID number of the object to delete
Explanation
GsRemoveObj2() searches for an object with the ID number specified by the object table, and returns it. The value of the vacant area ID is set in GsOBJ_UNDEF without filling the vacant area that has occurred.
Return value
Returns 0 for a successful deletion, but NULL in the case of failure.
Runtime Library Release 3.0
Extended Graphics Library (libgs) Functions 565
GsSearchObj ByID2
Object search. Syntax
GsDOBJ2 *GsSearchObjByID2 (table, id); GsOBJTABLE2 *table;
unsigned long id;
Arguments
table Pointer to the object table
id ID number of the object to be found
Explanation
Finds the object with the ID number specified by id from the object table displayed in table, and returns its address.
Return value
Returns a pointer to the relevant object. Returns NULL if it is not found.
Runtime Library Release 3.0
566 Extended Graphics Library (libgs) Functions
GsSearchTmdByID
Searches for modelling data search in TMD data. Syntax
unsigned long *GsSearchTmdByID (tmd, id_list, id); unsigned long *tmd;
int *id_list;
int id;
Arguments
tmd Pointer to TMD data
id_list Pointer to the modelling data ID list
id ID number of the modelling data
Explanation
It searches from the modelling data list corresponding to TMD data for TMD data and modelling data with the ID number specified.
Return value
This function returns a pointer to relevant modelling data. This value may be entered instead of the value of the GsDOBJ2 structure member tmd. NULL is returned if it cannot be found.
Runtime Library Release 3.0
Extended Graphics Library (libgs) Functions 567
GsSetAmbient
Sets ambient color. Syntax
void GsSetAmbient (r, g, b) unsigned short r, g, b;
Arguments
r, g, b Ambient color RGB values (0-65535) Explanation
This function sets the ambient light level. This should be done according to the ratio of the portion exposed to light and kthat not exposed to light. 1/1 and 1/8 are set as 4096 and 4096/8 respectively.
If values larger than 4096 are entered, the color is strengthened.
Return value None.
Runtime Library Release 3.0
568 Extended Graphics Library (libgs) Functions
GsSetClip
Sets a drawing clipping area. Syntax
void GsSetClip (clip) RECT *clip;
Arguments
clip Beginning address of a RECT structure for setting a clipping area Explanation
Sets clipping for drawing. This function is different from GsSetDrawBuffClip() in that its argument can be used to specify a clip area. Note that this clipping value is a relative one within the double buffer, and thus the clip position will not change even if the double buffer is swapped.
Return value
None Remarks
Clipping is done by libgpu.
Runtime Library Release 3.0
Extended Graphics Library (libgs) Functions 569
GsSetClip2
Sets a drawing clipping area. Syntax
DRAWENV *GsSetClip2(clip) RECT *clip;
Arguments
clip Beginning address of a RECT structure for setting a clipping area Explanation
Gets a parameter to set clipping for drawing. This function does not set DRAWENV; it is different from GsSetClip() in that DRAWENV must be specified to return.
This function does not copy the DRAWENV, DISPENV of libgpu cueing. When you want to modify the cueing environment, use PutDrawEnv() after copying the return value of GsSetClip2.
Note that this clipping value is a relative one within the double buffer, and thus the clip position will not change when the double buffer is swapped.
Return value Returns a pointer to DRAWENV, which must be set
Remarks Clipping is done by libgpu.
Runtime Library Release 3.0
570 Extended Graphics Library (libgs) Functions
GsSetClip2D
Sets two-dimensional clipping. Syntax
GsSetClip2D (rectp) RECT *rectp;
Arguments
rectp Specifies the area to be clipped. Explanation
This function sets the area given by RECT as the area to be clipped.
This setting is affected by the double buffer. This means that the function leads to the automatic clipping of the same area even though the double buffer has been swapped.
GsSetDrawBuffClip must be invoked in order to validate this setting immediately afterwards. If GsSetDrawBuffClip is not specifically invoked, the setting is valid from the next frame.
Return value None.
Runtime Library Release 3.0
Extended Graphics Library (libgs) Functions 571
GsSetDrawBuffClip
Sets drawing clipping area.
Syntax
void GsSetDrawBuffClip (void)
Arguments
None.
Explanation
This function sets clipping for drawing. The clipping value set by GsClip2D() is set in ligbs.
This clipping value is a relative one within the double buffers. The clipping position does not change when double buffers are swapped.
Return value
None. Remarks
This function does not execute correctly when GPU drawing is in progress, so it is necessary to call this function after terminating drawing using ResetGraph (1).
Clipping is done by libgpu.
572 Extended Graphics Library (libgs) Functions
GsSetDrawB uffOffset
Sets the drawing offset.
Syntax
void GsSetDrawBuffOffset (void)
Arguments None.
Explanation
GsSetDrawBuffOffset sets the drawing offset. The offset value set in the global variable "POSITION" is updated.
This offset is relative within the double buffer. The offset value is preserved even if double buffers are swapped.
GsSetDrawBuffOffset sets the libgte or libgpu offset.
Note: Using the GsOFSGPU or GsOFSGTE macro for the third argument of GsInitGraph() determines whether the libgte or libgpu offset should be set.
Return value
None. Remarks
This function does not execute correctly when GPU drawing is in progress, so it is necessary to call this function after terminating drawing using ResetGraph (1).
Extended Graphics Library (libgs) Functions 573
GsSetFlatLight
Sets parallel light source. Syntax
void GsSetFlatLight (id, lt) unsigned int id;
GsF_LIGHT *lt;
Arguments
id Light source number (0, 1, 2)
lt Light source data
Explanation
GsSetFlatLight sets a parallel light source. Up to three light sources (ID = 0, 1, 2) may be set. Light source data is given GsF_LIGHT structure.
Return value None.
Remarks
Note that even when the contents of the GsF_LIGHT structure are written over, the setting will be not reflected in libgs unless this function is invoked.
Runtime Library Release 3.0
574 Extended Graphics Library (libgs) Functions
GsSetFogParam
Sets the fog parameter. Syntax
void GsSetFogParam (fogparam) GsFOGPARAM *fogparam;
Arguments
fogparam Pointer to a fog parameter Structure Explanation
GsSetFogParam sets the fog parameter. Fog is valid only in lighting mode 1 and 3. (Light mode 3 is not supported.)
Return value None.
Runtime Library Release 3.0
Extended Graphics Library (libgs) Functions 575
GsSetLightMatrix
Sets a light matrix. Syntax
void GsSetLightMatrix (mp) MATRIX *mp;
Arguments
mp Matrix Explanation
This function multiplies the local screen light matrix mp by the matrices for the three light vectors, and sets the results in libgte.
When using libgte during application execution of light source calculations, GsSetLightMatrix() must be set in advance.
Depending on the type of modelling data, some GsSortObject.. .() will calculate the light source during execution. In this case, also, you must use GsSetLightMatrix() to set a light matrix in advance.
Matrices to be set as GsSetLightMatrix() arguments are usually local screen matrices.
Return value None.
Runtime Library Release 3.0
576 Extended Graphics Library (libgs) Functions
GsSetLightMode
Sets light source mode. Syntax
void GsSetLightMode (mode) int mode;
Arguments
mode Light source mode value (0-3)
0: Normal lighting
1: Normal lighting with fog ON
2: Material lighting (not currently supported)
3: Material lighting with fog ON (not currently supported)
Explanation
This function sets the default light source mode. The method of light source calculation can be also set using status bits for each object. The setting of the status bit overrides the default setting.
Return value None.
Runtime Library Release 3.0
Extended Graphics Library (libgs) Functions 577
GsSetLsMatrix
Sets a local screen matrix. Syntax
void GsSetLsMatrix (mp) MATRIX *mp;
Arguments
mp Local screen matrix to be set Explanation
This function sets a local screen matrix in libgte.
When you use GsSetLsMatrix for libgte perspective transformation processing, you must set a local screen matrix in libgte beforehand.
For GsSortObject. . .() to perform perspective transformations and use them in libgte, it is necessary to execute GsSetLsMatrix before calling the functions.
Return value
None.
Runtime Library Release 3.0
578 Extended Graphics Library (libgs) Functions
GsSetOffset(offx,offy)
Sets an offset. Syntax
void GsSetOffset (offx, offy) int offx;
int offy;
Arguments
offx drawing offset X
offy drawing offset Y
Explanation
Specifies a drawing offset. This function is different from GsSetDrawBuffOffset() in that it sets an offset provided as an argument while GsSetDrawBuffOffset() sets a value for the global variable, POSITION. The offset to be provided as an argument is a relative offset inside the double buffer. In other words, the double buffer base offset is added to the offset provided by the argument.
Using the GsOFSGPU or GsOFSGTE macro for the third argument of GsInitGraph() determines whether the libgte or libgpu offset should be set.
Return value
None Remarks
This function does not execute correctly when GPU drawing is in progress, so it is necessary to call this function after terminating drawing using ResetGraph (1).
Runtime Library Release 3.0
GsSetProjection
Sets the projection plane position. Syntax
void GsSetProjection (h) unsigned long h;
Arguments
h Distance (projection) between the viewpoint and projection plane Default: 1000
Explanation
This function adjusts the drawing angle.
A projection is the distance from the viewpoint to the projection plane.
The size of the projection plane is specified by (xres, yres) in the GsInitGraph() function. The size of the projection plane is constant with respect to the resolution, so the drawing angle is reduced as projection is increased, and the drawing angle is increased as projection is decreased,..
Depending on the resolution, the aspect ratio may not be 1 to 1. In this case, set the X coordinate scale to 1/2 and adjust the aspect ratio.
Resolution 640x480 640x240 320x240
Aspect ratio 1:1 2:1 1:1
Table: Resolution and aspect ratio
Return value None.
580 Extended Graphics Library (libgs) Functions
GsSetRefView2
Sets viewpoint position. Syntax
int GsSetRefView2 (pv) GsRVIEW2 *pv;
Arguments
pv Viewpoint position information Explanation
Calculates WSMATRIX using viewpoint information. pv is a pointer to a GsRVIEW2 structure.
Since WSMATRIX will not change unless the viewpoint is moved, it need not be called for each frame. However, if the viewpoint is moved, WSMATRIX must be called for each frame in order for changes to be updated.
Call GsSetRefView2() for each frame if the GsRVIEW2 member super is set to anything other than WORLD; even if the other parameters are not changed, if the parameters of the superior coordinate system are changed, the viewpoint will have moved.
Return value
Upon success, the function returns 0. Upon failure, it returns 1.
Runtime Library Release 3.0
GsSetTod Frame2
Manages TOD data of the frame section. Syntax
unsigned long *GsSetTodFrame2 (fn, dp, table, tmd_id, tmd, mode) int fn;
unsigned *dp;
GsOBJTABLE2 *table;
int *tmd_id;
unsigned *tmd;
int mode;
Arguments
fn Current frame number
dp Pointer to TOD data
table Pointer to object table
tmd_id Pointer to TMD ID list
tmd Pointer to TMD data
mode Gives the class of packet to be executed:
GsTOD_CREATE
executes entire packet
GsTOD_NOCREATE
does not carry out creation/deletion of object GsTOD_COORDONLY
executes coordinate change only
Explanation
Renews the object's parameters according to the content of the packet group of one frame within TOD data. The tmd_id and tmd value are not referenced when the mode value is made GsTOD_COORDONLY.
Return value
It returns the pointer to the TOD data after execution. This value always indicates the start of the TOD data of one frame section.
582 Extended Graphics Library (libgs) Functions
GsSetTod Packet2
Manages TOD data of one packet section. Syntax
unsigned long *GsSetTodPacket2 (dp, tbl, tmd_id, tmd, mode) unsigned *dp
GsOBJTABLE2 *tbl;
int *tmd_id;
unsigned *tmd;
int mode;
Arguments
dp Pointer to TOD data that is executing
tbl Object table
tmd_id Modelling data list
tmd Pointer to TMD data
mode Gives the class of the packet to be executed: GsTOD_CREATE
executes the entire packet
GsTOD_NOCREATE
does not carry out object creation/deletion GsTOD_COORDONLY
executes coordinate change only
Explanation
Manages the data of 1 packet section from TOD data.
Return value
It returns a pointer to TOD data after execution.
Extended Graphics Library (libgs) Functions 583
GsSetWorkBase
Sets address for storing drawing commands. Syntax
void GsSetWorkBase (base_addr) PACKET * base_addr;
Arguments
base_addr Specifies an address storing drawing commands Explanation
This function sets the memory address for storing drawing primitives generated by functions like GsSortObject.. .(), GsSortSprite(), and GsSortBg().
Primitives must be stored at the starting address of a packet area reserved by the user at the beginning of processing for each frame.
Return value None.
Runtime Library Release 3.0
584 Extended Graphics Library (libgs) Functions
GsSortBg, GsSortFastBg
Registers BG in the OT. Syntax
void GsSortBg (bg, otp, pri) GsBG *bg;
GsOT *otp;
unsigned short pri;
void GsSortFastBg (bg, otp, pri) GsBG *bg;
GsOT *otp;
unsigned short pri;
Arguments
bg Pointer to BG
otp Pointer to OT
pri Position in OT
Explanation
This function assigns BG indicated by bg to the ordering table indicated by otp. pri refers to the priority of the Sprite in the ordering table. The highest priority is zero, with the lowest priority depending on the size of the ordering table. Values beyond the ordering table size are clipped to the available maximum value.
Turning off extension and rotation functions in the bg attributes gives higher-speed processing.
In GsSortFastBg(), not using enlargement, rotation, and reduction functions results in higher-speed processing. The Sprite structure members values mx, my, scalex, scaley, and rotate are ignored.
Return value None.
Runtime Library Release 3.0
Extended Graphics Library (libgs) Functions 585
GsSortFixBg16, GsSortFixBg32
Registers high-speed BG in the OT Syntax
void GsSortFixBg16 (bg, work, otp, pri); GsBG *bg;
unsigned long *work;
GsOT *otp;
unsigned short pri;
void GsSortFixBg32 (bg, work, otp, pri); GsBG *bg;
unsigned long *work;
GsOT *otp;
unsigned short pri;
Arguments
bg Pointer to GsBG
work Pointer to work area (primitive area)
otp Pointer to OT
pri Position in OT
Explanation
This function performs high-speed BG registration processing. It is less CPU-intensive than GsSortFastBg(), with the following restrictions.
BG rotation/enlargement/reduction is not possible
Fixed cell size: 16 for GsSortFixBg16, 32 for GsSortFixBg32 Texture patter color mode is only 4-bit/8-bit
Map size is optional
Scroll is possible (in 1-pixel units)
Only full-screen
This function uses the work area to store drawing primitives. The work area uses an unsigned long array; this must be initialized beforehand by GsInitFixBg16() or GsInitFixBg32(). This function does not use the packet area (an area set by GsSetWorkBase()).
Return value None.
Runtime Library Release 3.0
586 Extended Graphics Library (libgs) Functions
GsSortBoxFill
Registers rectangle in the OT. Syntax
void GsSortBoxFill (bp, ot, pri) GsBOXF *bp;
GsOT *ot;
unsigned short pri;
Arguments
bp Pointer to GsBOXF
ot Pointer to OT
pri Position in OT
Explanation
This function assigns a rectangle indicated by bp to the ordering table indicated by ot.
Return value None.
Runtime Library Release 3.0
GsSortClear
Registers a screen clear command in the OT. Syntax
void GsSortObject (r, g, b, otp) unsigned char r, g, b;
GsOT *otp;
Arguments
r, g, b Background color RGB values
otp Pointer to OT
Explanation
Sets a screen clear command at the start of the OT indicated by otp. Return value
None Remarks
This function only registers a screen clear command in the OT; actual clearing will not be executed until the GsDrawOt() function is used to start drawing.
This function is called after GsSwapDispBuff().
588 Extended Graphics Library (libgs) Functions
GsSortLine, GsSortGLine
Registers straight line in the OT. Syntax
void GsSortLine (lp, ot, pri) GsLINE *lp;
GsOT *ot;
unsigned short pri;
Arguments
lp Pointer to GsLINE/GsGLINE
ot Pointer to OT
pri Position in OT
Explanation
This function assigns the straight line indicated by lp to the ordering table indicated by ot.
The GsSortLine() function registers single-color straight lines in OT, and the GsSortGLine() function graded straight lines in OT.
Return value None.
Runtime Library Release 3.0
GsSortObject3
Assigns an object to the ordering table (for use with GsDOBJ3). Syntax
void GsSortObject3 (objp, otp, shift) GsDOBJ3 *objp;
GsOT *otp;
long shift;
Arguments
objp Pointer to an object
otp Pointer to OT
shift Specifies how many bits the Z value must be shifted to the right when assigning an object to the OT.
Explanation
Performs perspective transformation and light source calculation for a three-dimensional object handled by GsDOBJ3, and creates a drawing command within the PMD format packet memory. Performs Z-sort of the drawing commands generated immediately afterwards and assigns them to the OT indicated by otp.
The accuracy of Z may be adjusted with the value of shift. The maximum size of the ordering table (resolution) is 14 bits, but if this value is set to 12 bits, for example, the shift value must be set at 2 (=14 - 12), so that it will not be larger than the ordering table area.
Return value None
590 Extended Graphics Library (libgs) Functions
GsSortObject4
Assigns an object to the ordering table (for use with GsDOBJ2). Syntax
void GsSortObject4 (objp, otp, shift, scratch) GsDOBJ2 *objp;
GsOT *otp;
long shift;
unsigned long *scratch;
Arguments
objp Pointer to an object
otp Pointer to OT
shift Specifies how many bits the Z value must be shifted to the right when assigning an object to the OT.
scratch Specifies the address of the scratch pad.
Explanation
Performs perspective transformation and light source calculation for a three-dimensional object to be handled by GsDOBJ2, and creates a drawing command within the packet area specified by GsSetWorkBase(). Performs Z-sort of the drawing commands generated immediately afterwards and assigns them to the OT indicated by otp.
The accuracy of Z may be adjusted with the value of shift. The maximum size of the ordering table (resolution) is 14 bits. If this value is set to 12 bits, for example, the shift value must be set at 2 (=14 - 12), so that it will not be larger than the ordering table area.
scratch is the specified scratchpad address used as work when automatic division is being performed. The scratchpad runs for 256 words from 0x1f800000 in cache memory.
To use the GsOBJ2 member attribute to enable division, perform an OR operation on the macros GsDIV1 through GsDIV5 (defined in libgs.h). For GsDIV1, a single polygon will be divided into four segments of 2 x 2. For GsDIV5, a single polygon will be divided into 1,024 segments of 32 x 32.
Return value None
GsSortObject5
Assigns an object to the ordering table (for use with GsDOBJ5). Syntax
void GsSortObject5 (objp, otp, shift, scratch) GsDOBJ2 *objp;
GsOT *otp;
long shift;
unsigned long *scratch;
Arguments
objp Pointer to an object
otp Pointer to OT
shift Specifies how many bits the Z value must be shifted to the right when assigning an object to the OT.
scratch Specifies the address of the scratch pad.
Explanation
Performs transparency transformation and light source calculation for a three-dimensional object to be handled by GsDOBJ5, and creates in the preset packet area drawing commands that do not divide, and in the packet area specified by GsSetWorkBase() those drawing commands that do divide. Performs Z-sort of the drawing commands generated immediately afterwards and assigns them to the OT indicated by otp.
The accuracy of Z may be adjusted using the shift value. The maximum size of the ordering table (resolution) is 14 bits. If this value is set to 12 bits, for example, the shift value must be set at 2 (=14 - 12), so that it will not be larger than the ordering table area.
scratch is used as work when automatic division is being performed. To use attribute to enable division, perform an OR operation on the macros GsDIV1 ~ GsDIV5 of libgs.h. For GsDIV1, a single polygon will be divided into four segments of 2 x 2. For GsDIV5, a single polygon will be divided into 1, 024 segments of 32 x 32.
scratch is the specified scratchpad address used as work when automatic division is being performed. The scratchpad runs for 256 words from 0x1f800000 in cache memory.
To use the GsOBJ2 member attribute to enable division, perform an OR operation on the macros GsDIV1 through GsDIV5 (defined in libgs.h). For GsDIV1, a single polygon will be divided into four segments of 2 x 2. For GsDIV5, a single polygon will be divided into 1,024 segments of 32 x 32.
Return value None
592 Extended Graphics Library (libgs) Functions
GsSortOt
Assigns an OT to another OT. Syntax
GsOT *GsSortOt (ot_src, ot_dest) GsOT *ot_src;
GsOT *ot_dest;
Arguments
ot_src Pointer to source OT ot_dest Pointer to destination OT
Explanation
This function assigns the OT given by ot_src to ot_dest. The representative value in the point field for each OT is used as the OTZ value. The integrated OT is inserted into ot_dest.
Return value
Pointer to the integrated OT
Runtime Library Release 3.0
Extended Graphics Library (libgs) Functions 593
GsSortPoly
Registers polygon drawing primitive in the OT. Syntax
void GsSortPoly (prim, ot, pri) void *prim;
GsOt *ot;
unsigned short pri;
Arguments
prim Pointer to drawing primitive
ot Pointer to OT
pri Location in OT
Explanation This function assigns the drawing primitive given by prim to the ordering table given by ot. Out of the primitives defined by libgpu, the drawing primitive refers only to POLY_....
libgs requires no double buffering, since the contents of the primitive structure are copied in the packet generation area. Drawing coordinate values match the drawing coordinate system handled by libgs.
Return value None.
Runtime Library Release 3.0
GsSortSprite, GsSortFastSprite, GsSortFlipSprite
Registers a Sprite in the OT. Syntax
void GsSortSprite (sp, otp, pri) GsSPRITE *sp;
GsOT *otp;
unsigned short pri;
void GsSortFastSprite (sp, otp, pri) GsSPRITE *sp;
GsOT *otp;
unsigned short pri;
void GsSortFlipSprite (sp, otp, pri) GsSPRITE *sp;
GsOT *otp;
unsigned short pri;
Arguments
sp Pointer to a Sprite
otp Pointer to OT
pri Position in OT
Explanation
This function assigns the Sprite given by sp to the ordering table provided by otp.
All the parameters including Sprite indication locations are given by the sp members.
pri refers to the priority of the Sprite in the ordering table. The highest priority value is zero, with the lowest value depending on the size of the ordering table. Values beyond the size of the ordering table are clipped to the maximum ordering table value.
The GsSortFastSprite function provides high-speed processing, though enlargement, rotation, and reduction cannot be used. The Sprite structure members nx, my, scalex, scaley, and rotate are ignored.
GsSortFlipSprite() does not use the enlargement / rotation / reduction functions, and only supports flipping.
Return value None.
Extended Graphics Library (libgs) Functions 595
GsSwapDispBuffer
Swaps double buffers.
Syntax
void GsSwapDispBuffer (void)
Arguments None.
Explanation
This function exchanges the display buffer with the drawing buffer according to double buffer data set by GsSetDefDispBuffer(). Normally, swapping is done immediately after beginning vertical blanking.
This function performs the following:
(1) sets display starting address
(2) cancels blanking
(3) sets double buffer index
(4) switches two-dimensional clipping
(5) sets libgte or libgpu offset
(6) sets libgs offset
Note: The double buffer is implemented by offset. Using the GsOFSGPU or GsOFSGTE macro for the third argument of GsInitGraph() determines whether the libgte or libgpu offset should be set.
Return value
None. Remarks
This function does not execute correctly when GPU drawing is in progress, so it is necessary to call this function after terminating drawing using ResetGraph (1).
Chapter 8
Sound Library (libspu)
This chapter describes structures defined in the basic sound library and the functions available in this library. The sound library directly controls the PlayStation sound playback processing processor. Sound buffer transmission of sounds other than music is offered independently.
Chapter 8: Sound Library (libspu) Table of Contents
Structures
SpuCommonAttr601
Spu DecodeData
602
SpuExtAttr
603
SpuReverbAttr
604
SpuVoiceAttr
605
SpuVolume
607
Functions
SpuClearReverbWorkArea
608
SpuFree
609
SpuGetAllKeysStatus
610
SpuGetCommonAttr
611
SpuGetIRQ
612
SpuGetIRQAddr
613
SpuGetKeyStatus
614
SpuGetMute
615
SpuGetNoiseClock
616
SpuGetNoiseVoice
617
SpuGetPitchLFOVoice
618
SpuGetReverb
619
SpuGetReverbModeParam
620
SpuGetReverbVoice
621
SpuGetTransferMode
622
SpuGetTransferStartAddr
623
SpuGetVoiceAttr
624
SpuInit
625
SpuInitMalloc
626
SpuIsReverbWorkAreaReserved
627
SpuIsTransferCompleted
628
SpuMalloc
629
SpuMallocWithStartAddr
630
SpuQuit
631
Spu Read
632
Spu ReadDecodeData
633
Spu ReserveReverbWorkArea
635
SpuSetCommonAttr
636
SpuSetIRQ
638
SpuSetIRQAddr
639
SpuSetIRQCallback
640
SpuSetKey
641
SpuSetKeyOnWithAttr
642
SpuSetMute
643
SpuSetNoiseClock
644
SpuSetNoiseVoice
645
SpuSetPitchLFOVoice
646
SpuSetReverb
647
SpuSetReverbDepth
648
SpuSetReverbModeParam
649
SpuSetReverbVoice
652
SpuSetTransferMode
653
SpuSetTransferStartAddr
654
SpuSetVoiceAttr
655
SpuStart
660
Spu Write
661
SpuWrite0
662
SpuWritePartly
663
Basic Sound Library (libspu) Structures 601
SpuCommonAttr
Common attributes. Structure
typedef struct {
unsigned long mask; SpuVolume mvol; SpuVolume mvolmode; SpuVolume mvolx; SpuExtAttr cd;
SpuExtAttr ext;
} SpuCommonAttr;
Members
mask
mvol mvolmodemaster mvolx
cd
ext
Set mask
Master volume
Master volume mode
Current master volume
Cd input attributes
External digital input attributes
Explanation
Used when setting/checking common attributes. The members needed for setting are set as bit values in mask.
See also: structures SpuVolume (p. 607), SpuExtAttr (p. 603), SpuSetCommonAttr (p. 636), SpuGetCommonAttr (p. 611).
SpuDecodeData
Decode data. Structure
#define SPU_DECODEDATA_SIZE 0x200
typedef struct {
short cd_left[SPU_DECODEDATA_SIZE]; short cd_right[S PU_D ECOD EDATA_S IZE]; short voice 1 [SPU_DECODEDATA_SIZE]; short voice3[SPU_DECODEDATA_SIZE]; } SpuDecodeData;
Members
cd_left cd_ri ght voice 1 voice3
Explanation
CD L channel data decoded by SPU CD R channel data decoded by SPU Voice 1 data decoded by SPU
Voice 3 data decoded by SPU
Used when getting CD-ROM, voice 1 and voice 3 data decoded by the SPU.
The data which can actually be used is each member's first half 0x100 data or second half 0x100 data. This is determined by the return value of SpuReadDecodeData().
See also: SpuReadDecodeData (p. 633).
Basic Sound Library (libspu) Structures 603
SpuExtAttr
External input attributes. Structure
typedef struct {
SpuVolume volume; long reverb;
long mix;
} SpuExtAttr;
Members
volume Volume
reverb Reverb on/off
mix Mixing on/off
Explanation
Used when setting/checking CD and external digital input attributes.
See also: structure SpuCommonAttr (p. 601).
Runtime Library Release 3.0
SpuReverbAttr
Reverb attributes. Structure
typedef struct {
unsigned long mask; long mode;
SpuVolume depth; long delay;
long feedback;
} SpuReverbAttr;
Members
mask mode depth delay feedback
Explanation
Set mask (bit value)
Reverb mode
Reverb depth
Delay Time (ECHO, DELAY only) Feedback (ECHO only)
Used when setting/checking reverb attributes. The members required at setting are set in mask as bit values.
See also: structure SpuVolume (p. 607), SpuSetReverbModeParam ( p. 649), SpuGetReverbModeParam (p. 620), SpuSetReverbDepth (p. 648).
SpuVoiceAttr
Voice attributes. Structure
typedef struct { unsigned long voice;
unsigned long mask; SpuVolume volume; SpuVolume volmode; SpuVolume volumex; unsigned short pitch; unsigned short note; unsigned short sample_note;
short envx;
unsigned long addr; unsigned long loop_addr; long a_mode;
long s_mode;
long r_mode;
unsigned short ar; unsigned short dr; unsigned short sr; unsigned short rr; unsigned short sl; unsigned short adsr1; unsigned short adsr2; } SpuVoiceAttr;
Members
voice
mask
volume volmode volumex
pitch
note sample_note envx
addr loop_addrloop a_mode s_mode r_mode
ar dr sr rr sl adsr1
adsr2
Explanation
Set voice (value is bit string)
Set attribute bit (value is bit string) Volume
Volume mode
Current volume
Interval (set pitch)
Interval (set note)
Interval (set note) at the time of waveform sampling Current envelope volume value
Waveform data start address
Starting address of loop
Attack rate mode
Sustain rate mode
Release rate mode
Attack rate
Decay rate
Sustain rate
Release rate
Sustain level
Same value as structure VagAtr adsr1 Same value as structure VagAtr adsr2
Used when setting/checking the attributes of each voice. The voice number is provided/obtained from the voice bit value, and the members needed for setting are set
as bit values in mask. Runtime Library Release 3.0
See also: structure SpuVolume (p. 607) SpuSetVoiceAttr (p. 655), SpuGetVoiceAttr (p. 624), SpuSetKeyOnWithAttr (p. 642).
SpuVolume
Volume. Structure
typedef struct { short left;
short right;
} SpuVolume;
Members
left L channel value
right R channel value
Explanation
Used in attributes that require L channel/R channel values when setting/getting each voice.
See also: structures SpuVoiceAttr (p. 605), SpuReverbAttr (p. 604), SpuExtAttr (p. 603), SpuCommonAttr (p. 601).
SpuClearReverbWorkArea
Clears reverb work area. Syntax
long SpuClearReverbWorkArea(rev_mode) ong rev_mode;
Arguments
rev_mode Reverb mode Explanation
Clears the area occupied by the reverb work area corresponding to the reverb mode specified by rev_mode.
Regardless of whether or not it is reserved at this time, the function checks to see if the area is being used or not.
This operation uses synchronous DMA transfer, so depending on the reverb mode, some time may be needed.
Return value
If successful, 0 is returned.
SPU_ERROR is returned if the reverb work area corresponding to the reverb mode set by rev_mode is in use, or if the specified reverb mode value is wrong.
See also: SpuSetReverbModeParam (p.649), Spu ReserveReverbWorkArea (p. 635), SpuSetReverb (p. 647), SpuMalloc (p. 629), SpuMallocWithStartAddr (p. 630).
Basic Sound Library (libspu) Functions 609
SpuFree
Releases area allocated in the sound buffer. Syntax
void SpuFree(addr) unsigned long addr;
Arguments
addr Start address of allocated area (in bytes) Explanation
Releases area allocated in the sound buffer as indicated by the start address addr, and deletes that area's information from the management table.
Return value None.
See also: SpuInitMalloc (p. 626), SpuMalloc (p. 629), SpuMallocWithStartAddr (p. 630).
Runtime Library Release 3.0
SpuGetAllKeysStatus
Checks key on/key off for all voices. Syntax
void SpuGetAll KeysStatus(status) char *status;
Arguments
status Buffer that stores the result of checking a voice (requires 24 bytes = status[24])
Explanation
Checks key on/key off status of all voices, and actual envelope status.
Return value
None.
The current key on/key off and envelope status of each voice is returned by the argument status.
Value Status
SPU_ON key on status
not turned off by SpuSetKey envelope not 0
SPU_ON_ENV_OFFkey on status
not turned off by SpuSetKey envelope 0
SPU_OFF_ENV_ON key off status turned off by SpuSetKey envelope not 0
SPU_OFF key off status
turned off by SpuSetKey envelope 0
Remarks
An error may result if multiple envelopes are set, and if volume goes to 0 in the course of changing envelope status.
See also: SpuSetKey (p. 641), SpuGetKeyStatus (p. 614).
Basic Sound Library (libspu) Functions 611
SpuGetCommonAttr
Checks attributes common to all voices (infrequent change requests). Syntax
void SpuGetCommonAttr(attr) SpuCommonAttr *attr;
Arguments
attr Attributes common to all voices
Explanation
Returns attributes common to all voices in attr. See SpuSetCommonAttr() for details.
Return value None.
Modes and parameters for members other than attr.mask are stored.
See also: SpuSetCommonAttr (p. 611).
Runtime Library Release 3.0
SpuGetIRQ
Checks status of interrupt request on/off.
Syntax
long SpuGetIRQ(void)
Arguments None.
Explanation
Checks status of interrupt request on/off
Return value
Currently set value (SPU_ON/SPU_OFF).
See also: SpuSetIRQ (p. 638).
SpuGetIRQAddr
Checks interrupt request address. Syntax
Basic Sound Library (libspu) Functions 613
unsigned long SpuGetIRQAddr(void)
Arguments None.
Explanation
Returns interrupt request address value.
Return value
Currently set address value
See also: SpuSetIRQAddr (p. 639), SpuSetIRQ (p. 638).
Runtime Library Release 3.0
SpuGetKeyStatus
Checks key on/key off status for voices set. Syntax
long SpuGetKeyStatus(voice_bit) unsigned long voice_bit;
Arguments
voice_bit Checked voice
Explanation
Checks key on/key off status of specified voices, and actual envelope status.
Explicitly specify the voices targeted in voice_bit by ORing together SPU_0CHSPU_23CH.
1 function call gets the attributes of only 1 voice, so, in the case of multiple specifications, the smallest voice number specified is selected.
Return value
If successful, the current key on/key off status and envelope status of the specified voice are returned. (See the table below.) If the specified voice is incorrect, SpuGetKeyStatus() returns -1.
Value Status
SPU_ON key on status
not turned off by SpuSetKey envelope not 0
SPU_ON_ENV_OFFkey on status
not turned off by SpuSetKey envelope 0
SPU_OFF_ENV_ON key off status turned off by SpuSetKey envelope not 0
SPU_OFF key off status
turned off by SpuSetKey envelope 0
Remarks
An error may result if multiple envelopes are set, and if volume goes to 0 in the course of changing envelope status.
See also: SpuSetKey (p. 641), SpuGetAllKeysStatus (p. 610).
Basic Sound Library (libspu) Functions 615
SpuGetMute
Checks status of sound muting.
Syntax
long SpuGetMute(void)
Arguments None.
Explanation Checks sound current mute on/off status.
Return value
Currently set value (SPU_ON/SPU_OFF)
Value Description
SPU_ON mute on
SPU_OFF mute off
See also: SpuSetMute (p. 643).
SpuGetNoiseClock
Checks noise source clock.
Syntax
long SpuGetNoiseClock(void)
Arguments None.
Explanation
Returns the value of noise source clock.
Return value
Currently set noise source clock value.
See also: SpuSetNoiseClock (p. 644).
Basic Sound Library (libspu) Functions 617
SpuGetNoiseVoice
Checks noise source ON/OFF for each voice
Syntax
unsigned long SpuGetNoiseVoice(void)
Arguments None.
Explanation
Checks current status of noise source ON/OFF for each voice.
Return value
Returns the noise source ON/OFF value of the current voice. SPU_23CH.
Distinguishes the noise source ON/OFF value by ANDing the SPU_xxCH(xx=0~23).
OR together SPU_0CH-
return value and
Result of AND Description
0 Sets noise source off
Other than 0 Sets noise source on
See also: SpuSetNoiseClock (p. 644), SpuSetNoiseVoice (p. 617).
618 Basic Sound Library (libspu) Functions
SpuGetPitchLFOVoice
Checks pitch LFO ON/OFF for each voice.
Syntax
unsigned long SpuGetPitchLFOVoice(void)
Arguments None.
Explanation
Checks current status of pitch LFO ON/OFF for each voice.
Return value
Returns the pitch LFO ON/OFF value of the current voice. SPU_23CH.
Distinguishes the pitch LFO ON/OFF value by AN Ding the SPU_xxCH(xx=0~23).
OR together SPU_0CH-
return value and
Result of AND Description
0 Sets pitch LFO off
Other than 0 Sets pitch LFO on
See also: SpuSetPitchLFOVoice (p. 646).
SpuGetReverb
Checks reverb status.
Syntax
long SpuGetReverb(void)
Arguments None.
Explanation Checks current reverb ON/OFF status.
Return value
Set value (SPU_ON/SPU_OFF).
Value Description
SPU_ON Set reverb on 0
SPU_OFF Set reverb off
See also: SpuSetReverb (p. 647).
SpuGetReverbModeParam
Checks reverb mode and parameters. Syntax
void SpuGetReverbModeParam(attr) SpuReverbAttr *attr;
Arguments
attr Reverb attributes
Explanation
Gets currently set reverb mode and parameters.
For details see SpuSetReverbModeParam().
Return value
None.
Modes and parameters for members other than attr.mask are stored.
See also: SpuSetReverbModeParam (p. 649).
SpuGetReverbVoice
Checks reverb ON/OFF for each voice.
Syntax
unsigned long SpuGetReverbVoice(void)
Arguments None.
Explanation Checks current reverb ON/OFF status for each voice.
Return value
Returns the reverb ON/OFF value of the current voice. OR together SPU_0CHSPU_23CH.
Distinguishes the noise source ON/OFF value by ANDing the return value and SPU_xxCH(xx=0~23).
Result of AND Description
0 Sets reverb off
Other than 0 Sets reverb on
See also: SpuSetReverbVoice (p. 652).
SpuGetTransferMode
Checks sound buffer transfer mode. Syntax
long SpuGetTransferMode(void)
Arguments None.
Explanation
Returns currently set value of the transfer mode when transferring from main memory to the sound buffer.
Return value
Current value of transfer mode (SPU_TRANSFER_BY_DMA/ SPU_TRANSFER_BY_IO).
See also: SpuSetTransferMode (p. 653), SpuWrite (p. 661).
SpuGetTransferStartAddr
Checks sound buffer transfer destination/transfer source start address.
Syntax
unsigned long SpuGetTransferStartAddr(void)
Arguments None.
Explanation
Returns currently set value for start address when transferring from main memory to the sound buffer, and from the sound buffer to main memory.
Return value
Currently set sound buffer starting address value.
See also: SpuSetTransferStartAddr (p. 654), SpuWrite (p. 661), SpuRead (p. 632).
SpuGetVoiceAttr
Checks voice attributes. Syntax
void SpuGetVoiceAttr(attr) SpuVoiceAttr *attr;
Arguments
attr Voice attributes
Explanation
Checks voice attributes
When the single voice (SPU_0CH - SPU_23CH) to be checked by attr.voice is explicitly set and called, all the attribute members are stored except mask.
Return value
None.
All the attribute members of the argument attr except attr.mask are returned. See SpuSetVoiceAttr() for the details of these attributes.
See also: structure SpuVoiceAttr (p. 605), SpuSetVoiceAttr (p. 655), SpuSetKey (p. 641), SpuSetKeyOnWithAttr (p. 642).
SpuInit
SPU initialization. Syntax
void SpuInit(void)
Arguments None.
Explanation
Initializes SPU. Called only once within the program. After initialization, SPU may have the following states.
* Master volume is 0 for both L/R
* Reverb is off
* Reverb work area is not reserved
* Reverb depth is 0 for both L/R
* Reverb volume is 0 for both L/R
* Sound buffer transfer mode is DMA transfer
* For all voices:
Key off
Pitch LFO function not set Noise function not set
Reverb function not set
* CD input volume is 0 for both L/R
* External digital input volume is 0 for both L/R
* DMA transfer initialization set The status of the sound buffer is indeterminate after initialization.
Return value
None.
See also: SpuStart (p. 660), SpuQuit (p. 631).
SpuInitMalloc
Initializes the sound buffer memory management mechanism. Syntax
long SpuInitMalloc(num, top) long num;
char *top;
Arguments
num Maximum number of times memory is allocated
top Start address of area storing management table
Explanation
Performs initialization in order to divide the sound buffer into num number of areas and manage them. The individual num memory management blocks used by each request are allocated in the area provided by top. The size of the area must be
(SPU_MALLOC_RECSIZ * (num + 1)) bytes Return value
Returns the number of memory management blocks allocated. Example
When creating memory management blocks to be used by 10 SpuMalloc() calls, SpuInitMalloc() is called as follows.
char rec[SPU_MALLOC_RECSIZ * (10 + 1)];
SpuInitMalloc (10, /* 10 SpuMalloc calls can beused*/ rec); /*memory management block*/
See also: malloc (see Ch 14), SpuMalloc (p. 629), SpuMallocWithStartAddr (p. 630), SpuFree (p. 609).
SpuIsReverbWorkAreaReserved
Checks to see if reverb work area is reserved/Checks to see if reverb work area can be reserved.
Syntax
long Spu IsReverbWorkAreaReserved(on_off) long on_off;
Arguments
on_off Contents of the checking process Explanation
Checks to see if the reverb work area corresponding to the current reverb mode is reserved, or checks to see if it can be reserved.
on_off specifies which action is performed. These settings are explained below.
Value Description
SPU_DIAG Checks to see if reverb work area can be reserved
SPU_CHECK Checks reverb work area reserve status
a) SPU_DIAG
Using sound buffer memory management mechanism information, SPU_DIAG checks to see whether or not the reverb work area is an area allocated by
SpuMalloc()/SpuMallocWithStartAddr(). If it can be reserved, SPU_ON is returned. If it cannot be reserved, SPU_OFF is returned.
b) SPU_CHECK
Returns current reverb work area reserve status.
Return value
When on_off is SPU_DIAG, if the reverb work area can be reserved, SPU_ON is returned. If it cannot be reserved, SPU_OFF is returned.
When on_off is SPU_CHECK, if the reverb work area is reserved, SPU_ON is returned. If it is not reserved, SPU_OFF is returned.
See also: SpuReserveReverbWorkArea (p. 635), SpuSetReverbModeParam (p. 649), SpuSetReverb (p. 647), SpuMalloc (p. 629), SpuMallocWithStartAddr (p. 630).
SpuIsTransferCompleted
Checks completion of transfer to the sound buffer. Syntax
long SpuIsTransferCompleted(flag) long flag;
Arguments
flag Check flag
Explanation
Checks whether transfer is completed. Flag values may be specified as follows.
Value Description
SPU_TRANSFER_WAIT Wait until transfer ends
SPU_TRANSFER_PEEK Check whether transfer has ended return result
SPU_TRANSFER_GLANCE Same as SPU_TRANSFER_PEEK
Return value
Returns 1 if transfer completed, 0 if transfer not completed.
If flag = SPU_TRANSFER_WAIT, wait until transfer ends and always return 1. If transfer mode is "I/O transfer", 1 is returned immediately.
See also: SpuWrite (p. 661), SpuRead (p. 632).
SpuMalloc
Allocates an area in the sound buffer. Syntax
long SpuMalloc(size) long size;
Arguments
size Size of area allocated (in bytes)
Explanation
Allocate an area of size bytes in the sound buffer.
The return value is the address of the start of the allocated area. When this value is set by an argument of SpuSetTransferStartAddr(), and the transfer start address is set, SpuWrite() transfers waveform data.
The following states cause failure in allocation.
* The requested size cannot be continuously allocated.
* There is an area which satisfies the requested size, but that area is part or all of a
reverb work area allocated by SpuReserveReverbWorkArea(), and essentially cannot be allocated.
Return value
If allocation is successful, the starting address of the allocated area is returned. If unsuccessful, -1 is returned.
See also: SpuInitMalloc (p. 626), SpuMallocWithStartAddr (p. 630), SpuFree (p. 609), SpuSetTransferStartAddr (p. 654), SpuWrite (p. 661), Spu ReserveReverbWorkArea (p. 635), SpuSetReverb (p. 647), SpuSetReverbModeParam (p. 649).
SpuMallocWithStartAddr
Allocates an area from a specified start address in sound buffer. Syntax
long SpuMallocWithStartAddr(addr, size) unsigned long addr;
long size;
Arguments
addr Allocated area starting address (in bytes)
size Size of allocated area (in bytes)
Explanation
Allocates an area in the sound buffer of size bytes starting from the start address addr.
The starting address value must be the same as that of SpuSetTransferStartAddr(). It must be
* in bytes
* divisible by 8
* greater than 0x1 000 and 512 KB or less
If that address is in an area already allocated, an area of size bytes, starting from the nearest empty area after the addr area, is allocated.
The following states cause failure in allocation.
* The requested size cannot be continuously allocated.
* There is an area which satisfies the requested size, but that area is part or all of a
reverb work area allocated by SpuReserveReverbWorkArea(), and essentially cannot be allocated.
Return value
If allocation is successful, the starting address of the allocated area is returned. If unsuccessful, -1 is returned.
See also: SpuInitMalloc (p. 626), SpuMalloc (p. 629), SpuFree (p. 609), SpuSetTransferStartAddr (p. 654), SpuWrite (p. 661), Spu ReserveReverbWorkArea (p. 635), SpuSetReverb (p. 647), SpuSetReverbModeParam (p. 649).
SpuQuit
Terminates SPU processing.
Syntax
void SpuQuit(void)
Arguments None.
Explanation
Terminates SPU processing. In an actual game, all devices, including SPU, are usually reset with a hardware reset, so it is not necessary to call SpuQuit().
SpuQuit() must be called before Exec is performed.
The following processing must be performed for SpuQuit() is called.
• DMA transfer setting OFF (after this setting is made, DMA transfer to the sound
buffer cannot be used)
Return value
None.
See also: SpuInit (p. 625), SpuStart (p. 660).
Spu Read
Transfers data from the sound buffer to main memory. Syntax
unsigned long SpuRead(addr, size) unsigned char *addr;
unsigned long size;
Arguments
addr Transfer data start address in main memory
size Transfered data size (in bytes)
Explanation
Transfers size bytes of data from the sound buffer to main memory addr.
The transfer destination main memory address addr must fulfill the following conditions.
* It is an address of an allocated variable that is a global variable
* It is an address of an allocated variable that is in the heap and is allocated by a function such as malloc.
That is, it does not address a stack area (a variable (= auto variable) declared in a function.
Return value
Transferred data size.
If the specified data size is larger than 512 KB, the actual transferred size is returned.
See also: SpuWrite (p. 661), SpuSetTransferStartAddr (p. 654), SpuGetTransferStartAddr (p. 623).
SpuReadDecodeDataTransfers sound data decoded by the SPU from the sound buffer to main memory.
Syntax
long Spu Read DecodeData(d_data, flag) SpuDecodeData *d_data;
unsigned long flag;
Arguments
d_data Start address of SpuDecodeData structure in main memory
flag Flag (valued determined by type of data)
Explanation
Transfers waveform data decoded by the SPU from the sound buffer to main memory. Flag may be specified as the following, depending on the type of data transferred.
Value Description
SPU_CDONLY set transfer of CD input only
SPU_ALL set transfer of all data
The SPU writes sound data after CD input volume processing and sound data after Voice 1 and Voice 3 envelope processing to the sound buffer's starting 0x1 000 byte (0x800 short int) area 16 bits (1 short int) at a time at each clock (44.1 kHz). Each piece of sound data has 0x400 byte (0x200 short int) buffers.
Data is signed 16-bit data, so access is in units of 16 bits (1 short int). Data is arranged as shown below.
Table: Arrangement of data
Map (short int) Data Contents
0x000 - 0x1ff CD Left channel
0x200 - 0x3ff CD Right channel
0x400 - 0x5ff Voice 1
0x600 - 0x7ff Voice 3
These are divided into the first half (0x100 short int) and the second half (0x100 short int); which buffer area is currently being written to is decided by the return value.
What is reported in this way is the area currently being written to, so data that can actually be used is in the area not being reported.
Return value Meaning
SPU_DECODE_FIRSTHALF writes the first half of data
SPU_DECODE_SECONDHALF writes the second half of data
The main memory address addr storing the transfer data must fulfill the following conditions.
* It is an address of an allocated variable that is a global variable
* It is an address of an allocated variable that is in the heap and is allocated by a function such as malloc.
That is, it does not address a stack area (a variable (= auto variable) declared in a function.
Return value
Returns the buffer area currently being written to, as shown below.
What is reported in this way is the area currently being written to, so data that can actually be used is in the area not being reported.
Return value Meaning
SPU_DECODE_FIRSTHALF writes the first half of data
SPU_DECODE_SECONDHALF writes the second half of data
See also: structure SpuDecodeData (p. 602), SpuWrite (p. 661), SpuSetTransferStartAddr (p. 654), SpuGetTransferStartAddr (p. 623).
SpuReserveReverbWorkArea
Reserve/release reverb work area. Syntax
long Spu ReserveReverbWorkArea(on_off) long on_off;
Arguments
on_off Reserve/release flag Explanation
Reserves the current reverb work area corresponding to the current reverb mode in such a way that it is not allocated by SpuMalloc()/SpuMallocWithStartAddr(), or releases it so that it is allocated.
on_off specifies which action is performed. These settings are explained below.
Value Description
SPU_ON Reserve reverb work area
SPU_OFF Reserve reverb work area
a) SPU_ON
Reserves the reverb work area so that it is not an area allocated by SpuMalloc()/SpuMallocWithStartAddr(). Reserves the area without regard to reverb ON/OFF.
If the reverb work area has already been allocated by
SpuMalloc()/SpuMallocWithStartAddr() as another area, it is not allocated and SPU_OFF is returned.
b) SPU_OFF
Releases the reverb work area so that it can be allocated by
SpuMalloc()/SpuMallocWithStartAddr() as another area. Releases it regardless of reverb ON/OFF; reverb must have been turned off beforehand.
Return value
When on_off is set to SPU_ON, if the reverb work area has already been allocated by SpuMalloc()/SpuMallocWithStartAddr() as another area, it is not reserved and SPU_OFF is returned. If it is reserved, SPU_ON is returned.
When on_off is set to SPU_OFF, SPU_OFF is always returned.
See also: Spu IsReverbWorkAreaReserved (p. 627), SpuSetReverbModeParam (p. 649), SpuSetReverb (p. 647), SpuMalloc (p. 629), SpuMallocWithStartAddr (p. 630).
SpuSetCommonAttr
Sets attributes common to all voices (infrequent change requests). Syntax
void SpuSetCommonAttr(attr) SpuCommonAttr *attr;
Arguments
attr Attributes common to all voices Explanation
Sets attributes common to all voices.
You can set each attribute (members of attr) in attr.mask by ORing together the terms shown below. If attr.mask is 0, left and right attributes are set simultaneously.
Attribute Description
SPU_COMMON_MVOLL master volume (left)
SPU_COMMON_MVOLR master volume (right)
Individual setting parameters are explained below.
a) Master Volume and Master Volume Mode
Master volume is set in attr.mvol; master volume mode is set in attr.mvolmode. Left and right are set independently.
The volume range obtainable and the various modes are the same as the settings for each voice; see Table 1 under SpuSetVoiceAttr().
b) CD Input Volume
CD input volume is set independently for left and right in attr.cd.volume in the range - 0x8000 - 0x7fff. If the volume set is negative, the phase is inverted.
c) CD Input Reverb On/Off Reverb is set in attr.cd.reverb. The values that may be specified are as follows.
Value Description
SPU_ON Set reverb on
SPU_OFF Set reverb off
d) CD Input Mixing On/Off Runtime Library Release 3.0
Sets CD input mixing in attr.cd.mix. The values that may be specified are as follows. CD input is not output unless this value is on.
Value Description
SPU_ON Set mixing on
SPU_OFF Set mixing off
e External Digital Input Volume
External digital input volume is set independently for left and right in attr.ext.volume in the range -0x8000 - 0x7fff. If the volume set is negative, the phase is inverted.
f) External Digital Input Reverb On/Off Reverb is set in attr.ext.reverb. The values that may be specified are as follows.
Value Description
SPU_ON Set reverb on
SPU_OFF Set reverb off
g) External Digital Input Mixing On/Off
Reverb is set in attr.cd.mix. The values that may be specified are as follows. External digital input is not output unless this value is on.
Value Description
SPU_ON Set mixing on
SPU_OFF Set mixing off
Return value None.
See also: structures SpuVolume (p. 607), SpuExtrAttr (p. 603), SpuCommonAttr (p. 601), SpuGetCommonAttr (p. 611).
SpuSetIRQ
Sets interrupt request ON/OFF. Syntax
long SpuSetIRQ (on_off) long on_off;
Arguments
on_off Sets interrupt request ON/OFF
Explanation
Sets interrupt request ON/OFF. on_off setting values are as follows.
Value
Description
SPU_ON
SPU_OFF
SPU_RESET
Set interrupt request
Cancel interrupt request
Reset interrupt request
(= set after cancel)
Return value
Set value (SPU_ON/SPU_OFF/SPU_RESET)
See also: SpuGetIRQ (p. 612).
SpuSetIRQAddr
Sets interrupt request address. Syntax
unsigned long SpuSetIRQAddr(addr) unsigned long addr;
Arguments
addr Interrupt request address Explanation
Sets interrupt request address. The address must be
* in bytes
* divisible by 8
* lower 4 bits is 1000
* 512 KB or less
Return value
Returns the value of the address that is set.
Remarks
If the value of the set address addr is not divisible by 8, the set value is advanced to the next value divisible by 8, and that value is set and returned.
If the lower 4 bits is 0000, the lower 4 bits are set to the value 1000 and returned. If the address exceeds 512 KB, 0 is returned.
See also: SpuGetIRQAddr (p. 613), SpuSetIRQ (p. 638), SpuGetIRQ (p. 612).
640 Basic Sound Library (libspu) Functions
SpuSetIRQCallback
Sets callback at the time of an interrupt request. Syntax
typedef void (*SpuIRQCallbackProc)(void); void SpuSetIRQCallback(func) SpuIRQCallbackProc func;
Arguments
func The callback function activated at the time of an interrupt request
Explanation
Sets the callback function specified by func and activated at the time of an interrupt request.
If the callback function value is set to NULL, callback is cleared.
Return value None.
See also: SpuSetIRQ (p. 638), SpuSetIRQAddr (p. 639).
Runtime Library Release 3.0
SpuSetKey
Sets key on/key off for each voice. Syntax
void SpuSetKey(on_off, voice_bit) long on_off;
unsigned long voice_bit;
Arguments
on_off Sets key on/key off
voice_bit Set voice
Explanation
Sets each voice specified by voice_bit as key on/key off. Values that may be set by on_off are as follows.
Value Description
SPU_ON set key on
SPU_OFF set key off
Specify the voices set in voice_bit by ORing together SPU_0CH-SPU_23CH.
Return value None.
Example When setting key on for voice 0 and voice 2, call SpuSetKey() as follows.
SpuSetKey (SPU_ON, /* set key on */
SPU_0CH | SPU_2CH);/* 0 ch and 2 ch */
See also: SpuSetKeyOnWithAttr (p. 642), SpuSetVoiceAttr (p. 655).
SpuSetKeyOnWithAttr
Sets key on with attributes for voice. Syntax
void SpuSetKeyOnWithAttr(attr) SpuVoiceAttr *attr;
Arguments
attr Voice attributes
Explanation
Specifies attributes for each voice and sets key on.
Explicitly specify the voices to be produced by ORing together SPU_0CH-SPU_23CH in attr.voice.
You can set each attribute (members of attr) in attr.mask by ORing together the terms shown below. See SpuSetVoiceAttr() for the details of these attributes.
Attribute Description
SPU_VOICE_VOLL volume (left)
SPU_VOICE_VOLR volume (right) SPU_VOICE_VOLMODEL volume mode (left) SPU_VOICE_VOLMODER volume mode (right)
SPU_VOICE_PITCH interval (pitch
SPU_VOICE_NOTE interval (note SPU_VOICE_SAMPLE_NOTE waveform data
SPU_VOICE_WDSA waveform data start SPU_VOICE_ADSR_AMODEADSR Attack rate SPU_VOICE_ADSR_SMODEADSR Sustain rate SPU_VOICE_ADSR_RMODEADSR Release rate
SPU_VOICE_ADSR_AR ADSR Attack rate
SPU_VOICE_ADSR_DR ADSR Decay rate
SPU_VOICE_ADSR_SR ADSR Sustain rate
SPU_VOICE_ADSR_RR ADSR Release rate
SPU_VOICE_ADSR_SL ADSR Sustain level SPU_VOICE_ADSR_ADSR1 ADSR adsr1 for SPU_VOICE_ADSR_ADSR2 ADSR adsr2 for
SPU_VOICE_LSAX loop start address
Return value None.
See also: structures SetVolume (p. 607), SpuVoiceAttr (p. 605), SpuSetKey (p. 641), SpuSetVoiceAttr (p. 655), SpuGetVoiceAttr (p. 624).
SpuSetMute
Sets sound muting ON/OFF. Syntax
long SpuSetMute(on_off) long on_off;
Arguments on_off Explanation
Sets sound muting ON/OFF. on_off setting values are as follows.
Value Description
SPU_ON mute on
SPU_OFF mute off
However, CD input and external digital input are not muted by this mute ON/OFF.
Return value
Set value (SPU_ON/SPU_OFF).
See also: SpuGetMute (p. 615).
SpuSetNoiseClock
Sets noise source clock. Syntax
long SpuSetNoiseClock(n_clock) long n_clock;
Arguments
n_clock Noise source clock
Explanation
Set noise source clock value in n_clock. The clock value n_clock must be - 0x00 - 0x3f.
Return value
Noise source clock value set.
See also: SpuGetNoiseClock (p. 616).
SpuSetNoiseVoice
Sets noise source ON/OFF for each voice. Syntax
unsigned long SpuSetNoiseVoice(on_off, voice_bit) long on_off;
unsigned long voice_bit;
Arguments
on_off Sets noise source ON/OFF
voice_bit Set voice
Explanation
Sets each voice specified by voice_bit as noise on/noise off (i.e., use/do not use noise). Values that may be set by on_off are as follows.
Value Description
SPU_ON Sets noise source
SPU_OFF Releases noise source
Specify the voices set in voice_bit by ORing together SPU_0CH-SPU_23CH.
Return value
Returns the noise source ON/OFF value of the current voice. OR together SPU_0CHSPU_23CH.
Distinguishes the noise source ON/OFF value by ANDing the return value and SPU_xxCH(xx=0~23).
Result of AND Description
0 Sets noise source off
Other than 0 Sets noise source on
Example
Set voice 0 and voice 2 noise source on as follows.
SpuSetNoiseVoice(SPU_ON, /*set noise source on*/ SPU_0CH | SPU_2CH); /*0 ch and 2 ch*/
See also: SpuSetNoiseClock (p. 644), SpuGetNoiseClock (p. 616), SpuGetNoiseVoice (p. 617).
646 Basic Sound Library (libspu) Functions
SpuSetPitchLFOVoice
Sets pitch LFO ON/OFF for each voice. Syntax
unsigned long SpuSetPitchLFOVoice(on_off, voice_bit) long on_off;
unsigned long voice_bit;
Arguments
on_off Sets pitch LFO ON/OFF
voice_bit Sets voice
Explanation
Sets pitch LFO ON/OFF for each voice. on_off may be specified as shown below
Value Description
SPU_ON Sets pitch LFO on
SPU_OFF Sets pitch LFO off
Specify the voices set in voice_bit by ORing together SPU_0CH-SPU_23CH.
Voice n, having pitch LFO set on, is set so that LFO sets pitch when the volume of voice (n - 1) undergoes a time change.
To make this pitch LFO valid, voice n and voice (n - 1) must produce sound, and the volume of voice (n - 1) must be set to 0 in advance.
Voice (n - 1) can produce sound at an optional timing after voice n produces sound; LFO is applied at the moment when voice (n - 1) produces sound.
Return value
Returns the pitch LFO ON/OFF value of the current voice. SPU_23CH.
Distinguishes the pitch LFO ON/OFF value by AN Ding the SPU_xxCH(xx=0~23).
OR together SPU_0CH-
return value and
Result of AND Description
0 Sets pitch LFO off
Other than 0 Sets pitch LFO on
See also: SpuGetPitchLFOVoice (p. 618), SpuSetKey (p. 641), SpuSetKeyOnWithAttr (p. 642).
SpuSetReverb
Sets reverb ON/OFF. Syntax
long SpuSetReverb(on_off) long on_off;
Arguments
on_off Sets reverb ON/OFF
Explanation
Sets reverb ON/OFF.
Values that may be set by on_off are as follows.
Value Description
SPU_ON Set reverb on
SPU_OFF Set reverb off
Return value
Set value (SPU_ON/SPU_OFF).
Remarks
If a reverb work area is not reserved with SpuReserveReverbWorkArea(), when SPU_ON is specified by on_off, SpuSetReverb() checks on whether the area used as a work area by SpuMalloc()/ SpuMallocWithStartAddr() is being used as another area, and if it is being used, reverb is set off, and SPU_OFF is returned.
If it is not being used, reverb is set on and SPU_ON is returned. When a reverb work area is reserved, SPU_ON sets reverb on in on_off and returns SPU_ON.
See also: SpuGetReverb (p. 619), SpuSetReverbModeParam (p. 649), SpuReserveReverbWorkArea (p. 608).
SpuSetReverb Depth
Sets the reverb depth parameter. Syntax
void SpuSetReverbDepth(attr) SpuReverbAttr *attr;
Arguments
attr Reverb attribute
Explanation
Sets the reverb depth parameter attribute.
You can set each attribute (members of attr) in attr.mask by ORing together the terms shown below. If attr.mask is 0, left and right attributes are set simultaneously.
Value Description
SPU_REV_DEPTHLReverb depth (left) SPU_REV_DEPTHRReverb depth (right)
a) Reverb Depth
Reverb depth is set independently for left and right. The range for this specification is - 0x8000 - 0x7fff.
If the value set is negative, the reverb sound (wet) phase is inverted.
Return value
Always returns 0
See also: SpuVolume (p. 607), structures SpuReverbAttr (p. 604), SpuSetReverbModeParam (p. 649), SpuGetReverbModeParam (p. 620).
SpuSetReverbModeParam
Sets reverb mode and parameters. Syntax
void SpuSetReverb ModeParam (attr) SpuReverbAttr *attr;
Arguments
attr Reverb attributes
Explanation
Sets reverb mode and parameter attributes.
You can set each attribute (members of attr) in attr.mask by ORing together the terms shown below. If attr.mask is 0, all attributes are set.
Attribute Description
SPU_REV_MODE mode setting
SPU_REV_DEPTHL reverb depth (left)
SPU_REV_DEPTHR reverb depth (right)
SPU_REV_DELAYTIME delay time (ECHO, DELAY only) SPU_REV_FEEDBACK feedback (ECHO only)
a) Reverb Mode (Table 8)
Sets reverb mode. Setting attributes other than "Depth" (reverb depth) varies according to the reverb mode.
attr. mode mode Delay time Feedback
SPU_REV_MODE_OFF off
SPU_REV_MODE_ROOM room
SPU_REV_MODE_STUDIO_A studio (small) SPU_REV_MODE_STUDIO_B studio (med) SPU_REV_MODE_STUDIO_C studio (big) SPU_REV_MODE_HALL hall
SPU_REV_MODE_SPACE space echo
SPU_REV_MODE_ECHO echo can set can set
SPU_REV_MODE_DELAY delay can set can set SPU_REV_MODE_PIP half echo
Table 8: Reverb Mode and Other Attributes
When reverb mode is changed (this happens even at initial setting because the initial value is SPU_REV_MODE_OFF), the internal reverb Depth value is 0 even if Depth was previously set in SpuSetReverbModeParam(). This is because the work area size changes when this mode changes, so incorrect data in the work area produces noise. So after the reverb mode changes, Depth needs to be reset in
SpuSetReverbModeParam() or SpuSetReverbDepth().
Based on reverb characteristics, the time to complete one scan of the work area is estimated and the mode/depth are set; or, after the mode is set, the work area data is erased then Depth is set (to be described later).
The sound buffer volume occupied by the work area depends on the reverb mode as shown in Table 9. However, this area is managed by a memory management mechanism such as SpuMalloc(). See SpuMalloc() for details.
attr.mode mode hexadecimaldecimal
SPU_REV_MODE_OFF off 0/80 (*) 0/128 (*)
SPU_REV_MODE_ROOM room 26c0 9920
SPU_REV_MODE_STUDIO_A studio (small) 1f40 8000
SPU_REV_MODE_STUDIO_B studio (med) 4840 18496
SPU_REV_MODE_STUDIO_C studio (big) 6fe0 28640
SPU_REV_MODE_HALL hall ade0 44512
SPU_REV_MODE_SPACE space echo f6c0 63168
SPU_REV_MODE_ECHO
echo 18040
98368
SPU_REV_MODE_DELAY
delay 18040
98368
SPU_REV_MODE_PIPE
half echo 3c00
15360
(*) In address setting, if it is SpuReserveReverbWorkArea(SPU_ON), it consumes 128 bytes even if the mode is off. If it is SpuReserveReverbWorkArea (SPU_OFF), it consumes 0 bytes.
Table 9: Volume Occupied by Reverb Mode In Sound Buffer
When the mode changes, a decision is made by SpuMalloc()/SpuMallocWithStartAddr() as to whether or not the area used as a work area by the new mode is already being used as another area. If it is already being used, none of the specified reverb attributes are set and SPU_ERROR is returned. If it is not being used, the specified reverb attributes are set and 0 is returned.
If SPU_REV_MODE_CLEAR_WA is ORed in attr.mode, it clears the area needed by reverb mode set when setting reverb mode. This is a measure against noise when changing modes. However, the sound buffer is cleared by synchronous DMA transfer, so other processing (drawing, sound generation) is not performed during this processing, and some wait time is needed, depending on the reverb type.
SpuClearReverbWorkArea() is used to forcibly clear the area used by the reverb mode specified when setting reverb mode with optional timing.
b) Reverb Depth
Set in attr.depth, independently for left and right. Values are set in the range -0x8000 - 0x7fff.
If the set value is negative, the reverb sound (wet) phase is inverted.
c) Delay Time
Set in attr.delay. Values are set in the range 0 - 127. Valid when mode is SPU_REV_MODE_ECHO or SPU_REV_MODE_DELAY.
d) Feedback
Valid when mode is SPU_REV_MODE_ECHO or SPU_REV_MODE_DELAY. Delay time is set in attr.feedback with values from 0 to 127.
Return value
When the mode changes, a decision is made as to whether or not the area used as a work area by the new mode is being used as another area by SpuMalloc()/ SpuMallocWithStartAddr(). If it is being used, none of the set reverb attributes are set and SPU_ERROR is returned. If it is not being used, the set reverb attributes are set and 0 is returned.
See also: SpuVolume (p. 607), structures SpuReverbAttr (p. 604),
SpuGetReverbModeParam (p. 620), SpuMalloc (p. 629), SpuMallocWithStartAddr (p. 630), Spu ReserveReverbWorkArea (p. 597), SpuClearReverbWorkArea (p. 608).
SpuSetReverbVoice
Sets reverb ON/OFF for each voice. Syntax
unsigned long SpuSetReverbVoice(on_off, voice_bit) long on_off;
unsigned long voice_bit
Arguments
on_off Sets reverb ON/OFF
voice_bit Set voice
Explanation
Sets each voice specified by voice_bit as reverb on/reverb off. Values that may be set by on_off are as follows.
Value Description
SPU_ON set reverb on SPU_OFF set reverb off
Specify the voices set in voice_bit by ORing together SPU_0CH-SPU_23CH. Return value
Returns the reverb ON/OFF value of the current voice. OR together SPU_0CHSPU_23CH.
Distinguishes the noise source ON/OFF value by ANDing the return value and SPU_xxCH(xx=0~23).
Result of AND Description
0 Sets reverb off
Other than 0 Sets reverb on
Example
Set voice 0 and voice 2 reverb on as follows.
SpuSetReverbVoice(S PU_ON ,/*set reverb on*/ SPU_0CH | SPU_2CH); /*0 ch and 2 ch*/
See also: SpuGetReverbVoice (p. 621).
SpuSetTransferMode
Sets sound buffer transfer mode. Syntax
long SpuSetTransferMode(mode) long mode;
Arguments
mode transfer mode
Explanation
Sets mode when transferring data from main memory to the sound buffer. Mode values are as shown below. DMA transfer is the default.
These specifications are valid only when transferring data from main memory to the sound buffer. DMA transfer is always used when transferring data from the sound buffer to main memory.
Value Description
SPU_TRANSFER_BY_DMA
DMA transfer setting
Can do other
processing
during transfer
SPU_TRANSFER_BY_IO
I/O transfer setting
Transfer uses the CPU;
cannot do other
processing during transfer
Return value
Set transfer mode
(SPU_TRANSFER_BY_DMA/ SPU_TRANSFER_BY_IO).
See also: SpuGetTransferMode (p. 622), SpuWrite (p. 661).
SpuSetTransferStartAddr
Sets sound buffer transfer destination/transfer source start address. Syntax
unsigned long SpuSetTransferStartAddr(addr) unsigned long addr;
Arguments
addr Sound buffer transfer destination/transfer source start address Explanation
Sets an address specified in addr for the starting address when transferring from main memory to the sound buffer, and from the sound buffer to main memory.
However, the start address value must be
* in bytes
* divisible by 8
* greater than 0x1 000 and 512 KB or less
For transfers from the 0x0 - 0xfff area, see Spu Read DecodeData().
Return value
Set start address value.
If the value of the set address addr is not divisible by 8, the set value is advanced to the next value divisible by 8 and that value is returned.
For values smaller than 0x1000 or greater than 512 KB, 0 is returned.
See also: SpuGetTransferStartAddr (p. 623), SpuWrite (p. 661), SpuRead (p. 632).
SpuSetVoiceAttr
Sets attributes for each voice. Syntax
void SpuSetVoiceAttr(attr) SpuVoiceAttr *attr;
Arguments
attr Voice attributes
Explanation
Sets attributes for each voice
Explicitly specify the voices you wish to set by ORing together SPU_0CH-SPU_23CH in attr.voice.
You can set each attribute in attr.mask by ORing together the terms shown below.
Attribute Description
SPU_VOICE_VOLL volume (left)
SPU_VOICE_VOLR volume (right) SPU_VOICE_VOLMODEL volume mode (left) SPU_VOICE_VOLMODER volume mode (right)
SPU_VOICE_PITCH interval (pitch specification)
SPU_VOICE_NOTE interval (note specification) SPU_VOICE_SAMPLE_NOTE waveform data sample
SPU_VOICE_WDSA waveform data start SPU_VOICE_ADSR_AMODEADSR Attack rate mode SPU_VOICE_ADSR_SMODEADSR Sustain rate mode SPU_VOICE_ADSR_RMODEADSR Release rate mode SPU_VOICE_ADSR_AR ADSR Attack rate SPU_VOICE_ADSR_DR ADSR Decay rate SPU_VOICE_ADSR_SR ADSR Sustain rate SPU_VOICE_ADSR_RR ADSR Release rate SPU_VOICE_ADSR_SL ADSR Sustain level SPU_VOICE_ADSR_ADSR1 ADSR adsr1 for VagAtr SPU_VOICE_ADSR_ADSR2 ADSR adsr2 for VagAtr
SPU_VOICE_LSAX loop start address
note address
Each of these settings is described below. a) Volume and Volume Mode (Table 1)
The settings for Volume Mode are shown below. Sound is normally produced in direct mode.
mode (phase) SPU_VOICE_VOLMODEx SPU_VOICE_VOLx
direct mode SPU_VOICE_DIRECT -0x4000 - 0x3fff
linear inc. mode SPU_VOICE_LINEARIncN 0x00 - 0x7f (normal) linear inc. mode SPU_VOICE_LINEARIncR 0x00 - 0x7f (inverted)
linear dec. mode SPU_VOICE_LINEARDecN 0x00 - 0x7f (normal) linear dec. mode SPU_VOICE_LINEARDecR 0x00 - 0x7f (inverted) expon. inc. modeSPU_VOICE_EXPIncN 0x00 - 0x7f (normal) expon. inc. modeSPU_VOICE_EXPIncR 0x00 - 0x7f (inverted) expon. dec. mode SPU_VOICE_EXPDec 0x00 - 0x7f
Table 1: Volume Mode and Volume Setting Ranges
* Direct Mode
Fixed volume mode. In normal usage, this mode produces sound.
When the set volume is negative, its phase is reversed. In this situation, "inverted phase", described below, is valid.
* Linear Increase Mode (Normal Phase)
When the current volume value is positive and this mode is set, volume increases linearly from the current value to the maximum value.
* Linear Increase Mode (Inverted Phase)
When the current volume value is negative (inverted phase) and this mode is set, volume increases linearly from the current value to the maximum value, with phase inverted.
* Linear Decrease Mode (Normal Phase)
When the current volume value is positive and this mode is set, volume decreases linearly from the current value to the minimum volume value (= volume 0).
* Linear Decrease Mode (Inverted Phase)
When the current volume value is negative (inverted phase) and this mode is set, volume decreases linearly from the current value to the minimum volume value (= volume 0), with phase inverted.
* Exponential Increase Mode (Normal Phase)
When the current volume value is positive and this mode is set, volume increases exponentially from the current value to the maximum value.
* Exponential Increase Mode (Inverted Phase)
When the current volume value is negative (inverted phase) and this mode is set, volume increases exponentially from the current value to the maximum value, with phase inverted.
* Exponential Decrease Mode
When this mode is set, whether the current volume value is positive or negative, volume decreases exponentially from the current value to the minimum volume value (= volume 0).
b) Interval (set pitch, set note)
Interval may be set by the two methods listed below.
* Pitch specification
Specification of interval by pitch. Specify a value in attr.pitch in the range 0x0000 - 0x3fff.
See Table 2 for an explanation of the meaning of these values. The only unit shown in the table is octaves, but any value in the range 0x0000 - 0x3fff may be set.
Value Set 0x0200 0x0400 0x0800 0x1000 0x2000 0x3fff
Interval - 3 oct. - 2 oct. - 1 oct. tone + 1 oct. + 2 oct.
Table 2: Pitch Specification Values and Interval
• Note specification
Specification of interval by pitch. An interval is set in attr.note as follows, using a 16-bit value for note and cent (here, the value of a half tone divided by 128).
This setting cannot be used unless the waveform data sample note feature, described later, is set.
Bit Value Set
Upper 8 bits MIDI note number
Lower 8 bits Cent (expressed as a half tone divided by 128)
Table 3: Note Specification Values
c) Waveform Data Sample Note
Sets interval in attr.sample_note at the time of sampling, using a 16-bit value for note and cent (here, the value of a half tone divided by 128). Setting this value makes it possible to set Interval--Note specification mentioned in the previous section.
Bit Value Set
Upper 8 bits:
MIDI note number
Lower 8 bits :
Cent (expressed as half tone
divided by 128)
Table 4: Waveform Data Sample Note Specification Values
d) Waveform Data Start Address
The sound buffer starting address of the waveform data you want to produce in the voice is set in attr.addr.
e) Loop Start Address
If waveform data is created with a loop specified, and if the waveform starting address is set, the loop start address is usually automatically identified and set. Explicit setting is unnecessary.
However, when you wish to set a loop start address dynamically at the time of execution, you must set the address that is the starting point of the loop in the sound buffer in attr.loop_addr.
If a loop was not set at the time of waveform data creation, even if SPU_VOICE_LSAX is specified and set in attr.loop_addr, that setting is invalid,.
f) ADSR
A conceptual diagram of ADSR is shown below.
Figure: ADSR Conceptual Diagram
ADSR attributes are set by the structure members listed in Table 5; the range of these attributes is listed in Table 6.
Attribute Structure Member
Rate: Attack rate
attr.ar, attr.a_mode
Decay rate
attr.dr
Sustain rate
attr.sr, attr.s_mode
Release rate
attr.rr, attr.r_mode
Level: Sustain level attr.sl
Table 5: Parameters and Structure Members
Attribute
Structure Member Setting Range
Attack rate
attr.ar
0x00 - 0x7f
Decay rate attr.dr
0x0 - 0xf
Sustain rate attr.sr
0x00 - 0x7f
Release rate
attr.rr
0x00 - 0x1f
Sustain level
attr.sl
0x0 - 0xf
Table 6: Rate and Level Ranges
Rate curves may be set for Attack, Sustain, Release (see Table 7).
Because only exponential decrease may be used for Decay, that attribute cannot be set.
Attribute Mode setable in attr.?_mode
Attack rate SPU_VOICE_LINEARIncN (linear increase ) SPU_VOICE_EXPIncN (exponential increase)
Decay rate N/A
Sustain rate SPU_VOICE_LINEARIncN (linear increase ) SPU_VOICE_LINEARDecN (linear decrease) SPU_VOICE_EXPIncN (exponential increase) SPU_VOICE_EXPDecN (exponential decrease)
Release rate SPU_VOICE_LINEARDecN (linear decrease) SPU_VOICE_EXPDecN (exponential decrease)
Table 7: ADSR Rate Mode
Also, data from structure VagAtr members adsr1 and adsr2 may be set directly in attr.adsr1 and attr.adsr2.
In this case only SPU_VOICE_ADSR_ADSR1 and SPU_VOICE_ADSR_ADSR2 can be set for ADSR in attr. mask.
Return value None.
See also: structure SpuVoiceAttr (p. 605), SpuGetVoiceAttr (p. 624), SpuSetKey (p. 641), SpuSetKeyOnWithAttr (p. 642).
660 Basic Sound Library (libspu) Functions
SpuStart
Starts SPU processing. Syntax
void SpuStart(void)
Arguments None.
Explanation
SpuStart() starts SPU processing. This function is also called by SpuInit(), so it is not necessary to call it when initializing, but it must be called if you use SpuQuit() to turn functionality off.
In the current specification, the following processing is performed after it is called. • DMA transfer initialization setting
Return value None.
See also: SpuQuit(), SpuInit()
Runtime Library Release 3.0
Spu Write
Transfers data from main memory to the sound buffer. Syntax
unsigned long SpuWrite(addr, size) unsigned char *addr;
unsigned long size;
Arguments
addr Transfer data start address in main memory
size Transfer data size (in bytes)
Explanation
Transfers size bytes of data from main memory addr to the sound buffer
The main memory address addr storing the transfer data must fulfill the following conditions.
* It is an address of an allocated variable that is a global variable
* It is an address of an allocated variable that is in the heap and is allocated by a function such as malloc.
That is, it does not address a stack area (a variable (= auto variable) declared in a function.
SpuWrite() does not perform sound buffer memory management, so real waveform data cannot be used if theuser does not transfer to addresses which avoid the following areas.
* SPU decoded data transfer area: 0x0000 - 0xfff
* addresses after the reverb work area offset (start) address
Return value
Transferred data size.
If the specified data size is larger than 512 KB, the actual transferred size is returned.
See also: SpuRead (p. 632), SpuSetTransferStartAddr (p. 654), SpuGetTransferStartAddr (p. 623).
SpuWrite0
Clears sound buffer. Syntax
unsigned long SpuWrite0(size) unsigned long size;
Arguments
size: Clear an area size (in bytes)
Explanation
Zero-clears a sound buffer area of a size specified by the argrument size.
The starting address of the zero-cleared area is specified by SpuSetTransferStartAddr(). This writing is done by DMA transfer, but is started synchronously.
Return value
Returns the size of the area written with 0s.
If the data size set is larger than 512 KB, the actual transferred size is returned.
See also: SpuWrite (p. 661), SpuSetTransferStartAddr (p. 654).
Spu Write Partly
Transfers data from main memory to the sound buffer (assuming the transfer is divided into sections).
Syntax
unsigned long SpuWritePartly(addr, size) unsigned char *addr;
unsigned long size;
Arguments
addr Transfer data start address in main memory
size Transfer data size (in bytes)
Explanation
Transfers size bytes of data from main memory addr to the sound buffer.
The main memory address addr storing the transfer data must fulfill the following conditions.
* It is an address of an allocated variable that is a global variable
* It is an address of an allocated variable that is in the heap and is allocated by a function such as malloc.
That is, it does not address a stack area (a variable (= auto variable) declared in a function.
Data is transferred from the address set by SpuSetTransferStartAddr(), and after completion of the transfer specified by size, the starting address is incremented by size, and stored internally.
Normally, in the case of continuous transfer, the size of each transfer must be a number divisible by 8. But when transferring the final block of a continuous transfer, the size need not be divisible by 8.
If SpuSetTransferStartAddr() is called during continuous transfer processing, correct continuous transfer is not guaranteed.
SpuWritePartly() does not perform sound buffer memory management, so real waveform data cannot be used if theuser does not transfer to addresses which avoid the following areas.
* SPU decoded data transfer area: 0x0000 - 0xfff
* addresses after the reverb work area offset (start) address
Return value
Returns the size of the area written with 0s.
If the data size set is larger than 512 KB, the actual transferred size is returned.
See also: SpuWrite (p. 661), SpuRead (p. 632), SpuSetTransferStartAddr (p. 654), SpuGetTransferStartAddr (p. 623).
Chapter 9
Extended Sound Library (libsnd)
This chapter describes structures defined in the extended sound library (libsnd) and the available functions. The extended sound library is a service created for use with the special PlayStation Sound Artist tool. It converts sound data so it can be used by the PlayStation.
Chapter 9: Extended Sound Library (libsnd) Table of Contents
Structures
ProgAtr
669
SndVolume
670
VabHdr
671
VagAtr
672
SsEnd
673
Functions
SsGetMVol
674
SsGetRVol
675
SsGetSerialAttr
676
SsInit
677
SsIsEos
678
SsPlayBack
679
SsQuit
680
SsSepClose
681
SsSepOpen
682
SsSepPause
683
SsSepPlay
684
SsSepReplay
685
SsSepSetAccelerando
686
SsSepSetCrescendo
687
SsSepSetDecrescendo
688
SsSepSetRitardando
689
SsSepSetVol
690
SsSepStop
691
SsSeqCalledTbyT
692
SsSeqClose
693
SsSeqOpen
694
SsSeqPause
695
SsSeqPlay
696
SsSeqReplay
697
SsSeqSetAccelerando
698
SsSeqSetCrescendo
699
SsSeqSetDecrescendo
700
SsSeqSetNext
701
SsSeqSetRitardando
702
SsSeqSetVol
703
SsSeqStop
704
SsSetAutoKeyOffMode
705
SsSetLoop
706
SsSetMarkCallback
707
SsSetMono
708
SsSetMute
709
SsSetMVol
710
SsSetNoiseOff
711
SsSetNoiseOn
712
SsSetReservedVoice
713
SsSetRVol
714
SsSetSerialAttr
715
SsSetSerialVol
716
SsSetStereo
717
SsSetTableSize
718
SsSetTempo
718
SsSetTickMode
720
SsStart
722
SsUtAllKeyOff
723
SsUtAutoPan
724
SsUtAutoVol
725
SsUtChangeADSR
726
SsUtChangePitch
727
SsUtFlush
728
SsUtGetDetVVol
729
SsUtGetProgAtr
730
SsUtGetReverbType
731
SsUtGetVabHdr
732
SsUtGetVagAtr
733
SsUtGetVBaddrInSB
734
SsUtGetVVol
735
SsUtKeyOff
736
SsUtKeyOffV
737
SsUtKeyOn
738
SsUtKeyOnV
739
SsUtPitchBend
740
SsUtReverbOff
741
SsUtReverbOn
742
SsUtSetDetVVol
743
SsUtSetProgAtr
744
SsUtSetReverbDelay
745
SsUtSetReverbDepth
746
SsUtSetReverbFeedback
747
SsUtSetReverbType
748
SsUtSetVabHdr
749
SsUtSetVagAtr
750
SsUtSetVVol
751
SsVabClose
752
SsVabFakeBody
753
SsVabFakeHead
754
SsVabOpen
755
SsVabOpenHead
756
SsVabOpenHeadSticky
757
SsVabTransBody
758
SsVabTransBodyPartly
759
SsVabTransCompleted
760
SsVoKeyOff
761
SsVoKeyOn
762
Extended Sound Library (libsnd) Structures 669
ProgAtr
Program header. Structure
struct ProgAtr { char tones;
char mvol;
char prior;
char mode;
short attr;
short reserved0; long reserved1; long reserved2; };
Members
tones
mvol
prior
mode
attr reserved0 reserved1 reserved2
Number of VAG attribute sets contained in the program
Master volume for the program
Program priority (0-15) Sound source mode Program attribute
Reserved by the system Reserved by the system Reserved by the system
Runtime Library Release 3.0
SndVolume
Volume. Structure
struct SndVolume { short left;
short right;
};
Members
left L channel's volume value
right R channel's volume value
Extended Sound Library (libsnd) Structures 671
VabHdr
Bank header. Structure
struct VabHdr {
long form; long ver;
long id;
unsigned long fsize;
short reserved0;
short ps; short ts;
short vs;
char mvol; char pan; char attr1; char attr2;
unsigned long reserved;
};
Members
form ver
id
fsize reserved0
ps
ts
vs
mvol pan attr1 attr2
Explanation
Format name (always 'VAB1')
Format version number
Bank (VAB) number
Bank file size
Reserved by the system
Total number of programs contained in the bank
Total number of VAG attribute sets contained in the bank Number of VAGs contained in the bank
Master volume
Master pan level
Bank attribute 1 that can be defined by the user Bank attribute 2 that can be defined by the user
The VAB bank header contains information, such as sound source data set size and sound source numerals, that is used at the time of execution.
When the SsVabOpen () function is called, it is read by the system and wave form data is generated in the SPU's local memory. Also, volume setting and panning setting are referred at the time of voice allocation.
Information about VAB, the program and each VAG header can change at the time of execution by the user, and the attribute value is reflected in the voice application after the next KEY ON.
VagAtr
Task Execute Queue. Structure
struct VagAtr { char prior; char mode; char vol;
char pan;
char center; char shift; char min;
char max; char vibW; char vibT; char porW; char porT; char pbmin; char pbmax; char reserved1; short reserved2;
short adsr1; short adsr2; short prog; short vag;
short reserved [4];
};
Members
prior mode vol
pan center shift
min
max
vibW vibT porW porT pbmin pbmax reserved1 reserved2 adsr1 adsr2
Priority (0-15)
Sound source mode
Volume (0-127, 0:min, 127:max)
Pan pot (0-127, 0:left, 63:center, 127:right) Center note (0-127)
Pitch correction (0-99, in cents)
Minimum note limit Maximum note limit
Vibrato width (0-127 over one octave) Period of vibrato cycle (in ticks)
Portamento width
Period of portamento duration (in ticks) Minimum pitch bend limit
Maximum pitch bend limit
Reserved by the system
Reserved by the system
Set ADSR value 1 Set ADSR value 2
prog Master program containing the VAG attribute
vag VAG's ID number utilized by the VAG attribute reserved [0...3]Reserved by the system
Extended Sound Library (libsnd) Functions 673
SsEnd
Finalizes the sound system. Syntax
void SsEnd (void)
Argument
None.
Explanation
If SsSetTickMode () is used to set the mode that automatically calls SsSeqCalledTbyT (), this function, after it is called, stops SsSeqCalledTbyT () from being called for every Tick.
Return value None.
See also: SsStart (p. 722), SsSetTickMode (p. 720), SsSeqCalled TbyT (p. 692), SsQuit (p. 680).
674 Extended Sound Library (libsnd) Functions
SsGetM Vol
Main volume value acquisition. Syntax
void SsGetMVol (m_vol) SndVolume* m_vol;
Arguments
m_vol main volume value Explanation
Returns the main volume value to m_vol.
Return value None.
See also: SsSetMVol (p. 710).
Runtime Library Release 3.0
SsGetRVol
Sets Reverberant volume value. Syntax
Extended Sound Library (libsnd) Functions 675
Void SsGetRVol (r_vol) SndVolume *r_vol;
Arguments
r_vol Reverb volume value Explanation
Returns the reverb volume value to r_vol.
Return value None.
See also: SsSetRVol (p. 714).
Runtime Library Release 3.0
SsGetSerialAttr
Gets the value of the serial input line volume. Syntax
char SsGetSerialAttr (s_n um, attr) char s_n um;
char attr;
Arguments
s_num Serial Number attr Attribute
Explanation
Returns the specified serial input line attribute value. s_num and attr may be set as follows.
(a) s_n um
Macro Contents
SS_SERIAL_A Serial A (CD input)
SS_SERIAL_B Serial input line B (external digital input)
(b) attr
Macro Contents
SS_MIX Mixing
SS_REV Reverb
Return value
Attribute: Returns 1 if on. Return 0 if off.
Related items SsSetSerialAttr
See also: SsSetSerialVol (p. 716).
Extended Sound Library (libsnd) Functions 677
SsInit
Initialize Sound system. Syntax
void SsInit ()
Arguments None.
Explanation
This function initializes the sound system, clearing the sound local memory.
Return value None.
Runtime Library Release 3.0
SsIsEos
Determines whether or not a song is being played. Syntax
short SsIsEos (access_num, seq_n um) short access_num;
short seq_n um;
Arguments
access_n um SEQ/SEP access number seq_n um SEQ number inside SEP data
Explanation
Determines whether or not a specified song is being played.
When using this function for SEQ data, set 0 in seq_num; when using this function for SEP data, set the number that contains the SEQ to be played.
Return value
Returns 1 if the song is being played. Returns 0 if the song is not being played.
Extended Sound Library (libsnd) Functions 679
SsPlayBack
Read SEQ/SEP data. Syntax
void SsPlayBack (access_num, seq_n um, l_count) short access_num;
short seq_n um;
short l_count;
Arguments
access_n um SEQ/SEP access number
seq_n um SEQ number inside SEP data
l_count Song repetition count
Explanation
In the current play mode, no event occurs when a function is called again during execution. However, this function, if called again during execution, stops the song being played, returns to the start of the song, and begins playing it again.
When using this function for SEQ data, set 0 in seq_num; when using this function for SEP data, set the number that contains the SEQ to be played. Specify a song repetition count in l_count.
For infinite play repetition, specify SSPLAY_INFINITY.
Return value
None.
See also: SsSeqPlay (p. 684).
680 Extended Sound Library (libsnd) Functions
SsQuit
Terminate the sound system. Syntax
void SsQuit (void) Explanation
Terminates the sound system. After this function is called, transfer to the sound buffer will be disabled. To enable transfer to the sound buffer again, SsInit () must be called.
SsEnd () must be called before SsQuit ().
Return value None.
See also: SsEnd (p. 672), SsStart (p. 722), SsSetTickMode (p. 720), SsSeqCalledTbyT (p. 692).
Runtime Library Release 3.0
Extended Sound Library (libsnd) Functions 681
SsSepClose
Close SEP data. Syntax
void SsSepClose (sep_access_n um) short sep_access_num;
Arguments
sep_access_n um SEP access number Explanation
Closes SEP data possessing sep_access_num that is no longer needed.
Because closing is performed on a SEP unit basis, all SEQ data stored in the closed SEP will become inaccessible.
See also: SsSepOpen (p. 682).
Runtime Library Release 3.0
SsSepOpen
Open SEP data. Syntax
short SsSepOpen (*addr, vab_id, seq_n um) unsigned long *addr;
short vab_id;
short seq_n um)
Arguments
addr Leading address of SEP data inside the main memory
vab_id VAB id
seq_n um Number of SEQs contained in SEP
Explanation
Analyzes the SEP data located in the main memory, and returns a SEP access number. Maximum of 32 pieces of SEP data can be opened simultaneously when combined with the number of open SEQ data.
Return value
SEP access number
An internal SEP data management table number that possesses the same characteristics as the SEQ access number.
See also: SsSepClose (p. 682).
Extended Sound Library (libsnd) Functions 683
SsSepPause
Pause the reading of SEP data. Syntax
void SsSep Pause (sep_access_num, seq_n um) short sep_access_num;
short seq_n um;
Arguments
sep_access_n um SEP access number
seq_n um SEQ number inside SEP data
Explanation
Pauses the reading (playing) of the seq_num-th SEQ data of SEP data possessing sep_access_num.
Return value None.
See also: SsSepReplay (p. 684).
Runtime Library Release 3.0
SsSepPlay
Reads (plays) SEP data. Syntax
void SsSepPlay (sep_access_num, seq_num, play_mode, l_count) short sep_access_num;
short seq_num;
char play_mode;
short l_count;
Arguments
sep_access_num seq_num play_mode l_count
Explanation
SEP access number SEP data SEQ number Play mode
Song repetition count
Reads (plays) SEQ data specified by the SEP data seq_num specified by seq_access_num. At this time, depending on the play_mode, it is possible to choose whether to immediately begin reading (playing) the SEQ data specified by seq_num, or to pause at the beginning of a song.
play_mode Actions
SSPLAY_PAUSE Pauses a song at the beginning SSPLAY_PLAY Plays immediately
Specify a song repetition count in l_count. For infinite play repetition, specify SS PLAY_IN FIN ITY.
Return value
None.
Remarks
(1) Opens SEP data containing four pieces of SEQ data:
sep1 = SsSepOpen (addr, vab_id, 4);
(2) Immediately plays the third piece of data of the opened SEP data twice. SsSepPlay (sep1, 2, SSPLAY_PLAY, 2);
See also: SsSepStop (p. 691).
Extended Sound Library (libsnd) Functions 685
SsSepReplay
Resume (replay) the reading of SEP data. Syntax
void SsSepReplay (sep_access_num, seq_n um) short sep_access_num;
short seq_n um;
Arguments
sep_access_n um SEP access number
seq_n um SEQ number inside SEP data
Explanation
Resumes the reading of the seq_num-th SEQ data of SEP data possessing sep_access_num, that was paused by SsSepPause.
Return value None.
See also: SsSepPause (p. 683).
Runtime Library Release 3.0
SsSepSetAccelerando
Accelerate the tempo. Syntax
void SsSepSetAccelerando (sep_access_num, seq_n um, tempo, v_time)
short sep_access_num;
short seq_n um;
long tempo; long v_time;
Arguments
sep_access_num seq_num
tempo v_time
Explanation
SEQ access number
SEQ number inside SEP data Song tempo
Time (in tick units)
Slows the tempo of the seq_num-th SEQ data of SEP data possessing sep_access_num down to tempo within v_time.
However, if the specified tempo is larger (faster) than the current tempo, this function acts the same as SsSepSetRitardando.
Return value
None.
See also: SsSepSetRitardando (p. 689).
SsSepSetCrescendo
Crescendo. Syntax
void SsSepSetCrescendo (sep_access_num, seq_num, vol, v_time) short sep_access_num;
short seq_num;
short vol;
long v_time;
Arguments
sep_access_num seq_num
vol
v_time
Explanation
SEP access number
SEQ number inside SEP data Volume value
Time (in tick units)
Raises the main volume of the seq_num-th SEQ data of SEP data possessing sep_access_num by vol within v_time. Setting a negative number for vol is the same as using SsSepSetDecrescendo.
Note that this function will have no effect if the volume of each voice is at the maximum.
Return value
None.
See also: SsSepSetDecrescendo (p. 687).
SsSepSetDecrescendo
Decrescendo. Syntax
void SsSepSetDecrescendo (sep_access_num, seq_n um, hort vol, v_time) short sep_access_num;
short seq_n um;
short vol;
long v_time;
Arguments
sep_access_num seq_num SEQ vol
v_time
Explanation
SEP access number number inside SEP data Volume value
Time (in tick units)
Lowers the main volume of the seq_num-th SEQ data of SEP data possessing sep_access_num by vol within v_time. Setting a negative number for vol is the same as using SsSepSetCrescendo.
Note that this function will have no effect if the volume of each voice is at the minimum.
Return value
None.
See also: SsSepSetCrescendo (p. 687).
SsSepSetRitardando
Slows the tempo. Syntax
void SsSepSetRitardando (sep_access_num, seq_n um, tempo, v_time)
short sep_access_num;
short seq_n um;
long tempo; long v_time;
Arguments
sep_access_num seq_num
tempo v_time
Explanation
SEQ access number
SEQ number inside SEP data Song tempo
Time (in tick units)
Slows the tempo of the seq_num-th SEQ data of SEP data possessing sep_access_num down to tempo within v_time.
However, if the specified tempo is larger (faster) than the current tempo, this function acts the same as SsSepSetAccelerando.
Return value
None.
See also: SsSepSetAccelerando (p. 686).
SsSepSetVol
SEP volume setting. Syntax
void SsSepSetVol (sep_access_num, seq_num, voll, volr)
short sep_access_num;
short seq_n um;
short voll; short volr;
Arguments
sep_access_n um seq_n um
voll volr
SEP access number
SEQ number inside SEP data L channel main volume value R channel main volume value
Explanation
Sets the L and R channels for the main volume of the seq_num-th SEQ data of SEP data possessing sep_access_num to specified values.
A value between 0 and 127 can be set.
Return value
None.
Extended Sound Library (libsnd) Functions 691
SsSepStop
Stops the reading of SEP data. Syntax
void SsSepStop (sep_access_num, seq_n um) short sep_access_num;
short seq_n um;
Arguments
sep_access_n um SEP access number
seq_n um SEQ number inside SEP data
Explanation
Terminates the reading (playing) of the seq_num-th SEQ data of SEP data possessing sep_access_num.
Return value None.
See also: SsSepPlay (p. 684).
Runtime Library Release 3.0
SsSeqCalledTbyT
It is called at each 1 Tick, interprets SEQ data and carries out playing. Syntax
void SsSeqCalledTbyT (void)
Arguments
None.
Explanation
At each Tick this function is called, interprets SEQ data and carries out playing. Tick is set by SsSetTickMode (), but this Tick merely regulates the internal sound system, without depending either on the speed or resolution appointed by SEQ data.
By designating SsSetTickMode, the sound system calls this function with the given resolution if the tick_mode is macro SS_TICK60 or SS_TIC K240. However, if SS_NOTICK is designated, this function must be called by the program with each 1/60 second duration (usually with the timing of vertical return interruption).
Return value
None.
See also: SsSetTickMode (p. 720).
Extended Sound Library (libsnd) Functions 693
SsSeqClose
Closes SEQ data. Syntax
void SsSeqClose (seq_access_n um) short seq_access_num;
Arguments
seq_access_n um SEQ access number Explanation
This function closes SEQ data with seq_access_num not needed.
See also: SsSeqOpen (p. 694).
Runtime Library Release 3.0
694 Extended Sound Library (libsnd) Functions
SsSeqOpen
Opens SEQ data. Syntax
short SsSeqOpen (*addr, vab_id) unsigned long *addr;
short va b_id;
Arguments
addr Start address of SEQ data in the main storage vab_id VAB id
Explanation
This function analyzes SEQ data in the main memory to return the SEQ access number.
Return value
SEQ access number, which is used in the Ss library, being the inner SEQ data control table number.
See also: SsSeqClose (p. 693).
Runtime Library Release 3.0
Extended Sound Library (libsnd) Functions 695
SsSeq Pause
Pauses SEQ data reading. Syntax
void SsSeq Pause (seq_access _n um) short seq_access_num;
Arguments
seq_access_n um SEQ access number Explanation
This function stops reading SEQ data with seq_access_num (performance).
Return value None.
See also: SsSeqReplay (p. 697).
Runtime Library Release 3.0
696 Extended Sound Library (libsnd) Functions
SsSeq Play
Reads SEQ data (Performance). Syntax
void SsSeq Play (seq_access_num, play_mode, l_count) short seq_access_num;
char play_mode;
short l_count
Arguments
seq_access_num SEQ access number
play_mode Performance mode
l_count Number of repeats of the music
Explanation
This function selects immediate SEQ data reading (performance) or a stop at the start of SEQ data (music piece). Also, designate repeat play of the music by l_count, and SSPLAY_INFINITY if play is unlimited. For play mode, the parameters below may be specified.
SSPLAY PAUSE Stop
SSPLAY PLAY Immediate performance
Return value
None.
See also: SsSeqPause (p. 695), SsStop (p. 704) SsSeqPlay (p. 696).
Runtime Library Release 3.0
Extended Sound Library (libsnd) Functions 697
SsSeq Replay
Resumes SEQ data reading (Replay) . Syntax
void SsSeq Replay (seq_access_n um) short seq_access_num;
Arguments
seq_access_n um SEQ access number Explanation
This function resumes reading SEQ data with seq_access_num stopped by SsPause
Return value None.
See also: SsSeqPause (p. 695).
Runtime Library Release 3.0
698 Extended Sound Library (libsnd) Functions
SsSeqSetAccelerando
Quickens tempo. Syntax
void SsSeqSetAccelerando (seq_access_num, tempo, v_time) short seq_access_num;
long tempo; long v_time;
Arguments
seq_access_num SEQ access number
tempo Quarter note resolution
v_time Time (in ticks)
Explanation
This function quickens the SEQ data with seq_access_num to the tempo resolution in v_time. With the specified resolution smaller than the current resolution, the function provides the same effect as SsSeqSetRitardando.
Return value None.
See also: SsSeqSetRitardando (p. 702).
Runtime Library Release 3.0
Extended Sound Library (libsnd) Functions 699
SsSeqSetCrescendo
Crescendo. Syntax
void SsSeqSetCrescendo (seq_access_num, vol, v_time)
short seq_access_num;
short vol;
long v_time;
Arguments
seq_access_num vol
v_time
Explanation
This function increases the main volume of SEQ data with seq_access_num by the vol value in v_time. Specifying a negative value for vol provides the same effect as SsSetDecrescendo. With the maximum voice volume, the function provides no effect.
Return value
None.
See also: SsSeqSetDecrescendo (p. 700).
700 Extended Sound Library (libsnd) Functions
SsSeqSetDecrescendo
Decrescendo. Syntax
void SsSeqSetDecrescendo (seq_access_num, vol, v_time) short seq_access_num;
short vol;
long v_time;
Arguments
seq_access_num vol
v_time
Explanation
Lowers only the vol value in v_time for the main volume of SEQ data with seq_access_num. By setting a minus value to vol, it has the same effect as SsSeqSetCrescendo.
Return value
None.
See also: SsSeqSetCrescendo (p. 699).
Extended Sound Library (libsnd) Functions 701
SsSeqSetNext
Specifies subsequent SEQ data. Syntax
void SsSeqSetDecrescendo (seq_access _n um1, seq_access_num2) short seq_access _n um1;
short seq_access_num2;
Arguments
seq_access_n um1 SEQ access number seq_access_n um2 SEQ access number
Explanation
This function specifies the SEQ access number (seq_access_num2) of SEQ data to be performed next to the SEQ data with seq_access_n um1.
Return value None.
Runtime Library Release 3.0
702 Extended Sound Library (libsnd) Functions
SsSeqSetRitardando
Slows tempo. Syntax
void SsSeqSetRitardando (seq_access_num, tempo, v_time) short seq_access_num;
long tempo; long v_time;
Arguments
seq_access_num SEQ access number
tempo Resolution of quarter note
v_time Time (in ticks)
Explanation
This function slows the SEQ data with seq_access _num to the tempo resolution in v_time. With the specified resolution larger (faster) than the current resolution, however, the function provides the same effect as SsSeqSetAccelerando.
Return value None.
See also: SsSeqSetAccelerando (p. 698).
Runtime Library Release 3.0
Extended Sound Library (libsnd) Functions 703
SsSeqSetVol
Sets SEQ volume. Syntax
void SsSeqSetVol (seq_access_num, voll, volr) short seq_access_num;
short voll; short volr;
Arguments
seq_access_n um SEQ access number
vol L channel's main volume value
volr R channel's main volume value
Explanation
This function sets the main volume of music with seq_access_num at values specified for the L and R channels. voll and volr range from 0 to 127.
Return value None.
Runtime Library Release 3.0
704 Extended Sound Library (libsnd) Functions
SsSeqStop
Terminates SEQ data reading. Syntax
void SsSeqStop (seq_access_num) short seq_access_num;
Arguments
seq_access_n um SEQ access number Explanation
This function terminates the reading of SEQ data with seq_access_num (performance).
Return value None.
Runtime Library Release 3.0
Extended Sound Library (libsnd) Functions 705
SsSetAuto KeyOffM ode
Sets the automatic KeyOff mode. Syntax
void SsSetAutoKeyOffMode (mode) short mode;
Arguments
mode 0 Automatically keys off.
mode 1 Does not key off until a KeyOff request comes in.
Explanation
Sets the automatic KeyOff mode. The default is the automatic
KeyOff mode. If the envelopes for the past 16 interrupts contain all 0's, the automatic KeyOff mode assumes that waveform playback has been automatically terminated, and uses the voice for other waveform playback.
Return value None.
Runtime Library Release 3.0
706 Extended Sound Library (libsnd) Functions
SsSetLoop
Sets a song repetition count. Syntax
void SsSetLoop (access_num, seq_num, I_count) short access_num;
short seq_n um;
short I_count;
Arguments
access_n um SEQ/SEP access number
seq_n um SEQ number inside SEP data
l_count Song repetition count
Explanation
Sets a song repetition count.
This function is useful for changing the song repetition count set in SsSeqPlay. After this function is called, the current song repetition count will be reset, and the song will be played for the number of times set by the new count.
When using this function for SEQ data, set 0 in seq_num; when using this function for SEP data, set the number that contains the SEQ to be played.
Return value None.
Runtime Library Release 3.0
Extended Sound Library (libsnd) Functions 707
SsSetMarkCallback
Register a function to be called when a mark is detected. Syntax
typedef void (*SsSeqMarkCallbackProc) (short, short, short) void SsSetM arkCall back (access_num, seq_num, proc) short access_num;
short seq_n um;
SsMarkCallbackProc proc;
Arguments
access_n um SEQ/SEP access number
seq_n um SEQ number inside SEP data
proc Callback function to be called when Mark is detected
Explanation
When a mark is detected inside a song possessing access_num, a Callback function will be called. During this operation, SEQ/SEP number will be handed over to the first argument; SEQ number inside SEP data will be handed over to the second argument; and the data2 value set in Mark will be handed over to the third argument. Set the second argument to 0 when using SEQ. The function clears the Callback function when NULL is given to proc.
Only one Callback function can be registered at a time.
Sample
/* Callback function-definition*/
SsMarkCallbackProc proc (short ac_no, short tr_no, short data);
:
/* Opens SEQ */
short seq_a_num = SsSeqOpen (addr, vab_id);
/* Sets Callback function */
SsSetMarkCallback (seq_a_num, 0, (SsMarkCallbackProc) proc);
Return value
None.
Runtime Library Release 3.0
708 Extended Sound Library (libsnd) Functions
SsSetMono
Set monaural mode. Syntax
void SsSetMono (void)
Arguments None.
Explanation
Sets the output to monaural mode.
Return value None.
See also: SsSetStereo (p. 71 7)
Runtime Library Release 3.0
Extended Sound Library (libsnd) Functions 709
SsSetM ute
Set a Mute. Syntax
void SsSetMute (mode) char mode;
Arguments
mode Setting mode Explanation
This function sets a mute. The values below may be specified for mode.
Macro Contents
SS_MUTE_ON Mute on
SS_MUTE_OFF Mute off
Return value None.
Runtime Library Release 3.0
710 Extended Sound Library (libsnd) Functions
SsSetM Vol
Set main volume value. Syntax
void SsSetMVol (voll, volr) short voll;
short volr;
Arguments
voll L channel's volume value
volr R channel's volume value
Explanation
This function sets the main volume values for voll and volr. The value ranges from 0 to 127.
Return value None.
See also: SsGetMVolL (p. 674).
Runtime Library Release 3.0
SsSetNoiseOff
Sets Noise off. Syntax
Extended Sound Library (libsnd) Functions 711
void SsSetNoiseOff (void)
Arguments None.
Explanation Makes Noise Off
Return value None.
See also: SsSetNoiseOn (p. 712).
Runtime Library Release 3.0
712 Extended Sound Library (libsnd) Functions
SsSetNoiseOn
Sets Noise on. Syntax
void SsSetNoiseOn (voll, volr) short voll;
short volr;
Arguments
voll L channel volume value
volr R channel volume value
Explanation
Makes Noise On with the given volume value. It sets the Noise Clock value with SsSetNck before making Noise On.
Return value None.
See also: SsSetNoiseOff (p. 711).
Runtime Library Release 3.0
SsSetReservedVoice
Declares the number of voices to be allocated by libsnd library.
Syntax
char SsSetReservedVoice (voices) char voices;
Arguments
voices Voice count Explanation
Declares the number of voices libsnd library will use for allocation. Other voices can be used in libspu by the user. (They must always be called in "all key off.")
Return value
Returns the set voice count if successful. Returns /-1 if unsuccessful.
714 Extended Sound Library (libsnd) Functions
SsSetRVol
Sets reverberant volume values. Syntax
void SsSetRVol (voll, volr) short voll;
short volr;
Arguments
voll L channel's volume value
volr R channel's volume value
Explanation
This function sets the reverberant volume values for voll and volr. The value ranges from 0 to 127.
Return value None.
See also: SsGetRVol (p. 675).
Runtime Library Release 3.0
SsSetSerialAttr
Sets the serial input line attribute. Syntax
void SsSetSerialAttr (s_n um, attr, mode) char s_num;
char attr;
char mode;
Arguments
s_num Serial input line number
attr Attribute value
mode Setting mode
Explanation
Sets the attribute relating to the serial input line. The values below may be specified for s_num, attr and mode.
(a) s_num
Macro Contents
SS_SERIAL_A Serial A (CD input)
SS_SERIAL_B Serial input line B (external digital input)
(b) attr
Macro Contents
SS_MIX Mixing
SC_REVERB Reverb
(c) mode
Macro Contents
SS_SON attr on
SS_SOFF attr OFF
Return value None.
See also: SsGetSerialAttr (p. 676).
SsSetSerialVol
Sets the value of the serial input line volume. Syntax
void SsSetSerialVol (s_num, voll, volr)
char s_num;
short voll; short volr;
Arguments
s_num Serial input line number
voll L channel's volume value
volr R channel's volume value
Explanation
Sets the value of the serial input line volume in voll, volr. The values below may be specified for s_n um.
Macro
Contents
SS_SERIAL_A
SS_SERIAL_B
Serial A (CD input)
Serial input line B (external
digital input)
Return value None.
See also: SsGetSerialVol (p. 676).
Extended Sound Library (libsnd) Functions 717
SsSetStereo
Sets stereo mode. Syntax
void SsSetStereo (void)
Arguments None.
Explanation
Sets the output to stereo mode. The sound system default output is stereo.
Return value None.
See also: SsSetMono (p. 708).
Runtime Library Release 3.0
SsSetTableSize
Specifies the area of a SEQ/SEP data attribute table. Syntax
void SsSetTableSize (table, s_max, t_max)
char *table; short s_max; short t_max;
Arguments
table SEQ/SEP data attribute table area
s_max Maximum frequency of opening SEQ/SEP data t_max Number of SEQ included in SEP
Explanation
The area of a SEQ/SEP data attribute table is set in the library. The library uses this area to analyze SEQ/SEP data, then saves it and plays it back.
s_max specifies the maximum number of times SEQ/SEP data may be opened. The upper limit is 32.
t_max specifies the number of SEQ included in the SEP data. Set t_max to 1 to handle only SEQ data and not use SEP data. The upper limit of t_max is 16.
In table, you must preserve the area by using global variables or functions like malloc() (auto variables cannot be used in a function).
Use the following to find the size from the library: (SS_SEQ_TABSIZE x s_max x t_max)
where the constant SS_SEQ_TABSIZE is declared in sndlib.h. Note that the value of this constant varies from version to version, so use the constant when saving the table area.
SsSetTableSize() is called immediately after SsInit(). Both functions are set to be called only once; what happens when multiple calls are made is unclear.
Return value None.
SsSetTempo
Set a tempo. Syntax
void SsSetTempo (access_num, seq_n um, tempo) short access_num;
short seq_n um;
short tempo;
Arguments
access_num SEQ/SEP access number
seq_n um SEQ number inside SEP data
tempo Song tempo
Explanation
Sets a tempo. This function is useful for changing the tempo set
After this function is called, the current tempo will be changed to specified for playing songs.
When using this function for SEQ data, set 0 in seq_num; when SEP data, set the number that contains the SEQ to be played.
in SsSeqPlay. the new tempo
using this function for
Return value None.
SsSetTickMode
Sets Tick.
Syntax
void SsSetTickMode (tick_mode) long tick_mode;
Arguments
tick_mode Tick mode Explanation
Sets the resolution of Tick. Call this function only once before calling SsSeqOpen() or SsSepOpen() for the first time. When it is called multiple times, correct operation cannot be guaranteed.
Tick Mode does not depend on the speed or resolution specified by SEQ/SEP data, and merely specifies the resolution inside the sound system.
tick_mode may be specified with the following values.
tick_mode Setting
SS_TICK60 Tick = 1/60 second
SsSeqCalledTbyT Automatic call SS_TICK1 20 Tick = 1/120 second
SsSeqCalledTbyT Automatic call SS_TICK240 Tick = 1/240 second
SsSeqCalledTbyT Automatic call SS_NOTICK Tick = 1/60 second
SsSeqCallTbyT No automatic call Any resolution Tick = 1/tick_mode seconds
SsSeqCalledTbyT Automatic call (Any resolution Tick = 1/tick_mode seconds
| SS_NOTICK) SsSeqCallTbyT No automatic call.
1. tick_mode = SS_TICK60
The timing of the vertical retrace lines (1/60 seconds) becomes 1 Tick, and the SEQ file will be played at this resolution.
2. tick_mode = SS_TICK120
1/120 seconds become 1 Tick, and the SEQ file will be played at this resolution. However, because RCntCNT2 will be used by the OS Root Counter Management Service at this resolution, it cannot be used by programs at this resolution.
3. tick_mode = SS_TICK240
1/240 seconds become 1 Tick, and the SEQ file will be played at this resolution. However, because the OS Root Counter Management Service, RCntCNT2, will be used by at this resolution, it cannot be used by programs at other resolutions.
4. tick_mode = SS_NOTICK Runtime Library Release 3.0
The timing of the vertical retrace lines (1/60 seconds) becomes 1 Tick, and the SEQ file will be played at this resolution. However, because SsSeqCalledTbyT () will not be automatically called, it must be called inside the user program at the timing of the vertical retrace lines.
5. tick_mode = Any resolution
By setting a value between 60 and 240 in the argument, 1 Tick can be set at (1/tick_mode), and the SEQ file will be played at this resolution.
In this case, the OS Root Counter Management Services RCntCNT1 or RCntCNT2 are used at this resolution. The value of tick_mode differs for each counter in the following fashion.
tick_mode Counter used Resoluton
tick_mode < 70 RCntCNT1 (1/tick_mode) seconds
tick_mode 70 RCntCNT2(1 /tick_mode) seconds
Note that depending on the specified value of tick_mode, RCntCNT1 or RCntCNT2 may not be used at the same resolution in programs.
6. tick_mode = (Any resolution | SS_NOTICK)
tick_mode may be specified either as any resolution, or as SS_NOTICK. When you specify the argument tick_mode as a value between 60 and 240, 1 Tick may be set at (1/tick_mode), and the SEQ file will be played at this resolution.
Or, if SS_NOTICK is specified as an argument, SsSeqCalledTbyT() will not be called automatically. Therefore, the user must call SsSeqCalledTbyT() at the timing specified by the program.
In this case, the OS Root Counter Management Services RCntCNT1 or RCntCNT2 are used at this resolution. The value of tick_mode differs for each counter in the following fashion.
tick_mode Counter used Resoluton
tick_mode < 70 RCntCNT1 (1/tick_mode) seconds
tick_mode 70 RCntCNT2(1 /tick_mode) seconds
Note that depending on the specified value of tick_mode, RCntCNT1 or RCntCNT2 may not be used at the same resolution in programs.
Return value None.
See also: SsStart (p. 722), SsSeqCalledTbyT (p. 692).
722 Extended Sound Library (libsnd) Functions
SsStart
Starts the sound system. Syntax
void SsStart (void)
Arguments None.
Explanation
Carries out the sound system start process.
When the mode is set to call SsSeqCalledTbyT () automatically by SsSetTickMode (), SsSeqCalledTbyT () is called in each Tick after calling this function.
Return value None.
See also: SsEnd ( p. 672), SsSetTickMode (p. 720), SsSeqCalledTbyT ( p. 692).
Runtime Library Release 3.0
Ss UtAllKeyOff
Keys off all voices. Syntax
Extended Sound Library (libsnd) Functions 723
void SsUtAllKeyOff (short mode) short mode;
Arguments
mode always 0 Explanation
Forcibly keys off all voices used by libsnd.
Return value None.
Runtime Library Release 3.0
SsUtAutoPan
(not currently supported) Automatically changes panning.
Syntax
short SsUtAutoPan (vc, start_pan, end_pan, delta_time) short vc;
short start_pan;
short end_pan;
short delta_time;
Arguments
vc
start_pan end_pan delta_time
Explanation
Voice number (0-23)
Panning change starting value (0-127) Panning change starting value (0-127)
Change starting time (in units of 1/60 sec, to a maximum of 180 Seconds) (0-10800)
Linearly changes the voice panning that was keyed on by SsUtKeyOn (), from start_pan to end_pan at delta_time (1/60 sec increments).
Return value
Returns 0 if successful. Returns -1 if unsuccessful.
SsUtAutoVol
(not currently supported) Automatically changes voice volume.
Syntax
short SsUtAutoVol (vc, start_vol, end_vol, delta_time) short vc;
short start _vol;
short end_vol;
short delta_time; ;
Arguments
vc
start_vol end_vol delta_time
Explanation
Voice number (0-23)
Volume change starting value (0-127) Volume change starting value (0-127)
Change starting time (in units of 1/60 sec, to a maximum of 180 Seconds) (0-10800)
Linearly changes the voice volume that was keyed on by SsUtKeyOn (), from start_vol to end_vol at delta_time (1/60 sec increments).
Return value
Returns 0 if successful. Returns -1 if unsuccessful.
SsUtChangeADSR
Changes ADSR. Syntax
short SsUtChangeADSR (vc, vabId, prog, old_note, adsr1, adsr2)
short vc;
short va bId;
short prog;
short old_note;
unsigned short adsr1; unsigned short adsr2;
Arguments
vc
vabId prog old_note adsr1 adsr2
Explanation
Voice number (0-23)
VAB number (0-3 1) from the return value of the function SsVabOpen() Program number (0-127)
Previous pitch specification in half-tone units (note number)(0-1 27) ADS R1
ADSR2
Changes the ADSR of the voice keyed on by SsUtKeyOn ().
Return value
Returns 0 if successful. Returns -1 if unsuccessful.
SsUtChangePitch
Changes the pitch. Syntax
short SsUtChangePitch (voice, vabId, prog, old_note, old_fine, new_note, new_fine) short voice;
short vabId;
short prog;
short old_note;
short old_fine;
short new_note;
short new_fine;
Arguments
voice
vabId
prog old_note old_fine new_note new_fine
Explanation
Voice number (0-23)
VAB number (0-3 1) from the return value of the function SsVabOpen() Program number (0-127)
Previous pitch specification in half-tone units (note number)(0-1 27) Previous fine pitch specification (1 00/1 27 sento?) (0-127)
New pitch specification in half-tone units (note number)(0-127) New fine pitch specification (100/127 sento?) (0-1 27)
Changes the pitch of the voice keyed on by SsUtKeyOn ().
Return value
Returns 0 if successful. Returns -1 if unsuccessful.
See also: SsUtPitch Bend
728 Extended Sound Library (libsnd) Functions
SsUtFlush
Executes KeyOn/KeyOff requests that have been queued. (Flushing) Syntax
void SsUtFlush (void)
Arguments None.
Explanation
Executes KeyOn/KeyOff requests that have been queued.
Normally, flushing is performed by an automatic interrupt of Sound Library (when the mode is set by SsSetTickMode to mode other than SS_NOTICK) or by a clear call of SsSeqCalledTbyT (when the mode is set by SsSetTickMode to SS_NOTICK).
However, if neither of these is used, use this function for flushing.
An interval of at least 1/441 00 sec must be inserted before calling this function.
Return value None.
Runtime Library Release 3.0
Extended Sound Library (libsnd) Functions 729
SsUtGetDetVVol
Obtains a detailed value of voice volume. Syntax
short SsUtGetDetVVol (vc, detvoll, detvolr) short vc;
short detvoll; short detvolr;
Arguments
vc Voice number (0-23)
detvoll Detailed volume, left (0-16383)
detvolr Detailed volume, right (0-16383)
Explanation
Returns the detailed value of the voice volume that was keyed on by SsUtKeyOn ().
Return value
Returns 0 if successful. Returns -1 if unsuccessful.
See also: SsUtSetDetVVol (p. 743).
Runtime Library Release 3.0
SsUtGetProgAtr
Gets a program attribute table.
Syntax
short SsUtGetProgAtr (vabId, pro gNum, pro gatrptr) short va bId;
short progNum;
ProgAtr pro gatrptr;
Arguments
vabId VAB number (0-3 1) from the return value of the function SsVabOpen()
pro gNum Program number (0-127)
pro gatrptr Pointer to program attribute table
Explanation
Specifies a VAB number and a program number, and returns the VAB attribute header to progatrptr.
Return value
Returns 0 if successful. Returns -1 if unsuccessful.
See also: SsUtSetProgAtr (p. 744).
SsUtGetReverbType
Obtains a reverb type.
Syntax
short SsUtGetReverbType (void)
Arguments None.
Explanation
Obtains the current reverb type value.
Return value
Current reverb type value.
See also: SsUtSetReverbType (p. 731).
SsUtGetVabHdr
Returns VAB attribute header. Syntax
short SsUtGetVabHdr (vabId, *vabhdrptr) short va bId;
VabHdr *vabhdrptr;
Arguments
vabId VAB number (0-3 1) from the return value of the function SsVabOpen()
vabhdrptr Pointer to VAB attribute header
Explanation
Specifies the VAB number (the return value of SsVabOpen ()) and returns the VAB attribute header to vabhdrptr.
Return value
Returns 0 if successful. Returns -1 if unsuccessful.
See also: SsUtSetVabHdr (749).
SsUtGetVagAtr
Returns a tone attribute table (VagAtr). Syntax
short SsUtGetVagAtr (vabId, pro gNum, toneNum, *vagatrptr) short va bId;
short progNum;
short toneNum;
VagAtr *vagatrptr;
Arguments
vabId
pro gNum toneNum vagatrptr
Explanation
VAB number (0-3 1) from the return value of the function SsVabOpen() Program number (0-127)
Tone number (0-15)
ADS R1
Specifies a VAB number, a program number, and a tone number, and returns a tone attribute table to vagatrptr.
Return value
Returns 0 if successful. Returns -1 if unsuccessful.
See also: SsUtSetVagAtr (p. 750).
SsUtGetVBaddrInSB
Returns the address inside the sound buffer to which VAB data specified by VAB id has been transferred.
Syntax
unsigned long SsUtGetVBaddrInSB (vabid) short va bid;
Arguments vabid VAB id
Explanation
Executes a queueing key-on/key-off request. Usually, flushing is performed with sound driver automatic interrupts (when SsSetTickMode() is set to other than SS_NOTICK), or calls the specific function SsSeqCalledTbyT() (when SsSetTickMode() is set to SS_NOTICK), but in cases when neither case above applies, use this function, SsUtGetVBaddrInSB(), to perform flushing.
This function calls and empties an interval more than 1/441 00 sec.
Return value
Address inside the sound buffer. Returns -1 if unsuccessful.
SsUtGetVVol
Obtains voice volume. Syntax
short SsUtGetVVol (vc, voll, volr)
short vc; short voll; short volr;
Arguments
vc Voice number (0-23)
voll Volume, left (0-127)
volr Volume, right (0-127)
Explanation
Returns a detailed voice volume value that was keyed on by SsUtKeyOn ().
Return value
Returns 0 if successful. Returns -1 if unsuccessful.
See also: SsUtSetVVol (p. 751).
SsUtKeyOff
Keys off voice. Syntax
short SsUtKeyOff (voice, vabId, prog, tone, note)
short voice; short vabId; short prog; short tone; short note;
Arguments
voice vabId prog tone note
Voice number (0-23) access number VAB number (0-31) from the return value Program number (0-127)
Tone number (0-15)
Pitch specification in half-tone units (note
of the function SsVabOpen()
number) (0-127)
Explanation
Keys off the voice that was keyed on by SsUtKeyOn ().
Return value
Returns 0 if successful. Returns -1 if unsuccessful.
Return value
See also: SsUtKeyOn (p. 738).
SsUtKeyOffV
Keys off the voice specified by the voice number. Syntax
short SsUtKeyOffV (voice) short voice;
Arguments
voice Voice number (0-23)
Explanation
Keys off the voice specified by the voice number (0~23).
Return value
Returns 0 if successful. Returns -1 if unsuccessful.
See also: SsUtKeyOnV (p. 739).
SsUtKeyOn
Keys on voice. Syntax
short SsUtKeyOn (vabId, prog, tone, ote, fine, voll, volr) short va bId;
short prog; short tone; short ote; short fine; short voll; short volr;
Arguments
VAB number (0-31) from the return value of the function SsVabOpen() Program number (0-127)
Tone number (0-15)
Pitch specification in half-tone units (note number) (0-127)
Detailed pitch specification (1 00/1 27 sento?) (0-127)
Volume, left (0-127)
Volume, right (0-127)
Explanation
Keys on the voice specified by the VAB number of SE, the program number (0~127), and the tone number (0~15), and returns the allocated voice number.
Return value
Returns the voice number (0~23) used for KeyOn. Returns -1 if unsuccessful.
See also: SsUtKeyOff (p. 736).
SsUtKeyOnV
Keys on the voice specified by voice number. Syntax
short SsUtKeyOnV (voice, vabId, prog, tone, note, fine, voll, volr)
short voice; short vabId; short prog; short tone; short note; short fine;
short voll; short volr;
Arguments
Voice number (0-23)
VAB number (0-31) from the return value of the function SsVabOpen() Program number (0-127)
Tone number (0-15)
Pitch specification in half-tone units (note number) (0-127)
Detailed pitch specification (1 00/1 27 sento?) (0-127)
Volume, left (0-127) Volume, right (0-127)
Explanation
Keys on the voice specified by the voice number (0~23), the VAB number of SE, the program number (0~127), and the tone number (0~15), and returns the allocated voice number.
Return value
Returns the voice number (0~23) used for KeyOn. Returns -1 if unsuccessful.
See also: SsUtKeyOffV (p. 737).
SsUtPitchBend
Applies a pitch bend. Syntax
short SsUtPitchBend (voice, vabId, prog, note, pbend) short voice;
short vabId; short prog; short note; short pbend;
Arguments
Voice number (0-23)
VAB number (0-31) from the return value of the function SsVabOpen() Program number (0-127)
Pitch specification in half-tone units (note number) (0-127)
Pitch-bend value (0-127)
Explanation
Applies a pitch bend (0~127, 64:center) to the voice keyed on by SsUtKeyOn ().
Return value
Returns 0 if successful. Returns -1 if unsuccessful.
See also: SsUtChangePitch (p. 727).
SsUtReverbOff
Turns off Reverb. Syntax
Extended Sound Library (libsnd) Functions 741
void SsUtReverbOff (void)
Arguments None.
Explanation
Turns off Reverb.
Return value None.
See also: SsUtReverbOn (p. 742).
Runtime Library Release 3.0
742 Extended Sound Library (libsnd) Functions
SsUtReverbOn
Turns on Reverb. Syntax
void SsUtReverbOn (void)
Arguments None.
Explanation Turns on Reverb at the specified Type and Depth.
Return value None.
See also: SsUtReverbOff (p. 741).
Runtime Library Release 3.0
Extended Sound Library (libsnd) Functions 743
SsUtSetDetVVol
Sets a detailed value of voice volume. Syntax
short SsUtSetDetVVol (vc, detvoll, detvolr) short vc;
short detvoll; short detvolr;
Arguments
vc Voice number (0-23)
detvoll Detailed volume, left (0-16383)
detvolr Detailed volume, right (0-16383)
Explanation
Sets the detailed value of voice volume that was keyed on by SsUtKeyOn ().
Return value
Returns 0 if successful. Returns -1 if unsuccessful.
See also: SsUtGetDetVVol (p. 729).
Runtime Library Release 3.0
744 Extended Sound Library (libsnd) Functions
SsUtSetProgAtr
Sets a program attribute table. Syntax
short SsUtSetProgAtr (vabId, pro gNum, Pro gAtr pro gatrptr) short va bId;
short progNum;
ProgAtr pro gatrptr;
Arguments
vabId VAB number (0-3 1) from the return value of the function SsVabOpen()
pro gNum Program number (0-127)
pro gatrptr Pointer to program attribute table
Explanation
Specifies a VAB number and a program number, and changes the VAB attribute header, progatrptr.
Return value
Returns 0 if successful. Returns -1 if unsuccessful.
See also: SsUtGetProgAtr (p. 730).
Runtime Library Release 3.0
Extended Sound Library (libsnd) Functions 745
SsUtSetReverbDelay
Sets a Delay volume. Syntax
void SsUtSetReverbDelay (delay) short delay;
Arguments delay
Explanation delay 0 ~ 127
Sets a delay volume for using the Echo and Delay type reverb.
Return value None.
Runtime Library Release 3.0
746 Extended Sound Library (libsnd) Functions
SsUtSetReverbDepth
Sets a reverb depth. Syntax
void SsUtSetReverbDepth (ldepth, rdepth) short ldepth;
short rdepth
Arguments
ldepth Left depth (0-127)
rdepth RIght depth (0-127)
Explanation
ldepth 0 ~ 127
rdepth 0 ~ 127
Sets a reverb depth.
Return value None.
Runtime Library Release 3.0
SsUtSetReverbFeedback
Sets a feedback volume. Syntax
Extended Sound Library (libsnd) Functions 747
void SsUtSetReverbFeedback (feedback) short feedback;
Arguments
feedback Feedback (0-127)
Explanation feedback 0 ~ 127
Sets a feedback volume for using the Echo reverb.
Return value None.
Runtime Library Release 3.0
SsUtSetReverbType
Sets reverb type. Syntax
short SsUtSetReverbType (type) short type;
Arguments
type Reverb type
Explanation
Sets reverb type. Type may be set as follows.
type mode Delay time Feedback
SPU_REV_TYPE_OFF off X
SPU_REV_TYPE_ROOM room X
X
X
X
X
X
X
O
O
X
X
X
X
X
SPU_REV_TYPE_STUDIO_A studio (small)
SPU_REV_TYPE_STUDIO_B studio (med)
SPU_REV_TYPE_STUDIO_C studio (big)
SPU_REV_TYPE_HALL hall
X
X
O
O
X
SPU_REV_TYPE_SPACE space echo
SPU_REV_TYPE_ECHO
echo
SPU_REV_TYPE_DELAY delay
SPU_REV_TYPE_PIPE
pipe echo
Table: Reverb Type Overview (See Sound Delicatessen DSP)
When a reverb type is set, reverb depth is automatically set to 0. Because noise will occur as soon as depth is set if data remains in the reverb work area, follow the procedure below.
SsUtSetReverbType (SS_REV...); SsUtReverbOn();
Wait for several seconds.
SsUtSetReverbDepth (64, 64);
Return value
If setting was correctly performed, the Type number that was set is returned. If setting was not correctly performed, -1 is returned.
See also: SsUtGetReverbType (p. 731).
SsUtSetVabHdr
Sets a VAB attribute header. Syntax
short SsUtSetVabHdr (vabId, *vabhdrptr) short va bId;
VabHdr *vabhdrptr;
Arguments
vabId VAB number (0-3 1) from the return value of the function SsVabOpen()
vabhdrptr Pointer to VAB attribute header
Explanation
Specifies the VAB number (the return value of SsVabOpen ()) and changes the VAB attribute header, vabhdrptr.
Return value
Returns 0 if successful. Returns -1 if unsuccessful.
See also: SsUtGetVabHdr (p. 749).
SsUtSetVagAtr
Sets a tone attribute table (VagAtr). Syntax
short SsUtSetVagAtr (vabId, pro gNum, toneNum, *vagatrptr) short va bId;
short progNum;
short toneNum;
VagAtr *vagatrptr;
Arguments
vabId
pro gNum toneNum vagatrptr
Explanation
VAB number (0-3 1) from the return value of the function SsVabOpen() Program number (0-127)
Tone number (0-15)
Pointer to tone attribute table
Specifies a VAB number, a program number, and a tone number, and changes a tone attribute table, vagatrptr.
Change allowed: Items in VagAtr that are not listed below.
Change not allowed: prog, vag, reserved1, reserved2, reserved[0~3]
Return value
Returns 0 if successful. Returns -1 if unsuccessful.
See also: SsUtGetVagAtr (p. 733).
Ss UtSet VVo l
Sets voice volume. Syntax
short SsUtSetVVol (short vc, short voll, short volr)
short vc; short voll; short volr;
Arguments
vc Voice number (0-23)
voll Volume, left (0-127)
volr Volume, right (0-127)
Explanation
Sets the detail of the voice volume that was keyed on by SsUtKeyOn ().
Return value
Returns 0 if successful. Returns -1 if unsuccessful.
See also: SsUtGetVVol (p. 735).
752 Extended Sound Library (libsnd) Functions
SsVabClose
Closes VAB data file. Syntax
void SsVabClose (vab_id) short va b_id;
Arguments
vab_id VAB data id Explanation
This function closes the VAB data file with i or id.
Return value None.
See also: SsVabOpen (p. 755).
Runtime Library Release 3.0
SsVabFakeBody
Sets up a library using the sound source data in the sound buffer as the given VAB ID. This function does not perform any transfer.
Syntax
short SsVabFakeBody (vabid) short va bid;
Arguments vabid VAB id
Explanation
Uses SsVabFakeHead to recognize a header list, and sets up a library using the sound source data in the sound buffer as the given VAB ID.
Although this function does perform VAB ID verification, it does not perform the actual transfer. Instead, it sets the internal state of the library to "Transferred to SPU."
It is not necessary to use SsVabTransCompleted after calling this function.
Return value
VAB Identifying number Returns -1 if unsuccessful.
See also: SsVabFakeHead (p. 754), SsVabOpenHeadSticky (p. 757), SsVabTransBody (p. 758), SsVabTransBodyPartly (p. 759).
SsVabFakeHead
Recognizes a sound source header list. (re-recognition). Syntax
short SsVabFakeHead (*addr, vabid, sbaddr) unsigned char *addr;
short va bid;
unsigned long sbaddr;
Arguments
addr VH leading address
vabid Desired VAB ID. If "-1", the library will make the allocation.
sbaddr Address inside the sound buffer, to which VB is being transferred.
Explanation
Recognizes the sound source header in the main memory, and sets the previously read VH data in the state that can be used by the library again.
Specify a VAB ID for opening. When VAB ID is -1, the function searches for an empty VAB ID (0 ~ 16) and allocates.
The user must specify the leading address in sbaddr for the area inside the sound buffer to which VB is being transferred.
Return value
VAB Identifying number. Returns -1 if unsuccessful.
See also: SsVabFakeBody (p. 753), SsUtGetVBaddrInSB (p. 734), SsVabOpenHead (p. 756), SsVabOpenHeadSticky (p. 757).
SsVabOpen
Opens VAB data. Syntax
short SsVabOpen (addr, *vab_head) unsigned char *addr;
VabHdr *vab_head;
Arguments
addr Start address of VAB data in main storage
vab_head Address to VAB header structure corresponding to VAB id
Explanation
It analyses the VAB data header which is in the main memory, stores the header value in vab_head, and returns the VAB id that identifies the VAB given as the function's Return value. At the same time, it transmits to the SPU local memory the VAG data group (wave form) data contained in VAB.
Return value
It is the VAB id which identifies the given VAB. It is -1 in the event of failure.
See also: SsVabClose (p. 752).
SsVabOpen Head
Recognizes a sound source header list. Syntax
short SsVabOpen Head (*addr, vabid) unsigned char *addr;
short vabid
Arguments
addr VAB data leading address vabid VAB ID
Explanation
Recognizes a sound source header list in the main memory.
Sets the table in the main memory in the state that is usable by Sound Library. Specify a VAB ID for opening. When VAB ID is -1, the function searches for an empty VAB ID (0 ~ 16) and allocates.
Return value
VAB identification number. Returns -1 if unsuccessful.
See also: SsVabTransBody (p. 758), SsVabTransBodyPartly (p. 759).
SsVabOpenHeadSticky
Recognizes a sound source header list. (.VB transfer address specification). Syntax
short SsVabOpen HeadSticky (*addr, vabid, sbaddr) unsigned char *addr;
short va bid;
unsigned long sbaddr;
Arguments
addr
vabid
sbaddr
Explanation
Leading address of VAB data in the main memory
Desired VAB ID or -1
Leading address inside the sound buffer to be usedwhen transferring VabBody (.VB) to the sound buffer
Recognizes a sound source header list in the main memory.
Sets the table in the main memory in the state that is usable by Sound Library. Specify a VAB ID for opening. When VAB ID is -1, the function searches for an empty VAB ID (0 ~ 16) and allocates.
Specify for sbaddr the leading address inside the sound buffer for transferring VabBody (.VB) to the sound buffer, within the range of 0x1 000 to 0x7ffff. When doing so, take .VB size into consideration and specify the address so that the it will not be transferred into the reverb work area.
SsVabTransBody/SsVabTransBodyPartly that is called later transfers VabBody from sbaddr.
When using this function, because consistency cannot be maintained for the sound buffer memory management, SsVabOpenHead will not be able to be used when opening other VAB (.VH). Use this function to open all .VH.
Return value
VAB identifying number. Returns -1 if unsuccessful.
See also: SsVabOpenHead (p. 756), SsVabTransBody (p. 758), SsVabTransBodyPartly (p. 759).
SsVabTransBody
Transfers sound source data. Syntax
short SsVabTransBody (*addr, vabid) unsigned char *addr;
short va bid;
Arguments
addr VAB data leading address
vabid VAB ID
Explanation
SsVabOpen Head is used for recognizing a header list, and starts the transfer of the sound source data (VAB body) in the main memory to the SPU local memory.
Return value
VAB identifying number Returns -1 if unsuccessful.
See also: SsVabOpen Head (756), SsVabTransBodyPartly (759).
SsVabTransBodyPartly
Transfers sound source data in segments. Syntax
short SsVabTransBodyPartly (addr, bufsize, vabid) unsigned char *addr;
unsigned long bufsize;
short va bid;
Arguments
addr Starting address of the segment transfer buffer
bufsize Buffer size
vabid VAB ID
Explanation
Starts transfer to the SPU sound buffer of main memory sound source data (VAB body) whose data header list is recognized using SsVabOpenHead().
By continuously calling SsVabTransBodyPartly() while sequentially copying part of the sound source (VAB body) into the area possessing a bufsize indicated by addr, transfers may be made to a contiguous area within the sound buffer using only a limited area in main memory.
In order to ensure continuity of transfer, you must use SsVabTransCompleted() to verify whether each transfer has been completed, after SsVabTransBodyPartly() has been called.
Return value
Transfer results return the following values.
Return value Status
-2
The size of the sound source data
(VAB body) inherited from
SsVabOpenHead() has not been
completely transferred
-1
Transfer failed
vabid Transfer successful
See also: SsVabOpenHead (p. 756), SsVabTransBody (p. 758).
SsVabTransCompleted
Gets VAB data transfer state. Syntax
short SsVabTransCompleted (immediateFlag) short mmediateFlag;
Arguments
immediateFlag transfer status recognition flag
Explanation
Returns an indication of whether SsVabOpen() data transfer to SPU local memory terminated.
immediateFlag may be specified with the following values. immediateFlag Action
SS_I MM ED IATE Immediately returns transfer state
SS_WAIT_COMPLETED Loops until transfer is completed
Return value
Returns "1" if the transfer has been completed. Returns "0" if the transfer is ongoing.
See also: SsVabOpen (p. 755).
Extended Sound Library (libsnd) Functions 761
SsVo KeyOff
Key off. Syntax
void SsVoKeyOff (vab_pro, pitch) long vab_pro;
long pitch;
Arguments
vab_pro VAB data id, program number
pitch Pitch
Explanation
Of the lower 16 bits of vab_pro, the upper 8 bits are used for vab_id, and the lower 8 bits specify a program number. Of the lower 16 bits of pitch, the upper 8 bits specify a key number in MIDI standard. To specify a finer pitch, specify a key number in the lower 8 bits of pitch in 1/128 semitone units. This sound specified by vab_pro and pitch is keyed off at the specified voll and volr.
Return value None.
Runtime Library Release 3.0
SsVo KeyO n
Key on. Syntax
void SsVoKeyOn (long vab_pro, long pitch, unsigned short voll, unsigned short volr) long vab_pro;
long pitch;
unsigned short voll;
unsigned short volr;
Arguments
vab_pro
pitch volL volR
Explanation
VAB data id, program number
Pitch
Channel volume Channel volume
Of the lower 16 bits of vab_pro, the upper 8 bits are used forvab_id, and the lower 8 bits specify a program number. Of thelower 16 bits of pitch, the upper 8 bits specify a key number in MIDI standard. To specify a finer pitch, specify a key number in the lower 8 bits of pitch in 1/128 semitone units. This sound specified by vab_pro and pitch is keyed off at the specified voll and volr.
Return value
None.
See also: SsVoKeyOff (p. 761).
Chapter 10
Data Processing Library (libpress)
This chapter describes structures defined in the data processing library (libpress) and their common functions. The data processing library is for compressing (encoding) and uncompressing (decoding) drawing and sound data.
Chapter 10: Data Processing Library (libpress) Table of Contents
Functions
DecDCTBufSize
767
DecDCTin
768
DecDCTinCallback
769
DecDCTinSync
770
DecDCTout
771
DecDCToutCallBack
772
DecDCToutSync
773
Dec DCTR eset
774
Dec DCTvlc
775
DecDCTBufSize
Obtains the size of runlevel. Syntax
long DecDCTBufSize (bs) unsigned long *bs;
Arguments
bs Bitstream
Explanation
This function decodes the input bitstream ds and returns the size of the runlevel generated as intermediate format.
DecDCTBufSize() does not perform actual decoding.
Return value
Size of run level (long words).
768 Data Processing Library (libpress) Functions
DecDCTin
Transmits runlevel to the image processing subsystem. Syntax
void DecDCTin (runlevel, mode) unsigned long *runlevel;
long mode;
Arguments
runlevel Input runlevel mode Decode mode
Explanation
Decodes runlevel (starting with the address of runlevel) to a direct color image. The result of decoding is retrieved by DecDCTout().
Decode mode is specified by mode. The specification is in bits and is as follows.
The depth of the output pixels is specified by bit 0; either 24-bit or 16-bit can be selected. If it is 16-bit mode, bit 15 of the pixel (STP bit), can be specified by mode bit 1.
Return value
None. Remarks
Width and height information of the image resulting from decoding by DecDCTin() is not maintained by runlevel or bitstream. These parameters are defined by higher hierarchical data formats (such as STR format).
To prevent transmission and reception deadlocks, size data corresponding to the transmitted runlevel must be received through DecDCTout().
Data transmitted by one DecDCTin() call may be read out by multiple DecDCTout() calls and vice versa.
As DecDCTin() is a non-blocking function, termination of actual transmission needs to be detected by DecDCTinSync(). If the next DecDCTin() is executed without waiting for the previous DecDCTin() to be terminated, the second transmission is blocked until the first transmission is terminated.
DecDCTinCallback
Sets callback function at termination of transmission. Syntax
long DecDCTinCallback (func) void (*func)();
Arguments
func Callback function address
Explanation
It sets the callback function when transmission is terminated.
If callback is set, the function func is called at transmission termination. A callback is not generated if func is specified as 0.
Return value
A pointer to a previously set callback function. Remarks
Subsequent transmission termination interrupts are masked within func. Accordinly, func must return promptly after the required processing is terminated.
770 Data Processing Library (libpress) Functions
DecDCTinSync
Detects DecDCTin() termination. Syntax
long DecDCTinSync (mode) long mode;
Arguments mode Mode
Explanation
Detects termination of DecDCTin(). Mode values are as follows.
Value Description
0 blocks until termination
1 performs only status notification
Return value
Image processing subsystem status. 1 is returned if transmission is in process and 0 if transmission is not being performed.
Runtime Library Release 3.0
DecDCTout
Receives decoded data from the image processing subsystem. Syntax
void DecDCTout (cel, size) unsigned long *cell;
long size;
Arguments
cel Decoded image data
size Received data size (long word)
Explanation
Runlevel is decoded and the size of a word is stored in the area that starts with the address of cel. The format of decoded data depends on the DecDCTin() decode mode parameter; it is either 24-bit or 16-bit.
Specify a size value that is the same as or smaller than the size of all the decoded data. If a value smaller than the total decoded data is specified, the remaining data must be read out by DecDCTout() in order to prevent transmission and reception deadlocks.
The decoded image is output by macro block units (16x16 rectangular area). Data size must be specified in macro block sizes (if 16-bit mode, 1 6x1 6x2 = 51 2byte = 128 word; if 24-bit mode, 16x16x3 = 768 byte = 192 word).
Return value None.
Remarks
As DecDCTout() is a non-blocking function, termination of actual transmission needs to be detected by DecDCToutSync(). If the next DecDCTout() is executed without waiting for the previous DecDCTout() to be terminated, the second transmission is blocked until the first transmission is terminated.
Dec DCToutCallBack
Sets a callback function at termination of reception. Syntax
long DecDCToutCallback (func) long (*func)();
Arguments
func Callback function address
Explanation
Sets the callback function when reception is terminated.
If callback is set, the function func is called at reception termination. A callback is not generated if func is specified as 0.
Return value
A pointer to a previously set callback function. Remarks
Subsequent reception termination interrupts are masked within func. Accordinly, func must return promptly after the required processing is terminated.
Data Processing Library (libpress) Functions 773
DecDCToutSync
Detects termination of DecDCTout(). Syntax
long DecDCToutSync (mode) long mode;
Arguments mode Mode
Explanation
Detects termination of DecDCTout(). Mode values are as follows.
Value Description
0 blocks until termination
1 performs only status notification
Return value
Image processing subsystem status. 1 is returned if reception is in progress and 0 if reception is not being performed.
Runtime Library Release 3.0
DecDCTReset
Initializes image processing subsystem. Syntax
void DecDCTReset (mode) long mode;
Arguments
mode Reset mode Explanation
This function resets the image processing subsystem. Values that can be specified for mode are as follows.
Value Content
0 initializes all internal states
1 discontinues only current decoding; does not affect internal states
Return value None.
Remarks
Processing time is longer for mode0 than for mode1 because internal tables are initialized,
Data Processing Library (libpress) Functions 775
DecDCTvlc
Decodes VLC. Syntax
void DecDCTvlc (bs, runlevel) unsigned long *bs;
unsigned long *runlevel;
Arguments
bs Input bitstream runlevel Output runlevel
Explanation
Decodes bitstream bs, and creates medium format runlevel that begins with the address of runlevel. After decoding, the size of runlevel can be obtained with DecDCTBufSize()
Return value None.
Remarks
This is a blocking function.
The bitstream must always be transformed to runlevel by DecDCTvlc() before DecDCTIn() is executed.
Chapter 11
Memory Card Library (libcard)
This chapter describes the functions collected in the memory card library (libcard). It enables smooth access to the memory card, data reading and writing, and retrieval of memory card BIOS.
Chapter 11: Memory Card Library (libcard) Table of Contents
Functions
InitCARD
781
StartCARD
782
StopCARD
783
_bu_init
784
_card_auto
785
_card_chan
786
_card_clear
787
_card_info
788
_card_load
789
_card_read
790
_card_status
791
_card_wait
792
_card_write
793
_new_card
794
Memory Card Library (libcard) Functions 781
InitCARD
Initializes memory card BIOS Syntax
void InitCARD(val) long val;
Arguments
val Indicates sharing with controller 0: Not shared
1: Shared
Explanation
Initializes the memory card BIOS, and then enters a stop state. At this time, you can specify in val whether or not there is sharing with the controller.
When the BIOS is subsequently put into operation by StartCARD(), the low-level interface function that starts _card can be used directly.
The memory card file system uses these interfaces internally, so InitCARD needs to be executed before _bu_init().
There is no effect on the controller.
Return value
None.
See also: bu_init (p. 784).
StartCARD
Starts memory card BIOS.
Syntax
void StartCARD(void)
Arguments None.
Explanation Changes the memory card BIOS initialized by InitCARD() to a run state. Performs ChangeClearPAD(1) with internals.
Return value
None.
See also: InitCARD (p. 781), StopCARD (p. 783), _bu_init (p. 784), ChangeClearPAD (see Ch 2).
Memory Card Library (libcard) Functions 783
StopCARD
Stops memory card BIOS. Syntax
void StopCARD(void)
Arguments None.
Explanation
Changes memory card BIOS to a stop state (the same state as that immediately after executing InitCARD())
Performs ChangeClearPAD(1) with internals.
Return value None.
See also: InitCARD (p. 781), StartCARD (p. 782), _bu_init (p. 784), ChangeClearPAD (see Ch 2).
Runtime Library Release 3.0
_bu_init
Initializes memory card file system.
Syntax
void _bu_init(void)
Arguments None.
Explanation
Initializes the memory card file system.
When the file system driver is included in a patch module, it is registered in the kernel. The initialization routine does not execute automatically, so this function is required to explicitly initialize the file system.
Return value
None.
See also: InitCARD (p. 781), StartCARD (p. 782), StopCARD (p. 783).
_card_auto
Sets automatic format function. Syntax
long _card_auto(val) long val;
Arguments
val Indicates automatic formatting 0: Disable
1:Enable
Explanation
Sets automatic format function.
When 0 is specified in val, it is disabled; when 1 is set, it is enabled. Return value
None. Remarks
This function is used for testing purposes.
_card_chan
Gets a memory card BIOS event.
Syntax
long _card_chan(void)
Arguments None.
Explanation
Returns the device number of the memory card that just generated an event.
Without regard to whether or not it is open or test, some kind of event is generated and its return value is modified if any kind of event was generated. (Usually, these events are generated in channels without a card, during the VBLANK interval after the BIOS is started.)
Return value
2-digit hex device number
See also: card_status (p. 791), _card_wait (p. 792).
_card_clear
Clears unconfirmed flags. Syntax
long _card_clear(chan) long chan;
Arguments
chan Port number x 16 + Card number
Explanation
Performs a dummy write to the system management area of the card and clears unconfirmed flags specified in the card.
Specifies Port number x 16 + Card number in chan. Port A is 0, and Port B is 1. The card number is normally 0.
This function executes asynchronously, so it terminates immediately. Multiplex processing to the same card slot is not performed. Actual processing termination is communicated by an event. (See table below.)
Source Descriptor/Event Class Description
SwCARD/EvSpIOE Ends process
SwCARD/EvSpTIMOUT Not connected
SwCARD/EvSpERROR Error generation
Table: Posts an event on completion of processing
Return value
1 if successful processing registration, otherwise 0.
See also: card_info (p. 788).
_card_info
Gets card status. Syntax
long _card_info(chan) long chan;
Arguments
chan Port number x 16 + Card number
Explanation
Tests the connection of the memory card specified in chan.
Specifies Port number x 16 + Card number in chan. Port A is 0, and card number is normally 0.
This function executes asynchronously, so it terminates immediately. processing to the same card slot is not performed. Actual processing communicated by an event. (See table below.)
Port B is 1. The
Multiplex termination is
Source Descriptor / Event Class Description
SwCARD/EvSpIOE Connected
SwCARD/EvSpTIMOUT Not connected
SwCARD/EvSpNEW No writing after connection
SwCARD/EvSpERROR Generates an error
Table: Posts an event on completion of processing
Return value
1 if successful processing registration, otherwise 0. Remarks
Do not use _new_card() to suppress EvSpNEW.
See also: _card_clear (p. 787), _new_card (p. 794).
_card_load
Tests logical format Syntax
long _card_load(chan) long chan;
Arguments
chan Port number x 16 + Card number Explanation
Reads file management information for the card specified by chan in the file system in order to get asynchronous access using the I/O management service.
Specifies Port number x 16 + Card number in chan. Port A is 0, and Port B is 1. The card number is normally 0.
In _card_load, before you can use open() on a memory card file in O_NOWAIT mode, it must be called at least once first. The function does not have to be reissued unless a card is changedThis function executes asynchronously, so it terminates immediately. Multiplex processing to the same card slot is not performed. Actual processing termination is communicated by an event. (See table below.)
Source Descriptor / Event Class Contents
SwCARD/EvSpIOE Read completed
SwCARD/EvSpTIMOUT Not connected
SwCARD/EvSpNEW Uninitialized card
SwCARD/EvSpERROR Generates an error
Table: Posts an event on completion of processing
Return value
1 if successful completion, otherwise 0.
See also: format (see Ch 2), card_info (p. 788).
_ca rd_read
Reads one block from the memory card. Syntax
long _card_read(chan, block, buf)
long chan; long block; long *buf;
Arguments
chan Port number x 16 + card number block Target block number
buf Pointer to 128 byte data buffer
Explanation
Reads 128 bytes of buffer data into buf from the target block number (block) of the memory card of the specified channel (chan).
Specifies Port number x 16 + Card number in chan. Port A is 0, and Port B is 1. The card number is normally 0.
This function executes asynchronously so it terminates immediately after completion. Multiplex processing to the same card slot is not performed. Actual processing termination is communicated by an event. (See table below.)
Source Descriptor / Event Class Contents
HwCARD/EvSpIOE HwCARD/EvSpTIMOUT HwCARD/EvSpNEW HwCARD/EvSpERROR HwCARD/EvSpUN KOWN
Ends processing Card not connected New card detected Error generated
Source unknown
Table: Posts an event on completion of processing
Return value
1 if successful processing registration, otherwise 0. Remarks
This function exists within the low-level interface and is one of the special functions used for testing.
See also: _card_write (p. 793).
_card_status
Gets memory card BIOS status. Syntax
long _card_status(drv) long drv;
Arguments
drv Sets slot number (0: Faces left 1: Faces right)
Explanation
Gets the memory card BIOS status of each slot, drv. Specify drv as 0 (facing left) or 1 (facing right).
Terminates immediately even though it is a synchronous function. Return value
If the memory card BIOS is in run state, it can return any of the following values.
Value
State
0x01
No registered processing
0x02
READ processing
0x04
WRITE processing
0x08
Connection test processing
registration
0x11
No registration processing (just
prior to timeout generation)
0x21
No registration processing (just
prior to error generation)
See also: card_wait (p. 792), _card_chan (p. 786).
792 Memory Card Library (libcard) Functions
_card_wait
Waits for memory card BIOS completion Syntax
long _card_status(drv) long drv;
Arguments
drv Sets slot number (0: Faces left 1: Faces right) Explanation
Wait until registration processing completes for the drv slot. Specify drv as 0 (facing left) or 1 (facing right).
Return value Always 1.
See also: _card_status (p. 791), _card_chan (p. 786).
Runtime Library Release 3.0
_card_write
Writes to one block of the memory card. Syntax
long _card_write(chan, block, buf)
long chan; long block; long *buf;
Arguments
chan Port number x 16 + card number block Target block number
buf Pointer to 1 28-byte data buffer
Explanation
Writes 128 bytes of buffer data pointed to by buf to the target block number (block) of the memory card of the specified channel (chan).
Specifies Port number x 16 + Card number in chan. Port A is 0, and Port B is 1. The card number is normally 0.
This function executes asynchronously, so it terminates immediately. Multiplex processing to the same card slot is not performed. Actual processing termination is communicated by an event. (See table below.)
Source Descriptor / Event Class Contents
HwCARD/EvSpIOE HwCARD/EvSpTIMOUT HwCARD/EvSpNEW HwCARD/EvSpERROR HwCARD/EvSpUN KOWN
Ends process
Card not connected New card detected Error generated
Source unknown
Table: Posts an event on completion of processing
Return value
1 if successful processing registration, otherwise 0. Remarks
This function exists within the low-level interface and is one of the special functions used for testing.
See also: _card_read (p. 790).
794 Memory Card Library (libcard) Functions
_new_card
Changes settings of unconfirmed flag test.
Syntax
void _new_card(void)
Arguments None.
Explanation
Masks the generation of an EvSpNEW event immediately after _card_read() or _card_write().
Terminates immediately even though it is a synchronous function.
Return value
None.
See also: _card_clear (p. 787), _card_read (p. 790), _card_write (p. 793).
Chapter 12
Link Cable Library (libcomb)
This chapter describes common functions of the combat cable library (libcomb). When two PlayStations are connected, this library helps them cooperate.
Chapter 12: Link Cable Library (libcomb) Table of Contents
Functions
AddCOMB
799
ChangeClearSIO
800
DelCOMB
801
_comb_control
802
AddCOM B
Syntax
Link Cable Library (libcomb) Functions 799
AddCOMB (void)
Arguments None.
Explanation
Initialize opposition cable driver.
Runtime Library Release 3.0
800 Link Cable Library (libcomb) Functions
ChangeClearSIO
Syntax
ChangeClearSIO (val) Arguments
val Interrupt cause clear flag Explanation
If val is set as non-0, an interrupt from an expansion SIO in the driver is cleared. This is used only when other expansion SIO drivers are also present.
Runtime Library Release 3.0
DelCOMB
Syntax
Link Cable Library (libcomb) Functions 801
DelCOMB (void)
Arguments None.
Explanation
Remove opposition cable driver from kernel.
Runtime Library Release 3.0
802 Link Cable Library (libcomb) Functions
_comb_control
Combat cable BIOS Syntax
long _comb_control(cmd,arg) long cmd;
long org;
Arguments
cmd Control command
arg Control command argument
Explanation
Offers the same functionality as ioctl() to an sio device. The details are provided elsewhere. Return value
The return value depends on the control command used in cmd.
Chapter 13
Kernel Library (libc/libc2)
This chapter explains the standard C functions provided by the kernel library libapi.
Chapter 13: libc/libc2 Table of Contents
Functions
abs
807
atoi
808
atol
809
bcmp
810
bcopy
811
bsearch
812
bzero
813
calloc
814
exit
815
free
816
getc
817
getchar
818
gets
819
isXXXX...
820
labs
821
longjmp
822
malloc
823
memchr
824
memcmp
825
memcpy
826
memmove
827
memset
828
printf
829
putc
830
putchar
831
puts
832
qsort
833
rand
834
realloc
835
setjmp
836
srand
837
strcat
838
strchr
839
strcmp
840
strcpy
841
strcspn
842
strlen
843
strncat
844
strncmp
845
strncpy
846
strpbrk
847
strrchr
848
strspn
849
strstr
850
strtok
851
strtol
852
strtoul
853
toascii
854
tolower
855
toupper
856
Kernal Library (libc/libc2) Functions 807
Calculates absolute value.
Syntax
#include <stdlib.h> long abs(i)
long i;
Arguments
i Integer
Explanation
This function calculates the absolute value of the integer i. This is essentially a function for finding the absolute value of an integer of the type int, but in R3000, int and long are the same size, so on this system, this function is equivalent to the function labs() described later.
Return value
This function returns the absolute value of the argument.
See also: labs (p. 821).
atoi
Performs integer conversion of- character strings. Syntax
#include <stdlib.h> long atoi(s)
const char *s;
Arguments
s Character string Explanation
This function is the same as (long) strol(s, (chr**) NULL). On this system, it is equivalent to atol(), described later.
Return value
This function returns the result obtained by converting the input value s to an integer.
See also: atol (p. 809), strtol (p. 852).
atol
Converts a character string to an integer. Syntax
Kernal Library (libc/libc2) Functions 809
#include <stdlib.h> long atol(s)
const char *s;
Arguments
s Character string Explanation
This function is the same as(long) strol(s, (chr**) NULL).
See also: atoi (p. 808), strtol (p. 852).
Runtime Library Release 3.0
bcmp
Compares memory blocks. Syntax
#include <stdlib.h>
long bcmp(b1, b2, n)
char *b1; char *b2; long n;
Arguments
b1 Comparison source 1
b2 Comparison source 2
n Number of bytes compared
Explanation
This function compares the first n bytes of b1 and b2.
Return value
The return value may be as follows, depending on the results of the comparison.
Result Return value
b1<b2 <0
b1=b2 =0
b1>b2 >0
See also: memcmp (p. 825).
Kernal Library (libc/libc2) Functions 811
bcopy
src Copy source
dest Copy destination
n Number of bytes copied
Explanation
This function copies the first n bytes of src to dest.
Return value
None.
See also: memcpy (p. 826).
812 Kernal Library (libc/libc2) Functions
bsearch
Binary search. Syntax
#include <stdlib.h>
void *bsearch(key, base, n, w, fcmp) const void *key;
const void *base;
size_t n;
size_t w;
long (*fcmp) (const_void*, const void*);
Arguments
key base n
w
fcmp
Storage destination of the value to be searched for
Storage destination of the array to be searched for
Number of elements Size of one element
Address of comparison function
Explanation
This function carries out a binary search on a table of n items (of item size w) starting from base, for an item matching key.
Return value
This function returns the address of the first item matching the search key. If no matching item is found, it returns 0.
Runtime Library Release 3.0
bzero
Fills a memory block with zeros. Syntax
Kernal Library (libc/libc2) Functions 813
#include <stdlib.h> void bzero(p, n) char *p;
long n;
Arguments
p Memory block
n Size
Explanation
This function sets n bytes to the value 0, starting from p.
Return value None.
Runtime Library Release 3.0
calloc
Allocates main memory. Syntax
#include <stdlib.h> void *calloc(n, s) size_t n;
size_t s;
Arguments
n Number of blocks
s Size of block
Explanation
This function secures n block of s bytes each from the heap and clears memory allocated to 0.
Return value
This function returns a pointer to the memory block secured. If the function fails, it returns NULL.
See also: malloc (p. 823), realloc (p. 835), free (p. 816).
Kernal Library (libc/libc2) Functions 815
exit
Terminates a program normally. Syntax
#include <stdlib.h> void exit(err)
const long err;
Arguments
err Error code
Explanation
When this function is executed on the PlayStation itself, a system error notice window (including the error code) is displayed, and the system enters an infinite loop. When this function is executed on a development machine, the program currently being executed is terminated, and the system returns to the debug monitor.
Return value None.
Runtime Library Release 3.0
free
Releases allocated memory blocks. Syntax
#include <stdlib.h> void free(block)
void * block;
Arguments
block Memory block allocated by a function such as malloc().
Explanation
This function releases memory blocks secured by the functions calloc(), malloc() and realloc().
Return value
None.
See also: calloc (p. 814), malloc (p. 823), realloc (p. 835).
Gets one character from the stream. Syntax
#include <romio.h> long getc(stream)
unsigned long *stream;
Arguments
stream Input stream
Explanation
This function gets one character from the input stream.
Return value
If this function succeeds, it converts the character it has read to an unsigned long, and returns it.
When getc reaches the end of the file, or when an error is generated, it returns EOF. Remarks
Devices and systems with a block size of 1 may all be used as the standard input/output stream as follows.
close (0); close (1);
open (<device name>, O_RDONLY);
open (<device name>, O_WRONLY);
See also: getchar (p. 818), gets (p. 819).
getchar
Gets one character from the standard input stream. Syntax
#include <romio.h> long getchar(void)
Arguments
None.
Explanation
This function gets one character from the standard input stream. It is the same as getc(stdin).
Return value
The return value is the same as for getc().
See also: getc (p. 817), gets (p. 819).
Reads a character string from the standard input. Syntax
#include <romio.h> char *gets(s)
char *s;
Arguments
s Storage destination for input character string Explanation
This function reads a character string ending in a newline character from the standard input stream (stdin), and stores it in s.
Return value
If this function succeeds, it returns s. If it reaches the end of the file, or if an error is generated, it returns NULL.
See also: getc (p. 817), getchar (p. 818).
isXXXX. ..
Tests characters. Syntax
#include <ctype.h> long isXXXX(c)
long c;
Arguments
c Character
Explanation
This function tests on the character c. All of the tests are macros. The test conditions are as follows.
Name Conditions
isal nu m(c) iasalpha(c) isasci i(c) iscntrl(c) isdigit(c) isgraph(c) islower(c) isprint(c) ispunct(c) ispacet(c) isupper(c) isxdigit(c)
isapha(c) || isdigit(c)
isupper(c) || islower(c)
ASCII character
control character
decimal
printing characters other than space lower-case character
printing characters including space
printing characters other than space and alphanumerics space, new page, new line, restore, tab upper-case character
hexadecimal
Return value
This function returns a value other than 0 if the character c satisfies the test conditions, and returns the value 0 if it does not satisfy the test conditions.
Absolute value. Syntax
#include <stdlib.h> long labs(i)
long i;
Arguments
i Integer value
Explanation
This function calculates the absolute value of the integer i.
Return value
This function returns the absolute value of the argument.
See also: abs (p. 806).
longjmp
Non-local jump. Syntax
#include <setjmp.h> void longjmp(p, val) jmp_buf p;
long val;
Arguments
p Environment storage variable
val setjmp() Return value
Explanation
This function makes a non-local jump to the destination specified by p.
Return value
None. If the function executes normally, it does not return.
See also: setjmp (p. 836).
Allocates main memory. Syntax
#include <stdlib.h> void *malloc(s)
size_t s;
Arguments
s Number of bytes to be allocated
Explanation
This function secures a block of s bytes from the memory heap.
Return value
This function returns a pointer to the secured memory block. If it has failed to secure a block, it returns NULL.
Note that the memory heap is defined as follows. Bottom address: top address of module + 4.
Top address: available memory -4
See also: calloc (p. 814), realloc (p. 835), free (p. 816).
824 Kernal Library (libc/libc2) Functions
memchr
Searches memory block for a character. Syntax
#include <memory.h> void *memchr(s, c, n) const void *s;
long c;
size_t n;
Arguments
s Memory block
c Character
n Number of bytes
Explanation
This function searches the memory block of n bytes starting from s, looking for the first appearance of the character c.
Return value
This function returns a pointer to the location at which c was found. If c was not found, it returns NULL.
Runtime Library Release 3.0
Kernal Library (libc/libc2) Functions 825
memcmp
Compares memory blocks. Syntax
#include <memory.h>
void *memcmp(s1, s2, n)
const void *s1; const void *s2; size_t n;
Arguments
s1 Comparison source memory block1
s1 Comparison source memory block 2
n Number of bytes compared
Explanation
This function compares the first n bytes of s1 and s2.
Return value
This function returns the values shown below, depending on the results of the comparison of s1 and s2.
Result Return value
s1<s2 <0
s1=s2 =0
s1>s2 >0
See also: bcmp (p. 810).
826 Kernal Library (libc/libc2) Functions
memcpy
Copies memory blocks. Syntax
#include <memory.h> void *memcpy(dest, src, n) void *dest;
const void *src;
size_t n;
Arguments
dest Copy destination memory block
src Copy source memory block
n Number of bytes copied
Explanation
This function copies the first n bytes of src to dest.
Return value
This function returns dest.
See also: bcopy (p. 811).
Kernal Library (libc/libc2) Functions 827
memmove
Copies a memory block. Syntax
#include <memory.h>
void *memmove(dest, src, n) void *dest;
const void *src;
size_t n;
Arguments
dest Copy destination memory block
src Copy source memory block
n Number of bytes copied
Explanation
This function copies the first n bytes of src to dest. The block is copied correctly, even between overlapping objects.
Return value
This function returns dest.
Runtime Library Release 3.0
828 Kernal Library (libc/libc2) Functions
memset
Writes specified characters to a memory block. Syntax
#include <memory.h> void *memset(s, c, n) const void *s;
long c;
size_t n;
Arguments
s Memory block
c Character
n Number of characters
Explanation
This function writes c to a memory block of n bytes starting at s.
Return value
This function returns s.
Runtime Library Release 3.0
printf
Formatted output. Syntax
#include <romio.h>
long printf(const char *fmt[, argument ...])
Arguments
fmt Input format character string
argument Argument corresponding to fmt
Explanation
Omitted. See a C language reference. Conversion directives f, e, E, g and G cannot be used.
Return value
printf returns the length of the output character string. If an error is generated, the function returns NULL.
Outputs one character to the stream. Syntax
#include <romio.h> long putc(c, stream) long c;
unsigned long stream;
Arguments
c Output character stream Output stream
Explanation
This function outputs a character c to the output stream.
Return value
This function returns c if it succeeds, and EOF if an error is generated.
See also: putchar (p. 831), puts (p. 832).
putchar
Outputs one character to the standard output stream. Syntax
#include <romio.h> long putchar(c)
long c;
Arguments
c Output character
Explanation
This function outputs a character c to the standard output. It is the same as putc(stdout).
Return value
The return value is the same as for putc().
See also: putc (p. 830), puts (p. 832).
Outputs a character string to the standard output stream. Syntax
#include <romio.h> long puts(s)
const char *s
Arguments
s Output character string Explanation
This function outputs a character string ending in NULL to the standard output stream (stdout), and finally outputs a newline character.
Return value
This function returns a non-negative value if it succeeds, and EOF if an error is generated.
See also: putc (p. 830), putchar (p. 831).
Kernal Library (libc/libc2) Functions 833
qsort
Quick sort. Syntax
#include <stdlib.h>
void qsort (base, n, w, fcmp)
void *base;
size_t n;
size_t w;
long (*fcmp)(const void*, const void *)
Arguments
base Storage destination of array to be sorted
n Number of elements
w Size of on element
fcmp Address of comparison function
Explanation
This function quick-sorts a table of n items (of item size w) starting with base, with fcmp as the comparison function.
Return value None.
Runtime Library Release 3.0
rand
Generates random numbers. Syntax
#include <rand.h> long rand(void)
Arguments None.
Explanation
This function generates a pseudo-random number from 0 to RAND_MAX (0x7FFF=32767).
Return value
This function returns the pseudo-random number which has been generated.
See also: srand (p. 837).
realloc
Changing heap memory allocations. Syntax
#include <memory.h> void *realloc(block, s) void *block;
size_t s;
Arguments
block Block secured by a function such as malloc()
s New size
Explanation
This function takes a previously concerned block and contracts it or expands it to s bytes. If block is NULL, this function works in the same way as malloc.
Return value
This function returns the address of the reallocated block. This address may be different to the old address.
If it fails to perform the allocation, the function returns NULL. In this case, the old block is not released.
See also: calloc (p. 814), malloc (p. 823), free (p. 816).
setjmp
Defines non-local jump destination. Syntax
#include <setjmp.h> long setjmp(p)
jmp_buf p;
Arguments
p Environment storage variable
Explanation
This function stores the destination information for a non-local jump at p. If longjmp(p, val) is executed, the system will return from setjmp().
Return value
This function returns the value given to the second argument of longjmp() when the jump is executed.
See also: longjmp (p. 822).
srand
Initializes the random number generator. Syntax
#include <rand.h> void srand(seed) unsigned long seed;
Arguments
seed Random number seed
Explanation
This function sets a new starting point for random number generation. The default is 1.
Return value
None.
See also: rand (p. 834).
strcat
Concatenates character strings. Syntax
#include <strings.h> char *strcat(dest, src) char *dest;
const char *src;
Arguments
dest Concatenation target string
src Concatenation source string
Explanation
This function appends the character string src to the end of the character string dest.
Return value
This function returns dest.
See also: strncat (p. 844).
strchr
Searches for the first location at which a specified character appears in a character string. Syntax
#include <strings.h> char *strchr(s, c)
const char *s
long c;
Arguments
s Character string searched
c Character searched for
Explanation
This function searches for the first location at which the character c appears in the character string s.
Return value
This function returns the address of the location at which c appears. If c has not been found, it returns NULL.
840 Kernal Library (libc/libc2) Functions
strcmp
Compares character strings. Syntax
#include <strings.h> long strcmp(s1, s2) const char *s1; const char *s2;
Arguments
s1 Character string 1
s2 Character string 2
Explanation
This function compares the character string s2 with the character string s1, treating each character as an unsigned char.
Return value
This function returns one of the values shown below, depending on the comparison result.
Result Return value
s1<s2 <0
s1=s2 =0
s1>s2 >0
Runtime Library Release 3.0
strcpy
Copies a character string. Syntax
#include <strings.h> char *strcpy(dest, src) char *dest;
const char *src;
Arguments
dest Copy destination character string
src Copy source character string
Explanation
This function copies the character string src to the character string dest.
Return value
This function returns dest.
See also: strncpy (p. 846).
Search for a partial character string made up solely of characters not included in the specified character set.
Syntax
#include <strings.h> size_t strcspn(s1, s2) const char *s1;
const char *s2;
Arguments
s1 Character string
s2 Character group
Explanation
This function returns the length of the first part of the character string s1 consisting only of characters not included in the character string s2.
Return value
This function returns the length of the partial character string found.
strlen
Counts the number of characters in a character string. Syntax
#include <strings.h> long strlen(s)
const char *s;
Arguments
s Character string
Explanation
This function counts the number of characters in a character string s.
Return value
This function returns the number of characters.
Concatenates character strings. Syntax
#include <strings.h> long *strncat(dest, src, n) char *dest;
const char *src;
size_t n;
Arguments
dest Concatenation destination array
src Concatenation source character string
n Number of characters concatenated
Explanation
This function appends the first n characters from src to the end of the character string dest.
Return value
This function returns dest.
Kernal Library (libc/libc2) Functions 845
strncmp
Compares character strings. Syntax
#include <strings.h> long strcmp(s1, s2, n) const char *s1; const char *s2; size_t n;
Arguments
s1 Character string 1
s2 Character string 2
n Number of characters compared
Explanation
This function compares the first n characters of s1 and s2, treating each character as unsigned char.
Return value
This function returns one of the following values, depending on the comparison result (the values are the same as for strcmp).
Result Return value
s1<s2 <0
s1=s2 =0
s1>s2 >0
Runtime Library Release 3.0
846 Kernal Library (libc/libc2) Functions
strncpy
Copies a character string. Syntax
#include <strings.h> char *strncpy(dest, src, n) char *dest;
Reply With Quote
Bookmarks