User's Guide
Software Development Tool
User's Guide Software Development Tool
This product is sold to Members of Net Yaroze according to the terms of the membership agreement. Net Yaroze is operated by Sony Computer Entertainment Inc.
The elt. symbol, 'PlayStation' and 'Net Yaroze’ are trademarks of Sony Computer Entertainment Inc.
The names of companies and products referred to in Net Yaroze are trademarks of their respective companies. Company and product names recorded in/on this product are generally trademarks of each company. Note that the symbols '® 'and 'TM' are not used explicitly.
Published March 1997 ©1997 Sony Computer Entertainment Inc. All Rights Reserved.
Written and produced by :
Sony Computer Entertainment Inc.
Akasaka Oji Building
8-1-22 Akasaka, Minato-ku, Tokyo, Japan 107 Inquiries to: Network Business Project E-mail:ny-info@scei.co.jp
TEL:+81 (0) 3-3475-1711
Sony Computer Entertainment Europe Sony Computer Entertainment America Waverley House 919 E. Hillsdale Blvd., 2nd Floor
7-12 Noel Street Foster City, CA 94404
London W1V 4HH, England USA
Inquiries to: The Yaroze Team Inquiries to: The Yaroze Team
E-mail: yaroze-info@scee.sony.co.uk E-mail: yarozeQinteractive.sony.com TEL: +44 (0)-171-447-1616 TEL: +1-415-655-3600
| Table of Contents
SYSTEM OVER VIE Wiieccccssdccosvececcvesscusoscvacescossenestsccecescescesscosesseuseevesdscessusscvevesosssccsees’ 9 THE NET YAROZE SYSTEM cosirer HE er dodges A eons See Seas 10 THE NET YAROZE WEB SITE ........ccecececeenenenee ee ee eeeeeeeenene en aada e TAa SATa Taa a an Onia Sarea a aina 11 PLAYSTATION ARCHITECTURE. meio A LIS ad A o a 11 THE CPU AND ITS PERIPHERALS. ..ooooccccccncnononcncorocononononononononrnnonono no nono no nonrnrnronanonononononoss 13 GRAPHIES: SYSTEM id ia 15 SOUNDS VS TEM Lada ova de stew. sae IESO Dodd ee a outa lee Belek ae 18 OTHERS YSTEMS a obs 18
THE PLAYSTATION DEVELOPMENT ENVIRONMENT..........cccccosscescccsccscccsccesccescees 21 THE PROFESSIONAL PLAYSTATION DEVELOPMENT SYSTEM .........ccececececcececeseseesecesueeseeeususs 22 THE NET YAROZE PLAYSTATION DEVELOPMENT SYSTEM.........ccccccceceseceeceeeseeeseececuseseeeususs 23
DEVELOPING AN APPLICATION ............ccccccsscsscsccscescescsccsccsceccscescescescscescesceccscescesces 25 CREATING A PROGRAM. a ovee liebe Veet van bestehen 26 CREATING DATA»... nennen ERROR! BOOKMARK NOT DEFINED. PROGRAMMING TVE Dias rl dci 29 THE APPLICATION ENVIRONMENT. .oooccccccnononcnononcorononononono nono ncnnonono nro no nono ncnrnrorononanonononons 40
THE NET YAROZE LIBRARY sieer ceevesesesdsevaececcessbeseseasesveseses 43 GRAPHICSS ERVICES a A a 44 SOUND: SERVIGES 3 4 tirando idad AA E EE EET 44 STANDARD SERVICES a ai 44 OTHER SERVICES % an sense sad vase a a en es nee hen a daa 45 FIEE:ORGANIZAÄTION. an 28 dns AA AA sa 45 PROCESSING OF DATA aussen a IN IRB IRB IR BDO iii dió 47
FRAME BUFFER ACCESS visccstecsscicccscesscssceseecessbsiecsseehosscsteescsadalcccsdvsesseacesesesses soceestess 49 DESCRIPTION OF THE FRAME BUFFER.........c0ccccececeeeeeeeeneneseeeceeeeeeneneneneneeeeeeeeeeeeneeneneneneaes 50 ENVIRONMENT-SETTING FUNCTIONS.........0c0ccccececeeeeee eee en teen ee eeee eens nenen ease ee eeeeeeeeeeneneneneaeaes 51 FRAME-BUFFER-ACCESS FUNCTIONS ..0ococncncncncoconononononononcnnorononononononononcncnronanononononononcnnons 52 DRAWING-CONTROL FUNCTIONS ...ococnoncncncocononononononononcncononononrnono nono E EEEE EE Eed D 53 KANJI [JAPANESE CHARACTER] FONTS. ..ocoococoococononcncncnncncnnconnnconnnnnnnncnnrncnnnnnnnnnnrncnnnnnnnoos 54
INTEGRATED GRAPHICS 0 57 PROCESSING E LOW rar u ea RE LERNEN en AA A ri ia 59 GRAPHICS SYSTEM INITIALIZATION ...ooooooconncncncncncnconononononononononcnnonononn een en en ea ease ee eeeeeeneneneas 60 THE VIEWPOINT: <6 2:00 05404 codon racistas 61 PACKETS ¥ a. 2a aan nenn reines a 62 ORDERING TABLES: Sansa Renee AN TAO WEES LE SpE eS OSES lee ee 63 COORDINATE TRANSFORMATION & LIGHT SOURCE CALCULATION..........ccccceceeeseseeeesecusesees 64
CREATING+PACKET Strada dx codashadsedzostusaveds tovdanestaubduccstae otesssued tones a skew eesesseeouetes $e 12
SOUND. une aia Ie RARE idas 75 SCORE DATA: a a a ea N ne hen ne haven Tea Rs AN a a A teo te 76 MIDI;SUBPORE.. 2.30: 22. a e a ii 77 WAVEFORM DA TAS 23 Sees een ra nee Enke ae ia Hen EGAN Dr Soto ak 79 FUNCTION EXECUTION ORDER vienai A a sh dad 80
STANDARD:C-FUNCTIONS yin ccececescsevcuecsscuscsstccsccovevenscdcucsovevesssdcnsceaeecesscesaesesecesessseese 81 INCLUDE HEADERS ¿direc ii ind ii dai 82 SUPPORTED. FUNCTIONS uns nenn o EE OEE EE EANNA 83
MATH FUNCTIONS wosscisiscecesestvcsasslaccovescesscdalecscculsscetsodaedosssctesesvecvecdossevevestevovecstececcses 85 FLOATING-POINT NUMBERS 's unser A act 86 ERROR HANDLING +. e 87 SUPPORTED: FUNCTIONS aan ed 89
KERNEL MANA GEMEN Tin cciscdscecscvcssctescctsccecsocscetesecdsccecevsccvacecessceecsvsocvecteccececevesssese 91 ROOT COUNTER MANAGEMENT ......ccccecececec eee e eee e nen e ene ee ee eens eens en en ease sees eeeeeen en eneneneaeaeees 92 VOTMANAGEMEN Toe 93 MODULE MANAGEMENT SERVICE. .ocococncncncncocononononononononrnnonononononononononcnnononononononononcnranons 95 ADDITIONAL SERVICES: tata DA A a E rt a Led ations 96
CD-ROM MANAGEMEN T.........cccccsccsccscsccsccccsccsceccscesceccscsccscescscescessscescscesceccscsccscescsces 99 CD-ROM OVERVIEW cis in nenne diia ada Ed 100 THE FTE SYSTEM darse 102 FILE ACCESS aa oia 103
PERIPHERAL DEVICES MANAGEMEN T..........ccccoscosccssceccsscescescescescescescesccscssccecseces 105 CONTROLLER: MANAGEMEN Tenisa an A A e 106 MEMORY CARD MANAGEMENT. ooocconcnoncncocononononononono eee ence ee ee sees ee eeee een en en ease eeeeeeetneenes 110
CREATING PLAYSTATION APPLICATIONG.............ccccoscssccsccsccscceccescescescescescescesces 111 CREATING GRAPHICS DATA 1.0... ccc ec ec ec eee e nee e ene cece cece eee e teense ea ea ea es es eset EE EE EEE SESE EG EE EE EES 112 CREATING: SOUND: DATA: u nn 2 Ran A E rah AI 115 CREATING A PROGRAM... cc. cc ccccec cence eee e teen ene e eee eee e eee EEE nono EEA EE EE EE EE EG EEE; EERE EE EEE ED EE EE EE EE EE EE EE 117
GRAPHICS: TOOLS ee doocestetcatelawesdsdasel sectessacwsteristeveshebiaseeds 119 DXF2RSDIEXE aaa 121 DXF2RSDW.EXE vi is cs dis banda 132 RSD2BXF:EXE nn A erg ns có void 140 RSDCAT.EXE. ¿id Ai 141 RSDFORM.EXE + esse sen een tia 142 RSDLINK. EXE can a ati 148
RSDV:BAT (RSD: PREVIEWER). ne... ae nl a Hein E tU 155
TIMUTIE:EXEX TIM UTILITY ta da in res 157
TIM BAT Solista told iaa Trios aleteo 168 SOUND TOOD S 00d a ESAS Lidia 171 ITAS LON EXE aa 173 AC E A E E E TA OTT, 174 MK VABY EXE 6 oi a en AA A IS AO Stones alos EERE 175 VABSPLIT. EXE ii A A oats A di ves (eee dee ias 178 SOUND: PEAYERS cc a shoe 179 PROGRAMMING TOOLS wivancscccaceciedessesssaccsdssces soscnsocscetvescesovecvedescdsseseesdecseseccceeasseess 183 THEGEC COMPILER 0 cas 184 TAE ToD LINKER 30.40 002m Aa eis Aaa a les de Bes a 190 STRIP (SYMBOL INFORMATION REMOVER)........c.csseeeeeeeceeececeeeecueeeeaeeceaeeecueceeaeseeaeeceaeeeees 192 THE MAKE MAINTENANCE UTILITY ............cccccececeecececeeeesceeseeecsseeecuseeseeeeseeeeeeeseeeueusneees 192 MAKEFIEES ¿a A A en A A AAA 194 THE CONSOLE TOOL ¿ii aiii 203 AN OVERVIEW OF SIOCONS ooococcccncncncncncononononononcnrorononononononnnnonn nono no nrnrnnnnononononcnrananos 204 USAGE it A taaan 205 OPERATION tds da a E E aha raid aca da ie 205 DOWNLOADING AND EXECUTING FILES ...oococccncncnnnncnoncnonononcororonononono nono nonononcnrnranononononos 207 TERMINATING SIOCONS u... nen adds bees 208
ÄUFOFEXECUTION ne ii da una RR a A 208
| About Net Yaroze
In order to get started with Net Yaroze, you should have C programming competence and you should be familiar with 2D graphic creation/editing tools. You should also have a basic understanding of 3D modelling packages and sound creation/editing tools. Together these will help you get the most out of
your Net Yaroze System.
The Net Yaroze Manual Set
There are three books in the Net Yaroze manual set.
1. Start-Up Guide An introductory booklet explaining the contents and requirements of the Net Yaroze Starter Kit. The Start-Up Guide gives step-by-step instructions on setting up the Net Yaroze software on
your PC. It also explains how to run software on the Net Yaroze system.
2. User's Guide (this document)
A reference manual explaining how to create software for the Net Yaroze system.
3. Library Reference
A manual listing and describing the functions and structures in the Net Yaroze libraries.
Additional Reading See the Additional Reading section at the end of the Start-up Guide.
1
System Overview
HEE System Overview EY This chapter contains an overview of the Net Yaroze system and an explanation and overview of
PlayStation hardware.
Net Yaroze is a revolutionary product which enables anyone to create PlayStation applications using a set of Net Yaroze development tools, a personal computer and a special Net Yaroze PlayStation. Net Yaroze Members can post their applications to an exclusive Net Yaroze Web site where they can be
shared and enjoyed by other Members.
| The Net Yaroze System
The Net Yaroze system is designed to let you write, debug and test PlayStation applications on a personal computer (PC) linked to a special Net Yaroze PlayStation. The PC, which acts as a host machine,
is linked via a dedicated serial cable to the PlayStation which runs the applications.
C] YAROZE Web site
Communications cable
AV cable
| YAROZE O boot disk
Access card
moqem YAROZE softwarb1/+ development disk
Figure: Net Yaroze System Set Up
Controller
Your first step in developing a Net Yaroze application is to create a program using a set of special Net Yaroze programming tools. After you've written, compiled and linked your program, you need to download it to the Net Yaroze PlayStation using SIOCONS, the console tool (discussed in Chapter 17).
From there your application can be tested by running it directly on the Net Yaroze PlayStation.
You can also download and test data which is used by your application, such as a sound file. (You need
to use the Controller connected to the PlayStation to control your application.)
10
System Overview MEM
If your Net Yaroze host computer also has an Internet connection, you can not only post your Net Yaroze programs to the Web site very easily, but also download and immediately execute those programs posted
by other Members.
| The Net Yaroze Web site
The Net Yaroze Web site is hosted on Sony’s World Wide Web server and is accessible via the Internet. The Net Yaroze Web site has features such as a mail forum, Member's home pages and access to documentation and program libraries. It enables the exchange of information between Members as well as the uploading and downloading of Net Yaroze applications. The site also provides the latest Net Yaroze-
related information and technical support.
You'll need an Internet connection and a World Wide Web browser to access the Web site. Please refer to
the Start-Up Guide for detailed instructions.
| PlayStation Architecture
As is shown in the following diagram, the PlayStation system is based on a 32-bit RISC CPU, and
comprises a number of processors and devices dedicated to specific functions such as graphics and sound.
11
EEE System Overview
Figure : PlayStation Block Diagram
R3000 CPU
Peripheral device
Glossary GTE
GPU SPU MDEC PIO SIO
12
Main memory
OS ROM
MDEC
SIO
: Geometry Transfer Engine
: Graphics Processing Unit
: Sound Processing Unit
: Data Decompression Engine : Parallel Expansion port
: Serial Expansion Port
Video output Sound output
Sound buffer CD-ROM
drive
Controller
Memory card
System Overview MEM
| The CPU and lts Peripherals
The PlayStation uses a custom CPU based on the R3000 (33 MHz) 32-bit RISC CPU (little-endian
architecture).
The I-Cache The CPU reads instruction code from the I-cache at approximately 5 times the speed of main memory. Once instruction code has been read, it is stored in the I-cache within the CPU and can be re-executed without
accessing main memory. The I-cache cannot be directly accessed from a program.
The CPU is equipped with a 4 KB I-cache. The PlayStation”s logical memory space is divided into 4 KB
units and these are multiply-mapped into the I-cache.
The D-Cache
The D-cache uses a special structure called a scratch pad which is mapped into 1 KB of logical memory
space (addresses 0x1f800000-0x1f8003ff). The program developer can freely access this scratch pad area.
The General-Purpose Registers There are thirty-two 32-bit general-purpose registers. The compiler assigns a specific use to each register as shown in the table below. Threaded databases and application development using the assembler
require that registers be used according to the assignments shown below.
Register Assembler No. Assignments R_ZERO | RRO | zero always 0 R
RAT R RI reserved for the assembler
2-3 R_VO-1 R_R2-3 vo-1 values returned by functions 4-7 R_A0-3 a0-3 function arguments 15
24-25 R_T8-9 R_R24-25 t8~9
26~27 R_K0-1 R_R26-27 k0-1 reserved for the kernel p a
destroyed within functions
8-15 R_T0~7 t0-7 destroyed within functions 16-23 R_S0-7 R_R16-23 s0~7 saved within functions
28
29 s 30 fp 31 i
Table: R3000 General-Purpose Registers
global pointer stack pointer
frame pointer return address
13
EEE System Overview ee o ___ EOÓOOOÓOÓOÓáá,;,ÓXxz"“c_o.o< ón
Return Address
The R3000 does not have any built-in support for subroutine calls. Instead, a subroutine call is performed by executing a jump instruction that saves the return address in a register. The register that contains the return address can be specified using the assembler, however, the C compiler will always use general-
purpose register 31.
The Stack
The R3000 does not have any built-in support for a stack. Instead, the compiler implements a stack by storing a stack pointer in general-purpose register 29. In addition, efficient operation of function frames (memory areas used for automatic variables and as working areas) is achieved by saving the start address for the frame in general-purpose register 30. This address is known as the frame pointer. The value of the frame pointer is determined from the value of the stack pointer. When a module is activated, the frame
pointer and stack pointer have identical values.
The Global Pointer
The R3000 can access memory with a register-indirect addressing mode that uses a signed 16-bit offset. For efficiency, the compiler keeps up to 64 KB of data in a block called the bss section. The midpoint address of this block is stored in general-purpose register 28. Using register-indirect addressing and a 16-bit offset from general-purpose register 28, the R3000 can access data in the bss section with a single instruction. The address in general-purpose register 28 is known as the global pointer and does not
change within a module.
Main Memory The PlayStation is equipped with 2 MB of main memory. Addresses are allocated in this memory starting
from 0x0000 0000. This address space is referred to as 'physical memory space’. The CPU’s memory space consists of 32-bit addresses and is known as 'logical memory space'. Physical
memory space is mapped to three areas in logical memory space. The CPU is not equipped with a virtual
memory manager so this mapping between the two memory spaces is fixed as shown in the table below.
14
System Overview MEM
| PhysicalMemory | Memory | LogicalMemory | Memory Segment Name 0x00000000-0x00 1 fffff 0x00000000~x001 fffff ku Available 0x80000000~0x801 fffff k0 Not available 0xa0000000-0xa0 1 fffff kl Available
Table: Physical Memory and Logical Memory
The OS ROM
The PlayStation is equipped with 512 KB of ROM. The OS kernel and the boot loader are stored in this ROM. Access to the OS ROM is not permitted from an application program.
The DMA Controller A DMA Controller is attached to the CPU. The DMA Controller is used for data transfers between
memory and devices according to instructions from the CPU.
| Graphics System
The PlayStation is equipped with a graphics processing unit (GPU). The GPU features CRTC functions for displaying frames on the screen, as well as for performing high-speed polygon drawing using a frame buffer.
The Frame Buffer
The GPU has a 1 MB frame buffer. The frame buffer is described by a two-dimensional address space (1024 x 512) made up of 16-bit pixels. The frame buffer’s memory space is managed by the GPU and cannot be directly accessed from the CPU.
The Display The GPU displays the contents of an arbitrary rectangular area within the frame buffer directly on the CRT display. This area is called the 'display area".
The table below shows the 10 supported screen modes of the GPU.
15
EEE System Overview
Interlaced Non-interlaced Interlaced Non-interlaced
256(H) x 480(V) 256(H) x 240(V) 256(H) x 512(V) 256(H) x 256(V) 320 x 480 320 x 240 320 x 512 320 x 256 512 x 480 512 x 240 512x512 512 x 256 640 x 480 640 x 240 640 x 512 640 x 256 384 x 480 384 x 240 384 x 512 384 x 256
Table: Screen Modes (NTSC and PAL)
The GPU supports two color-display modes: 15-bit direct mode (32,768 colors) and 24-bit direct mode (full color).
In 15-bit direct mode 32,768 colors can be displayed simultaneously. This is fewer colors than can be displayed in 24-bit direct mode, however, color calculations within the GPU during drawing are always performed using 24 bits. Consequently, pseudo-full color can be achieved in 15-bit direct mode by
dithering.
In 24-bit direct mode 16,777,216 colors can be displayed simultaneously. However, in 24-bit direct mode only static images (still pictures) can be displayed from image data that has been transferred to the frame
buffer. The drawing functions of the GPU cannot be used in 24-bit direct mode.
In 24-bit direct mode a single pixel has a bit length of 24 bits, but the display position coordinates in the frame buffer must be specified as if the pixel size were 16 bits. Thus, a 640 x 240 image in 24-bit direct
mode will have an actual size of 960 x 480 in the frame buffer.
Drawing Capabilities
The GPU supports the following drawing functions.
Description
Polygon 4-bit CLUT (16 colors/polygon)
Drawing 8-bit CLUT (256 colors/polygon) 16-bit direct (32768 colors/polygon) Flat shading, Gouraud shading
Texture mapping
Gradation is possible Image CPU O frame buffer Transfer Frame buffer — frame buffer
a Blending (semi-transparency), dithering, clipping
16
System Overview MEM om)
Table: GPU Drawing Functions
Polygon Drawing
The GPU is capable of drawing polygons. The polygons that the GPU operates on can be either 3-sided or 4-sided figures. These polygons are drawn by specifying the screen coordinates for each of the vertices of the figure. The shape of the polygons, their color and/or texture can all be specified. For example, the GPU can perform 'texture mapping' (in which an image from an arbitrary area of the frame buffer is pasted onto the polygon surface), 'flat shading' (solid color paint out) and 'Gouraud shading' (gradation paint out, in which each pixel of the polygon is given a color calculated from the colors assigned to the
vertices).
Images and texture patterns pasted onto polygons are transferred to the frame buffer before drawing the polygon. Data is stored in the frame buffer in 256 x 256 pixel pages, in which there can be as many pages as available memory will allow. These 256 x 256 areas are referred to as 'texture pages'. The size of a texture
page in the frame buffer is determined by the color mode, as described below.
CLUT Processing There are 3 color modes for texture patterns: a 4-bit CLUT mode, an 8-bit CLUT mode and a 15-bit direct
mode.
CLUTs (Color Look-Up Tables) are used in 4-bit and 8-bit CLUT modes. A CLUT is a set of 16 or 256 RGB values stored in the frame buffer. These RGB values represent the colors that will ultimately be displayed on-screen. Each RGB value in the set is numbered in order from left to right. Each number corresponds to a pixel in a sprite pattern with the associated RGB value used to determine the pixel’s color. CLUTs can be selected at the sprite level which means each sprite can have its own independent CLUT.
Entry 0 1 2 3 15 or 255
OCI | TT ff
Figure: CLUT Structure
17
EEE System Overview e]
Each entry in the CLUT has the same structure as a single pixel in 15-bit direct mode. Therefore, one
CLUT is equivalent to 1 x 16 or 1 x 256 pixels of image data.
| Sound System
The PlayStation sound system is made up of the Sound Processing Unit (SPU) and the CD-ROM decoder. Audio output from the CD-ROM decoder enters the SPU, is mixed with the output from the SPU, then
transformed into the final audio output.
The CD-ROM Decoder
Data read from the compact disc (CD) can be reproduced directly as audio output or transferred as sound
data to main memory.
ADPCM data, defined by the CD-ROM XA standard, and CD-DA 16-bit PCM data are directly output as sound. Data read from the drive to the CD-ROM buffer is processed by the sound source within the CD- ROM decoder. The resulting audio signal is sent to the SPU via the mixer built into the decoder.
The SPU
The Sound Processing Unit (referred to as the SPU) is equipped with 24 voices and controls 512 KB of memory. This memory is known as the sound buffer. Compressed waveform data stored in the sound buffer is played back by the SPU at a sampling frequency of 44.1 KHz, in response to commands from the CPU. The sound buffer is composed of a one dimensional memory space made up of 2-byte units. The sound
buffer cannot be directly accessed from the CPU.
The sound buffer can be used as a work area for reverb and other special effects. The sound buffer also serves as a temporary buffer during transfer of sound data from the CD or SPU to main memory. The sound
buffer enables data to be transferred to main memory without interrupting sound production.
Each voice in the SPU is capable of operations such as pitch variation, envelope processing (attack,
decay, sustain, release) and volume control.
| Other Systems
The PlayStation is equipped with the following systems in addition to those described above.
18
System Overview MEM
The GTE The GTE is a coprocessor that performs the vector and matrix arithmetic operations essential for 3D graphics. The GTE performs its processing using fixed-point arithmetic. The results of GTE calculations
can be directly incorporated in drawing commands sent to the GPU.
The Data Decompression Engine The data decompression engine performs high-speed reverse DCT conversion. The engine can decompress JPEG data and MPEG data (only within the frame). The data decompression engine is not available in the
Net Yaroze system.
The Controller
The Controller serves as the interface by which players issue commands to an application. The main PlayStation unit has connectors for two Controllers. In professional PlayStation development, more Controllers can be connected using Multi tap ports. However, Multi tap ports cannot be used with the
Net Yaroze system.
The Memory Card
The Memory card provides storage for PlayStation application data when the PlayStation is reset or turned off. The main PlayStation unit has slots for two Memory cards. In professional PlayStation development, a larger number of cards can be connected using Multi tap ports and Multi taps. Note,
however, that Multi tap ports cannot be used with the Net Yaroze system. Expansion Ports Two expansion ports are provided: one serial, the other parallel.
In professional PlayStation development, two PlayStations can communicate with each other through a Link cable connected to the serial ports. However, the Net Yaroze system uses this serial port to connect the Net Yaroze PlayStation to your computer. Thus the PlayStation Link cable cannot be used with the
Net Yaroze system.
The parallel port is reserved for future expansion and is currently not supported.
19
2
The PlayStation Development Environment
HEE The PlayStation Development Environment ees
The PlayStation is equipped with the PlayStation operating system (OS). This OS was developed specifically for the PlayStation's R3000 CPU and incorporates extremely novel concepts used by both the Professional Development System and Net Yaroze. This chapter provides an overview of the
Professional PlayStation Development System and describes the features of Net Yaroze.
| The Professional PlayStation Development System
The PlayStation OS was developed specifically for the PlayStation’s R3000 CPU and is based on new
and innovative concepts.
The environment and services provided by a machine’s operating system can greatly affect how efficiently a program can be developed. If the CPU and peripheral devices operate at sufficient speed, the programmer canrely on the services provided by the operating system to control the hardware. Application development can proceed smoothly and rapidly as there is no need to spend time pushing hardware
performance to its limit. Thus, the programmer is free to concentrate on application development.
The design concept of the PlayStation OS is to provide the game developer with an optimal environment for developing interrupt-driven programs. Based on this concept, the kernel of the PlayStation OS
provides a collection of services (subroutines) to control the R3000 and the PlayStation hardware.
Access to these services is provided via a set of library functions written in the C programming language. Using C means that the source code can be more readily understood and maintained. Furthermore, the structured nature of the language and the ease with which functions can be called allows program
development to proceed easily.
The Professional PlayStation Development System is based on the concepts described above. It is composed of a small-scale OS kernel that provides efficient interrupt processing and multitasking support, and a hardware management library and middleware for high-level services such as a MIDI driver and 3D graphics system. The minimum memory required by the OS has been limited to 64 KB, and the OS has been designed so that the developer can have the maximum freedom possible under a CD-ROM system. SCE's R&D teams continue to expand the professional PlayStation library and middleware based on
requests from professional application developers.
In offering a high degree of freedom, however, this environment requires developers to have a high level of expertise in design and development. As of this writing, there are more than 1600 C language functions
available in the PlayStation library. With such a large number of functions it is possible to perform a
22
The PlayStation Development Environment MEM
single task in many different ways, each with its own set of advantages and disadvantages. Professional
developers must choose the particular method that is best suited to the task at hand.
The Professional PlayStation Development System can be described as a collection of parts designed for use by specialists, where the emphasis is on variety and freedom, rather than uniformity, consistency, or
ease of use.
| The Net Yaroze PlayStation Development System
The Net Yaroze PlayStation Development System was designed with the goal of making the development environment simpler and easier to understand by offering a subset of the Professional PlayStation
Development System.
The features of the Net Yaroze PlayStation Development System are described below.
Programming in C
All PlayStation OS services are provided as C functions so all programming can be done in C.
Ease of Using R3000 Functions Interrupt processing with the R3000 is known to be complicated. The PlayStation OS simplifies this task by handling all interrupt processing in the kernel. In addition, the OS provides a 'callback'
mechanism to notify the user that an interrupt has occurred.
Emphasis on Vertical Synchronization (VSync) Interrupts VSync interrupts are the key to efficient operation of the PlayStation since it was designed expressly for playing video games. VSync interrupts are the focal point of the PlayStation’s callback system. This
system provides a simple interface for coding interrupt processing routines directly in C.
Compactness of Programs
The PlayStation and the development host are connected through a simple serial interface in the Net Yaroze system. In order to overcome the slow data transfer speed of the serial interface, system programs such as graphics, sound, CD-ROM and the debugging monitor are all loaded into main memory from the boot disk as resident libraries. The addresses of these resident libraries are written directly into the
application program by the linker so the libraries can be easily accessed by the program. Thus the size of
23
HEE The PlayStation Development Environment eee
the application program, and hence the download time, is kept to a minimum.
Parallel Processing The PlayStation OS performs CPU program execution concurrently with dedicated hardware processing. In the Net Yaroze system, parallel processing functions are provided by making “polling” central to
programming style.
24
3
Developing an Application
"EN Developing an Application o > _____z5-z>z_____ => _ _ GE_x__ bj: :x::3®;;:x‚:|:.xv;.ii—i<iızı|@|(x:=::([(|'+—(:5x5:—-< |
This chapter presents an overview of how a PlayStation application is created with the Net Yaroze
system.
In the Net Yaroze system, application data such as sound and graphics files (e.g. .bmp files), can be easily
converted from standard file formats into PlayStation file formats.
The application development process is based on that of standard C program development, so standard development procedures can be used. The GNU C compiler and associated utilities are provided as
programming tools.
For detailed descriptions of each of the items given below, please refer to the chapter describing the
hardware or the chapter describing the corresponding service.
| Creating a Program
The Net Yaroze application development process is based on the standard process used in C language program development so it should be familiar to people who have had experience developing programs in
C,
Creating Source Code Source code should be saved in a standard MS-DOS text file using any commercial editor designed for
writing programs.
Compiling and Linking Source code files must be compiled and linked to create an executable program. The Net Yaroze system provides a special library, the GNU C compiler and various tools associated with the compiler for
creating the executable program.
Test Runs
Executable programs can be run and tested on the Net Yaroze PlayStation. The console tool, SIOCONS, (described in Chapter 17) can be used to download the executable program from your PC to the Net Yaroze PlayStation.
26
Developing an Application mmm
Debugging When your program fails to operate as it should, you can debug it at the source code level by using the GNU debugger (gdb) provided with your Net Yaroze kit. GDB allows you to step through your program
and see what's happening as it executes.
Using Makefiles Makefiles are a convenient way to simplify the series of operations needed for compiling and linking. The 'Make' command, which operates on makefiles, allows applications to be maintained at a high level. Make
is provided with the Net Yaroze system.
Making a Library of Useful Routines
You can increase the efficiency of application development by putting frequently called routines and subroutines that are shared by different programs into a library. In the Net Yaroze system, several GNU utilities are provided to assist this process. Two of these are 'ar', the librarian, which builds a library from object files and 'nm', the object symbol management tool, which provides details (such as the start address) of symbols in object files. (See Chapter 16, Programming Tools, the documentation with the GNU compiler on your Net Yaroze PC disk and commercially available documentation, for more
information on the GNU utilities.)
| Creating Data
Data needed within a PlayStation application can be broadly divided into three categories: 2D graphic data, 3D graphic data and sound data. (Note that a fourth type, movie data, while available in the
Professional PlayStation Development System cannot be used in the Net Yaroze system.)
Each of these data types is saved in a special PlayStation data format. The Net Yaroze system provides
utilities to convert files from the standard formats in which they were created into PlayStation formats.
2D Graphic Data
2D graphic data used by the PlayStation consists of image data, which is used for sprite pattern data, and texture data. PlayStation-format 2D graphics data is referred to as TIM data.
There is a special utility in the Net Yaroze system to convert data created using any Windows or
Macintosh painting tool to TIM data.
27
"EN Developing an Application ee
Data type: TIM - image data (sprite pattern and texture)
Tools provided: Utilities to convert from existing formats such as BMP, PICT, (among others) to TIM format
Operating environment: Windows, MS-DOS
3D Graphic Data 3D graphic data used by the PlayStation is used by 3D applications for modeling data. PlayStation- format 3D graphics data is referred to as TMD data.
In the Net Yaroze system, there is a special utility to temporarily convert data from DXF format - the standard 3D modeling format - into the artist-oriented RSD format file, then into the binary TMD format data used by the library.
Data types: RSD - modeling data (defines the shape of objects) TMD - modeling data (binary format) Tools provided: DXF > RSD format, RSD > TMD format converters
Operating environment: Windows, MS-DOS
Sound Data
Sound data used by the PlayStation can be either score data or waveform data. Score data is known as SEQ data while waveform data is referred to as VAB data (Note: This data is also known as VAG data - VAG is single-sound data, whereas a VAB is a collection of VAGs). All of these data types can be
directly processed using the sound services.
In the Net Yaroze system, a special utility converts AIFF data or standard MIDI data (SMF), which has
been created using commercial sound tools, into SEQ and VAB data.
Data types: VAG - waveform (single-sound) data VAB - waveform (bank - collection of VAGs) data SEQ - Score data
Tools provided: SMF > SEQ format, AIFF > VAG format converters Operating environment: Windows, MS-DOS
Data Verification The Net Yaroze system provides a viewer and player which, when called from the DOS prompt of your PC, will display sound and graphic data on your TV monitor via the Net Yaroze PlayStation. Thus you can
verify how sound and graphic data will look when your application is actually run.
28
Developing an Application mmm
Using these tools it is possible to capture application run-time images.
The Link Between Data and Programming Tools
In order to provide graphic and sound data files for PlayStation applications, you need to create and/or edit standard-format data files in a commercial graphic or sound application, then use the Net Yaroze conversion utilities to convert them into the appropriate PlayStation file formats. You can then use these files as part of a Net Yaroze application (where they will be loaded into main memory and accessed by the
program code).
| Programming Style
The following is an explanation of programming methods characteristic of PlayStation applications
together with an explanation of PlayStation terminology.
Basic Style The basic flow of graphics-processing in the PlayStation can be described by the following 3-step
sequence. These steps are performed simultaneously, enabling a continuous flow of new data to the screen. Basic Style Steps:
(1) Data describing a 'world' is placed in memory and is used to create a structure known as a ‘drawing command! list.
(2) The 'drawing command' list is sent to the GPU which draws the corresponding polygons in the frame buffer.
(3) The rendered image in the frame buffer is displayed on-screen.
List structures are created in main memory, whereas screen images are created in the frame buffer. Two sets of list structures and two sets of screen images are maintained. This allows the CPU to be creating the first list while the second is being transferred to the GPU. Similarly, the GPU can be drawing the first screen image while the second is being displayed in the frame buffer. GPU image drawing and display are shown
in the figure below.
29
"EN Developing an Application
Figure: The GPU Draws One Image and Displays Another Simultaneously
The problem with drawing a single frame of 3D graphics is that it can be time-consuming. To overcome this limitation, image creation is divided into two processes which are performed in parallel: drawing
command list creation and polygon drawing.
Of the Basic Style Steps listed on the previous page, step (1) is executed by the CPU according to the program stored in main memory. Step (2) is performed automatically by the DMA Controller, a hardware device dedicated to data transfer. Step (3) is carried out automatically by the image display part of the GPU. The CPU, and consequently the program, has no direct knowledge of the details of the execution of steps (2) and (3). The CPU is only involved in providing the dedicated hardware with very small
amounts of data such as the display location and the start address for data transfer. The benefit of
30
Developing an Application MEM
performing this processing in parallel is that the CPU can devote almost all of its time to creating drawing
command lists.
The technique of saving a previous image for later display also serves to increase the time that is available for image creation. Japanese and US TV NTSC receivers display a frame every 1/30 or 1/60 of a second (30 or 60 frames are displayed in a second. In Europe, the display rate is 25 or 50 frames per second). While one frame is being displayed, the next frame is prepared for display. Even if the next frame is not ready in time to be displayed, the one currently being displayed can be held until the next one is ready. Thus a
continuous display is maintained on-screen.
In the PlayStation, the CPU, DMA Controller and GPU work together to control this operation as
described in the following.
When the CPU completes a drawing command list structure for one full screen and, when the DMA Controller has finished transferring the previous list to the GPU for drawing, then the CPU instructs the DMA Controller to transfer its newly created list to the GPU. At the same time, the image that has been drawn is set up for display in the display part of the GPU.
These steps are summarized as follows:
e CPU makes command list structure e DMA Controller transfers list structure to GPU
e GPU draws one image while it displays another image
However, this process is governed by a time limit. It is not possible to freely switch the displayed image at any time. If image data that is in the process of being displayed is exchanged with other data, image discrepancies and display hardware activity will appear on the screen as noise. Image data switching must be performed at a time when the act of displaying to the screen is finished (the GPU has finished making the image on-screen and the whole image is being shown). The period of time during which this condition is met is called the vertical blanking interval. Vertical blanking occurs at a fixed rate of 60 times per second in NTSC and 50 times per second in PAL. The start of each vertical blanking interval is
communicated to the CPU through a vertical synchronization interruption provided by the hardware.
Thus, the CPU completes list creation, waits for the DMA Controller to complete its data transfer, then waits for the vertical synchronization interruption. When these three conditions are met, the CPU switches the display image in the GPU and sets up the address of the new list in the DMA Controller. Once this process is complete, the CPU starts creating the next drawing command list. It reads the state of
31
"EN Developing an Application ZZ oo pc j :- > ® = >> o... ROÓQQER PE @|€tfjöbkj- <üeiiür:iık?>Öxj@(@Uü xvxv ov;—;cmeb ,ö, |
the Controller and uses this information as the basis for creating a new image. The basic execution style of
PlayStation programs involves a repetition of this sequence.
Double Buffering Double buffering is a technique whereby two equivalent data storage areas, or buffers, are used to simultaneously generate and transfer data or render and display an image. These buffers are swapped at
appropriate times so that the two operations can be performed in parallel.
In standard PlayStation programs, two drawing command lists called 'ordering tables' (OT) (refer to Z sorting, below) are maintained in main memory. Double buffering speeds up image creation by enabling two operations to be performed in parallel. Similarly, two screen images are maintained in the frame buffer
to guarantee time for image creation.
Non-blocking Functions
Most of the processes that are actually performed by dedicated hardware, such as graphics drawing and loading from CD-ROM, can be done in parallel with CPU program execution. The functions that activate this kind of parallel processing are called non-blocking functions. A non-blocking function transmits the relevant processing request to the hardware or OS, then terminates once the request has been recorded.
The actual processing is performed after the non-blocking function has terminated.
In the Net Yaroze system, the completion of processing requested by means of non-blocking functions can be checked at any time by calling a special test function. This programming style, in which a program that
makes a processing request and explicitly tests for the completion of that processing, is called polling.
Z-Sorting When 3D objects are displayed on a 2D screen, a proper image is obtained only if surfaces that are hidden
by other surfaces are eliminated. In the PlayStation this is achieved by means of a Z-sorting algorithm.
Z-sorting is a method of omitting the surfaces that should be concealed by drawing each surface in order, starting from surfaces that are furthest from the viewpoint to those that are nearest. In terms of rendering speed and hardware requirements, Z-sorting is more efficient than other methods (such as Z-buffering). However, the time required for sorting tends to increase dramatically as the number of elements to be sorted increases. The PlayStation performs reliable Z-sorting by using an OT (Ordering Table) and a
drawing command list structure.
32
Developing an Application mmm
An OT is an empty drawing command array. An OT contains, for each drawing command, its own size and a pointer that specifies the next drawing command. In the initial state, as well as the cleared state, the pointers of each of the elements of an OT all point to the adjacent element. In other words, element N points to element N+1, and so on. In the initial state an OT is physically an array, and logically, a single list (see Ordering Tables, 6.5).
Each time a drawing command is created, the element number in the OT array is assumed to be the coordinate value along an axis perpendicular to the screen, (the z-axis, where x = vertical, y = horizontal and z = depth), and the new command is inserted between the corresponding OT array element and the
element to which that element points by means of a list operation.
The creation of drawing commands is carried out independently of the coordinate value of the z-axis. However, the list operations ensure that the commands all form a single list. Moreover, all drawing commands are linked in between the OT element representing their coordinate value on the z-axis and the following OT element thus ensuring that the list will be in a sorted state. (Using the example above, the new command is inserted in the list between N and N+1, N now pointing to the new command and the
new command pointing to N+1.)
Thus, even if the number of drawing commands increases, the amount of time required for sorting does not
greatly increase, and processing is more likely to be reliable.
This sorted linked list of drawing commands is then sent to the GPU with the end that holds the largest z-axis value first (1.e. the drawing objects furthest from the viewpoint first). As this is a simple operation, it is performed by the dedicated hardware unit known as the DMA Controller. (The DMA Controller is known as the hardware unit which executes Z-sorting at high speed. It also performs initialization of OTs at high speed.) Thus, drawing can be performed according to the Z-sorting algorithm, starting from
surfaces far away to those closest to the viewpoint.
Critical Section The EnterCriticalSection() function can block all interrupts through a software operation. Sections ofa program protected in this way are referred to as critical sections. Within a critical section, all interrupts
processed within the operating system, including vertical sync interrupts, are blocked.
In this state most library functions will not operate properly. However, there are library functions, such as
Exec(), that are guaranteed to operate normally only within a critical section.
33
34
"EN Developing an Application A — _——— www Fa (<< FF ————————r
The ExitCriticalSection() function is used to leave a critical section allowing interrupts to again be recognized.
Programs are always in a critical section at the start of execution.
Developing an Application mmm
Synchronizing with Vertical Synchronization Interrupts In order to display smooth images on the screen from the PlayStation, the executing program must be synchronized with the timing of vertical synchronization interrupts (VSyncs). (When a VSync interrupt
occurs, all lines of an image have been drawn on the screen. See the diagram below).
Figure: Displaying an Image On-Screen
The PlayStation OS is equipped with two methods for achieving VSync synchronization:
1. VSync() When this function is called with 0 specified as the first argument, VSync(0), it waits until a VSync interrupt occurs. Explicit synchronization of program execution with VSyncs can be achieved by calling this function in the main loop.
2. Callback
Callbacks allow certain functions to be executed when a VSync is generated. For details, please
refer to the following section, Callback Functions.
Callback Functions
The VSyncCallback() function is used to enter a pointer to a function into the callback system. This
causes the function to be executed automatically when a VSync interrupt is generated.
A function specified in this way is called a callback function. Callback functions are executed with the
same scope as the point where VSyncCallback() was called, so data can be shared with the main program
35
"EN Developing an Application HZ — bvbvg;c€c€ CC om m bı v .r.jqtz = |
through external variables. The stack resides in 4 KB of memory reserved within the operating system. If
the space used by automatic variables exceeds this size, OS code will be destroyed.
Callback functions are executed as critical sections. In other words, the functions are executed with interrupts disabled. Caution should be observed as leaving the critical section from within a callback
function can lead to unpredictable results.
While a callback function is being executed, the main flow of the program (whatever was being executed when the VSync occurred) is forcibly suspended temporarily. On return from the callback function, information related to the main flow, which had been saved, is restored by the CPU and execution of the
main flow resumes.
Processing of Vertical Synchronization Interrupts within the OS Immediately after a VSync interrupt occurs, the OS will communicate with the Controllers and the Memory card before any callback functions are called. (Communication with the Memory card can only occur
within the read() or write() functions.)
When the main flow calls VSync() and waits to synchronize with a VSync interrupt, communication with the Controllers will take place within VSync() before any callback functions are called. When control
returns from the callback function, VSync() will exit and the main flow will resume.
Multiple Vertical Synchronization Interrupts
Ifa callback function takes a long time to complete, the next VSync may occur while the callback function is still executing. Interrupts are disabled during execution of a callback function, so subsequent VSyncs are saved and held pending. When control returns from the callback function, a VSync interrupt that was
held pending becomes valid and the callback function will be called again.
Allowing a VSync interrupt to occur while a callback function is executing is undesirable. This behavior can cause delays in updating the screen or playing back music and should be avoided. Callback functions should return quickly and require as little time as possible to execute. Within the callback function, counters can be used to determine where the callback function is taking too much time. For example, the VSync(1) function, which returns the number of horizontal lines drawn (HSyncs) since it was last called, can be used as a rough counter and is useful in finding sections of code that could be slowing down the callback function. (See below for timings of VSyncs and HSyncs.) Note that VSync(1) can be used within VSyncCallback() despite VSyncCallback() being a critical section.
36
Developing an Application mmm
Note that only a single interrupt can be stored and held pending at a given time. Thus, if two or more
VSync interrupts occur during execution of a callback, only one VSync interrupt will be stored. Timings of VSyncs and HSyncs:
VSyncs: 50 (PAL) or 60 (NTSC) vertical synchronization interrupts per second HSyncs: 311 per VSync Video Mode
The library function SetVideoMode() sets the current video signal mode to either PAL or NTSC. The default video signal mode for the PlayStation is NTSC, but the mode can be changed by calling SetVideoMode() prior to calling any other function.
37
"EN Developing an Application
| The Application Environment
In this section, the memory map, stack pointer initialization and standard start-up routines that pertain to
running applications are described.
Memory Map
The memory map as seen by a Net Yaroze application is shown below.
Segments
ku ko kl
: Ox001fffff 0x801fffff Oxa01fffff
System stack area Ox001fff00 0x801fff00 Oxa01fff00
Application area
“— 0x00090000 0x80090000 0xa0090000
System area (576KB)
~<— 0x00000000 0x80000000 0xa0000000
Figure: Memory map
The OS itself (‘System area’ in the above diagram) is located at the low-address part of memory, and the system stack, which is the OS operating space, is located at the high-address part of memory. All other
memory is available to the application.
Start-Up Routine When an application is activated, a program called the start-up routine is executed prior to main(). The start-up routine performs a number of functions including initialization of global pointers and zeroing of
external variables which do not have initial values.
38
Developing an Application mmm y _— QG>>_ >_ a. _RO__Á—ÁKÁÁA :>|km-:®=*|kmk:|gq; - —m.Ö$üÖüeäch&umzm |
The Net Yaroze standard start-up routine is provided as part of the Net Yaroze library.
Stack Pointer
The value of the application”s stack pointer is inherited from that of the parent program. Where there is no
explicit parent program, the application stack pointer value is inherited from the system stack.
39
4
The Net Yaroze Library
EEE The Net Yaroze Library ol
The Net Yaroze library provides services that make use of PlayStation features such as graphics, sound, Memory card and CD-ROM management. The library also provides standard C and math functions. This
chapter gives a summary of each of these services.
| Graphics Services
These library services make use of the graphics features of the PlayStation. e Frame Buffer Access
Basic services for accessing the frame buffer and setting the drawing and display environments.
e Integrated Graphics
Various services relating to 2D and 3D graphics. Objects created with external tools can be
controlled through these services.
| Sound Services
These library services provide background playback of sound sequences which have previously been
recorded as score data (MIDI-type data).
| Standard Services
These library services provide support for standard C language functions.
e Standard C Functions These are a subset of the standard C language library and include character functions, memory
operation functions, character class tests, non-local jumps, and other utility functions.
. Math Functions These functions conform to the ANSI/IEEE754 standard. They include a package which provides
floating point arithmetic emulation in software.
42
The Net Yaroze Library Emm
| Other Services
These library services provide support for PlayStation OS functions such as the API, CD-ROM
management, and peripheral device management services
. Kernel Management
An interface (API) between applications and the PlayStation OS.
e CD-ROM Management Services for reading image data, sound data and programs from the CD-ROM drive as well as playback of CD-DA (digital audio) sound.
e Peripheral Device Management Services for managing the peripheral devices such as the Controller and Memory card, and for
managing callbacks for interrupt processing.
| File Organization
The following is a description of files related to the Net Yaroze library.
e Header Files To use a service provided by the Net Yaroze library, you need to include a header file in the source
code that defines the variables and functions used by that service.
The following is a description of how Net Yaroze library header files are organized. All PlayStation
functions are defined in the file ‘libps.h’. Always include ‘libps.h’ when creating programs.
43
EEE The Net Yaroze Library
abs.h included in stdlib.h
asm.h used with the assembler(*) convert.h included in stdlib.h eh
5 E.
malloc.h included in stdlib memory.h included in strings.h qsort.h included in stdlib.h r3000.h used with the assembler(*) rand.h included in stdlib.h romio.h Ps I I l for internal use
darg.h va_start(), va_end(), etc. (variable number of arguments)
ring.h identical to strings.h
libps.h all services related to PlayStation functions always include t limits.h C type limit macro definitions
sys/fentl.h used by sys/file.h sys/file.h used by open(),close(), etc. sys/ioctl.h for internal use
sys/types.h type definitions
Fe] Bee] MEN | a | Ber] [een | CN REC | imis | toon | E | we | METI EIN | mion = | [simn | semon | MA METE | asioin | MT
Table: Net Yaroze Header Files
* Refer to the Net Yaroze Web site for information related to assembler programming.
44
The Net Yaroze Library Wimm
e Library Files The Net Yaroze library file, libps.a, is automatically linked when compiling so it does not need to
be explicitly referred to.
| Processing of Data
The Net Yaroze library can directly process graphics and sound data which are in the PlayStation format without modification. Data that is in PlayStation format can be created through conversion from standard graphics and sound file formats. (See Chapter 13, Creating PlayStation Applications, or the Net Yaroze
Web site for more information.)
45
5
Frame Buffer Access
EEE Sound ] BR pp RpppRrr€€ppJoÉ mean The frame buffer access services provide basic functions such as setting of the drawing and display
environments, and transfer of image data to the frame buffer. These services can be broadly divided into the following three groups.
(1) Environment-setting functions (2) Frame-buffer-access functions
(3) Drawing-control functions
| Description of the Frame Buffer
Pixels
From a software point of view, a frame buffer is a 1024 x 512 two-dimensional address space composed of 16-bit pixels. The top left pixel has the coordinates (0, 0) and the bottom right pixel has the coordinates (1023, 511). Each pixel is made up of three 5-bit data items and a semi-transparency flag. The data items
each range from 0-31 and represent RGB brightness values.
The semi-transparency flag is only valid when the pixel is used as a texture.
S: Semi-transparency FLAG(STP)
Figure: Pixel structure
Display Area
The part of the frame buffer that is displayed on-screen is a rectangular area known as the 'display area". The size of the display area is determined by a GPU display function. The size can be selected as a pair of values ranging from 256 x 240 to 640 x 480 for NTSC and 256 x 256 to 640 x 512 for PAL. Interlace mode is on enabled when the display height is 480 for NTSC or 512 for PAL.
48
Sound MEM
Drawing Area
Drawing is limited to a rectangular area, referred to as the 'drawing area' within the frame buffer. The
drawing area may be any size that can be accommodated in the frame buffer.
| Environment-Setting Functions
Information related to drawing as a whole, such as where drawing is to be carried out within the frame
buffer and the starting point (offset) for drawing is referred to as the 'drawing environment'. In the same
way, information related to display of the frame buffer, such as which part of the frame buffer to display, is
referred to as the 'display environment'. The drawing environment is set up using the GsInitGraph()
function, and the display environment is set up using the GsDefDispBuff() function.
GsInitGraph() takes the following arguments:
x_res
y_res
intl
Horizontal resolution (256/320/384/512/640)
Specifies the horizontal screen resolution as well as the width of the display and drawing areas.
Drawing is clipped to the specified width. Vertical resolution (240/480) for NTSC and (256/512) for PAL.
Specifies the vertical screen resolution, and the height of the display and drawing areas.
Drawing is clipped to the specified height.
Attributes
Interlaced display flag (bit 0)
Non-interlaced display is set when bit 0 is 0, and interlaced display when bit 0 is 1. Set bit 0 to 1 when using a display height of 480 in NTSC or 512 in PAL.
Offset specification flag (bit 2)
When bit 2 is 0, the GTE offset feature is enabled. When bit 2 is 1, the GPU offset feature is enabled. The GPU offset feature is normally enabled.
49
mmm Sound ei
dither Dither processing flag (dtd) If this is set to 1, the drawing engine will perform dithering when drawing pixels. vram VRAM mode
When VRAM mode is 0, 16 bits are displayed as 1 pixel. When VRAM mode is 1, 24 bits are displayed as 1 pixel. When VRAM mode is 1, only frame buffer access functions such as the LoadImage() function, are available. Other drawing functions, such as the GsDrawOt() function
are only available when VRAM mode is 0.
GsDefDispBuff() takes the following arguments:
x0,y0 The top left coordinates of image buffer 0.
x1,y0 The top left coordinates of image buffer 1.
Image buffers '0' and '1' are rectangular areas in the frame buffer. The top left corners of the image buffers are (x0, y0) and (x1, y1), respectively. The width and height of the image buffers are specified with the x_res and y_res arguments of the GsInitGraph() function. One image buffer is used as the drawing area and the other as the display area. The buffers are swapped each time GsSwapDispBuff() is called which provides
for the implementation of double buffering.
| Frame-Buffer-Access Functions
The functions below allow data to be transferred within the frame buffer and between the frame buffer and
the main memory. These functions are the only way to directly manipulate data in the frame buffer.
Direction of Transmission LoadImage() main memory > frame buffer Storelmage() frame buffer > main memory
Movelmage() frame buffer > frame buffer
Table: Frame-Buffer-Access Functions
50
Sound MEM
These functions are non-blocking functions, that is to say, they terminate as soon as the access requests have been registered by the system. Up to 64 access requests may be registered (this number is the total for all three functions). These functions will block, i.e. will not terminate, until the access request has
been registered.
| Drawing-Control Functions
The functions below control drawing (specifically, the transfer of drawing commands to the GPU by the
DMA Controller) and frame-buffer-access request processing.
rn] e
DrawSync() waits for the termination of both drawing and the processing of frame? buffer-access Eo m or returns request status. ResetGraph() stops | stops drawing
Table: Drawing-Control Functions
Drawing Control in Non-Interlaced Mode A simple rule controls drawing in non-interlaced mode: image buffers are not swapped until drawing
completes.
After DrawSync(0) detects that drawing is complete, VSync(0) is executed. This delays the program until the next vertical synchronization interrupt. After the interrupt occurs, the image buffers are swapped using GsSwapDispBuff().
while (1) { DrawSync (0);
VSync (0);
GsSwapDispBuff();
51
mmm Sound E U j
Interlaced Mode
In interlaced mode, pixels with odd and even numbered vertical coordinates are displayed alternately every 1/60th of a second in NTSC, or every 1/50th of a second in PAL. This action forces automatic double buffering of the display.
This behavior, which applies solely to interlaced mode, can provide significant savings in frame buffer space since the display area and the drawing area are perfectly stacked on top of each other. However, the display area is always swapped every 1/60th of a second in NTSC or 1/50th of a second in PAL, regardless of how the program is executing. Therefore, the program must swap the image buffers at exactly
the same time as the display area.
Drawing Control in Interlaced Mode
In interlaced mode, calculation and drawing must always be completed within 1/60th of a second (in NTSC) or 1/50th of a second (in PAL). Therefore, it is essential that buffer swapping after a vertical synchronization interrupt be performed regardless of whether drawing has completed. Thus,
ResetGraph(1) is called following VSync(0) rather than using DrawSync().
while (1) {
VSync (0); ResetGraph (1); GsSwapDispBuff();
.r
| Kanji [Japanese Character] Fonts
The PlayStation is equipped with 16 dot x 16 dot kanji fonts stored as binary bit maps. You can use these
to create messages that are easy to read.
52
Sound MEM
16-dot x 16-dot binary bit map / 15-dot x 15-dot kanji size
Contents JIS Level 1 standard kanji/non-kanji/foreign language, gothic
Non-kanji includes top space (0x2121)
Table: Kanji Fonts
Font data is stored beginning with the upper left corner of the pattern and followed by the upper right byte, as shown in the figure below. Bits are ordered with the most significant bit (MSB) to the left.
Table: Font Data Format
The frame buffer access services include the Krom2Tim() function, which converts a SHIFT-JIS string to 4- bit TIM data, as well as character display functions that use font streams for debugging. For details refer to the Library Reference Manual and the SHIFT-JIS code and font data on the Net Yaroze PC CD under
\psx\sample\sjiscode.
53
6
Integrated Graphics
HEHE Integrated Graphics Sees
The integrated graphics service operates on 3D and 2D graphics such as polygons, sprites and
background surfaces.
The following functions are supported by the integrated graphics service.
1. Hierarchical coordinate systems
2; Light source calculation (3 parallel light sources, depth cueing, and ambient light)
3. Automatic object partitioning (polygon subdivision) and semi-transparency processing 4. Viewpoint management
3: Z-sorting
6. OT (ordering table) initialization, hierarchical organization and compression
IR Frame double buffering 8. Automatic aspect ratio adjustment 9. 2D clipping, offset processing
10. Sprites / backgrounds / lines
In addition, data created with all of the graphics tools can be handled without modification by the
integrated graphics service.
The 3D model format used by the integrated graphics service is called 'TMD'. TMD format efficiently stores the information required to define a 3D model such as polygon vertices, surface normals and texture
coordinates.
The 2D graphics data format used by the integrated graphics service is called 'TIM'. TIM format stores
image resolution, number of colors and color lookup table (CLUT) information, as well as pixel data.
For details of the TMD and TIM formats refer to Chapter 15, Graphics Tools.
56
Integrated Graphics MEM
| Drawing Process
The flow chart below shows the steps in the drawing process for the integrated graphics service.
Initialize
Record packet(s) in OT so that the i screen can be cleared
Calculate LS/LW matrices Set light matrices Calculate objects and set these in OT
Figure: Integrated Graphics Service Drawing Process
57
HEHE Integrated Graphics
eee The drawing process sequence is described below.
1. Initialize the drawing and display environments and variables to be used.(GsInitGraph, GsDefDispBuf)
2. Set parameters to reflect Controller data.
3. Set up the viewpoint. (GsSetRefView2, GsSetView2)
4. Setup the packet creation working area. (GsSetWorkBase)
5. Clear the ordering table. (GsClearOt)
6. Calculate the LS/LW (Local Screen/Local World) matrices. (GsGetLs, GsGetLw)
7. Set up the LS/LW (Local Screen/Local World) matrices. (GsSetLightMatrix, GsSetLsMatrix)
8. After performing coordinate calculation, perspective transformation and light source calculation,
enter the drawing packets in the ordering table. (GsSortObject4) 9. Wait for drawing to complete, then wait for V-blank. (DrawSync, VSync) 10. Swap the double buffers. (GsSwapDispBuff) 11. Draw the ordering table. (GsDrawOt) 12. Return to step 2.
* LS/LW refer to local/screen transformations and local/world transformations, respectively. These transformation matrices are used in perspective transformation and light source calculation. Please refer to
Coordinate Transformation & Light Source Calculation, below.
| Graphics System Initialization
The graphics system is initialized using the GsInitGraph() function. GsInitGraph() also sets the screen resolution and interlace mode. GsInitGraph() must be called before the integrated graphics service is used
as it initializes various internal system variables.
58
Integrated Graphics MEM
The GsDefDispBuff() function is used to define the two rectangular areas of the frame buffer used for double buffering. In addition, GsDefDispBuff() initializes the clipping area and GPU offset coordinates to prevent drawing outside of the drawing area. The clipping area and GPU offset coordinates can be
changed using the GsSetClip2D() and GsSetOrign() functions, respectively.
The GsSwapDispBuff() function is used to swap double buffers, while the GsGetActiveBuff() function can
be used to determine which buffer contains the current drawing area.
| The Viewpoint
A flat 2D TV screen cannot display 3D graphics directly. Instead, a 3D graphic must be drawn on a 2D screen so that it appears three dimensional. This is done by projecting 3D space onto a theoretical screen
positioned in front of a particular viewpoint.
Viewpoint
Projection Distange (h) 3D graphic
Screen
Figure: Projecting a 3D Image Onto a 2D Screen
Therefore, in order to project an image onto the physical screen, a viewpoint and a theoretical screen need
to be specified.
Setting the viewpoint The viewpoint is set by initializing the members of either a GSRVIEW2 or Gs VIEW2 structure, and calling either the GsSetRefView2() or GsSetView2() function, respectively.
59
HEH Integrated Graphics ees
GsRVIEW2 and GsVIEW2 set the viewpoint using different methods. GsRVIEW2 sets the coordinates of the viewpoint and a reference point, while GsVIEW2 directly sets up a matrix for conversion to the
viewpoint coordinate system.
You can set up a hierarchical coordinate system using GsVIEW2 or GsRVIEW2. For example, if the reference coordinate system is the world coordinate system, the result is an ordinary camera that captures an objective view. Alternatively if the reference coordinate system is the local coordinate system of an
object, then the result is a camera that captures the subjective view of that object.
Setting the Theoretical Screen The theoretical screen is positioned in front of the viewpoint. The GsSetProjection() function is used to
set h, the projection distance, which is the distance from the viewpoint to the theoretical screen.
The Theoretical Screen The height and width of the theoretical screen should match the resolution of the physical screen. For example, if the resolution of the physical screen is 640 x 480, the width of the theoretical screen should be
set to 640 and the height should be set to 480.
When the ratio of the screen’s horizontal resolution to its vertical resolution is 4 to 3, the dots on the screen will have a regular shape. If the actual screen resolution is such that the dots are irregular (that is, the ratio of horizontal to vertical resolution is not 4 to 3), the vertical resolution must be adjusted accordingly. For example, when the screen resolution is 640 x 240, objects should be displayed with one-
half of their original vertical values so that the objects will appear as if their dots were regular in shape.
The Projection Distance
The projection distance is used to adjust the field of view. The larger the projection distance, the narrower is the field of view (this tends towards a parallel projection). On the other hand, the smaller the projection distance, the wider is the field of view. A wide field of view emphasizes perspective, creating the
impression of close and distant objects from the viewpoint.
| Packets
A 'packet' (or 'primitive') is the smallest unit of drawing commands handled by the GPU. Packets can be generated using the GsSortObject4(). A large work area must be allocated before using this function as
packets can grow depending on the number and type of polygons. This work area is allocated using the
60
Integrated Graphics MEM
GsSetWorkBase( ) function, while the GsGetWorkBase() function can be used to determine how much of
the work area has been used for packet generation.
Packets in the packet generation work area are used during drawing. Consequently, GsSortObject4() should not be used to access the work area during drawing. Instead, double buffering should be used to
manage packet access by allocating two separate packet generation work areas.
| Ordering Tables
Polygons will either be hidden or visible when 3D graphics are displayed. Polygons are hidden when
they are obscured by other polygons that are in front of them along the Z axis.
An ordering table is a mechanism for controlling the proper display of polygons through a simple algorithm known as a Z-sort. Z-sorting ensures that polygons will be drawn in the correct order so that
those in back will be obscured by those in front.
An ordering table (OT) can be thought of as a Z axis 'ruler'. Each scale mark on this ruler can hold as many
polygons as needed.
Sorting is based on the average Z value of polygons, and is performed by placing polygons at the scale mark on the ruler corresponding to their average Z value. Polygons are transferred to the rendering chip in the order that they were placed along the ruler. Thus hidden surfaces are removed and polygons appear in
the correct order as drawing progresses.
GsOT
A 'GsOT' structure is used to manage an ordering table (OT). The GsOT structure contains a pointer to the
OT (the ‘org’ member) and a number of parameters indicating the attributes of the OT.
The resolution of the Z axis (i.e. the ruler markings) can be specified with the member 'length'. The length
can be set to any one of 14 levels from 2! to2',
GsOT_TAG
A GsOT_TAG represents a scale mark along the Z axis ruler. An OT is defined as an array of GSOT_TAGs with the number of elements of the array equal to 2'*"*%. For example, if the member ‘length’ has a value of 4, the actual OT will be an array of 16 GSOT_TAGs (16 = 2°).
61
HEHE Integrated Graphics EEE
OT Initialization The GsClearOt() function is used to initialize an OT. GsClearOt() takes three arguments: 'offset', 'point' and 'otp'. 'otp' is a pointer to the OT handler. ('offset' and 'point' are described later.)
When an OT is initialized it is placed in an empty state with no polygons linked to it. An OT must be
initialized each frame, prior to resorting.
Multiple OTs
The graphics service supports the use of multiple OTs. The GsSortOt() function can be used to merge and sort multiple OTs within one global OT. The typical Z value for the entire local OT is stored in the GsOT member 'point'. ‘Point’ is used when inserting and sorting the local OT into the global OT. Using
multiple OTs allows the order of sorting to be controlled.
For example, you can sort in object units by preparing a local OT for each object. These local OTs are then sorted and merged together into a single global OT. This technique is extremely useful if the depth relationship between objects (i.e. which objects are in front and behind) is already known. (For instance: when you are looking down from a helicopter on cars that are driving along a road you already know that
the helicopter is in front of all the cars.)
OT Compression
Using OTs increases the speed of sorting, but OTs consume a considerable amount of memory.
You can reduce an OT's memory consumption by making 'length' smaller. Doing this, though, reduces the
sorting resolution, and can result in flickering polygons on screen.
Decreasing the amount of memory consumed by an OT without reducing the resolution is possible using an offset. Offsetting can be used when you know that the Z values of the polygons to be sorted are all
higher than a certain value ('x').
Offsetting is implemented by setting the 'offset' parameter of GsClearOt() to the lowest value ('x'). With offsetting, the OT does not use up any memory for the part of the table below the offset value ('x'), thus
reducing the amount of memory consumed.
62
Integrated Graphics Wim m -OECC<CEá< Ca OííRROQAEQDEGRQPQÉÓÉÓTOUOA o |
| Coordinate Transformation & Light Source Calculation
Coordinate Transformation
The PlayStation stores all the vertices of the objects to be displayed as 3D coordinates so the image of an object, as seen from different viewpoints, can be generated solely through calculation. This allows the game's viewpoint to be freely selected as either the player's viewpoint, or the viewpoint of one of the
characters in a scene.
In order to display objects expressed in terms of 3D coordinates on a screen, 3D images need to be expressed as 2D images via a projective transformation. Projective transformation is performed by multiplying the 3D coordinate matrix by a 3 x 3 rotation matrix and adding a 3D translation vector. The result is then divided by the distance form the viewpoint in order to give perspective (so objects further
away appear smaller).
For example, if the object to be displayed is described by the coordinate system (Xw, Yw, Zw), and (Xs, Ys, Zs) represents the coordinate system of the theoretical screen, the following equation (Equation 1)
expresses the projective transformation calculation.
Equation 1 Xs} | SW11,SW12,SW13 || Xw| | SWx Ys |=| SW21,SW22,SW23 || Yw |+| SWy Zs | | SW31,SW32,SW33 || Zw | | SWz
* Swij is the world/theoretical screen transformation matrix.
If you want to display more than one object, each of which is independently movable, you need to assign
a coordinate system (X1, Y1, ZI) to each independent object. In the PlayStation the three types of coordinate systems are referred to as follows:
(XI, Y1, ZI) Local coordinate system (a coordinate system for a particular object and centered on that object)
(Xw, Yw, Zw) World coordinate system (a coordinate system fixed to the world in which objects are placed)
(Xs, Ys, Zs) Theoretical screen coordinate system (a coordinate system fixed to a theoretical screen and centered on a viewpoint)
63
EEE integrated Graphics A A] Vertex coordinates are usually expressed in terms of the local coordinate system, so the following
transformations are necessary in order to display an object on a theoretical screen.
local > world > screen Equation 1 (above) and Equation 2 (below) together perform the required projective transformation calculation. Equation 3 shows the combined calculation together, while Equation 4 presents it in a
reduced and simplified form.
Equation 2 Xw WL11,WL12,WL13 || XL WLx Yw |=| WL21,WL22,WL23 || YL |+| WLy Zw WL31,WL32,WL33 || ZL WLz Equation 3
Xs} | SW11,SW12,SW13 || WL11,WL12,WL13 || XL Ys |=| SW21,SW22,SW23 || WL21,WL22, WL23 | | YL Zs | | SW31,SW32,SW33 || WL31,WL32,WL33 | | ZL
SW11, SW12,SW13 | [WLx] [SWx +| SW21, SW22,SW23 | | WLy |+| SWy SW31,SW32,Sw33 || WLz | | SWz
Simplifying this equation gives:
Equation 4 XS SL11,5£12,5L13 || XL Trx Ys |=| SL21, SZ22,SL23 || YL |+| Try
Zs | | SL31, SZ32,SL33 || ZL | | Trz
64
Integrated Graphics MMM E AáTpDRR o Ro SLij and Tr can be determined using the GsGetLs() function. Also, as shown in Equation 5 (below), multiplying the theoretical screen coordinate values by h/Zs will apply a perspective transformation in
which objects appear to be projected in parallel onto the theoretical screen (i.e. the image size will be
scaled according to the distance from the viewpoint).
65
HEHE Integrated Graphics aa ee
Equation 5 Xss = Xs — Zs h Yss = Ys — Zs
*'h' is the distance (projection) from the viewpoint to the theoretical screen.
The GsSortObject4() function takes TMD data (which only contains the local coordinate system) and creates the polygon drawing packet for a polygon projected onto a theoretical screen. This is done by specifying the matrix in Equation 2 in the 'coord' member of the GsCOORDINATE? structure, the matrix in Equation 4 using the GsSetLsMatrix() function, and 'h' in Equation 5 using the GsSetProjection()
function.
Hierarchical Coordinate Systems
Hierarchical coordinate systems involve the introduction of a layered tree structure into the coordinates of an object. Consider, for example, the case in which the earth is traveling in an orbit around the sun, and the moon is orbiting around the earth. If the sun is at the origin of the world coordinate system, it is far easier to describe the motion of the moon using an earth coordinate system which has the earth as its origin, rather than using the world coordinate system centered on the sun. In this case, the best approach is to set up a pointer to the earth’s coordinate system in the 'super' member of the GsCOORDINATE2 structure which the moon's object handler would refer to. This would indicate that the moon's coordinate system is set based on the earth's coordinate system (i.e. the moon’s coordinate system is under the
earth’s coordinate system). See diagram below.
66
Integrated Graphics MEM
CSun A
CSun { coord super WORLD; } CEarth { coord ... /* describes orbital motion around the sun */
super CSun;
CMoon { coord ... /* describes orbital motion around the earth */
super CEarth;
Figure: A Hierarchical Coordinate System
67
HEHE Integrated Graphics
Light Source Calculation The light source calculation is used to determine the contribution of light from each light source within
the world. The PlayStation supports the following three methods for light source calculation:
(Note that the normal line vector or 'normal' is an imaginary line perpendicular to either the surface of a polygon or the polygon vertices (the points that define the position of the polygon). Similarly, the light
source vector is an imaginary line that defines where the light in an on-screen scene is coming from.)
. Flat shading In this method each polygon has a single normal line vector from its surface (the 'flat' or 'face' normal). The color and brightness is determined by the inner-product (measure of the angle)
between the face normal and light-source vector.
. Gouraud shading In this method each polygon vertex (each point that is a 'corner' of the polygon) has its own normal line vector. The color and brightness at each vertex is determined by the inner product of the vertex normal and the light source. The color and brightness at each vertex is then interpolated to approximate the light source contribution across the polygon. This produces a
smooth graduation of color and brightness across the polygon.
. Depth cueing This method varies the color and brightness of the polygon depending on the distance from the viewpoint. This achieves a fogging effect by making the color of a polygon closer to the
background color the further away it is from the viewpoint.
The following figure describes the model on which light source calculations are based.
68
Integrated Graphics MEM
Figure: Light Source Calculation
In this figure, point P represents a point on the surface of an object. To calculate the light source
contribution at point P the following terms are used:
(Nx, Ny, Nz) = The normal line vector at point P. (R, G, B) = The inherent color of the object. (Lx, Ly, Lz) = The light source vector.
(LR, LG, LB) = The light source color.
(RBK, GBK, BBK) = The background (ambient) light. The following is an example of the light source calculation sequence in the PlayStation if three light sources are used. (RR, GG, BB) represents the final color values used when point P is displayed.
(1) Convert coordinates of the normal line vector into the world coordinate system.
NWx| [WL11,WL12,WL13 | [ Nx NWy | =| WL21,WL22,WL23 || Ny NWz | | WL31,WL32,WL33 || Nz
(2) Obtain the inner product of the light source vector and the normal line vector.
Normal line vector (world) è Light source vector > Light source influence (L)
L1 Lx1, Lyl, Lz1 || NWx L2 | =| Lx2, Ly2, Lz2 || NWy L3 Lx3, Ly3, Lz3 || NWz
(3) Obtain the light source influence color by multiplying the inner product and the light source
color separately for each item.
Light source influence (L) x Light source color (Lr, Lg, Lb) > Light source influence color (LI)
69
HEH Integrated Graphics
Llr Lrl,Lr2,Lr3 || 21 Lig} =| Lgl, Lg2, Lg3 || L2 LIb Lbl,Lb2,Lb3 || L3
(4) Obtain the total influence color from the environment by adding together the light source
influence color and the ambient color.
Light source influence color (LI) + Ambient color (BK) — influence color (LT)
LTr Llr BKr LTg | =| Llg| +| BKg LTb LIb BKb
(5) Obtain the theoretical screen color by multiplying the inherent color with the influence color for
each item separately.
RR Rx LTr GG |=| G* LTg BB B* LTb
Use GsGetLw() to calculate the local world matrix. In order for this to be applied (as in the Wlij matrix in
Equation 1, above) set it internally using the GsSetLightMatrix() function.
Set the light source vector and the light source using the GsSetFlatLight() function, and the ambient
color using the GsSetAmbient() function.
When all the above are set, use the GsSortObject4() function to perform the light source calculation.
GsSortObject4() will perform the calculation in accordance with the equations given above.
| Creating Packets
The GsSortObject4() function performs coordinate calculation, perspective transformation and light source calculation on polygons defined within TMD data. The results are converted into drawing packets
which are then added to an ordering table.
70
Integrated Graphics MEM ZZ, ,—,_—
The GsSortObject4() function uses the GsDOBJ2 structure to handle object data (TMD data). In order for the GsDOBJ2 structure to handle TMD data, the TMD data must be mapped to a real address using the GsMapModelingData() function then linked to GSDOBJ2 using the GsLinkObject4() function.
The GsSortObject4() function performs coordinate transformation using the local screen matrix set with the GsSetLsMatrix() function. It then performs perspective transformation using the projection distance set with the GsSetProjection() function. Next, the GsSortObject4() function performs light source calculation using the local world light matrix set with the GsSetLightMatrix() function. Finally, the GsSortObject4() function creates a drawing packet and using the Z values determined during coordinate
transformation, links the drawing packet to an ordering table.
The GsDrawOt() function can be used to draw a drawing packet that has been linked to an ordering table. GsDrawOt() returns immediately after execution and drawing is performed in the background.
Subsequently, the DrawSync() function can be used to detect when drawing is complete.
| Objects
The graphics service provides the GsDOBJ2 structure to handle objects (TMD data). The *coord2” and
‘attribute’ members of GSDOBJ2 are used when operating on objects.
'coord2' is a pointer to a coordinate system GSCOORDINATE2. The position and orientation of the object are controlled by setting the parameters for GSCOORDINATEZ2. 'attribute' is used to set the
object's attributes. The following lists the attributes that can be set.
Light Source Mode
This attribute determines the method of light source calculation.
Light Source Calculation OFF
This attribute disables light source calculation.
Inhibit Display
This attribute disables packet creation for the entire object.
Automatic Partitioning (polygon subdivision) When enabled, this attribute causes all the polygons contained within the object to subdivide. The number of subdivisions can be 2 x 2, 4 x 4, 8 x 8, 16 x 16, 32 x 32 or 64 x 64. Subdividing polygons in
this way reduces texture distortion and polygon fragmentation. 71
HEH Integrated Graphics
72
Sound
mmm Sound
The sound service consists of functions that automatically playback sound data such as background
music and special effects. Sound service functions are classified into one of the following four groups. 1. SEQ access functions. Functions that handle score data (i.e. SEQ data).
2. Individual voice-setting functions. Functions that handle individual sounds, including single-
shot sounds and sound effects.
3. Shared-attribute setting functions. Functions that perform settings necessary to activate the
sound service. These functions also set attributes that are shared by all voices of the SPU.
4. Sound utility functions. Functions that change attribute tables within VAB data at runtime.
These functions also apply sound effects to an allocated voice after a 'KeyOn' is issued.
| Score Data
Within the sound service, score data is represented in the SEQ data format.
The SEQ Data Format The SEQ data format is a Format-1 SMF (Standard Midi File) converted for PlayStation use. SEQ is a
format in which all track and chunk data of the MIDI data structure is merged in time order
In the SEQ format, sixteen songs can be played simultaneously. Notes are expressed in the form of status, data and delta time. Status is 1 byte in length, whereas the data length is determined by the status byte,
and delta time length is variable up to a maximum of 4 bytes.
The SEQ format uses running status, where Note-Offs are converted to Note-Ons with zero velocity. The
SEQ format supports the following types of status data as defined within the MIDI standard.
. note on . note off . program change
. pitch bend
The following items are included from 'control change".
74
Sound MEM
EO ———————————22 _—_=_--___z»m__>=>_._>>>__=_—-_ —____ AAA | . data entry(6) . main volume( 7) . panpot(10) . expression(11) . nrpn data(98,99)
Note: The numbers inside parentheses are control numbers.
| MIDI Support
Setting VAB Attribute Data Using Control Change
NRPN data is defined so that VAB attribute data can be set from the MIDI standard Control Change NRPN.
When using a sequencer to create an SMF file, VAB attribute data can be set by sending the following
sequence. bnH 99 datal (NRPN MSB) bnH 98 data2 (NRPN LSB) bnH 06 data3 (Data Entry)
Using Control Change to Set Repeat Loops Within Music NRPN data can be used to implement a loop, or repeat function, for sections within music. Any number of
repetitions between 0 and 126 can be specified (specifying 127 will cause continuous playback).
The repetition symbol 'Il:' identifies Loop1 (the start of the loop) and the symbol ':ll' identifies Loop2 (the end of the loop). Although the repeat function can be used any number of times within one piece of music,
it is not possible to embed a loop within a loop, such as (Loop1...(Loop1'...Loop2')...Loop2).
75
mmm Sound
Attribute data1(CC 99) data2(CC 06)
Table: Repetition using Control Change
Caution
No MIDI event that needs to take place before another MIDI event should be placed at the same “tick” as that event. Depending on the sequencer, this situation could produce invalid output when the data is
converted to SMF.
If identical delta times are used, the order of the data may switch incorrectly during conversion and
invalid data may be generated, even ifthe data was originally entered in the correct order. For example, if a patch change, a controller 99, a controller 6 and the first key on ofthe sequence all appear
at 1/1/000 in the event list, there is no guarantee that the order will be preserved on conversion.
Note
When setting VAB attribute data, values become valid after Key On following Data Entry read.
Caution
The setting of a repeat loop should be done only in one place within the SEQ data for a given sequence.
It is not necessary to set the repeat loop for each channel.
| Waveform Data
Waveform data is described by the VAB data format.
VAB Format
VAB isa data format used for waveform management. Sampled sounds such as that from a piano or an explosion are compressed and encoded in a format known as VAG. The VAB format is a collection of these
individual VAG-formatted sounds. VAB-formatted data is organized in files for use at runtime.
A VAB file contains all ofthe sampled data and sound file attributes used in a particular scene. Multi-
timbral sound is supported with a voice priority protocol.
76
Sound MEM
A single VAB file can contain up to 254 VAG sounds and 128 programs with each program having up to 16 tone lists.
Individual waveforms can be referenced in more than one tone list so a single waveform can be played
back in many different ways. The PlayStation allows up to 16 VABs to be used simultaneously.
For further information on data formats, please refer to the Net Yaroze Web site.
| Function Execution Order
The following illustrates the order of operations when using sound service functions.
1. Open SEQ data Execute the SsSeqOpen() function. 2. Perform desired operations
After setting the main volume, perform the desired operations.
3. Close SEQ data
Execute the SsSeqClose() function.
77
S
Standard C Functions
mmm Standard C Functions
Net Yaroze provides a set of headers and functions that are broadly similar to standard C (as defined in
The C Programming Language by Kernighan & Ritchie).
| Include Headers
A JO Cean ANECA EN Tome | Summe nme meeaunen | _______ | man TSE | |
rand.h rand(), srand(), etc. (random number included in stdlib.h generation)
setjmp.h setjmp(), longjmp(), etc. (jump over large areas)
stdarg.h va_start(), va_end(), etc. (variable arguments)
a eee | ________ | ACCION AECE | MECO CT |]
80
Standard C Functions HMM
| Supported Functions
The following standard C functions are supported.
ne Y en O]
mmm Standard C Functions
82
realloc srand streat strchr stremp
strepy
strespn
strlen strncat strncmp strncpy strpbrk strrchr
strspn
strstr strtok strtol strtoul toascii tolower
toupper
reallocate heap memory
initialize random number generator
concatenate one character string to another
search for the position at which a specified character appears in a character string compare two character strings
copy a character string
return the length of the first part of a character string that is composed entirely of characters not included in a specified collection of characters
find the number of characters in a character string concatenate a character string of a specified length to another character string compare two character strings with each other
copy character strings of a specified length
find the position at which a specified character first appears in a character string
find the position at which a substring first appears in a character string
find the first part of a character string that contains only characters that occur within a specified subset
find the position where a substring occurs in a string
find a character string delimited by characters from a specified character set convert a character string into a long
convert a character string into an unsigned long
mask bit 7 from an input value
convert characters to lower case
convert characters to upper case
9
Math Functions
HEE Math Functions eC
| Floating-point Numbers
The Net Yaroze system includes a standard set of C math functions that support IEEE 754 standard
single-precision floating-point numbers ('float') and double-precision floating-point numbers (‘double’). gle-p g-p p g-p
Because the PlayStation version of the R3000 CPU does not possess a floating-point arithmetic
coprocessor, the floating-point arithmetic package is implemented entirely in software.
No. of digits available 6 digits (decimal number conversion)
Overflow limit value 2.00% = 3.4638 * (Largest number)
Underflow limit value 0.5'°° = 2.2e-38 * (Smallest Number)
Table: 'Float' DataType
Attribute Specification No. of digits available 15 digits (decimal number conversion)
Overflow limit value 2.00% =1.8e308 *
(Largest Number)
Underflow limit value 0.51%? = 2.2e-308 *
(Smallest Number)
Table: 'Double' Data Type
* Note: In scientific notation, 'e' means '10 to the power of so, 2.2e-308 is 2.2 x 10 308
Error Handling Errors related to floating-point arithmetic are reported via 'events' in addition to the normal C method of
setting external variables (such as 'math_errno').
84
Math Functions mmm eC
Error Types There are two types of errors that can be reported during floating point operations: ‘domain errors’ and
“range errors’.
A function tests the range of its arguments to ensure they fit in the appropriate range. A 'domain error' is reported if the argument value of a function is out of range, when the allowed range is stated explicitly in
the function definition
A ‘range error’ is reported when a function performs a calculation, or an application uses an arithmetic operator, that produces a value that exceeds the range of the data type.
Internal Processing when Errors Occur
When a function reports a 'domain' or 'range' error, an external variable is set with the appropriate error code. If the error occurred during an arithmetic calculation, the result of the operation is set to a signed
infinite number so that calculation can continue as long as possible (see table, below).
A function returns a NaN (Not a Number) when a division by zero error occurs.
| Float Data Type Double Data Type 0x7F800000 0x7FF0000000000000 Negative infinity OxFF800000 0xFFF0000000000000
Ox7FFFFFFF Ox7FFFFFFFFFFFFFFF Negative NaN OxFFFFFFFF OxFFFFFFFFFFFFFFFF
(Note that NaN is a bit pattern reserved so that the arithmetic subroutine can report an error to the
system. The value cannot be assigned to variables.)
Error Variables The math functions use an external variable, math_errno to indicate an error code. An 'extern' declaration
can be found in the /ibps.h file for this variable.
The variable math_errno is initially set to zero. When an error occurs, math_errno is set to the value
indicated by the macros EDOM or ERANGE (both of which are defined in the sys/errno.h file),
85
HEE Math Functions E U U U |
depending on the type of error. Note that math_errno does not automatically reset itself, so you should
explicitly set it to zero once your error handling is complete.
86
Math Functions mmm
| Supported Functions
rre Y E B AA
mantissa and exponent) formatted output to the console (supports 'float' and 'double' type arguments) formatted output to an array (supports 'float' and 'double' type arguments)
87
10
Kernel Management
EEE Kernel Management
Kernel management services provide basic functions for controlling the PlayStation hardware and the CPU. Kernel management services are implemented as a set of C functions which execute jump
instructions that branch directly into the kernel.
Kernel management services are classified as follows:
À. Root counter management . T/O management
. Module management
° Additional services
| Root Counter Management
Root counter management services are critical for game programs as they provide important functions like time period management and timing adjustment. The root counter is a single 16-bit counter that increments every 8 ticks of the system clock (about 0.24 microseconds). The value of the root counter can be obtained with the GetRCnt() function.
Up-Counting The root counter is incremented by hardware. The root counter will continue incrementing even if
interrupts are disabled by software.
Target Values A target value can be set for the root counter. When the value of the root counter reaches the target value,
the root counter is cleared and continues incrementing.
Macros
RCntCNT2 is the name of the root counter that is available in the Net Yaroze system. The RCntCNT2 macro is used within root counter functions such as SetRCnt() to specify this root counter. The operating mode of the root counter is specified as an argument to SetRCnt() and must be set to (RCntMANOINTR | RCntMdSP). No other operating mode is valid for Net Yaroze.
90
Kernel Management mmm
Start-Up State
The state of the root counter is unknown at start-up. The root counter must be initialized with StartRCnt()
before it is used.
| 1/O Management
The I/O management service provides support for file I/O. The data structures and macros used in the I/O
management service are defined in the file 'sys/file.h'.
The I/O management service is responsible for all PlayStation file management. General file access functions such as open() and close() are provided as well as other functions such as file search (firstfile(), nextfile()).
Block Size
Each device has its own “block size” which serves as its unit of data access. All data access operations are performed in multiples of the block size. Data which exceeds an integral
number of blocks will be ignored.
The Standard I/O Stream
File descriptors O and 1 are used for the standard input and standard output streams, respectively. On start-up, Net Yaroze assigns the standard input/output streams to the “tty” serial device. The serial
device performs input and output of characters via the serial interface.
The Memory Card Driver (bu) Memory cards are shared across multiple applications. Therefore, access to Memory cards is permitted only through the file system. The bu device is the Memory card driver and supports functions such as file
search.
A description of the 'bu' device is given in the table below.
91
EEE Kernel Management
O
Physical devices bu00: Memory card in slot 1 bul0: Memory card in slot 2 Functions supported open, close, read, write, firstfile,
nextfile, delete, rename, format
Table: The Memory Card Driver
E S|
Filename buXY filename 'filename' is a 21 character ASCII character string A colon (':') is placed between 'buXY' and 'filename' 'XY' specifies the insertion slot
Valid characters are the upper case English letters, numbers and the character '_'.
Number of files Between 1 and 15 for each card
File size Multiples of 8 KB
Specified at file creation. No automatic expansion using write(). Example: (this creates a 24K file)
long size = 3;
long fd = open(fname, O_CREAT | (size<<16));
close(fd); /* always close immediately after creation */
Table: The Memory Card File System
The Serial Driver (tty)
The serial driver provides the basic link between the host PC and the Net Yaroze PlayStation. The
transfer speed of the serial driver can be set with the ioctl() function.
92
Kernel Management mmm
A description of the serial driver is given in the table below.
Description
Functions supported open, close, read, write, ioctl Block size 1 byte
Table: The Serial Driver
| Module Management Service
The module management service provides basic functions for loading and executing application modules.
Executable Files
The PlayStation executable file format is known as 'PS-X EXE'. All applications that run on the
PlayStation must conform to this format. Executable files contain the information listed below.
Information within Executable Files (a) Code and data linked to fixed addresses (b) The execution start address (c) gp register initial value
(d) The starting address and size of the data area for uninitialized data
Layout within Executable Files
2048 body of the program] (a) from the list above multiple of F 2048 bytes text section + data section for initialized data
Table: Layout within Executable Files
93
EEE Kernel Management
Executable File Information Data Structure The functions that operate on executable files (Load() and Exec()) use the internal information described
above. The EXEC structure can be used to access this information directly.
EXEC has the following structure.
struct EXEC ( /* executable file information */ unsigned long pc0; /* execution start address */ unsigned long gp0; /* gp register initial value */ unsigned long t_addr; /* starting address of text section
and initialized data section */ unsigned long t_size; /* size of text section
+ size of initialized data section */
unsigned long d_addr; /* reserved for system use */ unsigned long d_size; /* reserved for system use */ unsigned long b_addr; /* starting address of the data section for
uninitialized data */ unsigned long b_size; /* size of the data section for
uninitialized data */
unsigned long s_addr; /* stack area starting address
(user-specified) */ unsigned long s_size; /* stack area size (user-specified)*/ unsigned long sp, fp,gp, ret,base; /* register save area */
};
Loading Executable Files Executable files are loaded from the CD-ROM using CdReadExec(). Loaded files are executed with Exec().
| Additional Services
The following additional services are provided for kernel management.
. InitHeap() InitHeap() initializes the heap area. The heap area should be initialized before using the memory allocation function, malloc(). However, InitHeap() should be called explicitly only when the
heap area is changed as it is usually called automatically prior to main().
94
Kernel Management mmm
. FlushCache() FlushCache() flushes the R3000 I-cache. FlushCache() should always be called between loading
an executable file (using CdReadExec(), for example) and executing the file with Exec().
The Heap
The heap is an area in memory used for storage allocation . It is dynamically controlled using malloc() and free().
The heap should be allocated a fixed amount of memory from inside the start-up routine according to the size of the application program.
95
11
CD-ROM Management
mmm CD ROM Management
The CD-ROM management service includes functions that support reading files from the CD-ROM and playing CD-DA data.
| CD-ROM Overview
Sectors Digital data is recorded in a spiral pattern on the surface of a CD-ROM, just as on an audio CD. The digital data on a CD-ROM is processed in units known as “sectors.” It takes 75 sectors to equal 1
second’s worth of digital data.
Each sector can be classified as an audio sector, a data sector, or an ADPCM sector, depending on how it
is used.
Audio Sectors Data stored in audio sectors is recorded as digital stereo audio data at a sampling frequency (fs) of 44.1 KHz,. This is the normal sampling frequency for CD audio data. Audio sectors can be played back with
the CdPlay() function, but audio sectors cannot be read as user data.
Data Sectors User data is recorded in data sectors. The amount of user data which can be recorded in a data sector differs
slightly depending on the mode, but generally, 2048 bytes are available (mode-1 format).
ADPCM Sectors
ADPCM sectors are more properly called 'real time sectors' or 'mode-2 form-2' sectors. ADPCM sectors store audio data compressed using ADPCM compression. ADPCM sectors are typically used to play back
audio in the same way as audio sectors. However, ADPCM sectors are not supported by Net Yaroze.
Transfer Rate The PlayStation CD-ROM can rotate at either standard speed or double speed.
Standard speed provides the same rotation rate as a standard CD player. The transfer rate for standard
speed is 150 KB/sec, while the transfer rate for double speed is 300 KB/sec.
98
CD ROM Management Mmm
This means that in one second, 75 sectors of data can be read at standard speed and 150 sectors can be read
at double speed.
The File System
The PlayStation CD-ROM uses a file system based on ISO-9660 level 1. The details of the file system are
shown in the table below.
E AS S|
File format basename.ext;version
'basename' can be up to 8 characters, 'ext' can be up to 3 characters.
A". (period) is placed between 'basename' and 'ext'. A ';' (semicolon) is placed between 'ext' and 'version'.
Valid characters are the upper case English letters, numbers and the character '_”.
Directory format basename
'basename' can be up to 8 characters. No extensions are allowed.
Valid characters are the upper case English letters, numbers and the character '_”.
Directory levels Maximum of 8 levels. The root directory has no name. All sectors in a file are physically arranged contiguously.
Table: The CD-ROM File System (ISO-9660 level 1 standard)
However, the PlayStation only supports lists of files and directories that can be stored in one sector (2048 bytes). As a result, there are certain restrictions specific to the PlayStation as shown in the table
below.
Total number of directories
Total no. of files per directory
Table: CD-ROM Restrictions Specific to the PlayStation
* The file and directory control data structure in ISO-9660 is of variable length. In cases where many of
the names are short, it is possible to have more directories and files than what is shown in the table above.
99
mmm CD ROM Management
| File Access
File Searching The CdSearchFile() function is used to find the starting position of a file in the ISO-9660 file system. CdSearchFile() searches for the start of a file using the absolute path name of the file. The search results are
saved in the CdIFILE structure, which is shown below.
typedef struct { CAlLOC pos; /* file position */ unsigned long size; /* file size */ char name[16]; /* file name (body) */ } CALFILE;
In addition, the CdILOC structure, which indicates the file position, has the following structure.
typedef struct { unsigned char minute; /* minute (BCD) */ unsigned char second; /* second (BCD) */ unsigned char sector; /* sector (BCD) */ unsigned char track; /* track (void) */
+ CAlboc;
Reading Data Files The CdReadFile() function is used to read a data file from the CD-ROM. The following is an example of how CdReadFile() is used.
CdlFILE fp; if (CdSearchFile(&fp, "\PSX\SAMPLE\RCUBE.TIM") != 0) CdReadFile(fp, sectbuf, 2048); Note that CdReadFile() executes asynchronously as a non-blocking function and returns immediately
after it is called. CdReadSync() is used to detect the actual completion of execution.
Reading Executable Files
The CdReadExec() function is used to load an executable file from the CD-ROM into memory. The file can
be executed with the Exec() function provided by the kernel management service.
100
CD ROM Management Mmm
Note that CdReadExec() executes asynchronously as a non-blocking function and returns immediately
after it is called. CdReadSync() can be used to determine the number of unread sectors remaining.
Read Synchronization
The CdReadFile() and CdReadExec() functions execute asynchronously as non-blocking functions that return immediately after they are called. CdReadSync() is used to detect the completion of these functions
and to determine the number of unread sectors remaining.
Playback of CD-DA Audio Data The CdPlay() function is used to play back audio data recorded in CD-DA audio sectors.
101
12
Peripheral Devices Management
EEE Peripheral Devices Management PEE] The peripheral devices service manages standard Net Yaroze PlayStation peripherals such as Controllers
and Memory cards.
| Controller Management
Controllers are important devices that communicate the player's commands to the application. Two Controllers can be connected to the PlayStation. Four types of Controllers are supported by the Net Yaroze PlayStation: the standard Controller, a mouse, a Namco neGcon analog controller, and an analog
joystick. Reading Data From the Controllers
The GetPadBuf() function can be used to read data from the Controllers.
Communication with the Controllers takes place every vertical synchronization interrupt (VSync). The data read from the Controllers is saved in two internal system buffers, one for each Controller. Pointers to
these buffers can be obtained using GetPadBuf().
The table below shows the data which is stored in the two Controller buffers.
Bytes from the Start Content of the Buffer
Oxff: no Controller, 0x00: Controller connected
1 Upper 4 bits: terminal type Lower 4 bits: size of received data (1/2 the number of bytes) Received data (maximum 32 bytes)
Table: Controller Receive Buffer Data Format (1)
Controller Types and Data Received The Net Yaroze library supports the standard Controller, the Mouse, the Namco neGcon analog controller
and the analog joystick.
GetPadBuf() can be used to obtain the contents of the Controller buffer. The contents of the buffer are
different for each type of Controller as shown in the table below.
104
Peripheral Devices Management mmm
Terminal Type Device Byte Number Content Name
Byte 3 Bit 2: right button Bit 3: left button Bit values:
1 - button released, 0 - button pushed
Displacement in X direction -128 to +127 Displacement in Y direction -128 to +127
Bytes 5-7 Analog channel values 0 to 255
Standard Bytes 2-3 Bit values: Controller
(a single 16-bit group) 1 - button released, 0 - button pushed Refer to the figure, below for button bit locations. Bytes 2-3 Bit values: Analog (a single 16-bit group) 1 - button released, 0 - button pushed
Joystick . : i Refer to the Net Yaroze Web site for button bit locations
ooo] Bytes 4-7 Analog channel value 0 to 255
Table: Receive Buffer Data Format (2)
0x2 neGcon Bytes 2-3 Bit values: Controller . i (a single 16-bit group) 1 - button released, 0 - button pushed Refer to the Net Yaroze Web site for button bit locations. Analog channel value -128 to +127
The button and bit assignments for the Standard Controller are shown in the figure and table below.
105
EEE Peripheral Devices Management
Figure: Standard Controller Button Assignments
106
Peripheral Devices Management MEM
me INCITA Meere rasen ran
HE HE KEG BETT ran ran
Table: Standard Controller Bit Assignments
* The macros in this table are defined in the file ‘pad.h’ in the check program (\PSX\SAMPLE\CHECK).
107
HEE Peripheral Devices Management A — _—_———————_—_———— bh({ üi F os -. a ee. iıs,:'-kıszızıb),r;:jzgj©$+Y7 Dub oh |
Memory Card Management
The Net Yaroze library supports the function TestCard(), which tests whether a Memory card is inserted
in the PlayStation. For details, please refer to the Library Reference manual.
108
13
Creating PlayStation Applications
EEE Creating PlayStation Applications y K——_—_—_—_—_—_— -_—_ SSS SSS Sy
This chapter presents an overview of how a PlayStation application is created using the Net Yaroze
system.
An application is composed of data and code.
. Code is the program that runs on the machine. PlayStation program code is written using the
standard GNU C development environment.
. Data consists of the 3D models, bitmaps and sound data that the program uses to generate the application's output. Although the PlayStation uses a set of proprietary data file formats, a wide
range of commercial file formats can be converted easily into PlayStation formats.
| Creating Graphics Data
The data used in a Net Yaroze PlayStation application can be classified into three general types: 2D graphics (often referred to as bitmaps), 3D graphics (often referred to as models) and sound data. Movies
(often referred to as Streaming or Full Motion Video), are not available for use with the Net Yaroze system.
2D Graphics Data
The 2D graphics data used by the PlayStation (i.e. bitmaps) provide the imagery for sprites and textures for 3D graphics. 2D graphics data is saved in the PlayStation’s TIM data format where it is handled directly by the integrated graphics service.
In the Net Yaroze system, 2D graphics data generated from paint tools on Windows and Macintosh
systems can be converted to TIM format using special converters such as the Net Yaroze tool TIMUTIL.
For more information on the TIM data format, refer to the Net Yaroze Members' Web site.
Supported File Formats
The Net Yaroze system provides support for converting the following file formats into TIM data. . Windows bit-mapped format (BMP) . Macintosh PICT format (PICT)
. RGB format (RGB)
110
Creating PlayStation Applications Wmm OO Tools
The Net Yaroze system provides the Windows-based TIMUTIL tool (timutil.exe) to convert files from
existing formats to TIM. Please refer to Chapter 14, Graphics Tools for details on how to use the TIMUTIL tool.
Creating Data and Converting to TIM
Use a painting tool which outputs data in one of the 2D file formats supported by the Net Yaroze system (BMP, PICT, RGB) then use the TIMUTIL tool to convert this file into TIM.
Verifying Data The Net Yaroze system has a DOS-based tool called the TIM viewer (timv.bat) which runs on the Net
Yaroze PlayStation. The contents of a TIM file can be viewed and verified using the TIM viewer tool.
Please refer to Chapter 14, Graphics Tools, for information on how to use the TIM viewer tool.
2D Tools List
timutil.exe Converts data from BMP, PICT, RGB to TIM
timv.bat MS-DOS Displays TIM data on the PlayStation
Table: 2D Graphic Tools
3D Graphics Data The 3D graphics data used by the PlayStation (i.e. modeling data) is used to draw 3D objects. 3D graphics data is saved in the PlayStation’s TMD data format where it is handled directly by the
integrated graphics service.
The Net Yaroze system provides several conversion tools for 3D graphics data. These tools convert models from the DXF format (a standard 3D modeling format) to the RSD format (an intermediate file format), then to the PlayStation’s TMD format. The intermediate RSD format is an ASCI-based file which can be edited using a text editor. The final TMD file is a binary format which can be used directly by the
Net Yaroze library functions.
Please refer to the Net Yaroze Members' Web site for more information on RSD and TMD data.
111
EEE Creating PlayStation Applications
Supported File Formats The DXF format is a standard 3D modeling format that is supported by virtually all of the commercial 3D
modeling tools. Please refer to the AutoCad Reference Manual published by AutoDesk Ltd for more information on the
DXF format.
Tools
The following tools are provided to convert files from existing 3D graphics formats.
Please refer to Chapter 14, Graphics Tools, for more information on how to use these tools.
| Tor | Environment | Fue | MS-DOS Converts DXF files to RSD files
Table: 3D Graphic Tools
Creating Data and Converting to TMD Create the original data file using a commercial modeling tool then convert it to TMD format using the
tools described above. The modeling tool must be able to output data in the DXF data format.
The DXF file must first be converted into RSD format before it can be converted to TMD. The RSD format is an artists' format primarily used to apply texture mapping. RSD is actually composed of four different file
types, as shown in the table below.
ANC IT File connection information
Material information
Polygon information
112
Creating PlayStation Applications Wmm Ee
These files are all text files and can be easily edited using a standard text editor. An RSD file must always
be created even if editing is not required. The conversion sequence is always DXF->RSD->TMD. Verifying Data
The Net Yaroze system has a DOS-based tool called the RSD viewer (rsdv.bat) which runs on the Net
Yaroze PlayStation. The contents of an RSD file can be viewed and verified using the RSD viewer tool.
Please refer to Chapter 14, Graphics Tools, for information on how to use the RSD viewer tool.
[rear I rn] ns]
MS-DOS displays RSD data on the PlayStation
Table: 3D Graphic Data Verification Tools
[Creating Sound Data
Sound data used in a Net Yaroze PlayStation application can be classified into two general types: score
data and waveform data.
Score data is stored in the PlayStation SEQ format. Waveform, or sampled data, is stored in the PlayStation VAB format. VAB is a multi-sound format which manages multiple VAG-encoded single- sound data units. The SEQ and VAB data formats can be handled directly by the Net Yaroze sound
services.
Standard MIDI data (SMF) and AIFF data created using commercial sound tools can be converted into
SEQ data and VAB data using special Net Yaroze conversion tools.
Please refer to the Net Yaroze Members' Web site for more information on SEQ and VAB data.
Supported File Formats
In the Net Yaroze system, the following standard file formats can be converted to SEQ and VAB data. 113
EEE Creating PlayStation Applications
. Standard MIDI file Format 1 (SMF)
. AIFF (or alternatively 16-bit straight PCM waveform data, these are formats for sampled data)
Tools
The following tools are provided for converting to PlayStation sound data formats.
For details on how to use these tools, please see Chapter 15, Sound Tools.
A A ] MS-DOS Converts standard MIDI files into SEQ data MS-DOS Converts AIFF or 16-bit straight PCM into VAG format
MS-DOS Creates VAB data based on VAG data and attribute definition files MS-DOS Divides VAB data into VH data and VB data
Table: Sound Tools
Creating Data and Converting to PlayStation Formats
Create sound data using commercial sequencing or waveform editing software which can output data in one of the file formats supported by the Net Yaroze system. This data can be converted into PlayStation
SEQ or VAB format using one of the tools listed above.
Verifying Data The Net Yaroze system has DOS-based tools for playing back SEQ and VAB data files on the Net Yaroze PlayStation. These tools can be used to find out how converted sound data will be reproduced within
the finished application.
Please refer to Chapter 15, Sound Tools, for information on how to use these tools.
EE O
sndplay.bat MS-DOS Reproduces SEQ data on the PlayStation vabplay.bat MS-DOS Reproduces VAB data on the PlayStation
Table: Sound Data Verification Tools
114
Creating PlayStation Applications Wmm ee +,
| Creating a Program
The Net Yaroze program development process uses the industry standard GNU program development tools and conforms to the standard process of program development in C. This section describes a simple example of how a program is created using this process. Please see the Net Yaroze Additional Reading
List at the end of the Start-Up Guide for further information.
Create Code
1. Write C code and save it in a text file. Code can be created using a standard text editor and is
usually saved with a file extension of “.c”.
2. Compile the source code (from step 1) using gcc, the GNU compiler. The compiler will convert source code into object code suitable for linking into the program executable. Object code is
often saved in a file with an extension of “.o” or “.obj” by the compiler.
3. Link the object code to the Net Yaroze library using /d, the GNU linker. The linker will combine the individual objects of your program with the library to produce the final program executable. By default, the executable is named “a.out” by the linker. Note that the compiler can be invoked
so that it calls the linker automatically to generate the executable. 4. Run the executable on the PlayStation by downloading it using the SIOCONS program.
The process described above is both incremental and iterative. It is incremental because your source code will often have syntax errors that are detected by the compiler. You will need to edit your source code to
fix the syntax errors before the compiler will generate an object file.
Once you have successfully linked your object code and created the executable, you will often find bugs that will cause the program to behave incorrectly. You will need to iterate through the entire process
until you have fixed your source code to remove the bugs. gdb, the GNU program debugger is a useful tool for finding bugs in your program. gdb allows you to
step through your program and monitor its behavior.
Makefile
The process of compiling and linking a program can be quite complex. It is often necessary to specify
many commands and options to run the development tools. A makefile can be used to simplify this
115
EEE Creating PlayStation Applications
process. A makefile makes it easier to compile and link a program by automatically issuing the proper
commands and options, much like a DOS batch file.
The makefile can also be used to manage a project that consists of many separate files. make, the program maintenance utility, operates on makefiles and can be used to recompile only those files that change when
the source code is updated.
Making a Library of Useful Routines
As you develop applications, over time you may create basic functions that you use repeatedly in your applications. Rather than copying the source code from one application to another, it is usually more efficient to group the set of functions into a library where they can be used by any application. Using
libraries properly can reduce development time and make your code cleaner and easier to read.
The Net Yaroze system provides ar, the GNU librarian, and nm, the GNU object symbol manager for
creating and maintaining libraries.
Creating a Release Version After you have successfully debugged your executable code, you need to remove any debugging information from it to create a release version. The utility strip, removes symbol information (used by the
debugger) from the executable program.
Tools
gec.exe MS-DOS Compiles .c (source code) files into .o or .obj (object) files Links object files together to make an executable program
ld.exe * MS-DOS Links object files together to make an executable program
siocons.exe Serial console program gdb.exe Debugger
strip.exe Removes symbol information make.exe Manages makefiles
116
Creating PlayStation Applications Wmm
* gcc (GNU compiler) is sufficient to create the executable file (it can compile and automatically call the
linker), although you may prefer to use the dedicated linker tool, ld.
117
14
Graphics Tools
HEE Graphics Tools sees
The Net Yaroze graphics tools consist of data converters and previewers. Data converters convert graphics files created by commercial tools (e.g. bmp, pict and dxf files) into data files in the PlayStation
format. Previewers display graphics data on a TV monitor using the PlayStation.
Listed below are the dedicated graphics formats used in the PlayStation. Please refer to the Net Yaroze
Web site for detailed information on each of these formats.
. RSD data 3D object data (initial conversion format for artists) . TMD data 3D object data (second conversion format for programmers) . TIM data Image data (2D)
Graphics tools run under Windows or MS-DOS. The rest of this chapter briefly describes the features of
the most important graphics tools of Net Yaroze.
dxf2rsd, dxf2rsdw dxf2rsd and dxf2rsdw convert standard 3D object files that are in DXF format into PlayStation 3D object files in RSD format. dfx2rsd is a DOS tool while dfx2rsdw is the Windows version.
rsd2dxf
rsd2dxf converts an RSD file set into a file in DXF format.
rsdcat rsdcat combines multiple RSD files into a single RSD file.
rsdform
rsdform performs simple editing of RSD data (such as moving, expanding and contracting of objects).
rsdlink rsdlink converts RSD data into TMD data. TMD is the 3D graphics format used by the PlayStation. PlayStation applications can process TMD files
directly using the graphics library, without further conversion.
rsdv rsdv is the RSD data previewer. rsdv displays RSD data on a TV monitor using the PlayStation.
120
Graphics Tools Wimm
eC‘ timutil
timutil is used to convert commonly-used image data formats into TIM format used by the PlayStation.
The list below show the image formats which timutil can process. . Windows BMP . Macintosh PICT . Standard RGB . PlayStation TIM
timv
timv is the TIM data previewer. timv displays TIM data on a TV monitor using the PlayStation.
| dxf2rsd.exe
dxf2rsd converts DXF files into PlayStation 3D object data files (RSD).
Usage dxf2rsd [options] DXF-files When a DXF file is provided as the argument, the following four files are created: . An RSD file (*.rsd) . A polygon file (*.ply) . A material file (*.mat) . A group file (*.grp)
Note: Wildcards can be used in the argument to convert more than one file at once. The file extension
‘dxf can be omitted.
121
HEE Graphics Tools . _ _ ____ _____ zz. (Qu OQ q Ch 3q qu qu gq q q q q q q q q q q q q q q q q q q q q q p1,e
Options
-o targetname Specifies the name of the RSD output file (where targetname is the specified file name). The default output
filename is the input filename minus the .dxf extension in the current directory.
-colrgb Specifies the color ofthe overall model using RGB values (each in the range of 0-255). The default setting
is gray (200 200 200).
-cf color-file Specifies a color table file which contains color definitions (where color-file is the specified file name).
The -cf option is almost always used in conjunction with the -cl option, described below.
-cl Outputs a list of undefined colors to standard output. Also, orders polygons of the same color and
outputs them to the MAT file. The default is OFF. (See Example 2, below.)
-info
Displays information about the DXF input file on the standard output. This option gives the approximate
size and number of polygons in the file. No conversion is performed when this option is specified.
-max n-poly Specifies the maximum number of polygons that can be converted (where n-poly is the specified number).
The default is 10000.
-quad or -quadl When this option is specified, division of 4-vertex 3DFACE polygons into triangles is not performed.
This option can reduce the number of polygons in the model. The default setting is OFF.
-quad2 (threshold-value) With this option, adjacent pairs of triangles are formed into single quadrilaterals. The optional argument
(threshold-value) must be a decimal number between 0.0 and 90.0. This argument controls the combining
of pairs of triangles by specifying a maximum angle of orientation difference (normal line vectors) between 122
Graphics Tools MMM
the triangles that can be combined. Any pair of triangles with an angle of orientation greater than the
threshold-value is not combined.
When the argument is 0.0, only triangles with exactly the same normal line vectors will be combined. When the argument is 10.0, a difference in orientation of up to 10 degrees is allowed. The default value of
this argument is 1.0. (See Example 4, below.)
-quad3 When this option is specified, triangles are created as quadrilaterals in which the 3rd and 4th vertices are
identical to each other. This option causes all polygons to be defined as quadrilaterals.
-s and -g Performs smooth (Gouraud) shading. The default is OFF.
-e distance-value Reduces the number of polygons by causing all vertices within a sphere having the specified radius (the distance-value) to be treated as a single vertex. (Note that the radius calculation is carried out after
scaling using the -sc option described below.)
-r Reduces the number of normals by not creating identical normal vectors. This option is valid for flat shading. The default is OFF.
-n Normals are not created. Use this option when there will be no light source calculation. The default is OFF.
-sc factor Expands and contracts the model by a scaling factor (factor) specified as a decimal number. The default is 1.0.
-txyz Translates the position of the model left or right, up or down, and backward or forward by the specified
amounts (x, y and z). Arguments are specified as decimal numbers. The default is (0.0, 0.0, 0.0).
123
HEE Graphics Tools EEE
-auto Shifts the position of the model toward the origin (x, y and z as zero) and scales the model so that it fits
within a cube with sides of 1000. The default is OFF.
-back Reverses the direction of the normals of all polygons. The default is OFF.
-both Creates all polygons as double-sided. The default is OFF.
-dup Creates front and back polygons for each polygon, doubling the number of polygons. The default is OFF.
-nopl Ignores POLYLINE data and converts only 3DFACE data. The default is OFF.
-Y+Z, +Y-Z, +Y+Z, -Z-Y, -Z+Y, +Z-Y, +Z+Y
Specifies how the coordinate system is converted. These options are used to specify the labelling and direction of the coordinate axes which extend towards the viewer and upwards, as if the viewer were looking at the modeller coordinate system from the front. The first value of the pair specifies the forward
axis and the second value, the upward axis.
For example, -Y+Z indicates that the forward axis is the negative Y axis and the upward axis is the positive Z axis. The coordinate system referred to here is the coordinate system of the DXF file. This
coordinate system does not necessarily coincide with the physical screen of the modeller. The default coordinate system is -Y+Z.
dxf2rsd converts the specified coordinate system into the PlayStation coordinate system (-Z-Y). (In the PlayStation coordinate system, the forward axis is the negative Z axis and the upward axis is the negative Y axis.)
-v
Outputs detailed information concerning the conversion to standard output. (See Example 1.)
124
Graphics Tools MMM
Restrictions
The current version of dxf2rsd has the following restrictions. e Only ASCII format DXF files are supported. e Among the DXF entities, only 3DFACE data and POLYLINE data are supported.
e Sometimes large POLYLINE polygons cannot be converted. Wherever possible use a modeller to convert POLYLINE data into 3DFACE data (triangles and quadrilaterals) before creating the DXF file.
e Occasionally quadrilaterals that have vertices which are not all on the same plane are not
displayed correctly.
e The number of polygons that can be converted is influenced by the number of vertices created and
the number of normal lines. As a general rule, this number can be considered to be about 5000.
Supplementary Notes
3DFACE and POLYLINE are both data formats used to express DXF polygons. 3DFACE data represents single polygons (triangles and quadrilaterals) using four vertices, while POLYLINE
data represents more than one polygon using connected line segments.
For a given model, 3DFACE format files tend to be larger in terms of amount of data than POLYLINE, but also have a higher level of compatibility. By contrast, using POLYLINE data reduces the amount of data and affords a greater degree of freedom, but, there may be cases when
data cannot be successfully exchanged between different modellers.
3DFACE data can be directly converted into RSD data, but with POLYLINE data, triangulation must be performed first. Sometimes triangulation is not successful (in which case a 'Fail to triangulate!' error message appears). Furthermore, even when triangulation is completed successfully, sometimes with POLYLINE data the orientation of some of the polygons ends up reversed. However, POLYLINE data created using the 3D Studio software package, referred to as 'POLYFACE MESH!' data, is equivalent to 3DFACE data and thus has no conversion problems.
125
HEE Graphics Tools
. The maximum number of polygons that can be realistically moved about as a single object on the
PlayStation is about 2000. Use this number as a guide when creating model data.
. When conversion with flat shading cannot be performed because there are too many polygons, it
is sometimes possible to convert using Gouraud shading.
. Each time the Y and Z coordinate axes are exchanged, or the positive and negative directions of
each axis are switched, the front and back surfaces of the polygons are reversed.
. Depending on the modeller used, polygons may sometimes end up back to front, even when the data has been output as 3DFACE data. If all of the polygons are reversed, either change the coordinate system (e.g. +Y+Z), or use the -back option. When only some of the polygons are
reversed, correct them using a modeller.
Use a modeller to create DXF data for conversion using dxf2rsd that can output the whole model as 3DFACE DXF data, then reverse polygons individually. (However, data from some modellers can be converted even if these conditions are not met. For example, even when data cannot be converted directly, it may be possible to alter the DXF file via a dxf2rsd-tool-compatible modeller. In other words, ifthe DXF file has been created by a dxf2rsd-tool-incompatible
modeller, open and re-save it in a modeller that is compatible with the dxf2rsd tool.) . With large files, use the -n option to create data without normal lines.
. The -r option is not valid with Gouraud shading (-s or -g options) and cannot be used with
normal line MIMe (the latter because -r changes the number and order of normal lines).
. The -quad2 option may be ignored in areas where the two triangles to be combined have been set to different colors in the DXF file by the modeller. In these cases, the -cl option should be used
together with the -quad2 option. (For example: dxf2rsd -quad2 -cl DXF-files [where
'DXF-files' are the files to be converted]).
126
Graphics Tools MMM
Example 1: Example of dxf2rsd output with the '-v' option
C:\> dxf2rsd -v -auto +2+Y -quad -s foo
Note: Input file = foo.dxf. Output files = foo.rsd, foo.ply, foo.mat, foo.grp
Min. value ... max value for each axis. Y and Z axes are converted to 'PS' if necessary.
(dx,dy,dz) = Amount of movement
(34.788,267.255,81.207)
CCOO O ETT Min. value ... max value for axes after conversion CO | CATE CO [6 ETT
Table: Example of dxf2rsd Output Using the '-v' Option
127
HEE Graphics Tools ee. a ([QQQRQEQQOEQ0033_E2EEEE0€eQQQ PA Example 2: Using color information
Use the -cl option to maintain color added by the modeller in the RSD file. Polygons in the resulting file will be modelled “appropriately,” so that parts that are colored the same in the unconverted file will be
assigned the same color in the RSD file.
Exact color matching cannot be achieved because the unconverted DXF file only holds color numbers rather than RGB values. To maintain colors, a text editor can be used to edit the MAT file after conversion,
or the colors can be specified before conversion using a color table file as shown below.
1. Output a list of undefined colors for the foo.dxf file, piped to a new file, foo.cl.
Cs det2rsd.-cl foo > too sel
2. Display the contents of the resulting file. (This is a list of unassigned colors).
C:\> type foo.cl 183 40
253
3. Colors can be assigned to color numbers by entering their RGB values (in the range 0-255) after
the color number.
C:\> edit foo.cl 183 100 100 200 40 58 20 43 253 10.400, 10 0 212 - 20100 8 0 128 126
4. Run dxf2rsd with the -cf option and the foo.cl file specified.
C:\> dxt2rsd -cf foo.cl foo
The newly created RSD file will have colors assigned according to the color table file.
128
Graphics Tools Wimm
Example 3: Converting large data For data that is extremely detailed (1.e. voluminous), the -e option can be used to reduce the volume of data
by combining several vertices into a single vertex.
In the following example the number of vertices, the number of polygons and the number of normal lines, are reduced by considering any two vertices separated by a distance of 100 or less to be a single vertex. (Note that the distance is calculated according to the scale after expansion.) Depending on the data, an
appropriate distance value can reduce the volume of data with virtually no change in shape. Using the file big.dxf,
C:\> dxf2rsd -v -e 100 -sc 1000 big.dxf
Note: Input File = big.dxf. Output files = big.rsd, big.ply, big.mat, big.grp
æ IESO E Perm O EEE ECON CET EEE EEE ET "20 INN EEE AA TEE HER TEE BET CCT EUCH TA A [mm | C | | | an |. | | Perm Pw A E KERN A a HA Tr Y > AT Tr
Table: Example Converting Large Data
129
HEE Graphics Tools boe o 21,
Specify the -r option in addition to those above to reduce the number of normal lines.
Example 4: Forming quadrilaterals The -quad2 option combines neighboring pairs of triangles into quadrilaterals. In the following example, all neighboring triangles with an angle between them of five degrees or less are converted into
quadrilaterals. Using the file, earth.dxf,
C:\> dxf2rsd -v -quad2 5.0 earth
Note: Input file = earth.dxf. Output files = earth.rsd, earth.ply, earth.mat, earth. grp
= J se ë o o ECT CN EEE proven NETAS |
WN] 3-poly 2937 Originally 2937 triangles
ee A me Ei BE ew p a EEE -O RRA] rr Te poa een | |
Table: Example Forming Quadrilaterals
130
Graphics Tools Wimm
*Note: 4.9870 indicates the largest angle between pairs of triangles that were actually converted. This angle is less than or equal to the allowed angle (in this case 5.0 degrees). Thus, if the same dxf file were converted using dxf2rsd with the option '-quad2 4.986', a smaller number of quadrilaterals would be
formed.
131
HEE Graphics Tools ee pr, QQ QQ QQ aa oQRnR
| dxf2rsdw.exe
dxf2rsdw is a Windows application that converts the DXF format files output by a variety of commercial modellers into RSD format files for use on the PlayStation. dxf2rsdw is the Windows version of dxf2rsd,
the DOS tool described above. dxf2rsdw reads a DXF file and creates the following four output files. . An RSD file (*.rsd) . A polygon file (*.ply) . A material file (*.mat) . A group file (*.grp) Usage
Double-click on dxf2rsdw.exe from the Windows File Manager or Windows Explorer. With the
application running, perform the following steps. 1. Select a DXF file using 'Open...' in the File menu. 2. The Parameter Settings window will appear.
3. Change parameters as required in the window and select either 'Convert...' or 'Save as...' from the
File menu. The save file dialog box will appear. 4. Specify the name for the converted file in this dialog box. 5. The file will be converted and saved under the specified name. Alternatively:
Drag the DXF file to be converted from Windows Explorer or File Manager and drop it into the
dxf2rsdw.exe window.
132
Graphics Tools MMM
Baro: DxF Color Position——— M Dump undefined colors
x 0. | T Auto-resize/translate
G Y I Ignore POLYLINEs Information.. Z o | l Reduce normals
"Smooth shading
Close
1
Maximum polygons |10000
Scale factor
Error of vertex Polygon style |Triangulate M Coord |-Y+Z ¥ Polygon attr. | Standard M
— Color table file
tl
Figure: The Parameter Settings Window
Description of Each Item in the Parameter Settings Window For each item, the corresponding options in the MS-DOS version (dxf2rsd.exe) are noted. Please see the
description of dxf2rsd in the previous section for more detailed information on each of the options.
Color
Specifies the color of the entire model in RGB format (each value in the range 0-255).
Corresponds to the '-col r g b' option in the MS-DOS version.
Position
Translates the model. The position should be specified.
Corresponds to the '-t x y z' option in the MS-DOS version.
Maximum polygons 133
HEE Graphics Tools ep,
Specifies the maximum number of polygons that can be converted.
Corresponds to the '-max n-poly' option in the MS-DOS version.
Scale factor
Performs scaling of the model. The scaling factor should be specified as a real number.
Corresponds to the '-sc factor' option in the MS-DOS version.
Error of vertex All vertices within a sphere having the specified radius are treated as a single vertex. The distance
calculation is made after scaling using the specified “Scale factor.”
Corresponds to the '-e distance-value' option in the MS-DOS version.
Coord Specifies how the coordinate system is converted. The options are used to specify the labelling and
direction of the coordinate axes which extend towards the viewer and upwards, as if the viewer were looking at the modeller coordinate system from the front. The first value of the pair specifies the forward
axis and the second value, the upward axis.
For example, '-Y+Z' indicates that the forward axis is the negative Y axis and the upward axis is the positive Z axis. The coordinate system referred to here is the coordinate system of the DXF file. This coordinate system does not necessarily coincide with the physical screen of the modeller. The default
coordinate system is '-Y+Z'.
dxf2rsdw converts the specified coordinate system into the PlayStation coordinate system (-Z-Y). (In the PlayStation coordinate system, the forward axis is the negative Z axis and the upward axis is the negative Y axis.)
Corresponds to each option in the MS-DOS version. See the description of '-Y+Z, +Y-Z, +Y+Z, -Z-Y, - Z+Y, +Z-Y, +Z+Y' under dxf2rsd for more information.
Dump undefined colors See Notes: Using Undefined Colors, below. (Unlike the MS-DOS version, the default setting for this
option is ON.)
Corresponds to the '-cl' option in the MS-DOS version.
134
Graphics Tools Wimm
Auto-resize/translate Shifts the position of the model toward the origin (x, y and z as zero) and scales the model so that it fits within a cube with sides of 1000. The default is OFF.
Corresponds to the '-auto' option in the MS-DOS version.
Ignore POLYLINEs Ignores POLYLINE data and only converts 3DFACE data.
Corresponds to the '-nopl' option in the MS-DOS version.
Reduce normals Reduces the number of normals by not generating identical normal vectors. Particularly effective with flat
shading.
Corresponds to the '-r' option in the MS-DOS version.
Smooth shading Performs smooth (Gouraud) shading.
Corresponds to the '-s' and '-g' options in the MS-DOS version.
Polygon style The following options are available.
'Triangulate' All polygons are divided into triangles.
‘No Triangulation' Specifies that 4-vertex 3DFACE polygons should NOT be divided into triangles. The overall
polygon count in the model can be reduced by using this option.
Corresponds to the '-quad' option in the MS-DOS version.
'Form Quadrilaterals'
135
HEE Graphics Tools esses
Adjacent pairs of triangles are formed into single quadrilaterals. The optional value, 'threshold-
angle' must be a decimal number between 0.0 and 90.0. This value controls the combining of pairs of triangles by specifying a maximum angle of orientation difference (normal line vectors) between the triangles that can be combined. Any pair of triangles with an angle of orientation greater than
the 'threshold-value' is not combined.
When the argument is 0.0, only triangles with exactly the same normal line vectors will be combined, when the argument is 10.0, a difference in orientation of up to 10 degrees is allowed. The
default value is 10.0.
'Quadrilaterals' Triangles are created as quadrilaterals in which the 3rd and 4th vertices are identical to each other.
Using this option, all polygons can be defined as quadrilaterals.
Corresponds to the '-quad2' option in the MS-DOS version.
Polygon attr.
The following options are available.
136
'Standard” Polygons and normal lines are created exactly as they are specified in the DXF file.
"Invert Normal Lines" Reverses the normal lines of all polygons.
Corresponds to the '-back' option in the MS-DOS version.
'Double-Sided Polygons’ All polygons are created as double-sided polygons.
Corresponds to the '-both' option in the MS-DOS version.
'Front and Back Polygons’ All polygons are created as backwards-facing polygons.
Corresponds to the '-dup' option in the MS-DOS version.
Graphics Tools Wimm Elf
"Don't Create Normal Lines' Normal lines are not created. Use this option when there will be no light source calculation.
When the amount of data is so large that conversion cannot be completed, this option is enabled
automatically.
Corresponds to the '-n' option in the MS-DOS version.
Color table file Specifies a color table file. When the "Reference ..." button is pressed, the File dialog box is displayed and
a filename can be selected. (See Notes: Using Color Information, below).
Corresponds to the '-cf color-file' option in the MS-DOS version.
Convert... Performs format conversion according to the specified parameters.
A Save File dialog box will be displayed. Enter the name of the converted file in the Save File dialog box.
The default directory is the current directory.
This function is the same as the 'Save As...' command from the File menu.
Information... Displays an information dialog box (shown below) containing details of the input DXF file, including the
approximate size and number of polygons.
Corresponds to the '-info' option in the MS-DOS version.
137
HEE Graphics Tools
Information
Input DXF file: F:SPSEDATARHDDELEAPOLSAPOL. OXF [DXF] SIZE : 87dd lines
WERTES : 1060
POLYGON : 480 iearin sted! 13 + + +
3-pol y
Figure: Information Dialog Box
Note: Text can be copied to the Windows clipboard by selecting a range of text with the mouse and
pressing Ctrl+C. To save the information in a file, the copied text can be pasted into a text editor.
Close
Closes the current window.
This function is the same as the 'Close' command from the File menu.
Menu Bar "Open..." Command ([File] menu)
Opens an existing DXF file. A File Open dialog box is displayed. The DXF file to be opened is
specified here. ‘Save As...” Command ([File] menu)
Saves an opened DXF file under a specified filename. A File Save dialog box is displayed. An appropriate filename should be entered then the file is saved. Conversion to RSD format is
performed according to the specified parameters.
138
Graphics Tools MMM
Notes
Using Color Information
To maintain color that has been added by the modeller in the RSD file, the DXF file must be converted twice. The first conversion is used to determine what colors are undefined. The second conversion allows you to specify how these colors will be converted. Note that when specifying undefined colors, exact color matching cannot be maintained because the unconverted DXF file only holds color numbers rather than RGB values.
The process is described below. e Find the undefined colors
1. Select 'Dump undefined colors' in the conversion dialog box to get a listing of the undefined
colors. After conversion, an Undefined Colors list is displayed in a dialog box as shown below.
Undefined colors
Save... | Ianore |
Reference. ..|
Figure: The Undefined Colors Dialog Box
e Specify colors Use the dialog box to specify colors for the list as follows:
1. Select a line in the table and edit the R, G and B fields to provide the required color (using RGB
values between 0-255). 2. Click 'Save' and specify a name for the resulting color table file in the File dialog box.
3. Redo the conversion specifying the name of this undefined color file in the 'Color table file’ field.
139
EEE Graphics Tools SSS SSS === SS SSS -____—_»>_>_ A |
Colors in the newly created RSD file will be assigned according to the color table file.
For other restrictions and additional notes, see “dxf2rsd.exe, Example 2: Using Color Information.”
| rsd2dxf.exe
Converts an RSD format file into a DXF format file.
Usage
rsd2dxf [options] [ARG-files ...] RSD-files
An RSD file set is specified as an argument and is converted to the DXF format. The file set is specified as name and refers to the four files, name.rsd, name.ply, name.mat and name.grp. The output DXF filename is
the input RSD filename appended with a ‘.dxf? extension (name.dxf).
Wildcards can be used as arguments. Options
-o output-file Specifies the output dxf filename. The default output filename is the input filename appended with a ‘.dxf?
extension, with the file being placed in the current directory. This option can be used only when there is a
single RSD input file. -r Reverses the orientation of all the polygons in the output DXF file.
-h Displays a list of the available options, as well as brief instructions on usage.
-v
Displays information about the conversion.
[ARG-file]
140
Graphics Tools Wimm
Specifies an argument file containing command arguments and input filenames. If a filename has a ‘.arg’
extension, it is assumed to be an argument file.
Argument files should be used when arguments are longer than 128 bytes. Lines beginning with "+"
inside the file are assumed to be comments and are ignored.
Notes
. In the coordinate system of the generated DXF file, +X will be to the right, +Y will be downward, and +Z will be inward. These settings are identical to the default values assumed by dxf2rsd for DXF files. Therefore, when a generated DXF file is to be opened and edited by a modeller, it may
be necessary to rotate the model to correspond to the coordinate system used by the specific
modeller. ° The normal, color, and texture information contained in the RSD files is discarded. . If the output filename is already being used, the contents of the file will be overwritten. Please
note that no warning messages will be displayed. . Argument files cannot be specified inside an argument file (they are ignored).
. Wildcards cannot be used in an argument file.
[redcat.exe
Joins multiple RSD format files into a single RSD file set.
Usage
rsdcat [options] [ARG-files ...] RSD-files
The RSD file sets supplied as arguments are joined together, and a new RSD file set is created. Wildcards can be used as arguments.
Options -o output-file
141
HEE Graphics Tools
Specifies the output filename. The default is ‘out.rsd’, ‘out.ply’, “out.mat”, and ‘out.grp’, with these files being placed in the current directory. When a filename is specified with this option, the output files are
generated using the input filename appended with the ‘.rsd’, ‘.ply’, ‘.mat’ and ‘.grp’ extensions.
-h Displays a list of the available options as well as brief instructions on usage.
-v
Displays information about the conversion.
[ARG-file] Specifies an argument file containing command arguments and input filenames. If a filename has a ‘.arg’
extension, it is assumed to be an argument file.
Argument files should be used when arguments are longer than 128 bytes. Lines beginning with "#"
inside the file are assumed to be comments and are ignored.
Notes
. For each RSD file from the input, a group is added to the generated group file (*.grp). All of the polygons from the RSD file are included as members of a group. The filename of the input RSD file
without the extension is used as the group name.
. No compression will be performed by rsdcat even if texture, vertex, normal, or group data overlaps across multiple input RSD files. Consequently, the files output from rsdeat may need some
manual editing.
. If the output filename is already being used, the contents of the file will be overwritten. Please
note that no warning messages will be displayed. . Argument files cannot be specified inside an argument file (they are ignored).
. Wildcards cannot be used in an argument file.
| rsdform.exe
Transforms and moves 3D object data (artist-oriented RSD data).
142
Graphics Tools MMM . — __ _—__— ooQ_ooa ÍA q ___0_0qp E qQ 5q 5 5q q 3 __ 55 E EEE E > == EECOOOOO RA
Usage
rsdform [options] RSD-name
This command alters the form of objects by applying scaling, rotation and translation to RSD format
object data. If more than one transformation operation is specified at the same time, the operations are
carried out in the following order: scaling — rotation > translation.
Specify the RSD file name as either 'file.rsd' or 'file' (without the .rsd extension). Options
-0 RSD-name Specifies the RSD name of the output file (where RSD-name is the specified file name). The output name
cannot be the same as the input file name. The default filename is 'a'.
-SXyx Specifies scaling values for the x, y and z axes. The values are specified as float values, where 1.0 indicates no change. Negative values can also be specified, in which case the corresponding axis will be output as
a mirror image of the original.
-r xyz Specifies angle of rotation around the x, y and z axes. The values are specified as float values. Positive
values indicate a clockwise rotation (see Supplementary Notes, below). The default unit is degrees, but
the -rad option can be used to specify angles in radians.
-txyz Specifies translation along the x, y and z axes. The values are specified as float values.
-rad Specifies that radians should be used as the default unit for the rotation angle.
-l Performs scaling and rotation around the center of the model. Used with the -s and -r options.
-C
143
HEE Graphics Tools ZZ — — —— — ————— ————
Share files if possible. (See Supplementary Notes, below.)
-c[pmg] Share PLY/MAT/GRP files. A shared file can be specified by combining the three letters (p, m, g). An
example would be -cpg (this is equivalent to -cp -cg). When other options are specified and files cannot be shared (see Supplementary Notes), a warning message will be displayed and the share option will be
ignored.
-k Keeps the version of the original file. If this option is not specified, the result is (YRSD940102, (APLY 940102, @MAT940801 and @GRP940102.
-quiet The modification history will not be added as comments to the output file. The default setting is OFF.
-v
Detailed information on the conversion is output to standard output.
Supplementary Notes
. RSD files are formed in sets of four files with the following extensions: .rsd, .ply, .mat, .grp. These files must be placed in the same directory, and are generally placed in the RSD directory within
the project directory. . Files can be shared if the following conditions are met.
PLY files: No transformations are specified. MAT files: The output file is not a mirror image of the original data.
GRP files: Can always be shared.
. The coordinate system of the PlayStation is represented as 16-bit values. The RSD format is not restricted to 16 bits, but when rsdlink is used to convert an RSD file to the TMD format, the
result must fit into the PlayStation coordinate system.
144
Graphics Tools Wimm
. 'Clockwise rotation' refers to the direction in which the fingers curl when the thumb of the right
hand is extended to point in the positive direction of the axis of rotation.
145
HEE Graphics Tools
Example 1: Basic usage In this example, the model is scaled along the x axis by a factor of 10, then a 45-degree rotation is
performed around the x axis. Files are to be shared if possible. Using the file cube.rsd as input,
C:\> rsdform -v -s 10 1 1 -r 45 0 0 -c cube
ee pepe EAN kormos [8 j a a | CO FRANCA IE TA o | cn | Te Tess [soo [m CTE
FILE cube.ply becomes a.ply TRANSFORMATION cube.mat becomes cube.mat This file can be shared (shared) cube.grp becomes cube.grp This file can be shared (shared)
RANGE +10000.0 +5000.0 Size after transformation mm
| 1071 | 1 Era 1 | +00 | Gmax, min and central | min | (max,minandeental | central
—— -707.1 +707.1 coordinate values for each axis)
Table: Example rsdform Basic Usage
146
Graphics Tools MMM
Example 2: Performing local transformation
The -l option is applied to the deformation from Example 1.
With this option enabled, rotation and scaling can be performed around the model's center of gravity so
the model’s position remains unchanged. Compare this with the results from Example 1. Using the file cube.rsd as input,
CiX> cesdiorm -=y =1 =s 10 1 1. =r 45 0 0 =e cube
CEA A E EA COCOS ACI AC | 0 | CTC Tevscanon [oe fe pe TA os ps BEN A Y >
FILE cube.ply becomes a.ply TRANSFORMATION cube.mat becomes cube.mat This file can be shared (shared) cube.grp becomes cube.grp This file can be shared (shared)
cube.rsd becomes a.rsd
-4500.0 +5500.0 +500.0 Size after transformation (center)
-707.1 +707.1 No change to center after transformation z | 071 | +7071
Table: Local Transformation with rsdform
147
HEE Graphics Tools i+
Example 3: Copying RSD files rsdform can also be used to copy and rename RSD files. A batch file such as the one shown below can be
useful for this. Contents of batch file:
@ECHO OFF
oe
rsdform -o %2 %1
Example 4: Overwriting RSD files rsdform does not allow RSD files to be overwritten before transformation. However, a batch file such as
the one shown below can be used to overwrite RSD files.
Contents of batch file:
@ECHO OFF
SET ARGS=
REM read all arguments :LOOP1
IF "%9"=="" GOTO LABEL1
SET ARGS=SARGS% %1
SHIFT
GOTO LOOP1
:LABEL1
for now
REM convert to filename _tmp
ole
3
oo ws ole oe
6
ole
7
oo
rsdform -o _tmp SARGS% $1 %2 5 8
IF ERRORLEVEL 1 GOTO END
REM find final argument (= input filename) :LOOP2
IF "%1"=="" GOTO LABEL2
SHIFT
GOTO LOOP2
: LABEL2 REM overwrite the input file (%0)
rsdform -o %0 -quiet _tmp
REM delete '_tmp.*' and exit
148
Graphics Tools MMM A al
DEL _tmp.* : END
SET ARGS=
| rsdlink.exe
Converts artist-oriented 3D object data files (RSD files) into object data files (TMD files) that can be handled by the PlayStation library.
Usage rsdlink [options] rsd-names rsdlink [options] rsd-names [options] rsd-names [options] rsdlink [options] arg-files Multiple RSD data files supplied as arguments are linked into a single TMD file. Scaling factors and
translation values should be specified separately for each RSD data file, if required. (See Example 1.)
If there are no file paths specified for the required RSD filenames in the argument, rsdlink searches the
current directory first, followed by the 'ARSD' directory.
When there are a large number of arguments, the arguments can be placed in an argument file. An argument file is a text file with a file extension of ‘.arg’ that contains a list of arguments. Note that argument files cannot be specified inside an argument file. The input filename extension of an RSD file ('.rsd') may be
omitted, but the filename extension of argument files ('.arg') must be specified. (See Example 2.) Options
-0 filename Specifies the output filename. The default is 'a.tmd'.
-s factor The RSD data specified in subsequent arguments is scaled by the specified scaling factor. This scaling
factor will be applied to all RSD data thereafter until a new scaling factor is specified.
-sc factor
149
HEE Graphics Tools P
factor The default value is 1.0. The coordinate values in TMD format are
The scaling factor is rounded to 2 16-bit integers, so the scaling factor must be specified appropriately to allow the data to fit within the
PlayStation’s coordinate system.
-t xyz The RSD data specified in subsequent arguments is translated by the indicated offsets. The default is (0 0
0). The specified offsets will be applied to all RSD data thereafter until new translation offsets are
specified.
-info
Detailed information about the object being converted such as its type, vertex coordinate values and
texture information is sent to standard output (see Example 4).
-v Detailed information about the conversion such as the number of polygons, is sent to standard output. The approximate size of each RSD in the PlayStation coordinate system is also output so the model’ s position and size can be confirmed before it is displayed on the PlayStation. (Range: vertex minimum and
maximum values (x, y, z)) (See Example 3.)
The following restrictions apply to the current version.
Restrictions
. Linking may not be possible when a single RSD data set contains an extremely large number of polygons. The maximum number of polygons in a file where linking is guaranteed is roughly 5000, although the actual limit varies according to the number of vertices, the number of normals, and the amount of free memory available. However, this restriction only applies to a single RSD data set. For practical purposes, there is no limit to the number of RSD data sets to be linked or to
the number of polygons in the entire TMD.
Note
. It is recommended that RSD translation and scaling operations be performed using the commands: dxf2rsd -sc -t and rsdform -s -t.
This will result in data that is more accurate and easier to manage.
150
Graphics Tools MMM
. The texture file (TIM file) specified in an .rsd file must be in the same directory as the RSD file (A) or in the ..\TIM directory because rsdlink will search for TIM files in this order.
151
HEE Graphics Tools i |
Example 1: Basic usage
C:\> rsdlink -v -o boxes.tmd boxl -s 2.0 -t 100 100 100 boxla box2 -t 200 - 200 200 box3
In this example the following four objects are combined to form a single TMD file ('boxes.tmd')
box1 original size
boxla box! scaled to twice the size and translated by (100 100 100) box2 box! scaled to twice the size and translated by (100 100 100) box3 box1 scaled to twice the size and translated by (200 -200 200)
Example 2: Collecting arguments together in a file If there are a large number of arguments as in Example 1, the arguments can be saved in an argument file as
shown below.
1. Create the argument file: test.arg as a text file.
boxl -s 2.0 -t 100 100 100 boxla box2
-t 200 -200 200 box3
2; Use test.arg as an argument.
C:\> rsdlink -v -o boxes.tmd test.arg
152
Graphics Tools MMM
Example 3: Example output with '-v' option
Using the input file dino.rsd,
C:\> rsdlink -v dino -s 100 box
DI o IA O CCT RSD files \PSXGRAPH\DATA\RSD\dino.ply, dino.mat, dino.grp ee
RANGE (-180, -210, -1690) - (180, 580, 290) maximum and minimum range values (x, y, z)
Table (Part 1): Example rsdlink Output
(See part 2, below.)
153
HEE Graphics Tools
RD pana | 2nd RSD ("boxtsd") | | 2nd RSD ("boxtsd") | rsd")
—— Boy er FILES \PSXGRAPH\DATA\RSD\box.ply, box.mat, box.grp
RANGE (-6400, -6400, -6400) - (6400, 6400, 6400) Maximum and minimum range values (x, y, z)
eo] E [man ninadenge | omnes [3 FCC enone mann | Ge ocon r [Brake reams | cee ce
NORMALS 2683 ( 21464 bytes) Piss oes | no. of normal lines Total File Size: 98244 bytes Output file size
Table (Part 2): Example rsdlink Output
(See part 1, above.)
154
Graphics Tools MMM
Example 4: Sample output with '-info' option
When the -info option is enabled, it is possible to see what the converted TMD data looks like.
C:\> rsdlink -info box
Description
INPUT RSDS No. of objects in the TMD file RSD[ 0] Name of each RSD
TOTAL VERTICES Pao Total no. of vertices
TOTAL NORMALS Total no. of normal lines TOTAL PRIMITIVES Total no. of primitives
FLAT TEX 3-POLY(0x24000507) LIGHT: ON =0
Vert-0: ( -150, -150, -150) (#2)
Vert-1: ( 150, -150, -150) (#6)
Vert-2: ( -150, 150, -150) (#0)
Norm-0:( 0, 0, -4096) (#0)
UV 0-2:( 0 0)(47 0)( 0 47)
Pixel mode : 4bit CLUT : (x y)=( 0 480)
Texture Page: 10 Texture No. : 0
FLAT TEX 3-POLY(0x24000507) LIGHT: ON = 1
For each primitive, the following information is displayed: e [the polygon number], flat or Gouraud e presence of absence of texture (TEX/NO TEX), shading (FLAT/GOURAUD), semi-transparency ON/OFF(TRANS),
e two-sided or one-sided polygons (TWO- e primitive type (3-POLY, 4-POLY, LINE, SIDED), gradation (GRADATION), SPRITE), primitive header in hexadecimal
notation (0x...),
e light source calculation ON/OFF (LIGHT: ON/OFF).
155
HEE Graphics Tools esses
Next, the coordinate values of each of the vertices of that primitive are shown as follows:
Vert-0: (-150,-150,-150) ($2) '(#...)' being the vertex number used in the PLY file.
Normal lines are displayed in the same way:
Norm-0: (0,0,-4096) (#0) (With RSD, normal lines are usually normalized to a size of 1 [in this case (0, 0, -1.0]), but with TMD the
values shown above occur because the floating point number 4096 is considered as having the value 1.)
Finally, material information such as UV coordinates and colors of the textures are displayed.
| rsdv.bat (RSD Previewer)
rsdv.bat is an RSD data previewer which displays RSD data on a TV monitor using the Net Yaroze PlayStation. rsdv.bat is a DOS batch program.
Usage
C:\>rsdv RSD_file The PlayStation cannot directly process RSD data, so the rsdv command first converts the RSD file passed as an argument into a TMD file using the rsdlink command. The TMD file and the corresponding TIM file are merged into a single file which is transferred to the PlayStation. Then the RSD preview program (rsdview) is transferred to the PlayStation and the previewer displays the file on the PlayStation's TV
monitor.
Using the Tool
The PlayStation Controller can be used to explore the model. (See Controller functions shown below.) Note: Before using the rsdv tool, check to see that:
. the PC and the PlayStation are connected by the communications cable DTL-H3050,
. the Net Yaroze PlayStation boot disk is in the Net Yaroze PlayStation,
. the power is switched on.
156
Graphics Tools MMM
Twist left Move In Rotate Left Twist right Move Right Move Out Move Up Rotate Up Move Left
Rotate Right
Exit Program
Move Down Rotate Down
Figure: Controller Button Functions
| timutil.exe (TIM utility)
timutil is a Windows application which converts files between each of the following bitmapped formats: PlayStation TIM, Windows BMP, Macintosh PICT, and ordinary RGB.
Usage To launch timutil, double-click on its icon from the Windows File Manager or Windows Explorer. With
the application running, perform the following steps. 1. Select a bitmap file by choosing 'Open...' from the File menu.
2. The Parameter Settings window will appear.
157
HEE Graphics Tools
3. Change these parameters as needed and press the 'Convert...' button or select 'Save as...' from the
File menu. The Save File dialog box will be displayed. 4. Specify the name for the converted file in this dialog box. 5. The file will be converted and saved under the specified name. Alternatively:
Drag the RSD file to be converted from Windows Explorer or File Manager and drop it into the timutil
window. EFireoi.rım A E „Read type Size Bit depth © BMP Width C4 es C16 024
©PICT CRGB Height |32 Preview... | Skip
-Image org Transparency —————————— Palette to use r Write type ————— x |704 C Translucent except black Close |
CBMP TIM yY |256 l Transparent for black
il
AL
CPICT CRGB
—File information
Skip x |0 File size{1568 | Image org: [704 z pp joyes Y |480 Bit depth:8 |] Palette org: fo] . 1480
—Palette org
AL
Figure: The Parameter Settings Window
Description of Each Item in the Parameter Settings Window
Read type Displays the format of the input file to be read. When this option is set to TIM, BMP, or PICT, RGB can
also be selected. In this case, the TIM, BMP, or PICT header information is ignored, and the tool is forced to read the data as RGB data.
'TIM' 158
Graphics Tools MMM
Selected when the input file is a PlayStation TIM format file.
'BMP' Selected when the input file is a Windows BMP format file.
'PICT' Selected when the input file is a Macintosh PICT format file.
'RGB' Selected when the input file was neither a TIM, BMP, nor PICT format file.
Skip Used to specify the number of bytes to skip when the input file format is 'RGB'.
Write type Selects the file format for the converted (output) file.
'TIM' Select this to convert to PlayStation TIM format.
'BMP" Select this to convert to Windows BMP format.
'PICT' Select this to convert to Macintosh PICT format.
'RGB' Select this to convert to ordinary RGB format.
Skip Used to specify the number of bytes to zero-fill when the output file format is 'RGB'.
Size
Used to specify the byte arrangement when the input file is 'RGB'. This information is essential for RGB image data interpretation. Reports an error if: the size of the image data (calculated from the values entered here and the value entered in the 'skip' box) is larger than the size of the input file. Displays a warning if
the size of the image data is smaller than the size of the input file.
159
HEE Graphics Tools ee € P€__Ó A E_E E E-=5 E > z5__EEEOÓOÓO LLL oo. A
Image org This sets the coordinates of the origin of the PlayStation frame buffer image for a TIM output file.
Palette org This sets the coordinates of the origin of the PlayStation frame buffer image palette (CLUT) for a TIM
output file when the bit depth is 8 or less.
Transparency Used to specify the transparency when the file format is TIM, and the bit depth is 16 or less.
When 'Translucent except black' is selected, the transparency control bit is set to '1' for all palette entries
which have at least one non-zero R, G, or B value.
When 'Transparent for black' is selected, the transparency control bit is set to '0' for all palette entries in which the R, G, and B values are all '0'. If this is not selected and if the R, G, and B values are all '0', the
color will be an opaque black.
Bit depth Specifies the number of bits per pixel in the output file.
When the output format is BMP only the values 4, 8 and 32 can be selected. When the output format is PICT, only 4, 8 and 16 can be selected, and when it is RGB only 24 can be selected.
Palette to use When the input file has more than one palette and the output format is TIM, this selects which palette(s)
will be used in the converted (output) file. The palette(s) selected here are also used when the image is displayed using the “Preview...” button.
When the ‘Link to Palette org * option is enabled for ‘Palette to use” in the ‘Setup’ command from the File menu, the Y coordinate of the origin of the selected palette is automatically increased or decreased to
match how far the selected entry is from the top of the write palette list.
File information Displays the size and pixel depth of the input file.
For an input file in TIM format, the image origin is displayed. For an input file with a bit depth of 8 or less, the palette origin is displayed.
Convert... 160
Graphics Tools Wimm
Performs format conversion according to the specified parameters. Enter the name for the converted file in the Save File dialog box. The default directory is the current
directory.
This function is the same as 'Save As...' from the File menu.
Preview... Reads and displays the specified input file. If the bit depth of the input file is larger than the depth of the display being used, colors will be
approximated.
Close
Closes the current window.
This function is the same as 'Close' from the File menu.
The Menu Bar
"Open..." Command ([File] menu) Opens an existing bitmapped file. Specify the file to open in the Open File dialog box. The TIM utility supports PlayStation TIM, uncompressed Windows BMP, 32-bit mode, as well as PICT and ordinary RGB formats which contain one or more bitmaps (the bit depth for the output file is restricted to 4, 8, 16, and 24 bits). RSD format model data can also be selected. In this case all TIM files specified in the model data
are opened.
'Close' Command ([File] menu)
Closes the current active window.
‘Save As..." Command ([File] menu) Saves the bitmap being worked on with a new filename. In the File Save dialog box, enter a suitable name for the converted file and save it. Conversion will be performed according to the
specified parameters.
‘Save All Files..." Command ([File] menu)
161
HEE Graphics Tools
Saves all bitmaps being worked on. When the Directory Selection dialog box is displayed, specify the directory where the output files will be written. Format conversions will be performed for
each bitmap according to the specified parameters. The filenames will be the same as the original filenames, except that the filename extensions are replaced by extensions appropriate to the
output format.
'Setup...' Command ([File] menu)
Specifies the initial values displayed in the Parameter Settings window when a file is opened.
(As shown below.)
Read type — -Size -Bit depth un Width => @ Auto C RGB Height[256 | cs C16 C24 Cancel | oa Image org Transparency
Joyes
V Use TIM info l Translucent except black x p ] l Transparent for black pe Be ype Y p ] | r Palette to use
CBMP € TIM -Paleteorg | ^ First palette FPICT RGB W Use TIM info C All palettes Skip x M Link to "Palette org"
Jones
Figure: The Setup Dialog Box
Notes on The Setup Dialog box
e When 'Read type’ is set to 'Auto', the file format displayed in the Parameter Settings window will match the format of the input file. When 'Read type” is set to 'RGB', the format is set to RGB regardless of the type of file. The same applies to 'Bit depth".
162
Graphics Tools Wimm
e When the read format is not TIM or when 'Use TIM info” is not checked, the utility uses the
values entered for 'Image org’ and 'Palette org’ as the conversion parameter default values.
e For an input TIM file with more than one palette (CLUT), there is a palette list in the Parameter Settings window to select the required palette(s). Set a default selection state for
this palette list using the 'Palette to use' option.
If 'First palette’ is selected, only palette 0 is used. If ‘All palettes' is selected, all the
palettes will be selected.
If the 'Link to Palette org' option (under 'Palette to use') is checked and 'First palette' is selected from the write palette list, the palette origin will be set to the Y coordinate of the
palette origin obtained from the input TIM file, plus 1.
e All parameters not described above are simply used as the initial values for each item in the
Parameter Settings window.
e The items set up in this dialog box are saved when the TIM utility is closed.
'TIM Arrangement...* Command ([Window] menu) The 'TIM Arrangement' window indicates graphically where the currently open TIM format
file(s) are located within the frame buffer.
163
HEE Graphics Tools
Sort Grid Zoom Resolution
FIRED1.TIM(texture) FIRED1.TIM(clut) SAND01.TIM(texture)
WOODY01.TIM(clut)
—Information
640 [$] vo [8 Width: 32 Height: 32
F:\PSX\DATA\TEXTURE\WOODY\WOODY01.TIM (8 bits texture)
Figure: the TIM Arrangement Dialog Box
The 'TIM Arrangement’ window is roughly divided up into the following four areas:
. A frame buffer image area . An information area
. A selection list area
° A menu bar
164
Graphics Tools MEM
Figure: The Frame Buffer Image Area
This area displays a graphical image of the PlayStation frame buffer.
In the figure above,
+
Green, red and blue rectangles on the right represent the images and palettes (CLUTs) of the TIM file that is currently open. These objects are located at the x and y coordinates where
they are stored in the frame buffer. The two white rectangles on the left represent the screen display areas.
The dotted lines represent the texture page boundaries. The texture page boundaries are the x and y coordinates where a texture page TIM file must start for the PlayStation hardware to display it correctly. The top and left sides of the rectangle should be aligned with these
boundaries.
A green rectangle indicates an image or palette rectangle that does not overlap with other
image or palette rectangles or the display region.
A red rectangle indicates an image or palette that is overlapping or extends beyond the
frame buffer.
165
HEE Graphics Tools
+ A blue rectangle indicates one which is selected by the mouse. Rectangles can be selected with the left mouse button and can be moved by dragging. Multiple image and palette rectangles can be selected by clicking the left mouse button while holding down the Shift key or the Ctrl key.
— Information
Xx: 640 [$ vo 18] Width: 32 Height: 32
FAPSXIDATAYTEXTUREYWOODY1WOODY01.TIM (8 bits texture)
Figure: Information Area
The Information window displays information relating to the currently selected image or palette such as the coordinates of the rectangle origin (top left corner), the size of the file, the filename
and bit depth. If more than one file is selected, no information is displayed in this window.
The coordinates of the origin can be modified by clicking the up arrow button or by directly
entering a numerical value in the text box.
FIREO1.TIM(texture) FIRE01.TIM(clut)
SAND01.TIM(texture) SANDO1.TIM(clut WOODY01.TIM(texture WOODY01.TIM(clut)
Fig: Selection List Area
The Selection List area shows a list of currently open images and palettes. This list can also be
used to select image and palette rectangles. The currently selected file (the light blue rectangle in
166
Graphics Tools Wimm
the frame buffer image area) will be highlighted. Click on a file on this list to change the selection (hold down the 'Shift' or 'Ctrl' key for multiple selection).
167
HEE Graphics Tools A al
TIM layout Sort Grid Zoom Resolution
Figure: Menu Bar
The ‘Sort’ Menu
'Textures' The upper left corner of each of the textures is aligned to the nearest texture region or display
region boundary. The textures can be arranged neatly by first using the mouse for approximate
placement and then using this menu command.
'Palettes' The palettes are all aligned vertically, starting at the bottom end of the current display region.
(This option works for NTSC but does not work for PAL where the display height is 256.)
The 'Grid' menu
"None’ Disables the grid function. Textures are arranged at the coordinates specified using the Mouse.
'Texture page" Textures are moved from the coordinates specified with the Mouse, and aligned in rows at the
nearest texture-page boundary. When 'XY' is selected, both X and Y coordinates are aligned to the texture-page boundary. When 'X' is selected, alignment is done only for the X coordinate, and
when 'Y' is selected, alignment is done only for the Y coordinate.
'Magnet' Textures are moved from the coordinates specified with the Mouse, and aligned with the edge of the
nearest texture area or display area. When 'XY' is selected, both X and Y coordinates are aligned {with the texture-page boundary). When 'X' is selected, alignment is done only for the X
coordinate, and when 'Y' is selected, alignment is done only for the Y coordinate.
168
Graphics Tools Wimm
The 'Zoom' Menu Sets the scaling factor for image display in the 'frame buffer image area'. This command can be used when
selecting and moving small textures and palettes that would be difficult to select under the standard zoom
factor.
The 'Resolution' Menu
Changes the display resolution used on the PlayStation's display. Changing this setting also changes the range of the display region.
Press the "OK" button to have the edited frame buffer image reflected in the Parameter Settings window. If
"Cancel" or "Close" is selected, the image and palette modifications will be cancelled.
Notes . The following file types cannot be opened for input: compressed format BMP, JPEG, compressed PICT, 32-bit PICT, and PICT files that do not contain at least one bitmap. . The following files cannot be output: compressed format BMP, JPEG, and compressed PICT files.
. The bit depth of output files is limited to 4, 8, 16 and 24 bits.
. Colors will be approximated when conversion is accompanied by a reduction in bit depth, e.g., when 16-bit data is converted to 8-bit data. The approximation will be performed by approximating the R, G, and B data to a uniformly assigned color map rather than using a method
such as color compression. Thus, color quality may decrease.
. As a rule, the input file cannot be overwritten. Overwriting is possible, however, when TIM format is used for both input and output formats, and if the image origin or the palette origin is
changed.
| timv.bat
timv is a TIM (image data) previewer. timv displays TIM data on a TV monitor using the PlayStation.
Usage
timv TIM_file
169
EEE Graphics Tools A al
Before starting this tool, ensure that the PC and Net Yaroze PlayStation are connected by the Net Yaroze communications cable, the Net Yaroze PlayStation boot disk is in the PlayStation, and the power is turned on.
When this command is executed, the TIM file supplied as the argument is transferred to the PlayStation. Then the TIM previewer (timview) is transferred to the PlayStation and the previewer starts. Use the
Controller to operate the previewer with the functions shown below.
Note that the TIM previewer (timview) only works when the baud rate is set to 9600 (the default baud
rate with no memory card in the right-hand slot).
Move Right
Move Up
Move Left Enlarge
Exit Program
Move Down Reduce
Figure: Controller Button Functions
170
15
Sound Tools
EEE Sound Tools E U |
The Net Yaroze sound tools consist of data converters and players. Data converters convert sound data (waveform and score data) created using commercial tools into the PlayStation format. Players permit sound data to be played back on the PlayStation through a TV monitor so it can be verified. The data
converters can also be used to create and edit waveform data.
The dedicated PlayStation sound data formats and their applications are listed below.
° SEQ data:Score data
. VAG data: Single waveform data
. VAB data: Sampled bank data
. VH data: Sampled data (attribute part) . VB data: Sampled data (waveform part)
The Net Yaroze sound tools all run from MS-DOS on the PC that is connected to the PlayStation. The
remainder of this chapter provides a description of these tools.
smf2seq.exe smf2seq takes Standard MIDI File (SMF) format-1 data created using commercial sequencer software (e.g.
a score creation editor), and converts it into PlayStation SEQ data.
aiff2vag.exe aiff2vag takes 16-bit straight PCM data or AIFF (Audio Interchange File Format) data created using
commercial waveform editing software, and converts it into PlayStation VAG data.
mkvab.exe mkvab takes PlayStation VAG data and attribute definition files, and generates PlayStation VAB data.
vabsplit.exe vabsplit splits a PlayStation VAB data file into a VH component and a VB component.
sndplay.bat sndplay plays back PlayStation SEQ data on the PlayStation using the standard waveform source found
on the Net Yaroze PlayStation boot disk.
172
Sound Tools mmm
vabplay.bat vabplay plays back PlayStation SEQ data on the PlayStation using a waveform source created on the PC.
| smf2seq.exe
smf2seq converts Standard MIDI File (SMF) format-1 data into PlayStation score data.
Usage
smf2seq [options] SMF-files
smf2seq creates a SEQ file (i.e. a PlayStation score data file) from an SMF file provided as an argument. More than one SMF file can be specified for batch conversion. The “.smf” file extension of the input SMF
file(s) can be omitted. The output filenames will be written with ‘.seq’ extensions.
Options
-Q
Conversion is performed in Quiet mode. No warning messages are displayed.
-V Conversion is performed in Verbose mode. A list of control changes and meta-events used in the SMF data
are displayed.
-B Forcibly deletes bank changes that were used in the SMF data.
Restrictions
The current version of smf2seq has the following restrictions. SMF format-0 is not supported. Files of 64 KB or more are not supported. The control changes listed below are supported. > Bank Select(#0)
> Data Entry(#6)
173
EEE Sound Tools E U j
> Main Volume(7) => Panpot(10)
> Expression(11) > NRPN(98, 99)
| aiff2vag.exe
aiff2vag converts Audio Interchange File Format data (AIFF), windows WAV Format data or 16-bit straight PCM data (without header(s)) into PlayStation waveform data files. All data must be either 16-
bit straight or monaural waveform data.
Usage
aiff2vag [options] aiff/WAV-files...
aiff2vag creates a PlayStation VAG file (*.VAG) from an AIFF, WAV format or 16-bit straight PCM format file. (The PlayStation’s VAG file is a compressed waveform data file.) More than one input file can
be specified for batch conversion. The “.aif” or ‘.wav’ file extension can be omitted. Options
-1
A waveform containing loops will be unconditionally encoded as a waveform without loops.
-L A waveform without loops will be unconditionally encoded as a waveform with loops.
-R fs Specifies the sampling rate for 16-bit straight PCM data input. fs is given in Hertz.
-E Endian conversion (byte ordering) will not be performed.
Restrictions
The current version of aiff2vag has the following restrictions.
174
Sound Tools mmm
Only 16-bit uncompressed data is supported. 4-bit, 8-bit and compressed format data are not
supported.
Only monophonic data is supported. Channels should be converted separately when converting
data from a stereo source.
| mkvab.exe
mkvab generates a VAB (PlayStation sampled bank) data file from an attribute definition file and one or more specified VAG (PlayStation format waveform) data files. mkvab can also analyze an existing VAB file to re-create the definition file originally used to create that VAB file. Note that VAG data must be created using aiff2vag.
Usage 1) mkvab -f def file -o vab_file vag files.....
Parses a user-created definition file (def file) and outputs a VAB file (vab_file) containing VAG files (vag_files) in the order they appear on the command line.
Example mkvab -f robl.def -o robl.vab boing.vag grunt.vag
will create vab file "rob1.vab" which consists of a vab header which is defined by "robl.def" and a vab body containing 2 vags - "boing.vag" and "grunt.vag".
2)mkvab -r vab_file [-o def _ file ]
Parses a VAB file and either prints the output to the screen (if output file option not entered) or outputs the VAB definition file to def file.
Options
-f def_file Specifies the definition file def_file used to create the attribute table(s).
-r vab_file Analyses a VAB file and outputs attribute definition files.
175
EEE Sound Tools
-o out_file Specifies the output file.
-o def file
Specifies the definition file to be output when also using the -r vab_file option.
Restrictions
The current version of mkvab has the following restrictions.
File size cannot be user-specified. The size of the VAB file and the size of each of the VAG files is
calculated automatically. Any specified value in the attribute definition file is ignored. ADSR linear mode is not supported; only exponential mode.
DOS allows a maximum number of 254 characters on a command line. Due to this limitation, the maximum number of VAGs which can be contained in a VAB created by mkvab, is 119. Use short
file names (no extensions necessary) for def file, vab_file, and vag_files to maximize VAG entry.
def_file Format
The def file is a text file containing four main sections (in sequence), as follows:
VabHdr One user-specified section per definition file. See table n below.
ProgAtr X One ProgAtr section for each specified program, where X=program number, ranging from 0 (1st program) - 127 (maximum program number). See table n below.
ToneAtr X Y One ToneAtr section for each specified tone contained in each specified program, where X=program number ranging from 0 (lst program) - 127 (maximum program number) and Y=tone number ranging from 0 (1st tone in program) -15 (maximum tone number in program). ToneAtr sections should be grouped consecutively based on program number, i.e. X=0 Y=0, X=0,
Y=1...,X=1 Y=0, X=1 Y=1...,X=last program used Y=last tone used in last
program used. See table n below.
vsize One vsize section which is automatically calculated by mkvab; it does not need to be input.
176
Sound Tools mmm
Input for each section of the definition file consists of a series of labels and related values in the format:
VabHdr label = value label = value ProgAtr 0
label = value label = value label = value
ProgAtr (num programs-1) label = value label = value label = value
ToneAtr0 0 label = value label = value label = value
ToneAtr 0 1 label = value label = value label = value
ToneAtr 10 label = value label = value label = value
ToneAtr (number programs-1, number tones in last program-1) label = value label = value label = value
177
EEE Sound Tools
Table: VabHdr Section of def file
Value Explanation VabHdr -no value- Master attributes of VAB. 'VABp' Format identifier
Format version number
VAB id (always 0)
File size (mkvab calculates this automatically.No input necessary). Total no. of programs in the VAB data Total no. of tones in the VAB data
Total no. of VAGs in the VAB data
Table: ProgAtr section def file (equivalent to instrument level)
Table: ToneAtr section def file
ToneAtr X Y -no value- Tone Attributes, where X= program number (0=1st, 127=max), Y= tone number (0=1st, 15=max)
0-127 Tone priority level - larger values have higher priority
178
Sound Tools mmm
shift 0-127 Center note fine tuning 0-127 Note limit minimum value. Must be <=max (see next entry) 0-127 Note limit maximum value. Must be >=min (see previous entry) 0-127 Maximum value for downwards pitchbend (in semitones) 0-127 Maximum value for upwards pitchbend (in semitones) 0-127 Attack rate (change rate after key-on until highest volume reached)
Decay rate (change rate from the highest volume to the sustain level) sr
-127-127 Sustain rate (change rate after the threshold level has been reached. to enter negative values, write the value followed by a minus sign)
Table: VSize section def file
vsize -no value- Sizes of VAGs in VAB file. Automatically calculated by mkvab and only output by usage 2 of mkvab. Input will be ignored.
filesize of vag 1. Automatically calculated.
filesize of vag 2. Automatically calculated. file size of last vag in VAB
*** To obtain a reverberation effect, the reverberation must be set using a separate sound function.
Supplementary Notes ADSR (envelope) rates, i.e. the rates for attack, decay, sustain and release, can be set individually. Linear or exponential function curves can be specified for the rate of change. The sustain level can also be
specified.
179
EEE Sound Tools
Attack . Decay. Sustain . Release
AR
Key on Key off
Figure: ADSR Concept Diagram
| vabsplit.exe
vabsplit splits sampled bank PlayStation VAB data previously created using mkvab into an attribute table part (VH) and a waveform data part (VB). VH data must be memory-resident during playback of
music, however, VB data need not be resident in memory once it has been transferred to the SPU.
Usage
vabsplit vab-files...
vabsplit splits PlayStation VAB data into a sampled bank attribute table part (VH) and a waveform data part (VB). More than one VAB file can be specified to perform batch conversions. The *.vab” file extension
can be omitted.
There are no options or restrictions associated with vabsplit.
180
Sound Tools mmm eC
| Sound Players
Running the Sound Players When the Net Yaroze system is installed, the batch files, 'seqplay.bat' and 'vabplay.bat', are placed in the ‘command’ directory of the PC, while sample sound files are placed in the ‘data’ directory. Included
among the sample files is 'samplel.seq', which is described in the example below. Follow the steps below to play back the sample file using the PlayStation’s sound player.
Turn on the PlayStation after making sure that the PC and the PlayStation are connected via the Communications cable and that the boot disk is mounted in the PlayStation. Type the following command from the 'data\sound' directory to load the standard waveform source files (STDO.VH and STDO.VB) from the boot disk and play back the sample SEQ file.
C:\> seqplay samplel.seq
You can play sound data using a waveform set other than the standard waveform source file by
transferring the data via the serial port with the following command.
C:\ > vabplay my.seq my.vh my.vb
Using the Sound Player If the program is running correctly, the PlayStation will play back music and output an image to the TV
monitor, similar to the one shown below.
181
EEE Sound Tools
STATUS : PLAYING
Use the Controller buttons shown in the diagram below to control the sound playback.
182
Sound Tools mmm
Reverberation Type Down Reverberation Type Up
Pan Right
Volume Up (With +œ Tempo Up)
Start Play
Exit Program
Volume Down (With+ Tempo Down) Stop Play
Waveform Data Specifications
Sampled waveform data can be used in the same way as MIDI waveform data. For more information, please check the Net Yaroze Web site.
183
16
Programming Tools
EEE Programming Tools
The Net Yaroze programming tools consist of the GNU C compiler and associated utilities. These are
shown in the table below.
Compiler Linker Debugger Librarian
Maintenance utility
Symbol information remover
Object Manager Assembler
Others
gec.exe ld.exe gdb.exe ar.exe make.exe
strip.exe
nm.exe as.exe, etc.
size.exe
This chapter describes only the most commonly used tools such as gce, Id, strip and make. For
information on the remaining tools, please refer to the documentation that accompanies the GNU C
compiler, or to related commercially available sources such as those mentioned in the Additional Reading
List at the end of the Start-Up Guide.
| The gcc Compiler
The gee compiler creates object and executable files from C source files.
Filename Extensions and Actions
gcc is actually a front-end processor which can call one or more tools used to link and compile the input
C source files. Which tools are called by gee depends on the extensions of the input files and the options
that are supplied on the command line. The table below shows a list of file extensions and what tools gec
will call when these file types are provided as input.
Note that files with filename extensions that the compiler cannot recognize are treated as object files.
These files are passed directly to the linker as arguments.
186
Programming Tools mmm
| Extension | Tools Called and Calling Order C preprocessor > C compiler > assembler — linker C compiler > assembler — linker
an Terme > men ae | EHE [ODE O
Table: Tool Calling Order
gce can also be used with various options to halt or control the execution flow during preprocessing,
linking, assembling or compiling.
The name of the object file or executable file that is output by gee depends on the compiler options you
have specified.
Usage
To execute gec, type the following command from the MS-DOS prompt. gcc [-option] <source files>...
[-option] Options are preceded by a *-* (hyphen) and multiple options are separated by spaces. Options are case
sensitive, so ‘-o’ and ‘-O’ have different meanings. The name of the source file is entered after the
option(s) and is preceded by a space.
The following sections give examples of some of the commonly used options.
Examples (using -c or -o options) . To compile a source file called 'test.c' and create an object file 'test.o', use the following command:
gcc -c test.c // Creates the object file ‘test.o’ from test.c.
187
EEE Programming Tools mm . To compile 'test.c' and create the executable file 'test', use the following command:
gcc -o test test.c