Copyright: Yaroze Library Reference Copyright Sony 1996 Compiled by ~arkitekt 2002


abs

Absolute value

#include <stdlib.h >

long abs (

        long i

)

Arguments

i	Integer argument

Explanation

The absolute value of i is calculated and its value is returned. Since int and long are declared as the same type in the R3000, this function is equivalent to labs().

Return Value

The absolute value of i is returned.

See Also

labs()

INDEX


atoi

Converts a string to an integer

#include <stdlib.h >

long atoi (

        const char *s

)

Arguments

s	Pointer to a character string

Explanation

The string pointed to by s is converted to its integer equivalent and its value is returned. atoi(s) is equivalent to (long)strtol(s,(char**)NULL). Since int and long are declared as the same type in the R3000, atoi() is also equivalent to atol().

Return Value

The integer value of the converted character string is returned.

See Also

atol(), strtol()

INDEX


atol

Converts a string to an integer

#include <stdlib.h >

long atol (

        const char *s

)

Arguments

s	Pointer to a character string

Explanation

The string pointed to by s is converted to its integer equivalent and its value is returned. atol(s) is equivalent to (long)strtol(s,(char**)NULL). Since int and long are declared as the same type in the R3000, atol() is also equivalent to atoi().

Return Value

The integer value of the converted character string is returned.

See Also

atoi(), strtol()

INDEX


bcmp

Compares two memory blocks

#include <memory.h >

long bcmp (

        char *b1,

        char *b2,

        long n

)

Arguments

b1	Pointer to memory block 1
b2	Pointer to memory block 2
n	Number of bytes to compare

Explanation

The first n bytes of the memory blocks pointed to by b1 and b2 are compared and the result is indicated in the return value.

Return Value

The result of the comparison is indicated in the return value as shown below:

Result	Return Value
b1<b2	<0
b1=b2	=0
b1>b2	>0

See Also

memcmp()

INDEX


bcopy

Copies memory

#include <memory.h >

void bcopy (

        char *src,

        char *dest,

        long n

)

Arguments

src	Pointer to source data area
dest	Pointer to destination data area
n	Number of bytes to copy

Explanation

The first n bytes of the data area pointed to by src are copied to the data area pointed to by dest.

Return Value

None

See Also

memcpy()

INDEX


bsearch

Binary search

#include <stdlib.h >

void *bsearch (

        const void *key,

        const void *base,

        size_t n,

        size_t w,

        long(*fcmp)(const void *, const void *)

)

Arguments

key	Pointer to data which is the retrieval key
base	Pointer to destination area to be searched
n	Number of elements in the data area
w	Size of 1 element
fcmp	Pointer to comparison function

Explanation

A binary search for the retrieval key pointed to by key is made in the destination area pointed to by base using the comparison function fcmp. A pointer to the found item is returned. base is considered to be an array of n items with size w. The search is performed looking for the first item that matches the retrieval key. fcmp must return a value representing the result of the comparison as in bcmp().

Return Value

The address of the first item matching the retrieval key is returned. 0 is returned if a matching item was not found.

INDEX


bzero

Clears memory

#include <memory.h >

void *bzero (

        u_char *p,

        int n

}

Arguments

p	Pointer to a memory block
n	Number of bytes to clear

Explanation

The first n bytes of the memory block pointed to by p are cleared.

Return Value

p, a pointer to the start of the memory block is returned.

See Also

bcopy(), bcmp()

INDEX


calloc

Allocates memory

#include <stdlib.h >

void *calloc (

        size_t n,

        size_t s

)

Arguments

n	Number of blocks to allocate
s	Block size

Explanation

An n * s byte block is allocated from the heap. The allocated memory is cleared.

Return Value

A pointer to the allocated memory block is returned. NULL is returned if the allocation failed.

See Also

malloc(), realloc(), free()

INDEX


free

Frees allocated memory blocks

#include <stdlib.h >

void free (

        void*block

)

Arguments

block	Pointer to allocated memory to be freed

Explanation

The memory area pointed to by block and previously allocated by calloc(), malloc() or realloc() is freed.

Return Value

None

See Also

calloc(), malloc(), realloc()

INDEX


getc

Gets one character from an input stream

#include <stdio.h >

char getc (

        FILE *stream

)

Arguments

stream	Pointer to an input stream

Explanation

The next character is read from the input stream pointed to by stream. The character is returned by the function.

Return Value

The next character read from the input stream is returned if the function was successful. Otherwise, EOF is returned in case of end-of-file or error.

See Also

getchar(), gets()

INDEX


getchar

Gets one character from the standard input stream

#include <stdio.h >

char getchar (

        void

)

Arguments

None

Explanation

The next character is read from the standard input stream and returned.

getchar() is equivalent to getc(stdin).

Return Value

The next character read from the standard input stream is returned if the function was

successful. Otherwise, EOF is returned in case of end-of-file or error.

See Also

getc(), gets()

INDEX


gets

Reads a line from the standard input stream

#include <stdio.h >

char *gets (

        char *s

)

Arguments

s	Pointer to destination buffer

Explanation

A line is read from the standard input stream (stdin) and placed in the buffer pointed to by s. The end of line is indicated by a newline character. The newline is discarded and replaced by a null character at the end of the string pointed to by s.

Return Value

A pointer to the character string s is returned if the function was successful. NULL is returned in case of end-of-file or error.

See Also

getc(), getchar()

INDEX


isalnum

Performs character testing

#include <ctype.h >

long isalnum (

        long c

)

Arguments

c	Input character

Explanation

The character c is tested as to whether it is alph-numeric character, i.e. a digit or upper or lower case character.

Return Value

A non-zero value is returned if the input character c is alph-numeric, otherwise 0 is returned.

See Also

isalpha(), isascii(), iscntrl(), isdigit(), isgraph(), islower(), isprint(), ispunct(), isspace(), isupper(), isxdigit()

INDEX


isalpha

Performs character testing

#include <ctype.h >

long isalpha (

        long c

)

Arguments

c	Input character

Explanation

The character c is tested as to whether it is an upper or lower case character.

Return Value

A non-zero value is returned if the input character c is an upper or lower case character, otherwise 0 is returned.

See Also

isalnum(), isascii(), iscntrl(), isdigit(), isgraph(), islower(), isprint(), ispunct(), isspace(), isupper(), isxdigit()

INDEX


isascii

Performs character testing

#include <ctype.h >

long isascii (

        long c

)

Arguments

c	Input character

Explanation

The character c is tested as to whether it is in the ascii character set.

Return Value

A non-zero value is returned if the input character c is in the ascii character set, otherwise 0 is returned.

See Also

isalnum(), isalpha(), iscntrl(), isdigit(), isgraph(), islower(), isprint(), ispunct(), isspace(), isupper(), isxdigit()

INDEX


iscntrl

Performs character testing

#include <ctype.h >

long iscntrl (

        long c

)

Arguments

c	Input character

Explanation

The character c is tested as to whether it is a control character.

Return Value

A non-zero value is returned if the input character c is a control character, otherwise 0 is returned.

See Also

isalnum(), isalpha(), isascii(), isdigit(), isgraph(), islower(), isprint(), ispunct(), isspace(), isupper(), isxdigit()

INDEX


isdigit

Performs character testing

#include <ctype.h >

long isdigit (

        long c

)

Arguments

c	Input character

Explanation

The character c is tested as to whether it is a decimal digit.

Return Value

A non-zero value is returned if the input character c is a decimal digit, otherwise 0 is returned.

See Also

isalnum(), isalpha(), isascii(), iscntrl(), isgraph(), islower(), isprint(), ispunct(), isspace(), isupper(), isxdigit()

INDEX


isgraph

Performs character testing

#include <ctype.h >

long isgraph (

        long c

)

Arguments

c	Input character

Explanation

The character c is tested as to whether it is a printable character, which does not in this case include spaces.

Return Value

A non-zero value is returned if the input character c is a printable character, not including spaces, otherwise 0 is returned.

See Also

isalnum(), isalpha(), isascii(), iscntrl(), isdigit(), islower(), isprint(), ispunct(), isspace(), isupper(), isxdigit()

INDEX


islower

Performs character testing

#include <ctype.h >

long islower (

        long c

)

Arguments

c	Input character

Explanation

The character c is tested as to whether it is a lower case character.

Return Value

A non-zero value is returned if the input character c is a lower case character, otherwise 0 is returned.

See Also

isalnum(), isalpha(), isascii(), iscntrl(), isdigit(), isgraph(), isprint(), ispunct(), isspace(), isupper(), isxdigit()

INDEX


isprint

Performs character testing

#include <ctype.h >

long isprint (

        long c

)

Arguments

c	Input character

Explanation

The character c is tested as to whether it is a printable character, including spaces.

Return Value

A non-zero value is returned if the input character c is a printable character, including spaces, otherwise 0 is returned.

See Also

isalnum(), isalpha(), isascii(), iscntrl(), isdigit(), isgraph(), islower(), ispunct(), isspace(), isupper(), isxdigit()

INDEX


ispunct

Performs character testing

#include <ctype.h >

long ispunct (

        long c

)

Arguments

c	Input character

Explanation

The character c is tested as to whether it is a printable character (except spaces), or English letter or number.

Return Value

A non-zero value is returned if the input character c is a printable character (except spaces), or English letter or number. Otherwise 0 is returned.

See Also

isalnum(), isalpha(), isascii(), iscntrl(), isdigit(), isgraph(), islower(), isprint(), isspace(), isupper(), isxdigit()

INDEX


isspace

Performs character testing

#include <ctype.h >

long isspace (

        long c

)

Arguments

c	Input character

Explanation

The character c is tested as to whether it is non-printable character, i.e. a space, tab, page break, carriage return or line feed.

Return Value

A non-zero value is returned if the input character c is a non-printable character, i.e. a space, tab, page break, carriage return or line feed. Otherwise 0 is returned.

See Also

isalnum(), isalpha(), isascii(), iscntrl(), isdigit(), isgraph(), islower(), isprint(), ispunct(), isupper(), isxdigit()

INDEX


isupper

Performs character testing

#include <ctype.h >

long isupper (

        long c

)

Arguments

c	Input character

Explanation

The character c is tested as to whether it is an upper case character.

Return Value

A non-zero value is returned if the input character c is an upper case character, otherwise 0 is returned.

See Also

isalnum(), isalpha(), isascii(), iscntrl(), isdigit(), isgraph(), islower(), isprint(), ispunct(), isspace(), isxdigit()

INDEX


isxdigit

Performs character testing

#include <ctype.h >

long isxdigit (

        long c

)

Arguments

c	Input character

Explanation

The character c is tested as to whether it is a hexadecimal character.

Return Value

A non-zero value is returned if the input character c is a hexadecimal character, otherwise 0 is returned.

See Also

isalnum(), isalpha(), isascii(), iscntrl(), isdigit(), isgraph(), islower(), isprint(), ispunct(), isspace(), isupper()

INDEX


labs

Absolute value

#include <stdlib.h >

long labs (

        long i

)

Arguments

i	Integer argument

Explanation

The absolute value of i is calculated and its value is returned. Since int and long are declared as the same type in the R3000, this function is equivalent to abs().

Return Value

The absolute value of i is returned.

See Also

abs()

INDEX


longjmp

Non-local jump

#include <setjmp.h >

void longjmp (

        jmp_buf p,

        int val

)

Arguments

p	Environment storage variable
val	Specified return value of setjmp()

Explanation

The program jumps to the location specified in the environment storage area pointed to by p which was set by a previous call to setjmp().

Return Value

After a longjmp() is completed, program execution continues as if the corresponding invocation of setjmp() had just returned the value specified by val. longjmp() cannot cause setjmp() to return the value 0; if val is 0, setjmp() returns the value 1.

See Also

setjmp()

INDEX


malloc

Allocates memory

#include <stdlib.h >

void *malloc (

        size_t s

)

Arguments

s	Number of bytes to allocate

Explanation

A block of s bytes is allocated from the heap.

Return Value

A pointer to the allocated memory block is returned. NULL is returned if the allocation failed.

Notes

At the time of user program activation heap memory is defined as follows:

Bottom address	Highest address of module + 4
Top address	Highest available memory - 64KB

See Also

calloc(), realloc(), free()

INDEX


memchar
memchr

Searches a memory block for a specified character

#include <memory.h >

void *memchr (

        const void *s,

        long c,

        size_t n

)

Arguments

s	Pointer to a memory block
c	Desired character
n	Maximum number of bytes to search

Explanation

The first occurrence of the character c in the memory block pointed to by s is located and a pointer to the character is returned. At most n bytes of the memory block will be searched.

Return Value

A pointer to the located character c is returned. NULL is returned if c cannot be found in the memory block.

INDEX


memcmp

Compares two memory blocks

#include <memory.h >

long memcmp (

        const void *s1,

        const void *s2,

        size_t n

)

Arguments

s1	Pointer to memory block 1
s2	Pointer to memory block 2
n	Maximum number of bytes to compare

Explanation

The first n bytes of the memory blocks pointed to by s1 and s2 are compared and the result is indicated in the return value.

Return Value

The result of the comparison is indicated in the return value as shown below:

Result	Return Value
s1<s2	<0
s1=s2	=0
s1>s2	>0

See Also

bcmp()

INDEX


memcpy

Copies a memory block

#include <memory.h >

void *memcpy (

        void *dest,

        const void *src,

        size_t n

)

Arguments

dest	Pointer to destination memory block
src	Pointer to source memory block
n	Number of bytes to copy

Explanation

The first n bytes of the memory block pointed to by src are copied to the memory block pointed to by dest.

Return Value

dest, a pointer to the destination memory block is returned.

See Also

bcopy()

INDEX


memmove

Copies a memory block

#include <memory.h >

void *memmove (

        void *dest,

        const void *src,

        size_t n

)

Arguments

dest	Pointer to destination memory block
src	Pointer to source memory block
n	Number of bytes to copy

Explanation

The first n bytes of the memory block pointed to by src are copied to the memory block pointed to by dest. The block is copied correctly even if src and dest overlap.

Return Value

dest, a pointer to the destination memory block is returned.

INDEX


memset

Writes a specified character to a memory block

#include <memory.h >

void *memset (

        const void *s,

        long c,

        size_t n

)

Arguments

s	Pointer to destination memory block
c	Fill character
n	Number of characters

Explanation

The first n bytes of the memory block pointed to by s are filled with the character c.

Return Value

s, a pointer to the destination memory block is returned.

INDEX


printf

Writes formatted output to the standard output stream

#include <stdio.h >

long printf (

        const char *fmt[,argument ...]

)

Arguments

fmt	Input format conversion string

Explanation

Writes formatted output to stdout, the standard output stream. Please refer to the C language reference for a detailed explanation of the input format conversion string. The format specifiers “f”, “e”, “E”, “g” and “G” cannot be used. printf2() of the mathematical function service is used to display floating-point numbers.

Return Value

The length of the output character string is returned. NULL is returned if an error occurred.

See Also

sprintf(), printf2()

INDEX


putc

Writes one character to an output stream

#include <stdio.h >

void putc (

        long c,

        FILE *stream

)

Arguments

c	Output character
stream	Pointer to output stream

Explanation

The character c is written to the output stream pointed to by stream.

Return Value

None

See Also

putchar(), puts()

INDEX


putchar

Writes one character to the standard output stream

#include <stdio.h >

long putchar (

        char c,

)

Arguments

c	Output character

Explanation

The character c is written to the standard output stream. putchar() is equivalent to putc(stdout).

Return Value

None

See Also

putc(), puts()

INDEX


puts

Writes a character string to the standard output stream

#include <stdio.h >

void puts (

        const char *s

)

Arguments

s	Output character string

Explanation

The character string s is written to the standard output stream (stdout). A newline character is appended to the end of the string.

Return Value

None

See Also

putc(), putchar()

INDEX


qsort

Quick sort

#include <stdlib.h >

void qsort (

        void *base,

        size_t n,

        size_t w,

        long (*fcmp)(const void *, const void *)

)

Arguments

base	Pointer to array in memory to be sorted
n	Number of elements
w	Size of each element
fcmp	Pointer to comparison function

Explanation

The array pointed to by base is sorted using a quicksort algorithm. n specifies the number of elements in the array and w is the size of each element. fcmp is the comparison function and must return a value representing the result of the comparison as in bcmp(). qsort() calls malloc() internally so there must be sufficient space on the heap to perform the sort.

Return Value

None.

INDEX


rand

Generates a random number

#include <stdlib.h >

long rand (

        void

)

Arguments

None

Explanation

A pseudo-random number is generated between 0 and RAND_MAX(0x7FFF=32767) and its value is returned.

Return Value

The generated pseudo random number is returned.

See Also

srand()

INDEX


realloc

Reallocates memory

#include <stdlib.h >

void *realloc (

        void *block,

        size_t s

)

Arguments

block	Pointer to area to be reallocated
s	Size of new area

Explanation

The previously allocated area of storage pointed to by block is reallocated to the size specified by s. realloc() is identical to malloc() if block is NULL.

Return Value

A pointer to the reallocated block is returned. The reallocated block may be located at a different address than the original block. NULL is returned if the allocation failed in which case the original block is not released.

See Also

calloc(), malloc(), free()

INDEX


setjmp

Defines destination of longjmp()

#include <setjmp.h >

int setjmp (

        jmp_buf p

)

Arguments

p	Environment storage variable

Explanation

Saves environmental information (such as the stack pointer) in the memory area pointed to by p for later use by longjmp().

Return Value

When setjmp() is directly invoked, 0 is returned. If the return is from a call to longjmp(), val, the argument to longjmp() is returned.

See Also

longjmp()

INDEX


sprintf

Writes formatted output to a character string

#include <stdio.h >

long sprintf (

        char *s,

        const char *fmt[,argument...]

)

Arguments

s	Pointer to storage area holding converted character string
fmt	Input format conversion string

Explanation

Writes formatted output to a character string and places the result in the storage area pointed to by s. Please refer to the C language reference for a detailed explanation of the input format conversion string. The format specifiers “f”, “e”, “E”, “g” and “G” cannot be used. sprintf2() of the mathematical function service is used to display floating-point numbers.

Return Value

The length of the output character string is returned. NULL is returned if an error occurred.

See Also

printf(), sprintf2()

INDEX


srand

Initializes the random number generator

#include <stdlib.h >

void srand (

        u_int seed

)

Arguments

seed	Random number seed

Explanation

Sets the new seed for the random number generator to the value specified by seed. The random number generator is reinitialized to its initial starting point by specifying a seed of 1.

Return Value

None

See Also

rand()

INDEX


strcat

Concatenates two character strings

#include <strings.h >

char *strcat (

        char *dest,

        const char *src

)

Arguments

dest	Pointer to destination character string
src	Pointer to source character string

Explanation

The string pointed to by src is concatenated to the end of the string pointed to by dest A pointer to the concatenated string is returned.

Return Value

dest, a pointer to the concatenated string is returned.

See Also

strncat()

INDEX


strchr

Searches for the first occurrence of a specified character in a character string

#include <strings.h >

char *strchr (

        const char *s,

        long c

)

Arguments

s	Pointer to a character string
c	Target character

Explanation

The first occurrence of the character c is located in the string pointed to by s. A pointer to the located character is returned.

Return Value

A pointer to the first occurrence of the character c within the string s is returned. NULL is returned if c cannot be found within s.

INDEX


strcmp

Compares two character strings

#include <strings.h >

long strcmp (

        const char *s1,

        const char *s2

)

Arguments

s1	Pointer to string 1
s2	Pointer to string 2

Explanation

The string pointed to by s1 is compared with the string pointed to by s2, character-by-character as unsigned chars, and the result is indicated in the return value.

Return Value

The result of the comparison is indicated in the return value as shown below:

Result	Return Value
s1<s2	<0
s1=s2	=0
s1>s2	>0
INDEX


strcpy

Copies a character string

#include <strings.h >

char *strcpy (

        char *dest,

        const char *src

)

Arguments

dest	Pointer to destination memory area
src	Pointer to source character string

Explanation

The string pointed to by src is copied to the memory area pointed to by dest.

Return Value

dest, a pointer to the destination string is returned.

See Also

strncpy()

INDEX


strcspn

Searches for a character string comprising only characters not included in a specified character set

#include <strings.h >

size_t strcspn (

        const char *s1,

        const char *s2

)

Arguments

s1	Pointer to target character string to be searched
s2	Pointer to string which contains the character set

Explanation

