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,f2) 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 [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 [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 [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 -> v Local Object 3D Vertex evmx -> sxyz Screen 3D Vertex evmx -> chx chx = vz* (hw/2)/h evmx -> 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 -> v evmx -> sxyz evmx -> sxyz.pad evmx -> sxy evmx -> chx evmx -> 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 -> v evmx -> sxyz evmx -> txuv evmx -> chx evmx -> 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; [/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i][/i]