The character string starting from the beginning of the string pointed to by s1 that does not contain any characters that are contained in the character set pointed to by s2 is located and its length is returned.

Return Value

The length of the segment within the string pointed to by s1 that does not contain any characters from the string pointed to by s2 is returned.

INDEX


strlen

Finds the length of a character string

#include <strings.h >

long strlen (

        const char *s

)

Arguments

s	Pointer to a character string

Explanation

The length of the string pointed to by s (i.e. the number of characters in the string) is obtained and its value is returned.

Return Value

The length of the string pointed to by s is returned.

INDEX


strncat

Concatenates two character strings

#include <strings.h >

char *strncat (

        char *dest,

        const char *src,

        size_t n

)

Arguments

dest	Pointer to destination character string
src	Pointer to source character string
n	Number of characters from source string to concatenate

Explanation

n characters from the string pointed to by src are concatenated to the end of the string pointed to by dest. The concatenated string is returned.

Return Value

dest, a pointer to the concatenated string is returned.

INDEX


strncmp

Compares two character strings

#include <strings.h >

long stncmp (

        const char *s1,

        const char *s2,

        size_t n

)

Arguments

s1	Pointer to string 1
s2	Pointer to string 2
n	Number of characters to compare

Explanation

The first n characters of the string pointed to by s1 are compared to the corresponding characters of the string pointed to by s2, character-by-character as unsigned chars, and the result is indicated in the return value.

Return Value

The result of the comparison is indicated in the return value as shown below:

Result	Return Value
s1<s2	<0
s1=s2	=0
s1>s2	>0
INDEX


strncpy

Copies a character string

#include <strings.h >

char *strncpy (

        char *dest,

        const char *src,

        size_t n

)

Arguments

dest	Pointer to destination memory area
src	Pointer to source character string
n	Number of bytes to copy

Explanation

n bytes of the string pointed to by src are copied to the memory area pointed to by dest.

Return Value

dest, a pointer to the destination string is returned.

INDEX


strpbrk

Searches for the first occurrence of a specified character in a character set

#include <strings.h >

char *strpbrk (

        const char *s1,

        const char *s2

)

Arguments

s1	Pointer to string to be searched
s2	Pointer to string containing the character set

Explanation

The character string pointed to by s1 is searched for the first occurrence of any character contained in the string pointed to by s2. A pointer to the character within s2 is returned.

Return Value

A pointer to the character within s2 is returned. NULL is returned if none of the characters in the string pointed to by s2 are contained within the character set.

INDEX


strrchr

Searches for the last occurrence of a specified character in a character string

#include <strings.h >

        char *strrchr (

        const char *s,

        long c

)

Arguments

s	Pointer to a character string
c	Target character

Explanation

The last occurrence of the character c is located in the character string pointed to by s. A pointer to the located character is returned.

Return Value

A pointer to the last occurrence of the character c within the string pointed to by s is returned. NULL is returned if c cannot be found within the string.

INDEX


strspn

Searches for a character string comprising only characters in a specified character set

#include <strings.h >

size_t strspn (

        const char *s1,

        const char *s2

)

Arguments

s1	Pointer to target character string to be searched
s2	Pointer to string containing the character set

Explanation

The character string starting from the beginning of the string pointed to by s1 that contains only characters from the string pointed to by s2 is located and its length is returned.

Return Value

The length of the segment within the string pointed to by s1 that contains only characters from the string pointed to by s2 is returned.

INDEX


strstr

Searches for the occurrence of a specified partial character string

#include <strings.h >

char *strstr (

        const char *s1,

        const char *s2

)

Arguments

s1	Pointer to target character string to be searched
s2	Pointer to character string to be located

Explanation

The first occurrence of the string pointed to by s2 is located within the string pointed to by s1. A pointer to the position of s2 within the string pointed to by s1 is returned.

Return Value

A pointer to the position of the located string pointed to by s2 within the string pointed to by s1 is returned. NULL is returned if the string pointed to by s2 is not contained within the string pointed to by s1.

INDEX


strtok

Searches for a character string bounded by characters in a specified set of delimiters

#include <strings.h >

char *strtok (

        char *s1,

        const char *s2

)

Arguments

s1	Pointer to target character string to search
s2	Pointer to character set containing token delimiters

Explanation

A sequence of calls to strtok() breaks the string pointed to by s1 into a sequence of tokens, each of which is delimited by a character from the string pointed to by s2. The first call in the sequence has s1 as its first argument, and is followed by calls with a NULL pointer as their first argument. The first call in the sequence searches the string pointed to by s1 for the first character that is not contained in the current separator string pointed to by s2. If no such character is found, then there are no tokens in the string pointed to by s1 and the function returns a NULL pointer. If such a character is found, it is the start of the first token. strtok() then searches from there for a character that is contained in the current separator string. If no such character is found, the current token extends to the end of the string pointed to by s1, and subsequent searches for a token will return a NULL pointer. If such a character is found, it is overwritten by a NULL character, which terminates the current token. strtok() saves a pointer to the following character, from which the next search for a token will start. Each subsequent call, with a NULL pointer as the value of the first argument, starts searching from the saved pointer and behaves as described above.

Return Value

A pointer to the first character of a token is returned, or NULL is returned if there is no token.

INDEX


strtol

Converts a character string to an integer

#include <stdlib.h >

long strtol (

        const char *s,

        char **endp

)

Arguments

s	Pointer to a character string
endp	Pointer to a storage area that will contain a pointer to the character that stopped the conversion

Explanation

The character string pointed to by s is converted to an integer and its value is returned. Note that long and int are declared as the same type in the R3000. The string pointed to by s must be in one of the following formats: [ws][sn][ddd]

[ws]	White space (can be omitted)
[sn]	Sign (can be omitted)
[ddd]	Number string (can be omitted)
strtol() stops conversion when a character is encountered that cannot be converted. A pointer to the character that terminated the conversion is placed at the storage location specified by endp unless endp is NULL.

Return Value

The result of converting the character string pointed to by s to an integer is returned if the conversion was successful. 0 is returned if an error occurred.

See Also

strtoul()

INDEX


strtoul

Converts a character string to an unsigned integer

#include <stdlib.h >

u_long strtoul (

        const char *s,

        char **endp

)

Arguments

s	Pointer to a character string
endp	Pointer to a storage area that will contain a pointer to the character that stopped the conversion

Explanation

The character string pointed to by s is converted to an unsigned integer and its value is returned. Note that long and int are declared as the same type in the R3000. The string pointed to by s must be in one of the following formats: [ws][sn][ddd]

[ws]	White space (can be omitted)
[sn]	Sign (can be omitted)
[ddd]	Number string (can be omitted)
strtoul() stops conversion when a character is encountered that cannot be converted. A pointer to the character that terminated the conversion is placed at the storage location specified by endp unless endp is NULL.

Return Value

The result of converting the character string pointed to by s to an unsigned integer is

returned if the conversion was successful. 0 is returned if an error occurred.

See Also

strtol()

INDEX


toascii

Masks off bit 7 of a specified character

#include <ctype.h >

long toascii (

        long c

)

Arguments

c	Input character

Explanation

Bit 7 of the input character c is masked off.

Return Value

The result of the masking operation is returned.

INDEX


tolower

Converts a character to lower case

#include <ctype.h >

long tolower (

        long c

)

Arguments

c	Input character

Explanation

The input character c is converted to lower case.

Return Value

The lower case character corresponding to the input character c is returned.

INDEX


toupper

Converts a character to upper case

#include <ctype.h >

long toupper (

        long c

)

Arguments

c	Input character

Explanation

The input character c is converted to upper case.

Return Value

The upper case character corresponding to the input character c is returned.

INDEX


ApplyMatrix

Multiplies a vector by matrix

VECTOR* ApplyMatrix (

        MATRIX* m,

        SVECTOR* v0,

        VECTOR* v1

)

Arguments

m	Pointer to input matrix
v0	Pointer to input short vector
v1	Pointer to result vector

Explanation

The short vector v0 is multiplied by the matrix m beginning with the rightmost end.

The product is stored in vector v1.

The argument format is as follows:

    m->m[i][j] : (1,3,12)

    v0->vx,vy,vz : (1,15,0)

    v1->vx,vy,vz : (1,31,0)

Return Value

The vector product v1 is returned.

Notes

This function destroys the rotation matrix.

See Also

MATRIX, SVECTOR, VECTOR

INDEX


ApplyMatrixLV

Multiplies a vector by a matrix

VECTOR* ApplyMatrixLV (

        MATRIX* m,

        VECTOR* v0,

        VECTOR* v1

)

Arguments

m	Pointer to input matrix
v0	Pointer to input vector
v1	Pointer to result vector

Explanation

The short vector v0 is multiplied by the matrix m beginning with the rightmost end.

The product is stored in vector v1.

The argument format is as follows:

    m->m[i][j] : (1,3,12)

    v0->vx,vy,vz : (1,15,0)

    v1->vx,vy,vz : (1,31,0)

Return Value

The vector product v1 is returned.

Notes

This function destroys the rotation matrix.

See Also

MATRIX, VECTOR

INDEX


ApplyMatrixSV

Multiplies a vector by a matrix

VECTOR* ApplyMatrixSV (

        MATRIX* m,

        SVECTOR* v0,

        SVECTOR* v1

)

Arguments

m	Pointer to input matrix
v0	Pointer to input short vector
v1	Pointer to result short vector

Explanation

The short vector v0 is multiplied by the matrix m beginning with the rightmost end.

The product is stored in vector v1.

The argument format is as follows:

    m->m[i][j] : (1,3,12)

    v0->vx,vy,vz : (1,15,0)

    v1->vx,vy,vz : (1,31,0)

Return Value

The vector procduct v1 is returned.

Notes

This function destroys the rotation matrix.

See Also

MATRIX, SVECTOR

INDEX


ClearImage

Frame the frame buffer with a specified pixel value

int ClearImage (

        RECT* recp,

        u_char r,

        u_char g,

        u_char b

)

Arguments

recp	Pointer to the rectangular area to be cleared in the frame buffer
r,g,b	Pixel value to be used for clearing

Explanation

The rectangular area of the frame buffer specified by recp is cleared with the pixel value specified by (r,g,b).

Return Value

The slot number of the GPU's draw command queue where the command resides is returned.

Notes

This is a non-blocking function, therefore DrawSync() must be used to determine the completion of transfer. The transfer is not affected by clipping or offsetting that may be in effect for the drawing environment.

INDEX


CompMatrix

Performs composite coordinate transformation

MATRIX* CompMatrix (

        MATRIX* m0,

        MATRIX* m1,

        MATRIX* m2

)

Arguments

m0	Pointer to input matrix
m1	Pointer to input matrix
m2	Pointer to result matrix

Explanation

The composite coordinate transformation of matrix m0 and matrix m1 (including translation) is performed.

The result is placed in matrix m2.

The following algorithm is used.

        [m2->m] = [m0->m] * [m1->m]

        (m2->t) = [m0->m] * (m1->t) + (m0->t)

However the values of the m1->t elements must be within the range of [-2^15,2^15) .

The argument format is as follows::

    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

The result matrix m2 is returned.

Notes

This function destroys the rotation matrix.

INDEX


Definitions
#definitions

As #defined in libps.h

Definition	Value
GsDIV1	(1<<9)
GsDIV2	(2<<9)
GsDIV3	(3<<9)
GsDIV4	(4<<9)
GsDIV5	(5<<9)
INDEX


DrawSync

Waits for completion of all drawing

int DrawSync (

        int mode

)

Argument

mode	0: Waits for completion of all non-blocking functions registered in the GPU's command/execution queue.  1: The current slot number of the GPU's command/execution queue is returned.

Return Value

The current slot number of the GPU's command execution queue is returned.

INDEX


FntFlush

Draws the contents of a print stream

u_long* FntFlush (

        int id

)

Arguments

id	Print Stream ID

Explanation

The contents of the specified print stream are drawn in the frame buffer.

FntFlush() initializes and draws a sprite primitive list corresponding to the characters in the specified print stream.

Return Value

A pointer to the start of the OT used for drawing is returned.

Notes

After the drawing is completed, the contents of the print stream are flushed.

INDEX


FntLoad

Loads the system font patterns into the frame buffer

void FntLoad (

        int tx,

        int ty

)

Arguments

tx,ty	Upper left-hand coordinate where the font patterns will be loaded into the frame buffer

Explanation

The system font patterns used for debugging are loaded into the frame buffer beginning at the coordinate specified by (tx,ty).

All print streams are initialized.

The system font patterns are 4-bit textures and require an area of size 256x128.

Return Value

None.

Notes

FntLoad() must always be executed before FntOpen() and FntFlush().

The font area must not overlap with the frame buffer area used by the application.

INDEX


FntOpen
FontOpen

Opens a print stream

int FntOpen (

        int x,

        int y,

        int w,

        int h,

        int isbg,

        int n

)

Arguments

x, y	Display start position
w, h	Display area
isbg	Background auto-clear flag  0: Clear the background to (0,0,0) when displaying  1: Do not clear the background
n	Maximum number of characters that can be drawn

Explanation

The stream used for on-screen printing is opened. Subsequently, character strings up to n characters long can be drawn in the rectangular area of the frame buffer specified by (x,y)-(x+w, y+h) using the FntPrint() function.

If isbg has a value of 1, the background is cleared when a character string is drawn.

Return Value

The ID of the print stream that was opened is returned.

Notes

Up to 8 streams can be opened simultaneously.

Opened streams cannot be closed until the next FntLoad().

INDEX


FntPrint

Sends output to a print stream

int FntPrint (

        int id ,

        char *format,

        ...

)

Arguments

id	Print stream ID
format	Print format string

Explanation

The character string specified as an argument is formatted and sent as output to the specified print stream. Formatting is performed according to format and is identical to the specification of the format string for the C library printf() function.

Return Value

The number of characters in the stream is returned.

Notes

The character string is not displayed until FntFlush() is executed.

Print formatted output to the standard output stream.

INDEX


GetClut

Calculates value of member clut in a primitive

u_short GetClut (

        int x,

        int y

)

Arguments

x, y	Frame buffer address of the CLUT

Explanation

The texture CLUT ID is calculated and its value is returned.

Return Value

The calculated CLUT ID is returned.

Notes

The CLUT address is limited to a multiple of 16 in the x direction.

Calculates primitive CLUT member value.

INDEX


GetTPage

Calculates value of member tpage in a primitive

u_short GetTPage (

        int tp ,

        int abr,

        int x,

        int y

)

Arguments

tp	Texture mode  0: 4-bit CLUT  1: 8-bit CLUT  2: 16-bit Direct
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

The texture page ID of the texture page address specified by (x, y) is calculated and its value is returned.

Return Value

The calculated texture page ID is returned.

Notes

The semi-transparency rate is also valid for polygons for which texture mapping is not performed.

The texture page address is limited to a multiple of 64 in the x direction and a multiple of 256 in the y direction.

INDEX


GsClearOt

Initializes an OT

void GsClearOt (

        u_short offset,

        u_short point,

        GsOT *otp

)

Arguments

offset	Ordering table offset value
point	Ordering table typical Z value
otp	Pointer to an ordering table

Explanation

The ordering table pointed to by otp is initialized.

offset specifies the Z value used for the start of the ordering table.

point specifies a typical Z value for the entire ordering table and is used to set depth priority when multiple ordering tables are linked together.

The length field of the GsOT structure must be properly set before this function is called so that the size of the ordering table to be cleared can be determined.

Return Value

None.

See Also

GsOT, GsDrawOt()

INDEX


GsDefDispBuff

Defines the double buffers used for drawing

void GsDefDispBuff (

        int x0,

        int y0,

        int x1,

        int y1,

)

Arguments

x0, y0	Buffer 0 origin (upper left-hand) coordinates
x1, y1	Buffer 1 origin (upper left-hand) coordinates

Explanation

The display areas in the frame buffer used for double buffering are established. The x0, y0 parameters specify the coordinates within the frame buffer for buffer #0. The x1, y1 parameters specify the coordinates within the frame buffer for buffer #1. If x0, y0 and x1, y1 are specified as the same coordinates in non-interlaced mode, 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 interlaced mode. Normally, buffer #0 is located at (0,0) and buffer #1 is located at (0, yres), where yres is the vertical resolution specified using the GsInitGraph() function.

The GsSwapDispBuff() function is used to swap the double buffers.

Double buffering is implemented using the GPU/GTE offset which can be set using GsInitGraph().

When using the GPU to manage the offset, the double buffer offset will be added at the time of drawing, not at the time of packet creation.

Return Value

None.

See Also

GsInitGraph(), GsSwapDispBuff()

INDEX


GsDrawOt

Execute drawing commands associated with an OT

void GsDrawOt (

        GsOT *otp

)

Arguments

otp	Pointer to an ordering table

Explanation

The drawing commands that are entered in the ordering table pointed to by otp are executed.

Drawing is performed by the GPU.

GsDrawOt() is a non-blocking function and returns immediately.

The actual drawing is performed in the background.

Notes

This function does not execute correctly if it is called when GPU drawing is in progress. ResetGraph(1) should be used to terminate any current drawing process or DrawSync(0) should be used to wait until drawing is completed before this function is called.

Return Value

None.

See Also

GsOT, GsClearOt()

INDEX


GsGetActiveBuff

Gets the drawing buffer index

int GsGetActiveBuff (

        void

)

Arguments

None.

Explanation

The double buffer index (PSDIDX) is obtained and its value is returned.

The value of the index is either 0 or 1.

By entering the index in the external variables PSDOFX[] and PSDOFY[], the two-dimensional address of the double buffer origin (upper left-hand coordinate) in the frame buffer can be obtained.

Return Value

The double buffer index (0 for buffer 0; 1 for buffer 1) is returned.

See Also

PSDIDX

INDEX


GsGetLs

Calculates a local-to-screen transformation matrix

void GsGetLs (

        GsCOORDINATE2 *coord,

        MATRIX *m

)

Arguments

coord	Pointer to a local coordinate system
m	Pointer to result matrix

Explanation

The local-to-screen transformation matrix of the coordinate system pointed to by coord is calculated and the result is stored in the matrix pointed to by m.

The GsCOORDINATE2 structure pointed to by coord describes a node in the hierarchical coordinate system.

When the transformation matrix is calculated, calculation is performed for each node in the hierarchy and results are stored in the workm member within each node of the coordinate system.

To improve performance, calculation is only performed for nodes which have changed, as determined by the value of the flag member, even when GsGetLw() is called repeatedly. It should be noted that when a parent node is changed, all subordinate nodes will be recalculated automatically even if their flag members are set. It is the responsibility of the programmer to clear flag within each node if the member coord has changed, otherwise the transformation matrix will not be calculated correctly.

Return Value

None.

See Also

GsSetLsMatrix()

INDEX


GsGetLw

Calculates a local-to-world transformation matrix

void GsGetLw (

        GsCOORDINATE2 *coord,

        MATRIX *m

)

Arguments

coord	Pointer to a local coordinate system
m	Pointer to the result matrix

Explanation

The local-to-world transformation matrix of the coordinate system pointed to by coord is calculated and the result is stored in the matrix pointed to by m.

The GsCOORDINATE2 structure pointed to by coord describes a node in the hierarchical coordinate system.

When the transformation matrix is calculated, calculation is performed for each node in the hierarchy and results are stored in the workm member within each node of the coordinate system.

To improve performance, calculation is only performed for nodes which have changed, as determined by the value of the flag member, even when GsGetLw() is called repeatedly. However, when a parent node is changed, all subordinate nodes will be recalculated automatically even if their flag members are set. It is the responsibility of the programmer to clear flag within each node if the member coord has changed, otherwise the transformation matrix will not be calculated correctly.

Return Value

None.

See Also

GsGetLws(), GsSetLightMatrix()

INDEX


GsGetLws

Calculates both local-to-world and local-to-screen transformation matrices

void GsGetLws (

        GsCOORDINATE2 *coord2

        MATRIX *lw,

        MATRIX *ls

)

Arguments

coord2	Pointer to local coordinate system
lw	Pointer to local-to-world coordinate system result matrix
ls	Pointer to local-to-screen coordinate system result matrix

Explanation

The local-to-world and the local-to-screen transformation matrices for the coordinate system pointed to by coord2 are calculated and the results are stored in the matrices pointed to by lw and ls , respectively.

The local-to-world matrix must be specified when light source calculation is performed.

GsGetLws() is a fast method for obtaining this matrix.

GsGetLws() is equivalent to calling GsGetLw() followed by GsGetLs(), only with faster performance.

Return Value

None.

See Also

GsGetLs(), GsGetLws(), GsCOORDINATE2, MATRIX

INDEX


GsGetTimInfo

Gets TIM data header

void GsGetTimInfo (

        u_long *tim,

        GsIMAGE *im

)

Arguments

tim	Pointer to TIM data header
im	Pointer to result image structure

Explanation

Information obtained from the TIM data header pointed to by tim is placed in the GsIMAGE structure pointed to by im.

TIM data begins at the address after the ID, which is 4 bytes after the start of the TIM file.

For a description of the TIM file format, please refer to the Net Yaroze Members' Web site.

Return Value

None.

See Also

GsIMAGE

INDEX


GsGetWorkBase

Gets the base address of the drawing command area

PACKET *GsGetWorkBase (

        void

)

Arguments

None

Explanation

The address of the first packet in the drawing command work area is obtained and its value is returned. Note that the type PACKET is defined as an unsigned char in libps.h.

Return Value

The address of the first packet in the drawing command work area is returned.

See Also

GsSetWorkBase(), GsOUT_PACKET_P

INDEX


GsIncFrame

Increments the frame ID

void GsIncFrame (

        void

)

Arguments

None.

Explanation

The global variable PSDCNT is incremented by 1.
PSDCNT is used by GsGetLw(), GsGetLs() and GsGetLws() to determine the validity of the matrix cache when the double buffer is swapped.
PSDCNT is 32 bits in length, and restarts at 1 rather than 0 when it overflows.

GsIncFrame() is automatically called from within GsSwapDispBuff(). If the double buffer is swapped without using GsSwapDispBuff(), but the functions GsGetLw(), GsGetLs() and GsGetLws() are used, GsIncFrame() needs to be called every time the double buffer is swapped.

See Also

GsGetLw(), GsGetLs(), GsGetLws(), GsSwapDispBuff()

INDEX


GsInit3D

Initializes the 3D graphics system

void GsInit3D (

        void

)

Arguments

None

Explanation

Initialises the 3D graphics system within the library.

The 3D graphics system needs to be initialized by this function first, so that 3D processing functions such as GsSetRefView2(), GsInitCoordinate2() and GsSortObject4() can be used.

The following are the steps in the initialization process:

1. The screen origin is reset to the center of the screen.

2. The default light source is set to LIGHT_NORMAL.

Return Value

None.

Notes

It is necessary to initialize the graphics system with GsInitGraph() before calling this function.

See Also

GsInitGraph(), GsSetRefView2(), GsInitCoordinate2(), GsSortObject4()

INDEX


temGsInitCoordinate2
GsInitCoordinate2

Initialize a local coordinate system

void GsInitCoordinate2 (

        GsCOORDINATE2 *super,

        GsCOORDINATE2 *base

)

Arguments

super	Pointer to the parent coordinate system
base	Pointer to the local coordinate system to be initialized

Explanation

The local coordinate system pointed to by base and its parent coordinate system pointed to by super are initialized. The base coordinate system is initialized using base- >coord whereas the parent coordinate system is initialized using super; i.e. the base- >super member is ignored.

Return Value

None.

See Also

GsCOORDINATE2

INDEX


GsInitFixBg16

Initializes high-speed BG work area

void GsInitFixBg16 (

        GsBG *bg,

        u_long *work

)

Arguments

bg	Pointer to a background descriptor
work	Pointer to the work area (primitive area)

Explanation

Initialises the work area used by the GsSortFixBg16() function.

The size of the work area varies with the screen resolution according to the following formula:

Work area size (in long units) = (((ScreenW/CellW+1)*(ScreenH/CellH+1+1)*6+4)*2+2)

where

    ScreenH = screen height in pixels (240/480)

    ScreenW = screen width in pixels (256/320/384/512/640)

    CellH = cell height (in pixels)

    CellW = cell width (in pixels)

GsInitFixBg16() should only be executed once. It does not need to be executed every frame.

Return Value

None.

See Also

GsSortFixBg16(), GsBG

INDEX


GsInitGraph

Initializes the graphics system

void GsInitGraph (

    int x_res,

    int y_res,

    int intl,

    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-interlaced  1: Interlaced  Double Buffer Offset Mode (bit 2)  0: GTE offset  1: GPU offset
dither	Dither processing flag  0: OFF  1: ON
vram	Frame buffer mode  0: 16-bit  1: 24-bit

Explanation

Initialises the graphics system.

The operational settings of the graphics system are reflected in the global variables GsDISPENV and GsDRAWENV. The program can use these global variables to determine the current settings of the graphics system.

The Double Buffer Offset Mode controls the offset that is added to the frame buffer when drawing is performed. This Mode determines whether the offset is managed by GTE or the GPU. When specified as GTE, the offset is added to the drawing address when the drawing packet is created, whereas when specified as GPU, it is added when drawing is performed. Having the GPU manage the offset is usually preferred because the offset is not included in the drawing packet.

In 24-bit mode, the frame buffer can only operate in image display mode and polygons cannot be drawn.

GsInitGraph() must be called to initialise the graphics system and also initialises the internal structures GsIDMATRIX and GsIDMATRIX2. These structures must be initialised before any of the Gs*** functions can be used.

Return Value

None.

INDEX


GsLinkObject4

Links an object to TMD data

void GsLinkObject4 (

        u_long *tmd,

        GsDOBJ2 *obj_base,

        u_long n

)

Arguments

tmd	Pointer to TMD data
obj_base	Pointer to the linking object structure
n	Index of the object to be linked

Explanation

The object pointed to by obj_base is linked to the nth object in the TMD data pointed to by tmd. This allows TMD 3D objects to be handled using GsDOBJ2.

Return Value

None.

Notes

Objects linked by GsLinkObject4() can be registered in ordering table by GsSortObject4().

See Also

GsSortObject4(), GsDOBJ2

INDEX


GsMapModelingData

Maps TMD data to real addresses

void GsMapModelingData (

        u_long *p

)

Arguments

p	Pointer to starting address of TMD data

Explanation

Offsets within the TMD data pointed to by p are converted into real addresses.

The converted addresses are stored back in the TMD data.

TMD data includes various fields which contain the memory addresses of certain pieces of data. During the reparation of TMD data, however, the memory address where the data will be loaded is not yet known. Therefore, address fields in the TMD data are stored as offsets from the start of the data. The GsMapModelingData() function changes these offsets into real addresses after the TMD data has been loaded into memory. This must be done before the TMD data can be used.

TMD data begins at the address after the ID which is 4 bytes after the start of the TMD file.

For a description of the TMD file format, please refer to the Net Yaroze Members' Web site.

Return Value

None.

Notes

A flag is set in the TMD data to indicate that the offset addresses have been converted into real addresses. So, no side effects occur even if GsMapModelingData() is called repeatedly.

INDEX


GsScaleScreen

Scales the screen coordinate system

void GsScaleScreen (

        SVECTOR *scale

)

Arguments

scale	Pointer to the scale vector (each element is a 12-bit integer)

Explanation

The screen coordinate system is scaled relative to the world coordinate system by an amount specified in the vector pointed to by scale.

Each element of scale is a 12-bit integer.

Scaling is performed relative to the original screen coordinate system set by GsSetView2() and GsSetRefView2().

If each element of scale is set to the value ONE, the screen coordinate system is reset to its original values. Note that ONE is defined to be the value 4096.

World coordinates are represented in 32 bits, whereas screen coordinates are represented in 16 bits. The different representations would normally cause problems such as Far Clip proximity. GsScaleScreen() eliminates these problems by scaling the screen coordinate system within the wider area of the world coordinate system. For example, if the elements of scale are each set to ONE/2, the screen coordinate system will be expanded to the equivalent of 17 bits after scaling. Since the precision of screen coordinate values is only 16 bits, the low-order bit will be ignored. Note that when scaling is performed, objects that exist in screen coordinate systems having different scaling factors cannot be entered in the same ordering table. For example, in order to enter an object that was calculated with the normal scale screen coordinate system in an ordering table which already contains an object with a 1/2 scale screen coordinate system, it is necessary to right-shift the excess bit before entering the object in the ordering table. This can be done by specifying the shift amount when calling GsSortObject4().

Return Value

None.

See Also

SVECTOR

INDEX


GsSetAmbient

Set ambient colour

void GsSetAmbient (

        u_short r,

        u_short g,

        u_short b

)

Arguments

r, g, b	RGB values of the ambient colour (0~4095)

Explanation

The ambient colour is set to the RGB value specified by (r, g, b). The r, g, b arguments can pass values up to but not including 4096. A value of 4096 would represent a fixed point value of 1.0 and correspond to normal ambient brightness. A value of 0 corresponds to minimum brightness. A value of 1/8 of normal brightness would be specified with r, g, b values of 4096/8.

Return Value

None.

See Also

GsSetFlatLight(), GsOT, GsClearOt()

INDEX


GsSetClip

Sets the clipping area for drawing

void GsSetClip (

        RECT *clip

)

Arguments

clip	Pointer to RECT structure defining the clipping area

Explanation

The clipping area defined by clip is set as the clipping area for drawing.

This function is different from GsSetDrawBuffClip() in that its argument can be used to specify a clipping area. Note that this clipping value is a relative one within the double buffer, and thus the clipping position will not change even when double buffers are swapped.

The clipping area set by GsSetClip() is valid only within the current drawing buffer and becomes invalid when the buffers are swapped using GsSwapDispBuff(). This is because GsSwapDispBuff() calls GsSetDrawBuffOffset() which sets the clipping area from the clip member in the global variable GsDRAWENV. This value is obtained from the global variable CLIP2.

Return Value

None.

Notes

This function does not execute correctly if it is called when GPU drawing is in progress. ResetGraph(1) should be used to terminate any current drawing process or DrawSync(0) should be used to wait until drawing is completed before this function is called.

See Also

GsSetDrawBuffClip()

INDEX


GsSetClip2D

Sets a 2-dimensional clipping area

void GsSetClip2D (

        RECT *rectp

)

Arguments

rectp	Pointer to a 2D clipping area

Explanation

The 2D area pointed to by rectp is set as the clipping area.

The clipping area is not affected by double buffer swapping, so the same area is automatically clipped regardless of which buffer is active.
GsSetDrawBuffClip() must be called in order for the clip area to take effect immediately. Otherwise, the setting becomes valid with the next frame.

Return Value

None.

See Also

GsSetDrawBuffClip(), RECT

INDEX


GsSetDrawBuffClip

Sets the clipping area for drawing

void GsSetDrawBuffClip (

        void

)

Arguments

None.

Explanation

The clipping area used in drawing is updated with the value that was set using GsSetClip2D().

The clipping value is relative within the double buffers. In other words, the clipping position does not change when the double buffers are swapped.

Return Value

None.

Notes

This function does not execute correctly if it is called when GPU drawing is in progress. ResetGraph(1) should be used to terminate any current drawing process or DrawSync(0) should be used to wait until drawing is completed before this function is called.

See Also

GsSetClip2D(), GsSetClip()

INDEX


GsSetDrawBuffOffset

Sets the drawing offset

void GsSetDrawBuffOffset (

        void

)

Arguments

None.

Explanation

Updates the drawing offset using the value defined in the global variable POSITION.

The drawing offset is used for double buffer swapping, can be managed by the GTE or the GPU and is a relative offset within the double buffer.

The offset value is preserved even when double buffers are swapped.

The third argument of GsInitGraph() determines whether the offset is managed by the GTE or the GPU.

Return Value

None.

Notes

This function does not execute correctly if it is called when GPU drawing is in progress.
ResetGraph(1) should be used to terminate any current drawing process or DrawSync(0) should be used to wait until drawing is completed before this function is called.

See Also

GsSetOrign(), GsSetOffset(), POSITION

INDEX


GsSetFlatLight

Sets a parallel light source

void GsSetFlatLight (

        u_short id,

        GsF_LIGHT *lt

)

Arguments

id	Light source number (0,1,2)
lt	Pointer to light source information

Explanation

The parallel light source specified by id is set according to the GsF_LIGHT information pointed to by lt. Up to three separate light sources can be set (id = 0, 1, 2).

Return Value

None.

Notes

When the contents of the GsF_LIGHT structure are overwritten, the new values will not be reflected in the light source until GsSetFlatLight() is called.

See Also

GsF_LIGHT, GsSetAmbient()

INDEX


GsSetFogParam

Sets the fog parameter

void GsSetFogParam (

        GsFOGPARAM *fogparam

)

Arguments

fogparam	Pointer to a fog parameter structure

Explanation

The fog parameter is set according to the GsFOGPARAM structure pointed to by fogparam.

Fog is only effective if the light source mode is 1 (see GsSetLightMode()).

Return Value

None.

See Also

GsFOGPARAM, GsSetLightMode()

INDEX


GsSetLightMatrix

Sets the light matrix

void GsSetLightMatrix (

        MATRIX *mp

)

Arguments

mp	Pointer to a local screen light matrix

Explanation

The local screen light matrix pointed to by mp is multiplied by the matrix of three light vectors and the result is set as the light matrix in GTE.

The light matrix needs to be set in GTE prior to performing light source calculations.

Depending on the type of model data, the GsSortObject4() function may perform light source calculation at the time of execution. In this case, the light matrix needs to be preset using GsSetLightMatrix().

The matrix mp specified as the argument to GsSetLightMatrix() is normally a local world matrix.

Return Value

None.

See Also

GsSortObject4(), GsGetLw(), MATRIX

INDEX


GsSetLightMode

Sets the default light source mode

void GsSetLightMode (

        u_short mode

)

Arguments

mode	Light source mode (0~1)  0: normal lighting  1: normal lighting with fog ON

Explanation

The default light source mode is set to the value specified by mode. This mode can also be set independently for each object using the attribute member of GsDOBJ2. Bit 5 of attribute determines whether the light source mode is set by the GsDOBJ2 attribute field or by the mode set with GsSetLightMode(). See the description of GsDOBJ2 for more information.

Return Value

None.

INDEX


GsSetLsMatrix

Sets the local screen matrix

void GsSetLsMatrix (

        MATRIX *mp

)

Arguments

mp	Pointer to a local screen matrix

Explanation

The local screen matrix pointed to by mp is set as the local screen matrix in GTE.

This matrix in the GTE needs to be set prior to performing perspective transformation using a function such as GsSortObject4().

Return Value

None.

See Also

GsSortObject4(), GsGetLs(), MATRIX

INDEX


GsSetOffset

Sets the drawing offset

void GsSetOffset (

        int offx,

        int offy

)

Arguments

offx	Drawing offset X coordinate
offy	Drawing offset Y coordinate

Explanation

The value of the drawing offset is set to (offx, offy).

GsSetOffset() differs from GsSetDrawBuffOffset() in that GsSetDrawBuffOffset() sets the offset to the value specified by the global variable POSITION, whereas GsSetOffset() sets the offset to the value specified by the argument.

The value set by GsSetOffset() is temporary in that it does not update the global variable POSITION and is only valid within the current draw buffer. This is because when the double buffer is swapped, GsSwapDispBuff() calls GsSetDrawBuffOffset() which sets the offset from the global variable POSITION. This value remains valid until it is changed by GsSetOrign().

The offset specified as an argument is a relative offset inside the double buffer. In other words, the offset is added to the double buffer base to calculate the drawing address. The third argument of GsInitGraph() determines whether the offset is managed by the GTE or the GPU.

Return Value

None.

Notes

This function does not execute correctly if it is called when GPU drawing is in progress. ResetGraph(1) should be used to terminate any current drawing process or DrawSync(0) should be used to wait until drawing is completed before this function is called.

See Also

GsSetDrawBuffOffset()

INDEX


GsSetOrign

Sets the drawing offset of the screen origin

void GsSetOrign (

        int x,

        int y

)

Arguments

x	Screen origin position X
y	Screen origin position Y

Explanation

The screen origin specified by (x, y) is set as the drawing offset in the global variable POSITION.

GsSetOrign() sets the drawing offset in the global variable POSITION but it does not set it in the GPU. In other words, the new offset will not take effect until a function such as GsSetDrawBuffOffset() that sets the GPU drawing offset is called. The offset value in the global variable POSITION is valid until GsSetOrgn() is called again. The offset specified by (x, y) is relative within the double buffer. In other words, the values (x, y) are added to the double buffer base. In reality, the offset is set by the offx and offy members of the global variable POSITION.

Notes

The third argument of GsInitGraph() determines whether the offset is executed by GTE or by GPU and is specified using GsOFSGTE (#defined as 0 in libps.h) or GsOFSGPU (#defined as 4 in libps.h), respectively.

Return Value

None.

INDEX


GsSetProjection

Sets the projection distance

void GsSetProjection (

        u_short h

)

Arguments

h	Projection distance

Explanation

Sets the projection distance to h.

The projection distance is the distance between the viewpoint and the projection plane.

The size of the projection plane is specified by the (xres, yres) arguments to GsInitGraph(). This size is constant for a given resolution. This means that the field of view decreases as the projection distance is increased, and conversely, the field of view increases as the projection distance is decreased.

As shown in the table below, the aspect ratio is a function of the screen resolution and may not always be 1 to 1. In particular, when the resolution is 640 x 240, the X coordinate should be scaled by 1/2 to compensate.

Resolution	640x480	640x240	320x240
Aspect ratio	1:1	2:1	1:1

Return Value

None.

INDEX


GsSetRefView2

Sets the viewpoint position

int GsSetRefView2 (

        GsRVIEW2 *pv

)

Arguments

pv	Pointer to viewpoint position information (reference type)

Explanation

The World Screen Matrix (WSMATRIX) is calculated using the viewpoint information pointed to by pv. Since WSMATRIX does not change unless the viewpoint is moved, this function need not be called for each frame. However, if the viewpoint is moved, GsSetRefView2() must be called for changes to be reflected in each frame. GsSetRefView2() should be called each frame if the GsRVIEW2 member super is set to anything other than WORLD. In this case, the viewpoint will move if the parameters of  the parent coordinate system change even if the other viewpoint parameters have not changed.

Return Value

0 is returned if the viewpoint was successfully set, otherwise, 1 is returned.

See Also

GsRVIEW2, GsWSMATRIX, GsSetView2()

INDEX


GsSetView2

Sets the viewpoint position

int GsSetView2 (

        GsVIEW2 *pv

)

Arguments

pv	Pointer to viewpoint position information (matrix type)

Explanation

The World Screen (WS) matrix is directly set from the viewpoint information pointed to by pv.

When GsSetRefView2() is used to determine the WS matrix from the viewpoint, errors may occur when the viewpoint is moved due to insufficient precision in the operation. For this reason it is usually better to use GsSetView2(). GsSetView2() should be called each frame if the GsRVIEW2 member super is set to anything other than WORLD. In this case, the viewpoint will move if the parameters of the parent coordinate system change even if the other viewpoint parameters have not changed.

If GsIDMATRIX2 is used as the base matrix, then the aspect ratio of the screen will be adjusted automatically.

Return Value

0 is returned if the viewpoint was successfully set, otherwise, 1 is returned.

See Also

GsVIEW2, GsWSMATRIX, GsSetRefView2()

INDEX


GsSetWorkBase

Sets the base address of the drawing command area

void GsSetWorkBase (

        PACKET *base_addr

)

Arguments

base_addr	Pointer to the first PACKET of the drawing command area

Explanation

The address of the packet at the start of the drawing command work area is set to the address specified by base_addr.

The drawing command work area is used by functions such as GsSortObject4() and GsSortSprite().

This function must be called at the start of processing for each frame.

base_addr should be set to the starting address of the packet area allocated by the user.

Note that the type PACKET is defined as an unsigned char in libps.h.

Return Value

None.

See Also

GsSortObject4(), GsSortSprite(), GsSortFastSprite(), GsOUT_PACKET_P

INDEX


GsSortBG

INDEX


GsSortBoxFill

Enters a rectangle in an OT

void GsSortBoxFill (

        GsBOXF *bp,

        GsOT *otp,

        u_short pri,

)

Arguments

bp	Pointer to a rectangle descriptor
otp	Pointer to an ordering table
pri	Position in the ordering table

Explanation

The rectangle pointed to by bp is entered into the ordering table pointed to by otp at position pri.

Return Value

None.

See Also

GsBOXF, GsOT

INDEX


GsSortClear

Enters a Clear Screen command in an OT

void GsSortClear (

        u_char r,

        u_char g,

        u_char b,

        GsOT *otp

)

Arguments

r, g, b	Background colour RGB values
otp	Pointer to an ordering table

Explanation

A Clear Screen command is entered at the beginning of the ordering table pointed to by otp.

Return Value

None.

Notes

GsSortClear() merely enters the Clear Screen command in the ordering table.

The screen will not actually be cleared until GsDrawOT() is called.

See Also

GsOT

INDEX


GsSortFastSprite

Enters a sprite in an OT

void GsSortFastSprite (

        GsSPRITE *sp,

        GsOT *otp,

        u_short pri

)

Arguments

sp	Pointer to a sprite
otp	Pointer to an ordering table
pri	Position in the ordering table

Explanation

The sprite pointed to by sp is entered into the ordering table pointed to by otp.

The parameters of the sprite, such as its display position, are provided by the members of GsSPRITE.

pri is the priority (i.e. position) of the sprite in the ordering table. The highest priority is obtained by setting pri to 0. The lowest priority is determined by the size of the ordering table. If the value of pri is greater than the size of the ordering table, it is clipped to the maximum size.

GsSortFastSprite() provides higher speed processing than GsSortSprite(), however, scaling and rotation cannot be used. The GsSPRITE members mx, my, scalex, scaley, and rotate are ignored.

Return Value

None.

See Also

GsSortSprite(), GsSPRITE

INDEX


GsSortFixBg16

Enters a background descriptor in an OT at high speed

void GsSortFixBg16 (

        GsBG *bg,

        u_long *work,

        GsOT *otp,

        u_short pri

)

Arguments

bg	Pointer to a background descriptor
work	Pointer to the work area (primitive area) initialized with GsInitFixBg16()
otp	Pointer to an ordering table
pri	Position in the ordering table

Explanation

The background image pointed to by bg is entered into the ordering table pointed to by otp at position pri.

GsSortFixBg16() has the following features and restrictions:

· BG rotation and scaling cannot be performed.

· Cell size is fixed (16x16).

· Only texture pattern colour modes 4-bit and 8-bit are supported.

· Map size is optional.

· Scrolling is permitted in 1 pixel units.

· Only full screen mode is supported.

This function uses the work area pointed to by work to store drawing primitives.

The work area must be initialized in advance by GsInitFixBg16().

The packet area set with GsSetWorkBase() is not used.

Return Value

None.

See Also

GsInitFixBg16(), GsBG, GsOT

INDEX


GsSortGLine

Enters a graded straight line in an OT

void GsSortGLine (

        GsGLINE *lp ,

        GsOT *otp,

        u_short pri

)

Arguments

lp	Pointer to a graded straight line descriptor
otp	Pointer to an ordering table
pri	Position in the ordering table

Explanation

The graded straight line pointed to by lp is entered into the ordering table pointed to by otp at position pri.

GsSortGLine() handles straight lines and GsSortLine() handles single-colour straight lines.

Return Value

None.

See Also

GsSortLine(), GsLINE, GsOT

INDEX


GsSortLine

Enters a single-colour straight line in an OT

void GsSortLine (

        GsLINE *lp ,

        GsOT *otp,

        u_short pri

)

Arguments

lp	Pointer to a single-colour straight line descriptor
otp	Pointer to an ordering table
pri	Position in the ordering table

Explanation

The single colour straight line pointed to by lp is entered into the ordering table pointed to by otp at position pri.

GsSortLine() handles single colour straight lines and GsSortGLine() handles straight lines with gradation.

Return Value

None.

See Also

GsSortGLine(), GsLINE, GsOT

INDEX


GsSortObject4

Inserts an object in an OT

void GsSortObject4 (

        GsDOBJ2 *objp,

        GsOT *otp,

        long shift,

        u_long *scratch

)

Arguments

objp	Pointer to a GsDOBJ2 object
otp	Pointer to an ordering table
shift	Number of bits the Z value will be right-shifted when the object is entered in the ordering table
scratch	Pointer to a scratchpad buffer

Explanation

Performs perspective transformation and light source calculation for the 3D object pointed to by objp.

Generates drawing commands for the object and stores those commands at the packet area work base address, previously specified with GsSetWorkBase().

Z-sorts the drawing commands and enters them in the ordering table pointed to by otp, shifting the Z values by an amount specified by shift. The precision of Z may be adjusted using shift. The maximum size of the ordering table (i.e. its resolution) is 14 bits and is specified in the GsOT structure. The value of shift must be set so that the area allocated to the ordering table will not be exceeded when the object is entered. For example, if the size of the ordering table is 12 bits, the shift value must be set to 14-12, or 2.

scratch is a pointer to the Scratchpad buffer which is used when automatic polygon subdivision is being performed on the object. The size of the Scratchpad buffer is 1024 bytes. The Scratchpad allows access to the Data Cache on the R3000. Using the Cache provides much faster access than main memory RAM for time-critical operations such as polygon subdivision. The Scratchpad is memory-mapped from addresses 0x1F800000 to 0x1F8003FF. Automatic polygon subdivision is enabled by setting the appropriate bits in the attribute member of GsDOBJ2. Subdivision is enabled by ORing the attribute member with one of the macros GSDIV1 through GsDIV5 which are defined in libps.h. For example, if GsDIV1 is specified, a single polygon will be divided into 4 segments of 2 x 2. If GsDIV5 is specified, a single polygon will be divided into 1024 segments of 32 x 32.

Return Value

None.

See Also

GsDOBJ2, GsOT, GsSetWorkBase()

INDEX


GsSortOt

Inserts a source OT into a destination OT

GsOT *GsSortOt (

        GsOT *ot_src,

        GsOT *ot_dest

)

Arguments

ot_src	Pointer to source ordering table
ot_dest	Pointer to destination ordering table

Explanation

The source ordering table pointed to by ot_src is inserted into the destination ordering table pointed to by ot_dest.

The typical Z value of the source ordering table used for the insertion operation is given by the point member of ot_src.

Return Value

ot_dest, the pointer to the combined ordering table is returned.

See Also

GsOT

INDEX


GsSortSprite

Enters a sprite in an OT

void GsSortSprite (

        GsSPRITE *sp,

        GsOT *otp,

        u_short pri

)

Arguments

sp	Pointer to a sprite
otp	Pointer to an ordering table
pri	Position in the ordering table

Explanation

The sprite pointed to by sp is entered into the ordering table pointed to by otp.

The parameters of the sprite, such as its display position, are provided by the members of GsSPRITE.

pri is the priority (i.e. position) of the sprite in the ordering table. The highest priority is obtained by setting pri to 0. The lowest priority is determined by the size of the ordering table. If the value of pri is greater than the size of the ordering table, it is clipped to the maximum size.

Return Value

None.

See Also

GsOT, GsSPRITE, GsSortFastSprite()

INDEX


GsSwapDispBuff

Swaps double buffers

void GsSwapDispBuff (

        void

)

Arguments

None.

Explanation

The display buffer and drawing buffer that were defined using GsDefDispBuff() are swapped.

Swapping is usually performed immediately after the start of the vertical blanking interval.

GsSwapDispBuff() performs the following functions:

1. Sets display starting address

2. Cancels blanking

3. Sets double buffer index

4. Switches two-dimensional clipping

5. Sets GTE or GPU offset

6. Increments PSDCNT

Note: Double buffering is implemented using an offset. The third argument of GsInitGraph() determines whether the offset is managed by the GTE or the GPU.

Return Value

None.

Notes

This function does not execute correctly if it is called when GPU drawing is in progress.
ResetGraph(1) should be used to terminate any current drawing process or DrawSync(0) should be used to wait until drawing is completed before this function is called.

See Also

GsDefDispBuff()

INDEX


gteMIMefunc

Adds a vertex data vector to a differential data vector multiplied by a control coefficient

void gteMIMefunc (

        SVECTOR *otp,

        SVECTOR *dfp,

        long n,

        long p

)

Arguments

otp	Pointer to vertex data vector (input/output)
dfp	Pointer to differential data vector (input)
n	Number of vertices (differentials)
p	MIMe weight (control) coefficient

Explanation

The vertex data vector otp is added to the product of the differential data vector dfp and the MIMe control coefficient p, and the result is stored back in the vertex data vector otp.

p is considered to be a 12-bit integer.

This following program fragment illustrates the algorithm that is used:

void gteMIMefunc(SVECTOR *otp, SVECTOR *dfp, long n, long 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;

    }

}

The argument format is as follows:

    p: (1,19,12)

    otp, dfp optional

Return Value

None.

See Also

SVECTOR

INDEX


KanjiFntClose

Closes a print stream

int KanjiFntClose (

        void

)

Arguments

None.

Explanation

All streams currently open and used by KanjiFntPrint() are initialized and cleared.

Return Value

None.

Notes

Since KanjiFntClose() only initializes the internal state, this function completes even when there is no stream open.

See Also

KanjiFntPrint()

INDEX


KanjiFntFlush

Draws the contents of a print stream

u_long *KanjiFntFlush (

        int id

)

Arguments

id	Print Stream ID

Explanation

The contents of the specified print stream are drawn in the frame buffer.

KanjiFntFlush() initializes and draws a sprite primitive list corresponding to the characters in the specified print stream.

Return Value

A pointer to the start of the ordering table used for drawing is returned.

Notes

After drawing is completed, the contents of the print stream are flushed.

See Also

KanjiFntPrint()

INDEX


KanjiFntLoad

Loads the system font patterns into the frame buffer

int KanjiFntLoad (

        int tx,

        int ty

)

Arguments

tx, ty	Upper left-hand coordinate where the font patterns will be loaded into the frame buffer

Explanation

The system font patterns used for debugging are loaded into the frame buffer beginning at the coordinate specified by (tx,ty).

All print streams are initialized.

Return Value

None.

Notes

KanjiFntLoad() must always be executed before KanjiFntOpen() and KanjiFntFlush().

The font area must not overlap with the frame buffer area used by the application.

INDEX


KanjiFntOpen

Opens a print stream

int KanjiFntOpen (

        int x,

        int y,

        int w,

        int h,

        int dx,

        int dy,

        int cx,

        int cy,

        int isbg,

        int n

)

Arguments

x, y	Display start positions
w, h	Display area
dx,dy	Kanji font pattern frame buffer address
cx,cy	Kanji CLUT frame buffer address
isbg	Background auto-clear flag  0: Clear the background to (0,0,0) when displaying  1: Do not clear the background
n	Maximum number of characters that can be drawn

Explanation

The stream used for on-screen printing is opened.

Subsequently, character strings up to n characters long can be drawn in the rectangular area of the frame buffer specified by (x,y)-(x+w, y+h) using the KanjiFntPrint() function.

If isbg has a value of “1”, the background is cleared when a character string is drawn.

Return Value

The ID of the print stream that was opened is returned.

Notes

Up to 8 streams can be opened simultaneously.

Opened streams cannot be closed until the next KanjiFntLoad().

The Kanji font area must not overlap with the frame buffer area used by the application.

See Also

KanjiFntPrint(), KanjiFntLoad()

INDEX


KanjiFntPrint

Sends output to a print stream

int KanjiFntPrint (

        int id ,

        char *format,

        ...

)

Arguments

id	Print stream ID
format	Print format

Explanation

The SHIFT-JIS full-width character string specified as an argument is formatted and sent as output to the specified print stream.

Formatting is performed according to the format string and is identical to the specification of the format string for the C library printf() function.

Return Value

The number of characters in the stream is returned.

Notes

The Kanji code must be SHIFT-JIS.

Full-width and half-width characters can be mixed in the character string, but they are all changed to full-width at the time of display.

Half-width kana are not supported.

The character string is not displayed until KanjiFntFlush() is executed.

See Also

KanjiFntFlush()

INDEX


Krom2Tim

Converts a SHIFT-JIS character string to 4-bit CLUT TIM data

int Krom2Tim (

        u_char *sjis,

        u_long *taddr,

        int dx,

        int dy,

        int cx,

        int cy,

        u_int fg ,

        u_int bg

)

Arguments

sjis	SHIFT-JIS Character String
taddr	Pointer to TIM data result storage area
dx, dy	x,y coordinates of pixel data in VRAM
cx, cy	x,y coordinates of CLUT data in VRAM
fg , bg	Foreground and background colours

Explanation

The SHIFT-JIS character string specified by sjis is converted to 4-bit CLUT TIM data.

The result is placed in the buffer pointed to by taddr.

Return Value

0 is returned when conversion is successful.

-1 is returned when the code specified by sjis is invalid.

Notes

The Kanji code must be SHIFT-JIS encoded.

Full-width and half-width characters can be mixed in the character string, but they are all changed to full-width at the time the characters are displayed.

Half-width kana are not supported.

For the area specified by taddr, the size shown in the following formula must be allocated in advance:

128 x (length of character string specified by sjis) + 84(bytes)

INDEX


Krom2Tim2

Converts a SHIFT-JIS character string to 4-bit CLUT TIM data

int Krom2Tim2 (

        u_char *sjis,

        u_long *taddr,

        int dx,

        int dy,

        int cdx,

        int cdy,

        u_int fg ,

        u_int bg

)

Arguments

sjis	SHIFT-JIS Character String
taddr	Pointer to TIM data result storage area
dx, dy	x,y coordinates of pixel data in VRAM
cx, cy	x,y coordinates of CLUT data in VRAM
fg , bg	Foreground and background colours

Explanation

The SHIFT-JIS character string specified by sjis is converted to 4-bit CLUT TIM data.

The result is placed in the buffer pointed to by taddr. Krom2Tim2() is the user-defined character version of Krom2Tim().

Return Value

0 is returned when conversion is successful.

-1 is returned when the code specified by sjis is invalid.

Notes

The Kanji code must be SHIFT-JIS encoded.

Full-width and half-width characters can be mixed in the character string, but they are all changed to full-width at the time the characters are displayed.

Half-width kana are not supported.

For the area specified by taddr, the size shown in the following formula must be allocated in advance, where num is the length of the string specified by sjis.

If (num<16)

 (32 * num + 16) * 4 (bytes)

else

 (32 * 16* ((num-1/16 + 1) +16) * 4 (bytes)

INDEX


LoadImage

Transfers image data from memory to the frame buffer

int LoadImage (

        RECT *recp,

        u_long *p

)

Arguments

recp	Pointer to the destination rectangular area in the frame buffer
p	Pointer to the source area in main memory

Explanation

Data from the source area in main memory pointed to by p is transferred to the rectangular area of the frame buffer pointed to by recp.

Return Value

The slot number of the GPU’s draw/command queue where the command resides is returned.

Notes

LoadImage() is a non-blocking function, therefore DrawSync() must be used to determine the completion of transfer. The transfer is not affected by clipping or offsetting that may be in effect for the drawing environment. The transfer area must be located within a drawable area: (0,0) - (1023,511).

INDEX


MoveImage

Transfers data within the frame buffer

int MoveImage (

        RECT *recp,

        int x,

        int y

)

Arguments

recp	Pointer to source rectangle in the frame buffer
x, y	Pointer to upper left-hand corner of the destination rectangle in the frame buffer

Explanation

The rectangular area in the frame buffer specified by recp is transferred to a rectangular area of the same size starting at location x,y in the frame buffer.

Return Value

The slot number of the GPU’s draw/command queue where the command resides is returned.

Notes

MoveImage() is a non-blocking function, therefore DrawSync() must be used to determine the completion of transfer. The transfer is not affected by clipping or offsetting that may be in effect for the drawing environment. The transfer area must be located within a drawable area: (0,0) - (1023,511). The contents of the source are unaffected by the transfer. If the source and destination areas are the same, the results are unpredictable.

INDEX


MulMatrix0

Multiplies two matrices

MATRIX* MulMatrix0 (

        MATRIX *m0,

        MATRIX *m1,

        MATRIX *m2

)

Arguments

m0, m1	Pointers to input matrices
m2	Pointer to result matrix

Explanation

Matrix m0 is multiplied by matrix m1 and the result is stored in matrix m2.

The argument format is as follows::

 m0,m1,m2->m[i][j] : (1,3,12)

Notes

This function destroys the rotation matrix.

See Also

MATRIX

INDEX


PopMatrix

Pops the rotation matrix off the stack

void PopMatrix (

        void

)

Arguments

None.

Explanation

The rotation matrix is popped off the stack.

Return Value

None.

INDEX


PushMatrix

Pushes the rotation matrix onto the stack

void PushMatrix (

        void

)

Arguments

None.

Explanation

The rotation matrix is pushed onto the stack. The stack has a maximum of 20 slots.

Return Value

None.

INDEX


PutDispEnv

Sets the display environment

DISPENV *PutDispEnv (

        DISPENV *env

)

Arguments

env	Pointer to the display environment

Explanation

The basic parameters of the display environment are established according to the display environment pointed to by env.

The display environment becomes effective immediately when the function is called.

Return Value

A pointer to the new display environment is returned if the function succeeded.

0 is returned if PutDispEnv() failed to set the new display environment.

Notes

The drawing environment specified by PutDispEnv() is valid until the next call to PutDispEnv() or GsSwapDispBuff().

See Also

GsSwapDispBuff(), DISPENV

INDEX


PutDrawEnv

Sets the drawing environment

DRAWENV *PutDrawEnv (

        DRAWENV *env

)

Arguments

env	Pointer to the drawing environment

Explanation

The basic parameters of the drawing environment (e.g. drawing offset and drawing clip area) are established according to the drawing environment pointed to by env.

Return Value

A pointer to the new drawing environment is returned if the function succeeded.

0 is returned if PutDrawEnv() failed to set the new drawing environment.

Notes

The drawing environment specified by PutDrawEnv() is valid until the next call to PutDrawEnv() or GsSwapDispBuff().

See Also

GsSwapDispBuff(), DRAWENV

INDEX


ResetGraph

Initializes the graphics system

int ResetGraph (

        int mode

)

Arguments

mode	Specifies the reset mode as indicated below.  0: Full reset. The drawing environment and display environment are initialized.  1: The current drawing is cancelled and the command queue is flushed.

Explanation

The graphics system is reset with the mode specified by mode.

Return Value

None.

INDEX


RotMatrix

Calculates a rotation matrix from a rotation vector

MATRIX* RotMatrix (

        MATRIX *m

        SVECTOR *r

)

Arguments

m	Pointer to output rotation matrix
r	Pointer to input rotation vector

Explanation

The rotation matrix m is calculated from the rotation vector (r->vx, r->vy, r->vz).

In the rotation vector, 360 degrees; is represented as 4096, and 4096 is equivalent to 1.0 in each element.

The matrix is an expansion of the following product:

	[	1      0     0   0    c0   -s0   0    s0     c0	] * [	c1    0    s1 0     1     0 -s1   0    c1	] * [	c2   -s2    0 s2     c2    0 0       0     1	]
Using GTE coordinate transformation, the vectors are multiplied from the right. Thus the matrix rotates around the Z, Y and X axes in that order.

Angle value:

c0=cos(r->vx), s0=sin(r->vx)

c1=cos(r->vy), s1=sin(r->vy)

c2=cos(r->vz), s2=sin(r->vz)

The argument format is as follows:

    m->m[i][j] : (1,3,12)

    r->vx,vy,vz :(1,3,12) (however 360 degrees; is 1.0)

Return Value

The rotation matrix m is returned.

See Also

MATRIX, SVECTOR

INDEX


RotMatrixX

Rotates a matrix around the X-Axis

MATRIX* RotMatrixX (

        long r,

        MATRIX *m

)

Arguments

r	Input rotation amount
m	Pointer to the matrix (used for both input and result)

Explanation

The matrix m is rotated around the X-axis by an amount specified by r.

In the rotation amount, 360 degrees; is represented as 4096, and 4096 is equivalent to 1.0.

The matrix is calculated as follows:

	[	1    0     0 0    c    -s 0    s     c	]* m
Angle value:

c=cos(r), s=sin(r)

The argument format is as follows:

    m->m[i][j] : (1,3,12)

    r: (1,3,12) (however 360 degrees; is 1.0)

Return Value

The rotated matrix m is returned.

See Also

MATRIX

INDEX


RotMatrixY

Rotates a matrix around the Y-Axis

MATRIX* RotMatrixY (

        long r,

        MATRIX *m

)

Arguments

r	Input rotation amount
m	Pointer to the matrix (used for both input and result)

Explanation

The matrix m is rotated around the Y-axis by an amount specified by r.

In the rotation amount, 360 degrees; is represented as 4096, and 4096 is equivalent to 1.0.

The matrix is calculated as follows:

	[	c    0    -s 0    1     0 c    0     c	]* m
Angle value:

c=cos(r), s=sin(r)

The argument format is as follows.

    m->m[i][j] : (1,3,12)

    r: (1,3,12) (however 360 degrees; is 1.0)

Return Value

The rotated matrix m is returned.

See Also

MATRIX

INDEX


RotMatrixZ

Rotates a matrix around the Z-Axis

MATRIX* RotMatrixZ (

        long r,

        MATRIX *m

)

Arguments

r	Input rotation amount
m	Pointer to the matrix (used for both input and result)

Explanation

The matrix m is rotated around the Z-axis by the amount specified by r.

In the rotation amount, 360 degrees; is represented as 4096, and 4096 is equivalent to 1.0.

The matrix is calculated as follows:

	[	c    -s    0 s     c     0 0    0     1	]* m
Angle value:

c=cos(r), s=sin(r)

The argument format is as follows.

    m->m[i][j] : (1,3,12)

    r: (1,3,12) (however 360 degrees; is 1.0)

Return Value

The rotated matrix m is returned.

See Also

MATRIX

INDEX


ScaleMatrix

Scales a matrix

MATRIX* ScaleMatrix (

        MATRIX*m,

        VECTOR*v

)

Arguments

m	Pointer to matrix (both input and result)
v	Pointer to scale vector

Explanation

The matrix m is scaled by an amount specified by the scale vector v.

Each element of v is an integer with 4096 equivalent to 1.0.

If

	m =[	a00   a01   a02 a10   a11   a12 a20    a21   a22	]
and

v = [sx  sy  sz]

then

	m = [	a00*sx   a01*sy   a02*sz a10*sx   a11*sy   a12*sz a20*sx    a21*sy   a22*sz	]
The argument format is as follows:

    m->m[i][j] : (1,3,12)

    v->vx,vy,vz : (1,19,12)

Return Value

The scaled matrix m is returned.

See Also

MATRIX, VECTOR

INDEX


ScaleMatrixL

Scales a matrix

MATRIX* ScaleMatrixL (

        MATRIX*m,

        VECTOR*v

)

Arguments

m	Pointer to matrix (both input and result)
v	Pointer to scale vector

Explanation

The matrix m is scaled by an amount specified by the scale vector v.

Each element of v is an integer with 4096 equivalent to 1.0.

If

	m =[	a00   a01   a02 a10   a11   a12 a20    a21   a22	]
and

v = [sx  sy  sz]

then

	m = [	a00*sx   a01*sy   a02*sz a10*sx   a11*sy   a12*sz a20*sx    a21*sy   a22*sz	]
The argument format is as follows:

    m->m[i][j] : (1,3,12)

    v->vx,vy,vz : (1,19,12)

Return Value

The scaled matrix m is returned.

See Also

MATRIX, VECTOR

INDEX


SetDispMask

Sets the display mask

void SetDispMask (

        int mask

)

Arguments

mask	0: Inhibits screen display  1: Enables screen display

Explanation

The display is turned on or off according to the value of mask.

Return Value

None.

INDEX


StoreImage

Transfers image data from the frame buffer to memory

int StoreImage (

        RECT *recp,

        u_long *p

)

Arguments

recp	Pointer to the source rectangular area in the frame buffer
p	Pointer to the upper left-hand corner of the destination rectangular area in main memory

Explanation

Data from the rectangular area pointed to by recp is transferred to the destination rectangular area in main memory pointed to by p.

Return Value

The slot number of the GPU’s draw/command queue where the command resides is returned.

Notes

StoreImage() is a non-blocking function, therefore DrawSync() must be used to determine the completion of transfer. The transfer is not affected by clipping or offsetting that may be in effect for the drawing environment. The transfer area must be located within a drawable area: (0,0) - (1023,511).

INDEX


TransMatrix

Translates a matrix

MATRIX* TransMatrix (

        MATRIX*m,

        VECTOR*v

)

Arguments

m	Pointer to the matrix (used for both input and result)
v	Pointer to the translation vector

Explanation

The matrix m is translated by an amount specified by the translation vector v.

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

The translated matrix m is returned.

See Also

MATRIX, VECTOR

INDEX


TransposeMatrix

Transposes a matrix

MATRIX* TransposeMatrix (

        MATRIX*m0

        MATRIX*m1

)

Arguments

m0	Pointer to input matrix
m1	Pointer to result matrix

Explanation

The transpose of matrix m0 is calculated and the result is placed in matrix m1.

The argument format is as follows:

    m0->m[i][j] : (1,3,12)

    m1->m[i][j] : (1,3,12)

Return Value

The transposed matrix m1 is returned.

See Also

MATRIX

INDEX


Graphics External Variables

Variable	Type	Description
CLIP2	RECT	2-dimensional clipping area.
PSDOFSX[2]	u_short	Double buffer base point (X coordinate)  Set by GsDefDispbuff()
PSDOFSY[2]	u_short	Double buffer base point (Y coordinate)  Set by GsDefDispbuff()
PSDIDX	u_short	Double buffer index
PSDCNT	u_long	Number incremented by frame buffer switch
POSITION	_GsPOSITION	2-dimensional offset
GsDRAWENV	DRAWENV	Drawing Environment
GsDISPENV	DISPENV	Display Environment
GsLSMATRIX	MATRIX	Local screen matrix  Set by GsSetLs()
GsWSMATRIX	MATRIX	World screen matrix  Set by GsSetRefView(), etc.
GsLIGHT_MODE	int	Default light mode
GsLIGHTWSMATRIX	MATRIX	Light matrix  Set by GsSetFlatLight()
GsIDMATRIX	MATRIX	Unit matrix
GsIDMATRIX2	MATRIX	Unit matrix (including aspect conversion)
GsOUT_PACKET_P	u_long	Pointer to top of packet area  Set by GsSetWorkBase()
GsLMODE	u_long	Attribute decoding result (light mode)
GsLIGNR	u_long	Attribute decoding result (light ignored)
GsLIOFF	u_long	Attribute decoding result (without shading)
GsNDIV	u_long	Attribute decoding result (division number)
GsTON	u_long	Attribute decoding result (semi-transparency)
GsDISPON	u_long	Attribute decoding result (display / no display)
INDEX


VSync

Waits for next vertical synchronization period

int VSync (

        int mode

)

Arguments

mode	0: Blocks until vertical synchronization occurs 1: Returns the elapsed time in HSync units from the last call to VSync() n: (n>1) Blocks for n VSync periods from the last call to VSync() n: (n<0) Returns absolute time from program start in VSync units.

Explanation

Vsync() waits for the start of the next vertical synchronization interval.

Return Value

mode>=0 The elapsed time since the last call to VSync() is returned in HSync units.

mode<0 The absolute time since program start is returned in VSync units.

INDEX


VSyncCallback

Defines a function to be executed during each VSync period

int VSyncCallback (

        void (*func)()

)

Arguments

func	Pointer to the callback function (function to be executed)

Explanation

Specifies that the function func will be called at the start of the vertical synchronization period. When func is 0, any function previously registered as a callback function is removed.

Return Value

None

Notes

Subsequent interrupts will be masked within func. Therefore, it is necessary to return quickly after func is called.

INDEX


CVECTOR

8-bit 3D (colour) vector

typedef struct {

        u_char r, g, b, cd;

} CVECTOR;

Members

r, g, b	Vector elements
cd	System reserved

Explanation

CVECTOR is used to define the structure of an 8-bit 3D (colour) vector.

INDEX


DISPENV

Display environment

typedef struct {

        RECT disp;

        RECT screen;

        u_char isinter;

        u_char isrgb24;

        u_char pad0, pad1;

} DISPENV;

Members

disp	Frame buffer display area.  disp defines the display area within the frame buffer.  The width of disp can be set to 256, 320, 360, 512 or 640.  The height of disp can be set to 240 or 480.
screen	Output screen display area.  screen is calculated on the basis of a standard monitor screen and is  independent of the value of disp. The standard monitor screen uses  (0,0) for the coordinate of the upper left-hand corner and (256, 240)  for the coordinate of the lower right-hand corner.
isinter	Interlaced mode flag  0: Non-interlaced mode  1: Interlaced mode
isrgb24	24-bit mode flag  0: 16-bit mode  1: 24 bit mode
pad0, pad1	System reserved

Explanation

DISPENV is used to specify parameters for the display environment such as screen display mode and frame buffer display position.

INDEX


DRAWENV

Drawing environment

typedef struct {

        RECT clip;

        short ofs[2];

        RECT tw;

        u_short tpage;

        u_char dtd;

        u_char dfe;

        u_char isbg;

        u_char r0, g0, b0;

        DR_ENV dr_env;

} DRAWENV;

Members

clip	Drawing area.  clip specifies the rectangular area used for drawing. Drawing will not be performed outside the area specified by clip.
ofs	Offset.  The values (ofs[0], ofs[1]) are used as offsets when calculating the address that is used for drawing in the frame buffer. The offsets are added to the values of all coordinates to determine the address used by drawing commands when drawing in the frame buffer.
tw	Texture window.  tw specifies the rectangular area within the texture page that is used repeatedly for applying textures.
tpage	Texture page initial value.
dtd	Dither treatment flag  0: Dithering OFF.  1: Dithering ON.
dfe	Display area drawing flag  0: Drawing to the display area is disabled.  1: Drawing to the display area is enabled.
isbg	Clear drawing area flag  0: The drawing area is not cleared when the drawing environment is established.  1: The entire clipped area is painted with the brightness values (r0,g0,b0) when the drawing environment is established.
r0, g0, b0	Background colour. Valid only when isbg = 1.
dr_env	System reserved.

Explanation

DRAWENV sets basic parameters related to drawing such as the drawing offset and the drawing clip area.

Notes

Drawing can be performed in the region (0, 0)-(1023, 511) within the drawing space. Offsets and addresses to which the offset has been added are wrapped around at (-1024, -1024)-(1023, 1023). Values that can be specified for the texture window are limited to the combinations shown in the following table:

tw.w	0(=256)	16	32	64	128
tw.x	0	multiple of 16	multiple of 32	multiple of 64	multiple of 128
tw.h	0(=256)	16	32	64	128
tw.y	0	multiple of 16	multiple of 32	multiple of 64	multiple of 128
INDEX


GsBG

BG (background picture) handler

struct GsBG {

        u_long attribute;

        short x, y;

        short w, h;

        short scrollx, scrolly;

        u_char r, g, b;

        GsMAP *map;

        short mx, my;

        short scalex, scaley;

        long rotate;

};

Members

attribute	32-bit attribute (see the description in GsSPRITE)
x, y	Display position of the upper left-hand point
w, h	BG display size (in pixels)
scrollx, scrolly	x,y scroll values
r, g, b	Display brightness is set in r, g, b. (Normal brightness is 128.)
map	Pointer to map data
mx, my	Rotation and enlargement central point coordinates
scalex, scaley	Scale values in x and y directions
rotate	Rotation angle (4096 = 1 degree)

Explanation

GsBG is a structure used to describe a background.

A background (BG) consists of a large rectangle drawn from GsMAP data based upon a combination of small rectangles defined by GsCELL data.

Every background has an associated GsBG structure.

The background may be manipulated via this structure.

To enter a GsBG object in an ordering table, use GsSortBg().

x, y specify the screen display position.

w, h specify the BG display size in pixels, and are 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 (this is referred to as tiling).

scrollx, scrolly specify the offset from the map display position in dots.

r, g, b specify the brightness values for red, green, and blue. The allowed range is 0 to 255. 128 is the brightness of the original pattern; 255 represents a two-fold increase in brightness.

map is a pointer to the start of the map data. Map data is represented by the GsMAP structure.

mx, my specify the center of rotation and scaling as relative coordinates. The upper left-hand point of the BG is the point of origin. For example, if rotation is around the center of the BG, these values should be specified as w/2 and h/2, respectively.

scalex, scaley specify enlargement/reduction values in the x and y directions. These values represent units of 4096 (which is equivalent to a fixed point value of 1.0). scalex and scaley can be set up to 8 times the original size.

rotate specifies the amount of rotation around the Z-axis (4096 = 1 degrees;).

Refer to GsSPRITE regarding attribute.

INDEX


GsBOXF

Rectangle handler

struct GsBOXF {

        u_long attribute;

        short x, y;

        u_short w, h;

        u_char r, g, b;

};

Members

attribute	Attribute bits as shown below. (Bits not defined below are reserved by the system)  28-29: 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  30: Semi-transparency mode      0: Semi-transparency OFF      1: Semi-transparency ON  31: Display mode      0: Enable display      1: Display display
x, y	Display position (upper left-hand point)
w, h	Size of rectangle (width, height)
r, g, b	Drawing colour

Explanation

GsBOXF is a structure used to represent a rectangle drawn in a single colour.

The GsSortBoxFill() function can be used to enter a GsBOXF object in the ordering table.

INDEX


GsCELL

Cells which define a BG

struct GsCELL {

        u_char u, v;

        u_short cba;

        u_short flag;

        u_short tpage;

};

Members

u	Offset (X-direction) within the page
v	Offset (Y-direction) within the page
cba	CLUT ID
flag	Inversion control flag
tpage	Texture page number

Explanation

A rectangular array of GsCell structures is used to describe individual cells that fit together to create a background (BG).

Each individual GsCell structure defines a rectangular portion of the overall BG.

cba displays the position within the frame buffer of a CLUT corresponding to the cell, and has the following meaning:

Bit	Value
Bit 0~5	X position of CLUT/16
Bit 6~15	Y position of CLUT

tpage is a page number that indicates the position of a sprite pattern within the frame buffer.

The u and v parameters specify the offset position for the sprite pattern within the texture page defined by tpage.

flag controls whether the image is flipped during 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)
Bit 2~15	Reserved
INDEX


GsCOORD2PARAM

Encapsulates scale, rotation and translation

typedef struct {

    VECTOR scale;

    SVECTOR rotate;

    VECTOR trans;

} GsCOORD2PARAM;

Members

scale	3D VECTOR identifying scale
rotate	3D SVECTOR identifying rotation
trans	3D VECTOR identifying translation

Explanation

Structure to contain scale, rotation and translation vectors.

INDEX


GsCOORDINATE2

Matrix-type coordinate system

struct GsCOORDINATE2 {

        u_long flg;

        MATRIX coord;

        MATRIX workm;

        GsCOORD2PARM *param;

        GsCOORDINATE2 *super;

};

Members

flg	Flag indicating whether coord was rewritten
coord	The matrix
workm	Result of multiplying this coordinate system with the WORLD coordinate system
param	Pointer for scaling, rotation and translation parameters
super	Pointer to the parent coordinate system

Explanation

GsCOORDINATE2 is defined by the matrix coord and a pointer to the parent coordinate system.

workm retains the result of matrix multiplication in each node of GsCOORDINATE2 from WORLD coordinates and performed by the GsGetLw() and GsGetLs() functions. However, workm does not store the result of matrix multiplication for a coordinate system that is directly coupled to the WORLD coordinate system.

flg is used during GsGetLw() and GsGetLs() to omit calculations for a node when calculations were already performed. When flg is set to 1, calculations are omitted. When flg is set to 0, calculations are performed. The programmer must clear this flag whenever coord is changed otherwise the GsGetLw() and GsGetLs() functions will not execute properly.

INDEX


GsDOBJ2

Object structure definition used by the GsCOORDINATE2 3D object handler

struct GsDOBJ2 {

        u_long attribute;

        GsCOORDINATE2 *coord2;

        u_long *tmd;

        u_long id ;

};

Members

attribute	Object attribute (32-bits)
coord2	Pointer to a local coordinate system
tmd	Pointer to model data
id	System reserved

Explanation

GsDOBJ2 structures can be used to manipulate 3D models.

Each object in a 3D model has an associated GsDOBJ2 structure.

The GsDOBJ2 structure can be linked to TMD file model data using GsLinkObject4() and can be registered in the ordering table using GsSortObject4().

The coord2 parameter is a pointer to a GsCOORDINATE2 structure defining the object's coordinate system. The location, inclination, and size of the object are defined in a matrix in this structure.

tmd contains the starting address of TMD model data stored in memory and is calculated and set using GsLinkObject4().

attribute is 32 bits and is used to store various display attributes as shown below (all other bits not defined below are reserved by the system):

a) Bit 3: Light source calculation mode

This bit controls whether light source calculation will be performed using FOG.

        0: Normal mode without FOG. This is the fastest mode requiring the least amount of calculation time.

        1: FOG mode. FOG attributes are set in the GsFOGPARAM structure and updated using the GsSetFogParam() function.

b) Bit 5: Light source calculation mode control bit

This bit controls whether light source calculation mode is determined by bit 3 of the attribute field or by the lighting mode set by GsSetLightMode().

        0: Lighting mode is set by GsSetLightMode(). Bit 3 of the attribute field is ignored.

        1: Lighting mode is set according to bit 3 of the attribute field.

c) Bit 6: Light source calculation ON/OFF switch

This bit is used to switch light source calculation on and off.

When light source calculation is turned off, a texture-mapped polygon is displayed in the original texture colour. An unmapped polygon is displayed in the model data colour.

d) Bit 30: Semi-transparency ON/OFF

This bit is used to switch semi-transparency on and off.

This bit must be used with the uppermost bit (STP bit) of the texture colour field to enable semi-transparency. (The texture colour field is the texture pattern when direct mode is set and the CLUT colour field when indexed mode is set). The semi-transparency and non-transparency of each pixel may also be controlled using the STP bit.

e) Bit 31: Display ON/OFF This bit is used to switch the display on and off.

f) Bits 9-11: Automatic partitioning (polygon subdivision)

        0: No automatic partitioning

        1: 2x2 partitioning

        2: 4x4 partitioning

        3: 8x8 partitioning

        4: 16x16 partitioning

        5: 32x32 partitioning

These bits specify the number of subdivisions for the automatic partitioning function. Automatic partitioning, or polygon subdivision, causes all the polygons contained within an object to subdivide. It is used for reducing texture distortion and preventing fragmentation of adjacent polygons. Note that division should be kept to a minimum in order to prevent the number of polygons from increasing exponentially.

INDEX


GsFOGPARAM

Fog (depth cue) information

struct GsFOGPARAM {

        short dqa;

        long dqb;

        u_char rfc, gfc, bfc;

};

Members

dqa	Parameter specifying the degree of blending with respect to depth
dqb	Parameter specifying the degree of blending with respect to depth
rfc, gfc, bfc	Background colours

Explanation

GsFOGPARAM describes fog (depth cue) information dqa and dqb are background colour attenuation coefficients.

They can be calculated using the following formulae:

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 the point where the background colours are completely blended.

h is the distance from the viewpoint to the screen and is also known as the projection distance.

INDEX


GsF_LIGHT

Parallel light source

struct GsF_LIGHT {

        long vx, vy, vz;

        u_char r, g, b;

};

Members

vx, vy, vz	Light source directional vectors
r, g, b	Light colours

Explanation

GsF_LIGHT describes parallel light source information.

It is set by the GsSetFlatLight() function.

Up to three parallel light sources can be set simultaneously.

The light source directional vector is specified by vx, vy, vz.

It is unnecessary for the programmer to perform normalization as this is done by the GsSetFlatLight() function.

A polygon whose normal vectors are opposite to these directional vectors is exposed to the strongest light.

Light source colours are specified in the 8-bit values r, g, b.

INDEX


GsGLINE

Straight line handler with gradation

struct GsGLINE {

        u_long attribute;

        short x0, y0;

        short x1, y1;

        u_char r0, g0, b0;

        u_char r1, g1, b1;

};

Members

attribute	Attribute bits as shown below. (Bits not defined below are reserved by the system)  28-29: 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  30: Semi-transparency mode      0: Semi-transparency OFF      1: Semi-transparency ON  31: Display mode      0: Enable display      1: Disable display
x0, y0	Drawing starting point position
x1, y1	Drawing ending point position
r0, g0, b0	Drawing colour of the starting point
r1, g1, b1	Drawing colour of the ending point

Explanation

GsGLINE is a structure used to represent straight lines with gradation.

It is the same as GsLINE except that drawing colours for the starting point and ending point may be specified separately.

See Also

GsLINE

INDEX


GsIMAGE

Image data structure information

struct GsIMAGE {

        short pmode;

        short px, py;

        u_short pw, ph;

        u_long *pixel;

        short cx, cy;

        u_short cw, ch;

        u_long *clut;

}

Members

pmode	Pixel mode  0: 4-bit CLUT  1: 8-bit CLUT  2: 16-bit Direct  3: 24-bit Direct  4: Multiple mode combinations
px, py	Pixel data storage location within the frame buffer
pw, ph	Pixel data width and height
pixel	Pointer to pixel data
cx, cy	CLUT data storage location within the frame buffer
cw, ch	CLUT data width and height
clut	Pointer to CLUT data

Explanation

GsIMAGE is loaded with TIM format data information using the GsGetTimInfo() function.

For information on the TIM file format, please refer to the Net Yaroze Members' Web site.

INDEX


GsLINE

Straight line handler

struct GsLINE {

        u_long attribute;

        short x0, y0;

        short x1, y1;

        u_char r, g, b;

};

Members

attribute	Attribute bits as shown below. (Bits not defined below are reserved by the system)  28-29: 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  30: Semi-transparency mode      0: Semi-transparency OFF      1: Semi-transparency ON  31: Display mode      0: Enable display      1: Disable display
x0, y0	Drawing starting point position
x1, y1	Drawing ending point position
r, g, b	Drawing colour

Explanation

GsLINE is a structure that represents straight lines.

Use GsSortLine() to register a GsLINE in the ordering table.

attribute is 32 bits, and sets various attributes for display as shown below:

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. Normal semi-transparency processing is performed when these bits are set to 0, pixel addition when set to 1, pixel subtraction when set to 2, and 25% addition when set to 3.

b) Semi-transparency mode (bit 30)

Turns semi-transparency ON/OFF

c) Display mode (bit 31)

Turns the display ON/OFF

INDEX


GsMAP

BG composition MAP

struct GsMAP {

        u_char cellw, cellh;

        u_short ncellw, ncellh;

        GsCELL *base;

        u_short *index;

};

Members

cellw, cellh	Cell size (0 is the same as 256)
ncellw, ncellh	Size of the background (BG) in cells
base	Pointer to the GsCELL structure array
index	Pointer to cell information

Explanation

The GsMAP structure contains map data that is used to create a background from GsCELL data.

Map data is 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 specify the size of the BG map in units of cells.

base specifies the starting address of the GsCELL array.

index specifies the starting address of the cell data table.

Cell data is a list of index values whose size is equivalent to (ncellw * ncellh) for the array specified by base. If a cell value is 0xFFFF it indicates a NULL (transparent) cell.

INDEX


GsOT

Ordering table header

struct GsOT {

        u_short length;

        GsOT_TAG *org;

        u_short offset;

        u_short point;

        GsOT_TAG *tag;

};

Members

length	Bit length of the ordering table (OT)
org	Pointer to 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 current GsOT_TAG

Explanation

The GsOT structure describes the header of the ordering table.

This header has pointers to the actual ordering table array, specified by the org and tag members.

These members are initialized using the GsClearOT() function.

org always points to the start of the ordering table.

tag points to the element within the ordering table at which drawing will take place.

length indicates the size of the ordering table. It is a value from 1-14 where the actual ordering table size is 2 (i.e. a value of 14 indicates an array of 16384 GsOT_TAG items, while a value of 8 indicates an array of 256 GsOT_TAG items).

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 up through 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 specified by offset. For example, if offset = 256, the start of the ordering table is Z = 256. (Not yet supported.)

Notes

The length and org values should be set first. The other members are set by the GsClearOt() function.

See Also

GsClearOt(), GsDrawOt(), GsSortOt()

INDEX


GsOT_TAG

Ordering table element

struct GsOT_TAG {

        unsigned p : 24;

        u_char num : 8;

};

Members

p	Pointer to next item in ordering table list
num	Number of words in current GPU packet (i.e. primitive)

Explanation

An ordering table is a linked list of GsOT_TAG structures and various types of GPU primitive structures.

p indicates the least significant 24-bits of a pointer to the next item in the list. A value of 0xFFFFFF indicates the end of the list.

The GsOT structure is used to manage an array of GsOT_TAG structures.

Memory should be allocated for the GsOT_TAG structures after the GsOT structure is initialized.

INDEX


GsRVIEW2

Viewpoint position (REFERENCE-type)

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 (GsCOORDINATE2 type)

Explanation

GsRVIEW2 holds information about the viewpoint and is set by the GsSetRefView2() function.

vpx, vpy, vpz specify the viewpoint coordinates in the coordinate system specified by super.

When the Z-axis is a vector from the viewpoint to the reference point, rz specifies the viewpoint twist, or screen inclination against the Z-axis. It is represented as an integer, with 4096 equivalent to one degree.

The 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.

INDEX


GsSPRITE

Sprite handler

struct GsSPRITE {

        u_long attribute;

        short x, y;

        u_short w, h;

        u_short tpage;

        u_char u, v;

        short cx, cy;

        u_char r, g, b;

        short mx, my;

        short scalex, scaley;

        long rotate;

};

Members

attribute	32-bit attribute field (explanation is given below)
x, y	Display position of the upper left-hand point
w, h	Width and height of the sprite (Not displayed if w or h is 0)
tpage	Sprite pattern texture page number
u, v	Sprite pattern offset within the page
cx, cy	Sprite CLUT address
r, g, b	Display brightness for r, g, and b (normal brightness is 128)
mx, my	Rotation and enlargement central point coordinates
scalex, scaley	Scale values in x and y directions
rotate	Rotation angle (4096 = 1 degree)
attribute	bits (Bits not defined below are reserved by the system)  6: Brightness adjustment switch      0: ON      1: OFF  24-25: Sprite pattern colour mode      0: 4-bit CLUT      1: 8-bit CLUT      2: 15-bit Direct  27: Rotation & scaling functions      0: ON      1: OFF  28-29: 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  30: Semi-transparency mode      0: Semi-transparency OFF      1: Semi-transparency ON  31: Sprite display mode      0: Displayed      1: Not displayed

Explanation

GsSPRITE is a structure used to display a sprite.

This structure makes it possible to manipulate each sprite via its parameters.

To enter a GsSPRITE in an ordering table, use GsSortSprite() or GsSortFastSprite().

x, y specify the screen display position.

mx, my specify the point in the sprite pattern used as the display position in GsSortSprite(); in GsSortFastSprite(), the point at the upper left-hand corner of the sprite is used as the display position.

w, h specify the width and height of the sprite in pixels.

tpage specifies the texture page number (0-31) of the sprite pattern.

u, v specify the offset within the page from the upper left-hand point of the sprite pattern. The range that may be specified is (0, 0) - (255, 255).

cx, cy specify the starting position of the CLUT (colour palette) as a VRAM address (Valid for 4-bit/8-bit mode only).

r, g, b specify the brightness values for red, green, and blue. The allowed range is 0 to 255. 128 is the brightness of the original pattern; 255 represents a two-fold increase in brightness.

mx, my specify the coordinates for the center of rotation and scaling. The upper left-hand point of the sprite is the point of origin. For example, if rotation is around the center of the sprite, mx and my should be specified as w/2 and h/2, respectively.

scalex, scaley specify enlargement/reduction values in the x and y directions. These values represent units of 4096 (which is equivalent to a fixed point value of 1.0). scalex and scaley can be set up to 8 times the original size.

rotate specifies the amount of rotation around the Z-axis and is represented as an integer, where 4096 is equivalent to 1 degree.

attribute is 32 bits, and sets various attributes for display. An explanation of each bit follows. Bits not defined below are reserved by the system.

a) Brightness adjustment switch (bit 6)

This bit sets whether or not the sprite pattern pixel colours are to be drawn with brightness adjusted according to the (r,g,b) values. When this bit is 1, brightness is not adjusted and the (r,g,b) values are ignored.

b) Sprite pattern colour mode (bit 24-25)

A sprite pattern can use either 4-bit colour mode or 8-bit colour mode, both of which use the colour table, and 15-bit mode, which directly displays colours. These bits are used to set one of these colour modes. Please see above for bit definitions.

c) Rotation & scaling functions (bit 27)

This bit turns on or off the sprite scaling function.

If rotation or scaling of the sprite is not needed, this bit should be set to OFF for high speed processing. GsSortFastSprite() ignores this bit and always set the scaling function to OFF.

d) Semi-transparency rate (bit 28-29)

These bits set the method of pixel blending together with bit 30, when semi-transparency is turned on.

Normal semi-transparent processing is performed when these bits are set to 0, pixel addition when set to 1, pixel subtraction when set to 2, and 25% addition when set to 3.

e) Semi-transparency mode (bit 30)

This bit turns semi-transparency on or off.

It must be used with the uppermost bit (STP bit) of the texture colour field to turn semi-transparency on (texture pattern when in direct mode and CLUT colour field when in indexed mode). The semi-transparency and non-transparency of each pixel may also be controlled using this STP bit.

f) Sprite display mode (bit 31)

This bit turns the display mode on and off.

INDEX


GsVIEW2

Viewpoint position (Matrix-type)

struct GsVIEW2 {

        MATRIX view;

        GsCOORDINATE2 *super

};

Members

view	Matrix for conversion from parent coordinates to viewpoint coordinates
super	Pointer to the coordinate system that sets the viewpoint

Explanation

GsVIEW2 sets the viewpoint coordinate system.

It directly specifies the matrix for converting from the parent coordinate system to the viewpoint coordinate system in view.

The function that sets GsVIEW2 is GsSetView2().

INDEX


MATRIX

3 x 3 matrix

typedef struct {

        short m[3][3];

        long t[3];

} MATRIX;

Members

m	Element values of the 3 x 3 matrix
t	Amount of translation

Explanation

MATRIX defines a 3 x 3 matrix.

The value of each element is specified by m[i][j].

t[i] specifies the amount of translation after conversion.

INDEX


RECT

Frame buffer rectangular area

typedef struct {

        short x, y;

        short w, h;

} RECT;

Members

x, y	Coordinates for the upper left-hand corner of the rectangular area
w, h	Width and height of the rectangular area

Explanation

RECT is used to specify a rectangular area in the frame buffer.

Negative values or values that exceed the size of the frame buffer (1024 x 512) cannot be used.

INDEX


SVECTOR

16-bit 3D vector

typedef struct {

        short vx, vy;

        short vz, pad;

} SVECTOR;

Members

vx, vy, vz	Vector elements
pad	System reserved

Explanation

SVECTOR is used to define the structure of a 16-bit 3D vector.

INDEX


VECTOR

32-bit 3D vector

typedef struct {

        long vx, vy;

        long vz, pad;

} VECTOR;

Members

vx, vy, vz	Vector elements
pad	System reserved

Explanation

VECTOR is used to define the structure of a 32-bit 3D vector.

INDEX


acos

Arccosine

double acos (

        double x

)

Arguments

x	Argument. Range is [-1 to 1]

Explanation

The arccosine of x is calculated and its value is returned.

Return value

The arccosine of x (acos(x)) is returned. The result range is [0, pi].

Notes

Error processing is shown in the table below:

Condition	Return value	Error
fabs(x)>1	0	Domain error

See Also

cos(), asin(), atan()

INDEX


asin

Arcsine

double asin (

        double x

)

Arguments

x	Argument. Range is [-1 to 1]

Explanation

The arcsine of x is calculated and its value is returned.

Return value

The arcsine of x (asin(x)) is returned. The result range is [-pi/2, pi/2].

Notes

Error processing is shown in the table below:

Condition	Return value	Error
fabs(x)>1	0	Domain error

See Also

sin(), acos(), atan()

INDEX


atan

Arctangent

double atan (

        double x

)

Arguments

x	Argument.

Explanation

The arctangent of x is calculated and its value is returned.

Return value

The arctangent of x (atan(x)) is returned. The result range is [-pi/2, pi/2].

See Also

tan(), asin(), acos(), atan2()

INDEX


atan2

Arctangent

double atan2 (

        double x,

        double y

)

Arguments

x	Dividend
y	Divisor

Explanation

The arctangent of x/y is calculated and its value is returned.

Return value

The arctangent of x/y (atan(x/y)) is returned. The result range is [-pi, pi].

Notes

Error processing is shown in the table below:

Condition	Return value	Error
x==0 && y==0	0	Domain error

See Also

atan()

INDEX


atof

Converts a character string to a floating-point number

double atof (

        const char *s

)

Arguments

s	Pointer to a character string

Explanation

The character string pointed to by s which represents a floating point number, is converted to a double-precision floating point value.

Return Value

The result of converting the input string pointed to by s to a double-precision value is returned. If the value exceeds the range that can be expressed, either +HUGE_VAL(1.797693134862316e+308) or -HUGE_VAL is returned according to the sign. 0 is returned if an underflow occurs.

Notes

Error processing is shown in the following table:

Condition	Return value	Error
Outside the range that can be expressed	+/- HUGE_VAL	Domain error
Underflow	0	Domain error

See Also

strtod()

INDEX


ceil

Finds the smallest integer not less than x (ceiling function)

double ceil (

        double x

)

Arguments

x	Argument

Explanation

The smallest integer greater than or equal to x is obtained and its corresponding double-precision floating point value is returned.

Return value

The smallest integer (in double-precision floating point format) that is not less than x is returned.

See Also

floor()

INDEX


cos

Cosine

double cos (

        double x

)

Arguments

x	Argument in radians

Explanation

The cosine of x is calculated and its value is returned.

Return value

The cosine of x (cos(x)) is returned.

See Also

sin(), tan(), acos()

INDEX


cosh

Hyperbolic cosine

double cosh (

        double x

)

Arguments

x	Argument in radians

Explanation

The hyperbolic cosine of x is calculated and its value is returned.

Return value

The hyperbolic cosine of x (cosh(x)) is returned.

See Also

sinh(), tanh()

INDEX


exp

Exponent

double exp (

        double x

)

Arguments

x	Argument

Explanation

The exponential of x (e to the xth power) is calculated and the result is returned.

Return Value

e to the xth power (ex) is returned.

See Also

pow(), log()

INDEX


fabs

Absolute value (macro)

fabs (

        double x

)

Arguments

x	Floating-point argument

Explanation

The absolute value of the argument x is calculated and its value is returned.

Return Value

The absolute value of x is returned.

Notes

fabs() is a macro.

INDEX


floor

Finds the largest integer not greater than x (base function)

double floor (

        double x

)

Arguments

x	Argument

Explanation

The largest integer less than or equal to x is obtained and its corresponding double-precision floating point value is returned.

Return value

The largest integer (in double-precision floating point format) that is not greater than x is returned.

See Also

ceil()

INDEX


fmod

Calculates floating point remainder of x/y

double fmod (

        double x,

        double y

)

Arguments

x	Floating point dividend
y	Floating point divisor

Explanation

The remainder of x/y is calculated and its value is returned as a double-precision floating point number.

Return value

The double precision floating point number remainder of x/y is returned.

Notes

The sign of the return value will be the same as the sign of x. 0 is returned if y is 0.

INDEX


frexp

Divides a floating point number into a normalized mantissa and an exponent

double frexp (

        double x,

        int *n

)

Arguments

x	Argument
n	Pointer to a storage location that stores the exponent

Explanation

The floating point number x is separated into a normalized mantissa [1/2,1) and an exponent (2n). The exponent is placed at the storage location pointed to by n.

The normalized mantissa is returned by the function.

Return value

The normalized mantissa [1/2, 1) is returned.

INDEX


hypot

Absolute value of a complex number

double hypot (

        double x,

        double y

)

Arguments

x	Real part
y	Imaginary part

Explanation

The absolute value of the complex number (x+iy) is calculated and its value is returned.

Return value

The square root of the sum of x^2 and y^2 is returned.

INDEX


ldexp

Calculates a real number from a mantissa and an exponent

double ldexp (

        double x,

        long n

)

Arguments

x	Floating point mantissa
n	Integer exponent

Explanation

The real number is calculated and its value is returned.

Return value

The value x * 2n is returned.

INDEX


log

Natural logarithm

double log (

        double x

)

Arguments

x	Argument

Explanation

The natural logarithm of x is calculated and the result is returned.

Return Value

The natural logarithm of x ( ln(x) ) is returned.

Notes

x must be greater than 0, otherwise an error will occur as shown below:

Condition	Return value	Error
x < 0	0	Domain error
x == 0	1	Range error

See Also

exp(), log10()

INDEX


log10

Common logarithm

double log10 (

        double x

)

Arguments

x	Argument

Explanation

The common logarithm of x is calculated and the result is returned.

Return Value

The common logarithm of x ( log10(x) ) is returned.

Notes

x must be greater than 0, otherwise an error will occur as shown below:

Condition	Return value	Error
x < 0	0	Domain error
x == 0	1	Range error

See Also

log()

INDEX


modf

Separates a floating point number into integer and fractional parts

double modf (

        double x,

        double *y

)

Arguments

x	Floating point number
y	Pointer to a buffer for storing the integer part

Explanation

x is separated into an integer part and a fractional part. The integer part is placed at the storage location pointed to by y. The fractional part is returned by the function.

Return value

The fractional part of x is returned.

Notes

The sign for both integer parts and fractional parts will be the same as the sign of x.

Example

#include <math.h >

#include <stdio.h >

void main(void)

{

    double x, y, n;

    x = -14.87654321; // Divide x into its fractional

    y = modf(x, &n); // and integer parts

    printf("For %f, the fraction is %f and the integer is %.f\n",

      x, y, n);

}

Output: For -14.876543, the fraction is -0.876543 and the integer is -14

INDEX


pow

x to the yth power

double pow (

        double x,

        double y

)

Arguments

x	Base number
y	Power

Explanation

x to the yth power is calculated and the result is returned.

Return Value

x to the yth power (xy) is returned.

Notes

Error processing is shown in the following table.

Condition	Return Value	Error
x == 0&& y>0	0
x == 0 && y <= 0	1	Domain error
x<0 && “y is not Integer value”	0	Domain error

See Also

exp()

INDEX


printf2

Writes formatted output to the standard output stream (supports float and double type)

long printf2 (

        const char *fmt, [argument...]

)

Arguments

fmt	Input format conversion string

Explanation

Writes formatted output to stdout, the standard output stream.

Please refer to the C language reference for a detailed explanation of the input format conversion string. The format specifiers “f”, “e”, “E”, “g” and “G” can be used.

printf2() requires more stack space than print().

Return Value

The length of the output character string is returned. NULL is returned if an error

occurred.

See Also

sprintf2()

INDEX


sin

Sine

double sin (

        double x

)

Arguments

x	Argument in radians

Explanation

The sine of x is calculated and its value is returned.

Return Value

The sine of x (sin(x)) is returned.

See Also

cos(), tan(), asin()

INDEX


sinh

Hyperbolic sine

double sinh (

        double x

)

Arguments

x	Argument in radians

Explanation

The hyperbolic sine of x is calculated and its value is returned.

Return Value

The hyperbolic sine of x (sinh(x)) is returned.

See Also

cosh(), tanh()

INDEX


sprintf2

Writes formatted output to a character string (supports float and double type)

long sprintf2(

        char *s,

        const char *fmt, [argument...]

)

Arguments

s	Pointer to storage area holding converted character string
fmt	Input format conversion string

Explanation

Writes formatted output to a character string and places the result in the storage area pointed to by s.

Please refer to the C language reference for a detailed explanation of the input format conversion string. The format specifiers “f”, “e”, “E”, “g” and “G” can be used.

sprintf2() requires more stack space than sprintf().

Return Value

The length of the output character string is returned. NULL is returned if an error occurred.

See Also

printf2()

INDEX


sqrt

Square root

double sqrt (

        double x

)

Arguments

x	Argument (must be >= 0)

Explanation

The square root of x is calculated and its value is returned.

Return Value

The square root of x (sqrt(x)) is returned.

Notes

Error processing is shown in the table below:

Condition	Return value	Error
x<0	0	Domain error
INDEX


strtod

Converts a character string to a floating-point number

double strtod (

        const char *s,

        char **endp

)

Arguments

s	Pointer to a character string
endp	Pointer to a storage area that will contain a pointer to the character that stopped the conversion

Explanation

The character string pointed to by s is converted to a double-precision floating point number and its value is returned. The string pointed to by s must be in one of the following formats.

[ws][sn][ddd]

[ws] White space (can be omitted)

[sn] Sign (can be omitted)

[ddd] Number string (can be omitted)

strtod() stops conversion when a character is encountered that cannot be converted. A pointer to the character that terminated the conversion is placed at the storage location specified by endp unless endp is NULL.

Return Value

The result of converting the input string pointed to by s to a double-precision value is returned. If the value exceeds the range that can be expressed, either +HUGE_VAL(1.797693134862316e+308) or -HUGE_VAL is returned according to the sign. 0 is returned if an underflow occurs.

Notes

Error processing is shown in the following table:

Condition	Return value	Error
Outside the range that can be expressed	+/- HUGE_VAL	Domain error
Underflow	0	Domain error

See Also

atof()

INDEX


tan

Tangent

double tan (

        double x

)

Arguments

x	Argument in radians

Explanation

The tangent of x is calculated and its value is returned.

Return Value

The tangent of x (tan(x)) is returned.

See Also

sin(), cos(), atan()

INDEX


tanh

Hyperbolic tangent

double tanh (

        double x

)

Arguments

x	Argument in radians

Explanation

The hyperbolic tangent of x is calculated and its value is returned.

Return Value

The hyperbolic tangent of x (tanh(x)) is returned.

See Also

sinh(), cosh()

INDEX


CdPlay

Plays back CD-DA tracks

int CdPlay (

        int mode,

        int *tracks,

        int offset

)

Arguments

mode	Mode (see below)
tracks	Pointer to array that specifies the track to be played. The last element must be 0.
offset	Index into the tracks array where playback will begin.

Explanation

The sequence of track numbers starting at the array element specified by tracks[offset] is played one after another. When the end of the sequence is reached, playback is repeated or ended according to the setting of mode as shown in the table below:

Value	Description
0	Stop playback immediately.
1	The tracks specified by tracks are played consecutively, and playback is stopped when all the specified tracks have been played.
2	The tracks specified by tracks are played consecutively, and playback is returned to the start and repeated when all the specified tracks have been played.
3	The index of the tracks array for the track currently being played is returned. (No other action is taken.)

Return Value

The array index of the track currently being played is returned (not the track number itself).

-1 is returned on error or if there is no song playing.

Notes

All playback is in units of tracks. Therefore, it is not possible to start or stop or playing in the middle of a track.

INDEX


CdReadExec

Loads executable files from the CD-ROM

struct EXEC *CdReadExec (

        char *file

)

Arguments

file	Executable filename

Explanation

The executable file specified by file is read from the CD-ROM and placed at the memory location specified in the header of the executable file.

Reading is performed in the background, so CdReadSync() should be used to determine when reading has completed.

The loaded file can be executed as a child process using Exec().

Return Value

A pointer to the EXEC structure containing information about the executable files that has been loaded is returned.

Notes

The load address of the executable file should not overlap the area used by the parent process.

INDEX


CdReadFile

Reads a data file from the CD-ROM

int CdReadFile (

        char *file,

        u_long *addr,

        int nbyte

)

Arguments

file	Filename
addr	Pointer to result memory buffer
nbyte	Number of bytes to read

Explanation

nbyte bytes of the file specified by file are read from the CD-ROM and placed in the buffer pointed to by addr.

If nbyte is set to 0, the entire file is read.

If file is set to NULL, the function starts reading at the last location read by the previous call.

Return Value

The number of bytes read is returned if the function was successful.

0 is returned in case of an error.

Notes

The filename must be specified as an absolute path with lower case characters automatically converted to upper case.

Reading is performed in the background, so CdReadSync() should be used to determine when reading has completed.

INDEX


CdReadSync

Waits for completion of CdRead

int CdReadSync (

        int mode,

        u_char *result

)

Arguments

mode	0: Wait for completion of read 1: Obtain current status and return immediately
result	Pointer to buffer storing the result

Explanation

CdReadSync() waits for reading to complete that was started by CdReadFile() and CdReadExec().

Return Value

The return value has the following meaning:

Return Value	Meaning
Positive integer	Number of sectors left to read
0	Read completed
-1	Read error
INDEX


CdSearchFile

Gets location and size of a CD-ROM file

CdlFILE *CdSearchFile (

        CdlFILE *fp ,

        char *name

)

Arguments

fp	Pointer to CD-ROM file structure for storing the result
name	Filename

Explanation

The location of the file on the CD-ROM specified by name is obtained (in minutes, seconds, sectors) and the result is stored in the CD-ROM file structure pointed to by fp.

Return Value

If the file was found on the CD-ROM, fp, the pointer to the CD-ROM file structure is returned.

0 is returned if the file was not found.

-1 is returned if an error occurred.

Notes

The filename must be specified as an absolute path.

When the same directory is accessed repeatedly, the file location information is cached to improve performance.

INDEX


close

Closes a file

int close (

        int fd

)

Arguments

fd	File descriptor

Explanation

The file specified by the file descriptor, fd, is closed.

Return Value

fd is returned if the file was successfully closed.

-1 is returned in all other cases.

See Also

open()

INDEX


delete

Deletes a file

int delete (

        char *name

)

Arguments

name	Filename

Explanation

The file specified by name is deleted.

Return Value

1 is returned if the file was successfully deleted.

0 is returned in all other cases.

INDEX


EnterCriticalSection

Inhibit interrupts

void EnterCriticalSection (

        void

)

Arguments

None.

Explanation

EnterCriticalSection() inhibits interrupts while in a critical section.

Return Value

None.

See Also

ExitCriticalSection()

INDEX


Exec

Execute an executable file

long Exec (

        struct EXEC *exec,

        long argc,

        char *argv

)

Arguments

exec	Pointer to executable file descriptor
argc	Number of arguments
argv	Argument string

Explanation

An executable file that has been loaded into memory and which is described by the information contained in the EXEC structure pointed to by exec is executed.

argc and argv are passed to the executable program.

If exec->s_addr is 0, neither the stack pointer nor the frame pointer is initialized.

The operation of Exec() is shown below:

1. The uninitialized data section is cleared.

2. sp, fp and gp are saved, then initialized (fp is set to the value of sp).

3. The arguments of main() are set in the a0 and a1 registers.

4. A jump is made to the execution start address.

5. sp, fp and gp are restored after returning.

Return value

1 is returned if the function was successful.

0 is returned in all other cases.

Notes

Exec() must be executed in a critical section.

See Also

EXEC, Load()

INDEX


ExitCriticalSection

Permit interrupts

void ExitCriticalSection (

        void

)

Arguments

None.

Explanation

ExitCriticalSection() enables interrupts after leaving a critical section.

Return Value

None.

See Also

EnterCriticalSection()

INDEX


firstfile

Retrieves information about a file

struct DIRENTRY *firstfile (

        char *name,

        struct DIRENTRY *dir

)

Arguments

name	Filename
dir	Pointer to DIRENTRY structure that stores information relating to the referenced file

Explanation

Information about the file corresponding to the specified filename is obtained and placed in the DIRENTRY structure pointed to by dir.

Return Value

dir is returned if the function is successful.

0 is returned in all other cases.

Notes

The wildcard character ‘*’ can be used in the filename. Characters after the ‘*’ are ignored.

See Also

DIRENTRY, nextfile()

INDEX


FlushCache

Flush the I-cache

void FlushCache (

        void

)

Arguments

None.

Explanation

The Instruction cache is flushed.

FlushCache() is usually called when a program modifies instruction code.

Return Value

None.

Notes

The contents of the instruction cache cannot be modified.

INDEX


format

Initializes the file system

int format (

    char *fs

)

Arguments

fs	File system name

Explanation

The file system specified by fs is initialized.

Return Value

1 is returned if the initialization was successful.

0 is returned in all other cases.

Notes

format() is valid only for writeable file systems.

INDEX


GetPadBuf

Gets controller buffers

void GetPadBuf (

        volatile unsigned char **buf1,

        volatile unsigned char **buf2

)

Arguments

buf1	Pointer to a storage location that will contain a pointer to the port1 controller.
buf2	Pointer to a storage location that will contain a pointer to the port2 controller.

Explanation

The storage locations of the system controller buffers are obtained and stored at the memory locations pointed to by buf1 and buf2.

Communication with the controllers occurs every vertical synchronization interruption and information read from the controllers is stored in the system controller buffers. GetPadBuf() can be used to obtain pointers to these buffers. There is a separate buffer for each controller. The table below shows the arrangement of data within each buffer.

Bytes	Content
0	0xff:   No controller  0x00: Controller present
1	Upper 4 bits: Terminal type  Lower 4 bits: Received data size (in 1/2 bytes)
2~	Received data (maximum 32 bytes)

The received data format varies according to the type of controller indicated by ‘terminal type’. The terminal types supported by the library are shown in the following table:

Terminal Type	Device Name
0x1	Mouse
0x2	NeGCon
0x4	Standard controller
0x5	Joystick

Please refer to the "User’s Guide" for a description of the contents of received data corresponding to each terminal type, or see the Net Yaroze Members' Web site.

Return Value

None.

INDEX


GetRCnt

Gets the value of a root counter

long GetRCnt (

        u_ long spec

)

Arguments

spec	The specified root counter

Explanation

The current value of the root counter specified by spec is returned.

Return Value

If the function is successful, the 32-bit unsigned and expanded root counter value is returned.

-1 is returned if the function failed to complete.

See Also

StartRCnt(), ResetRCnt()

INDEX


GetVideoMode

Obtains the currently active video signal mode

long GetVideoMode (

        void

)

Arguments

None.

Explanation

The currently active video signal mode is returned.

Return Value

The currently active video signal mode is returned and can assume one of the following values:

MODE_NTSC	NTSC video signal mode
MODE_PAL	PAL video signal mode

Notes

The default mode before SetVideoMode() is called is MODE_NTSC regardless of machine type.

See Also

SetVideoMode()

INDEX


InitHeap

Initialize the heap

void InitHeap (

        void *head,

        long size

)

Arguments

head	Pointer to heap start address
size	Heap size (multiple of 4 bytes)

Explanation

The heap pointed to by head is initialized. Memory management functions are also initialized, so that malloc() and the other memory allocation functions can be used.

The effective heap size is actually less than size because of overhead.

Return Value

None.

Notes

Multiple calls to InitHeap() are permitted only if they do not overlap, otherwise memory management functions will not operate properly.

See Also

malloc()

INDEX


ioctl

Controls i/o devices

long ioctl (

        long fd,

        long com,

        long arg

)

Arguments

fd	File descriptor returned by a preceding call to open()
com	Control command to be performed (macro defined in sys\ioctl.h)
arg	Control command argument

Explanation

ioctl() executes control commands (i.e. set baud, reopen, etc.) on the PlayStation I/O devices (ie tty, bu, etc). The Control Command macros are defined in include\sys\ioctl.h. Refer to the I/O Control Management section of the Kernel Management chapter for more information.

Return value

    1 is returned when successful, 0 otherwise.

See also

open(), read(), write(), close()

INDEX


Load

Loads an executable file

long Load (

        char *name,

        struct EXEC *exec

)

Arguments

name	Filename
exec	Pointer to an executable file structure for storing the result

Explanation

The executable file specified by name is loaded into memory at the address specified in its header. Internal information about the file is written to the EXEC structure pointed to by exec.

Return Value

1 is returned if the function was successful.

0 is returned in all other cases.

See Also

EXEC, Exec()

INDEX


LoadTest

Test load of an executable file

long LoadTest (

        char *name,

        struct EXEC *exec

)

Arguments

name	Filename
exec	Pointer to an executable file structure for storing the result

Explanation

The information contained in the executable file specified by name is written to the structure pointed to by exec.

Return Value

The execution start address is returned if the function is successful.

0 is returned in all other cases.

See Also

EXEC, Load()

INDEX


lseek

Moves the file pointer

int lseek (

        int fd,

        u_int offset,

        int flag

)

Arguments

fd	File descriptor
offset	Offset
flag	See below

Explanation

The file pointer of the device corresponding to the file descriptor specified by fd is moved according to the values of offset and flag.

offset specifies the number of bytes to move the pointer.

flag has the meaning indicated below:

Flag	Macro Function
SEEK_SET	Seek from the beginning of file. offset is relative to the beginning of the file.
SEEK_CUR	Seek from the current location. offset is relative from the current position of the file pointer.

lseek() cannot be used with character-type drivers.

Return Value

The current file pointer is returned if the function succeeded.

-1 is returned in all other cases.

See Also

open(), read(), write()

INDEX


nextfile

Retrieves information about the next file

struct DIRENTRY *nextfile (

        struct DIRENTRY *dir

)

Arguments

dir	Pointer to DIRENTRY structure that stores information relating to the referenced file

Explanation

nextfile() continues the lookup function started by firstfile(). Information on matching files is placed in the DIRENTRY structure pointed to by dir.

Return Value

dir is returned if the function is successful.

0 is returned in all other cases.

Notes

If the shell cover of the CD-ROM drive is opened after the execution of firstfile(), nextfile() will fail and report that the file was not found.

See Also

DIRENTRY, firstfile()

INDEX


open

Opens a file

int open (

        char *devname,

        int flag

)

Arguments

devname	Filename
flag	Open mode

Explanation

The file indicated by devname is opened and its file descriptor is returned.

flag can be set to one of the following macros:

Macro	Open Mode
O_RDONLY	Read only
O_WRONLY	Write only
O_RDWR	Read and write
O_CREAT	Create file
O_NOBUF	Non-buffering mode
O_NOWAIT	Asynchronous mode

Return Value

If the open succeeded, the file descriptor is returned.

-1 is returned in the event of failure.

See Also

close()

INDEX


read

Reads data from a file

int read (

        int fd,

        char *buf,

        int n

)

Arguments

fd	File descriptor
buf	Pointer to read buffer
n	Number of bytes to read

Explanation

n bytes are read from the file specified by fd and placed in the buffer pointed to by buf.

Return Value

The number of bytes read up to normal termination is returned.

-1 is returned if an error occurred.

See Also

open()

INDEX


rename

Renames a file

int rename (

        char *src,

        char *dest

)

Arguments

src	Source filename
dest	New filename

Explanation

The filename specified by src is renamed to the name specified by dest.

The full path from the device name must be specified for both src and dest.

Return Value

1 is returned if the rename was successful.

0 is returned in all other cases.

Notes

rename() is valid only for writeable file systems.

INDEX


ResetRCnt

Resets a root counter

long ResetRCnt (

        u_long spec

)

Arguments

spec	The specified root counter

Explanation

The root counter specified by spec is reset.

Return Value

1 is returned if the root counter was successfully reset.

0 is returned in the event of failure.

See Also

GetRCnt(), StartRCnt()

INDEX


SetVideoMode

Sets the currently active video signal mode

long SetVideoMode (

        long mode

)

Arguments

mode	Video signal mode MODE_NTSC: NTSC video signal mode MODE_PAL:    PAL video signal mode

Explanation

The currently active video signal mode is set to mode for use by the library functions.

Return Value

The previously active video signal mode is returned.

Notes

SetVideoMode() should be called before any library functions.

See Also

GetVideoMode()

INDEX


StartRCnt

Starts a root counter

long StartRCnt (

        u_long spec

)

Arguments

spec	The specified root counter

Explanation

The root counter specified by spec is activated and enabled for interrupts.

Return Value

1 is returned if the root counter was successfully activated.

0 is returned in the event of failure.

See Also

GetRCnt(), ResetRCnt()

INDEX


TestCard

Test a memory card

long TestCard (

        long chan

)

Arguments

chan	Slot number of memory card  0: Slot 1  1: Slot 2

Explanation

The memory card in the slot specified by chan is tested and the result of the test is returned.

Card initialization is performed from the memory card control screen of the PlayStation.

One to four vertical synchronization interruptions must be performed at the end of the operation (17 msec to 68 msec).

Return Value

The test result is indicated in the return value as shown below:

0:	Card missing
1:	Card present
2:	New card detected
3:	Communication or card error detected
4:	Uninitialized card detected
INDEX


write

Writes data to a file

int write (

        int fd ,

        char *buf,

        int n

)

Arguments

fd	File descriptor
buf	Pointer to data write buffer
n	Number of bytes to write

Explanation

The first n bytes from the buffer pointed to by buf are written to the file specified by fd.

Return Value

The number of bytes written up to normal termination is returned.

-1 is returned if an error occurred.

See Also

open()

INDEX


_get_errno

Obtains i/o error code

long _get_errno (

        void

)

Arguments

None.

Explanation

The cumulative error code from all file descriptors is obtained and its value is returned.

The error code is defined in sys/errno.h.

Return Value

The error code is returned.

INDEX


CdlFILE

ISO-9660 file descriptor

typedef struct {

        CdlLOC pos;

        u_long size;

        char name[16];

} CdlFILE;

Members

pos	File position
size	File size
name	Filename

Explanation

CdIFILE holds information that describes a file on the CD-ROM in the ISO-9660 file system.

INDEX


CdlLOC

CD-ROM location

typedef struct {

        u_char minute;

        u_char second;

        u_char sector;

        u_char track;

} CdlLOC;

Members

minute	Minute
second	Second
sector	Sector
track	Track number

Explanation

CDILOC holds information that describes a physical location on the CD-ROM.

Notes

The track member is not currently supported.

INDEX


DIRENTRY

Structure of a directory entry

struct DIRENTRY {

        char name[20];

        long attr;

        long size;

        struct DIRENTRY *next

        long head;

        char system[8];

}

Members

name	Filename
attr	Attribute (depends on file system)
size	File size (bytes)
next	Pointer to next file entry (for user)
head	Starting sector number
system	System reserved

Explanation

DIRENTRY stores information relating to files contained in the file system.

See Also

firstfile(), nextfile()

INDEX


EXEC

Structure of an executable file

struct EXEC {

        u_long pc0;

        u_long gp0;

        u_long t_addr;

        u_long t_size;

        u_long d_addr;

        u_long d_size;

        u_long s_addr;

        u_long s_size;

        u_long sp, fp , gp, base;

};

Members

pc0	Execution start address
gp0	gp register initial value
t_addr	Starting address of text section and initialized data section
t_size	Size of text section and initialized data section
d_addr	System reserved
d_size	System reserved
b_addr	Starting address of uninitialized data section
b_size	Size of uninitialized data section
s_addr	Stack start address (user-specified)
s_size	Stack size (user-specified)
sp,fp ,gp, base	Register storage area

Explanation

The EXEC structure is located in the upper 2K bytes of an executable file (a file in PS-X EXE format). EXEC maintains information used to load and execute a program.

When a program is executed, stack information is added to the members of the EXEC structure and the structure is passed as an argument to the Exec() function.

See Also

Exec()

INDEX


SsGetMute

Gets mute state

char SsGetMute (

        void

)

Arguments

None.

Explanation

The current mute state is obtained and returned.

Return Value

The mute state is returned as indicated below:

SS_MUTE_ON	Mute on
SS_MUTE_OFF	Mute off

See Also

SsSetMute()

INDEX


SsGetMVol

Gets the main volume

void SsGetMVol (

        SndVolume *m_vol

)

Arguments

m_vol	Pointer to SndVolume structure for storing result

Explanation

The value of the main volume is obtained and placed in the SndVolume structure

pointed to by m_vol.

Return Value

None.

See Also

SsSetMVol()

INDEX


SsGetSerialAttr

Gets the value of a CD audio attribute

char SsGetSerialAttr (

        char s_num,

        char attr

)

Arguments

s_num	Must be set to SS_CD
attr	Attribute to be obtained attr = SS_MIX Mixing attr = SS_REV Reverberation

Explanation

The value of the CD audio attribute specified by attr is obtained and returned.

Return Value

1 is returned if the specified attribute is on and 0 is returned if off.

See Also

SsSetSerialAttr()

INDEX


SsGetSerialVol

Gets CD audio volume

void SsGetSerialVol (

        char s_num,

        SndVolume *s_vol

)

Arguments

s_num	Must be set to SS_CD
s_vol	Pointer to SndVolume structure for storing result

Explanation

The current CD audio volume value is placed in the structure pointed to by s_vol.

Return Value

None.

See Also

SsSetSerialVol()

INDEX


SsIsEos

Returns the playback state of a song

short SsIsEos (

        short access_num,

        short seq_num

)

Arguments

access_num	SEQ access number
seq_num	Must be set to 0

Explanation

The playback state of the song specified by access_num is obtained and its value is returned.

Return Value

1 is returned if the song is being played, otherwise 0 is returned.

INDEX


SsPlayBack

Plays back SEQ data

void SsPlayBack (

        short access_num,

        short seq_num,

        short l_count

)

Arguments

access_num	SEQ access number
seq_num	Must be set to 0
l_count	Song repetition count

Explanation

The song which is currently playing is interrupted and the song which is specified by access_num is played.

The song repetition count is specified in l_count. If l_count is set to SSPLAY_INFINITY, the song will play continuously.

Return Value

None.

See Also

SsSeqPlay()

INDEX


SsSeqClose

Closes SEQ data

void SsSeqClose (

        short seq_access_num

)

Arguments

seq_access_num	SEQ access number

Explanation

The SEQ data specified by seq_access_num is closed.

Return Value

None.

See Also

SsSeqOpen()

INDEX


SsSeqGetVol

Gets SEQ volume

void SsSeqGetVol (

        short access_num,

        short seq_num,

        short *voll,

        short *volr

)

Arguments

access_num	SEQ access number
seq_num	Must be set to 0
voll	Pointer to SEQ left volume result value
volr	Pointer to SEQ right volume result value

Explanation

The current left and right volume values of the song specified by access_num are obtained and placed at the storage locations pointed to by voll and volr, respectively.

Return Value

None.

See Also

SsSeqSetVol()

INDEX


SsSeqOpen

Opens SEQ data

short SsSeqOpen (

        u_long* addr,

        short vab_id

)

Arguments

addr	Pointer to start of SEQ data in main memory
vab_id	VAB ID

Explanation

The SEQ data beginning at the area in memory pointed to by addr and having the specified vab_id is opened and its SEQ access number is returned.

If an attempt is made to open more than 32 SEQ data groups, the function fails and a value of -1 is returned.

Return Value

The SEQ access number is returned if the SEQ data was successfully opened.

-1 is returned if an error occurred.

See Also

SsSeqClose()

INDEX


SsSeqPause

Pauses the playback of SEQ data

void SsSeqPause (

        short seq_access_num

)

Arguments

seq_access_num	SEQ access number

Explanation

The playback of the song specified by seq_access_num is paused.

Return Value

None.

See Also

SsSeqPlay(), SsSeqReplay()

INDEX


SsSeqPlay

Plays SEQ data

void SsSeqPlay (

        short seq_access_num,

        char play_mode,

        short l_count

)

Arguments

seq_access_num	SEQ access number
play_mode	Playback mode SSPLAY_PAUSE Pause immediately before playing SSPLAY_PLAY Begin playing immediately
l_count	Song repetition count

Explanation

The song specified by seq_access_num is played according to the specified playback

mode.

The song repetition count is specified by l_count. If l_count is set to SSPLAY_INFINITY, the song will loop continuously.

If play_mode is set to SSPLAY_PAUSE, the song will be held in pause state until it is released. If play_mode is set to SSPLAY_PLAY, the song will begin playing immediately.

INDEX


SsSeqReplay

Resumes playback of SEQ data

void SsSeqReplay (

        short seq_access_num

)

Arguments

seq_access_num	SEQ access number

Explanation

The playback of the song specified by seq_access_num, which is currently paused, is resumed.

SsSeqReplay() can be used to continue playing a song that was previously paused with SsSeqPause() or SsSeqPlay().

Return Value

None.

See Also

SsSeqPlay(), SsSeqPause()

INDEX


SsSeqSetAccelerando

Accelerates the tempo

void SsSeqSetAccelerando (

        short seq_access_num,

        long tempo,

        long v_time

)

Arguments

seq_access_num	SEQ access number
tempo	Tempo
v_time	Time (in ticks)

Explanation

The tempo of the song specified by seq_access_num is incrementally increased to the value specified by tempo in the amount of time specified by v_time.

v_time is specified in number of ticks where 1 tick = 1/60 sec.

SsSeqSetAccelerando() gradually increases the tempo to the specified tempo.

v_time indicates how long it will take to reach that tempo.

Return Value

None.

See Also

SsSeqSetRitardando()

INDEX


SsSeqSetNext

Links SEQ data for playback

void SsSeqSetNext (

        short seq_access_num1,

        short seq_access_num2

)

Arguments

seq_access_num1	SEQ access number
seq_access_num2	SEQ access number

Explanation

The SEQ data specified by seq_access_num2 is linked to the SEQ data specified by seq_access_num1. This will cause the song specified by seq_access_num2 to be played immediately after the song specified by seq_access_num1.

Return Value

None.

INDEX


SsSeqSetRitardando

Slows the tempo

void SsSeqSetRitardando (

        short seq_access_num,

        long tempo,

        long v_time

)

Arguments

seq_access_num	SEQ access number
tempo	Tempo
v_time	Time (in ticks)

Explanation

The tempo of the song specified by seq_access_num is incrementally decreased to the value specified by tempo in the amount of time specified by v_time.

v_time is specified in number of ticks where 1 tick = 1/60 sec.

SsSeqSetRitardando() gradually decreases the tempo to the specified tempo.

v_time indicates how long it will take to reach that tempo.

Return Value

None.

See Also

SsSeqSetAccelerando()

INDEX


SsSeqSetVol

Sets SEQ volume

void SsSeqSetVol (

        short seq_access_num,

        short voll,

        short volr

)

Arguments

seq_access_num	SEQ access number
voll	Left channel main volume
volr	Right channel main volume

Explanation

The main volume of the song specified by seq_access_num is set to the values specified by voll (left) and volr (right). The volume values can range from 0 to 127.

Return Value

None.

See Also

SsSeqGetVol()

INDEX


SsSeqStop

Ends playback of SEQ data

void SsSeqStop (

        short seq_access_num

)

Arguments

seq_access_num	SEQ access number

Explanation

The playback of the song specified by seq_access_num is ended.

Return Value

None.

See Also

SsSeqPlay()

INDEX


SsSetMute

Sets or clears the mute state

void SsSetMute (

        char mode

)

Arguments

mode	Mute mode SS_MUTE_ON Mute on SS_MUTE_OFF Mute off

Explanation

The mute state is set to the mode specified by mode.

Return Value

None.

See Also

SsGetMute()

INDEX


SsSetMVol

Sets the main volume

void SsSetMVol (

        short voll,

        short volr

)

Arguments

voll	Left channel volume
volr	Right channel volume

Explanation

The main volume is set to the values specified by voll (left) and volr (right). Volume values can range from 0 to 127.

The main volume must be set before playing a song.

Return Value

None.

See Also

SsGetMVol()

INDEX


SsSetSerialAttr

Sets CD audio attribute

void SsSetSerialAttr (

        char s_num,

        char attr,

        char mode

)

Arguments

s_num	Must be set to SS_CD
attr	Attribute attr = SS_MIX Mixing attr = SS_REV Reverberation
mode	Desired mode mode = SS_SON Set attribute on mode = SS_SOFF Set attribute off

Explanation

The CD audio attribute specified by attr is set according to the value of mode.

Return Value

None.

See Also

SsGetSerialAttr()

INDEX


SsSetSerialVol

Set CD audio volume

void SsSetSerialVol (

        short s_num,

        short voll,

        short volr

)

Arguments

s_num	Must be set to SS_CD
voll	Left channel volume
volr	Right channel volume

Explanation

The CD audio volume is set to the values specified by voll (left) and volr (right).

Volume values can range from 0 to 127.

Return Value

None.

See Also

SsGetSerialVol()

INDEX


SsSetTempo

Sets the tempo

void SsSetTempo (

        short access_num,

        short seq_num,

        short tempo

)

Arguments

access_num	SEQ access number
seq_num	Must be set to 0
tempo	Song tempo

Explanation

The tempo of the song specified by access_num is set to the value specified by tempo.

SsSetTempo() can be used to change the tempo set by SsSeqPlay(). The new tempo will take effect immediately.

Return Value

None.

INDEX


SsUtAllKeyOff

Sets all voices to key off state

void SsUtAllKeyOff (

        short mode

)

Arguments

mode	Must be 0

Explanation

Forcibly keys off all voices.

Return Value

None.

See Also

SsUtKeyOn(), SsUtKeyOff(), SsSeqPlay()

INDEX


SsUtChangePitch

Changes the pitch

short SsUtChangePitch (

        short voice,

        short vabId,

        short prog,

        short old_note,

        short old_fine,

        short new_note,

        short new_fine

)

Arguments

voice	Voice number
vabId	VAB ID
prog	Program number
old_note	Note number passed to SsUtKeyOn()
old_fine	Fine pitch passed to SsUtKeyOn() (note number)
new_note	Updated note number
new_fine	Updated pitch

Explanation

The pitch of the voice keyed on by SsUtKeyOn() is changed according to the values specified by new_note and new_fine.

Return Value

0 is returned if the pitch was successfully changed, otherwise -1 is returned.

See Also

SsUtPitchBend()

INDEX


SsUtGetReverbType

Gets the reverberation type

short SsUtGetReverbType (

        void

)

Arguments

None.

Explanation

The value of the current reverberation type is obtained and returned.

Return Value

The value of the current reverberation type is returned.

See Also

SsUtSetReverbType()

INDEX


SsUtGetVVol

Gets voice volume

short SsUtGetVVol (

        short vc,

        short *voll,

        short *volr

)

Arguments

vc	Voice number
voll	Pointer to memory area for storing result volume (left)
volr	Pointer to memory area for storing result volume (right)

Explanation

The values of the volume specified by vc are obtained and placed in the storage locations specified by voll (left) and volr (right).

Return Value

0 is returned if the values were successfully obtained, otherwise -1 is returned.

See Also

SsUtSetVVol()

INDEX


SsUtKeyOff

Keys off voice

short SsUtKeyOff (

        short voice,

        short vabId,

        short prog,

        short tone,

        short note

)

Arguments

voice	Voice number
vabId	VAB ID
prog	Program number
tone	Tone number
note	Pitch specification (note number) in half tones

Explanation

The voice that was keyed on by SsUtKeyOn() is keyed off.

Return Value

0 is returned if the voice was successfully keyed off, otherwise -1 is returned.

See Also

SsUtKeyOn(), SsUtAllKeyOff()

INDEX


SsUtKeyOn

Keys on voice

short SsUtKeyOn (

        short vabId,

        short prog,

        short tone,

        short note,

        short fine,

        short voll,

        short volr

)

Arguments

vabId	VAB ID
prog	Program number
tone	Tone number
note	Pitch specification (note number) in half tones
fine	Fine pitch (100/127 cents)
voll	Volume (left)
volr	Volume (right)

Explanation

The voice specified by the vabid, prog, and other arguments is keyed on at the specified pitch and volume.

The allocated voice number is returned.

note specifies the actual key that will be played and represents one of the 128 keys on the piano.

fine specifies the pitch of that note.

Return Value

If the function is successful, the allocated voice number (0 to 23) is returned.

-1 is returned if the key on failed to complete.

See Also

SsUtKeyOff(), SsUtAllKeyOff()

INDEX


SsUtPitchBend

Applies a pitch bend

short SsUtPitchBend (

        short voice,

        short vabId,

        short prog,

        short note,

        short pbend

)

Arguments

voice	Voice number
vabId	VAB ID
prog	Program number
note	Pitch specification (note number) in half tones.
pbend	Pitch bend value

Explanation

The pitch bend specified by pbend is applied to the voice keyed on by SsUtKeyOn().

Return Value

0 is returned if the pitch bend was successfully applied, otherwise -1 is returned.

See Also

SsUtChangePitch()

INDEX


SsUtReverbOff

Turns off reverberation

void SsUtReverbOff (

        void

)

Arguments

None.

Explanation

Reverberation is turned off.

Return Value

None.

See Also

SsUtReverbOn()

INDEX


SsUtReverbOn

Turns reverberation on

void SsUtReverbOn (

        void

)

Arguments

None.

Explanation

Reverberation is turned on using the type and depth previously set with SsUtSetReverbType() and SsUtSetReverbDepth().

Return Value

None.

See Also

SsUtReverbOff()

INDEX


SsUtSetReverbDelay

Sets the amount of reverberation delay

void SsUtSetReverbDelay (

        short delay

)

Arguments

delay	Reverberation delay amount (0~127)

Explanation

The amount of reverberation delay is set to the value specified by delay.

Reverberation delay applies only to echo-type and delay-type reverberation.

Return Value

None.

See Also

SsUtSetReverbType()

INDEX


SsUtSetReverbDepth

Sets the reverberation depth

void SsUtSetReverbDepth (

        short ldepth,

        short rdepth

)

Arguments

ldepth	Left reverberation depth value (0~127)
rdepth	Right reverberation depth value (0~127)

Explanation

The reverberation depth is set to the values specified by ldepth (left) and rdepth (right).

Return Value

None.

See Also

SsUtSetReverbType()

INDEX


SsUtSetReverbFeedback

Sets the amount of reverberation feedback

void SsUtSetReverbFeedback (

        short feedback

)

Arguments

feedback	Amount of reverberation feedback (0~127)

Explanation

The amount of reverberation feedback is set to the value specified by feedback.

Reverberation feedback applies only to echo-type reverberation.

Return Value

None.

See Also

SsUtSetReverbType()

INDEX


SsUtSetReverbType

Sets the reverberation type

short SsUtSetReverbType (

        short type

)

Arguments

type	Reverberation type
Type	Mode	Delay Time*	Feedback*
SS_REV_TYPE_OFF	Off	X	X
SS_REV_TYPE_ROOM	Room	X	X
SS_REV_TYPE_STUDIO_A	Studio (small)	X	X
SS_REV_TYPE_STUDIO_B	Studio (medium)	X	X
SS_REV_TYPE_STUDIO_C	Studio (large)	X	X
SS_REV_TYPE_HALL	Hall	X	X
SS_REV_TYPE_SPACE	Space echo	X	X
SS_REV_TYPE_ECHO	Echo	O	O
SS_REV_TYPE_DELAY	Delay	O	O
SS_REV_TYPE_PIPE	Pipe echo	X	X
* Delay time and feedback amount can also be set

Explanation

The reverberation type specified by type is set.

When the reverberation type is set, the reverberation depth is automatically set to 0.

When data is left in the reverberation work area, noise will appear when the reverberation depth is set.

The following procedure can be used to circumvent this problem:

SsUtSetReverbType(SS_REV...);

SsUtReverbOn();

:

Wait several seconds

:

SsUtSetReverbDepth(64,64);

Number and type are as shown in the table above.

Return Value

Type is returned if the reverberation type was successfully set, otherwise -1 is returned.

See Also

SsUtGetReverbType(), SsUtSetReverbDepth(), SsUtSetReverbFeedback(), SsUtSetReverbDelay()

INDEX


SsUtSetVVol

Sets voice volume

short SsUtSetVVol (

        short vc,

        short voll,

        short volr

)

Arguments

vc	Voice number
voll	Volume (left)
volr	Volume (right)

Explanation

The volume of the voice specified by vc is set to the values specified by voll (left) and volr (right).

Return Value

0 is returned if the volume was successfully set, otherwise -1 is returned.

See Also

SsUtGetVVol()

INDEX


SsVabClose

Closes VAB data

void SsVabClose (

        short vab_id

)

Arguments

vab_id	VAB ID

Explanation

The VAB data specified by vab_id is closed.

Return Value

None.

See Also

SsVabTransfer()

INDEX


SsVabTransfer

Accesses and transfers VAB waveform data

short SsVabTransfer (

        u_char *vh_addr,

        u_char *vb_addr,

        short vabid,

        short i_flag

)

Arguments

vh_addr	Pointer to start of VH data
vb_addr	Pointer to start of VB data
vabid	VAB ID
i_flag	Must be set to 1

Explanation

The sound source header list (VH data) pointed to by vh_addr is accessed and the corresponding waveform data (VB data) pointed to by vb_addr is transferred to the SPU sound buffer.

The VAB identification number is specified in vabid.

When vabid is -1, SsVabTransfer() allocates and returns an available VAB ID number (0-15).

Return Value

The VAB ID number is returned if the VAB data was successfully transferred to the SPU sound buffer.

If the function fails to complete, one of the following values is returned:

-1	VAB ID cannot be assigned or invalid VH
-2	Invalid VB
-3 or greater	Other errors

See Also

SsVabClose()

INDEX


SndVolume

Volume

struct SndVolume {

        u_short left;

        u_short right;

};

Members

left	Left channel volume value
right	Right channel volume value
INDEX


Library Reference Index

C Functions
Graphics Functions
Graphics Structures
Mathematical Functions
Miscellaneous Functions
Miscellaneous Structures
Sound Functions
Sound Structures


C Functions

abs
atoi
atol
bcmp
bcopy
bsearch
bzero
calloc
free
getc
getchar
gets
isalnum()
isalpha()
isascii()
iscntrl()
isdigit()
isgraph()
islower()
isprint()
ispunct()
isspace()
isupper()
isxdigit
labs
longjmp
malloc
memchar
memcmp
memcpy
memmove
memset
printf
putc
putchar
puts
qsort
rand
realloc
setjmp
sprintf
srand
strcat
strchr
strcmp
strcpy
strcspn
strlen
strncat
strncmp
strncpy
strpbrk
strrchr
strspn
strstr
strtok
strtol
strtoul
toascii
tolower
toupper


Graphics Functions

ApplyMatrix
ApplyMatrixLV
ApplyMatrixSV
ClearImage
CompMatrix
DrawSync
FntFlush
FntLoad
FntOpen
FntPrint
GetClut
GetTPage
GsClearOt
GsDefDispBuff
GsDrawOt
GsGetActiveBuff
GsGetLs
GsGetLw
GsGetLws
GsGetTimInfo
GsGetWorkBase
GsIncFrame
GsInit3D
GsInitCoordinate2
GsInitFixBg16
GsInitGraph
GsLinkObject4
GsMapModelingData
GsScaleScreen
GsSetAmbient
GsSetClip
GsSetClip2D
GsSetDrawBuffClip
GsSetDrawBuffOffset
GsSetFlatLight
GsSetFogParam
GsSetLightMatrix
GsSetLightMode
GsSetLsMatrix
GsSetOffset
GsSetOrign
GsSetProjection
GsSetRefView2
GsSetView2
GsSetWorkBase
GsSortBG
GsSortBoxFill
GsSortClear
GsSortFastSprite
GsSortFixBg16
GsSortGLine
GsSortLine
GsSortObject4
GsSortOt
GsSortSprite
GsSwapDispBuff
gteMIMefunc
KanjiFntClose
KanjiFntFlush
KanjiFntLoad
KanjiFntOpen
KanjiFntPrint
Krom2Tim
Krom2Tim2
LoadImage
MoveImage
MulMatrix0
PopMatrix
PushMatrix
PutDispEnv
PutDrawEnv
ResetGraph
RotMatrix
RotMatrixX
RotMatrixY
RotMatrixZ
ScaleMatrix
ScaleMatrixL
SetDispMask
StoreImage
TransMatrix
TransposeMatrix
VSync
VSyncCallback


Graphics Structures

CVECTOR
DISPENV
DRAWENV
GsBG
GsBOXF
GsCELL
GsCOORD2PARAM
GsCOORDINATE2
GsDOBJ2
GsF_LIGHT
GsFOGPARAM
GsGLINE
GsIMAGE
GsLINE
GsMAP
GsOT
GsOT_TAG
GsRVIEW2
GsSPRITE
GsVIEW2
MATRIX
RECT
SVECTOR
VECTOR


Mathematical Functions

acos
asin
atan
atan2
atof
ceil
cos
cosh
exp
fabs
floor
fmod
frexp
hypot
ldexp
log
log10
modf
pow
printf2
sin
sinh
sprintf2
sqrt
strtod
tan
tanh


Miscellaneous Functions

_get_errno
CdPlay
CdReadExec
CdReadFile
CdReadSync
CdSearchFile
close
delete
EnterCriticalSection
Exec
ExitCriticalSection
firstfile
FlushCache
format
GetPadBuf
GetRCnt
GetVideoMode
InitHeap
ioctl
Load
LoadTest
lseek
nextfile
open
read
rename
ResetRCnt
SetVideoMode
StartRCnt
TestCard
write


Miscellaneous Structures

CdlFILE
CdlLOC
DIRENTRY
EXEC


Sound Functions

SsGetMute
SsGetMVol
SsGetSerialAttr
SsGetSerialVol
SsIsEos
SsPlayBack
SsSeqClose
SsSeqGetVol
SsSeqOpen
SsSeqPause
SsSeqPlay
SsSeqReplay
SsSeqSetAccelerando
SsSeqSetNext
SsSeqSetRitardando
SsSeqSetVol
SsSeqStop
SsSetMute
SsSetMVol
SsSetSerialAttr
SsSetSerialVol
SsSetTempo
SsUtAllKeyOff
SsUtChangePitch
SsUtGetReverbType
SsUtGetVVol
SsUtKeyOff
SsUtKeyOn
SsUtPitchBend
SsUtReverbOff
SsUtReverbOn
SsUtSetReverbDelay
SsUtSetReverbDepth
SsUtSetReverbFeedback
SsUtSetReverbType
SsUtSetVVol
SsVabClose
SsVabTransfer


Sound Structures

SndVolume