jA''m\ J>" I ( \, DRAFT Nintendo 64 programming Manual NU6-06-0030-001G of October 21, 1996 NU64 PROGRAMMING MANUAL DRAFT NINTENDO D.C.N. NU6-06-0030-001 REV G ""*' : ,;j:fConfid |ltia{|i?;% This documellcpntafns coriftfe. ntia! and proprietary infBfmation of Ninfpndo and is also protected under the copyright laws of th%United States an:d'l#lfgn countries. of this document may be released, No.ftt : dJfVibitted, transmitted or reproduced in Jlly fornflor by any electronic or fftechanill, means, including information storage anii; retrieval systems, without permission fijwiting from Nintendo. 1995, -1996 Nintendo Contents List of Figures xvii List of Tables xxi $+>.. PARTI Getting Started w ^li):,. 1. Hardware and Software Installation Notes 27 Hardware In^a^tion 28 tallailn Software ifis' . ,30 ? h REaB|^IEs and Release Notes 30 Other Sources 30 ||| Executables • 3,1 : 2. Troubleshooting Software Bringup 33 liDperattng System 33 4|f graphics 34 Audio 36 Integ¥||ion 37 Debugging CPU Faults 37 NU6-06-0030-001G of October 21, 1996 % Contents. PART II Ultra 64 System Overview 3. Hardware Architecture 41 : Execution Overview 42 $0 l - ^:^ RCP: Reality Coprocessor 4§> flatifc, : RSP: Reality Signal Process o:fe|4v4. ^' ;ff RDP: Reality Display Processor***! r R4300CPU 46 ^ '%fg# Issues 47 ; Memory ; 1IS; ; , Clock Speeds and Bui8ahc% idth 48 ' Development Hardware 48 4. Runtime Software Architecture 51 Resource Access an^Management 52 CPUAccesjj 54 ^0%,, Messagiilassifif Pnoritp5cheduled Threads 54 CPU Data Cache 54 v ; M .0jo Default Memory ; lManagement 55 <:;'; : Timers 55 :# V%able TLB Page Sizes 55 MlP&Coprocesser Access 56 PI Manager 56 v * Manipr 57 m . ! ;:f;; Memory Management 58 jm^BM:;;^ No Default Dynamic Memory Allocation 58 . 'f 58 , Jff | ;Region Libra ry Jfivlemory Buffer Placement 58 Alignment 58 _ Memory : 0pgff-? ^ RCP Access and Management 60 Graphics Interface 61 ''M$sh,. Graphics Binary Interface 61 GBI Geometry and Attribute Hierarchy 61 GBI Feature Set 62 RSP Geometry Microcode 63 Contents: Audio Interface 64 '%&->:•,,> RCP Task Management 65 The "Simple" Example 65 GameShop Debugger 67 Workshop Debugger Heritage 67J|; : g;|||& DebuggerComponents 6%; fe 5. Compile Time Overview 69 Database Modeling 7%:> NinGen 70 •' Alias 71 Other Modeling Tools 71 Custom Modeling Tools 71 Model to TenderSpace Database Conversion 72 Custom Convertors ;||> Conversion Considerations 72 CSamrna Correction 74 sgMufic Composition 75 :;->' Wav^table Construction 76 Build!%ROM Images 77 C Compiler Suite 77 ROMMage Packer 77 Headers and Libraries 78 Host Side Functionality 79 NU6-06-0030-001 G of October 21 , 1996 til Contents PART III Ultra 64 Operating System 6. Operating System Overview 83 Overview 83 ;,^,>, Threads 84 JP'^ll Messages 84 ||| M^'^^h Events 85 ^0§' || Memory Management 85 : > M : =' '•<-••<•>•>;& Input and Output 8fe,.. Timers 87 Controller Pack File S§%tem'*S^., Debugging Support 87 Boot Procedure, 87 7. Operating System Functionality 89 Overview 89 $§*"" System Threads, Application Threads, and the Idle Thread 90 Thread Data Structure ' 90 State . Thread 90 Scheduling and Preemption 91 ,; |Jv ; r ' j|s|f Thread Functions 92 Excef§t£>ns and Interrupts 93 Events : 'c$4 Event and Interrupt Functions 96 ^w^ Non-Maskable Interrupts and PRENMI 96 ' : -Ilk -0V " 'W%Internal OS Functions 98 IV 6 Contents 8, Inputy Output Functionality 101 Overview 101 M Design Approach 103 Synchronous I/O vs. AsynqhiSh&s I/O 104 Mutual Exclusion 105 ;||: I/O Components 105 lg ;^|Jf : System Exception Handler 106::::;;:;;. .@ Device Manager .406 '"'W0§p''''' Device-Dependent pj^tfm Interface 108 9. Basic Memory Management 113 Introduction 113 Hardware Overview 113 CPU^P'drels|ig^ 114 :: MixirJ| CPU|fhd SF Ad dresses 1 1 Flusrul§ the CPU Da|| Cache 118 Clearing uniraj;||Ji^lclata (Bss) section 119 Sfy Physical Memory Allocation 119 : 10. Advanced Memory Management 121 Introduction 121 Mi%g CPU and SP Data 121 Usm||,©verlays 122 : Using Multiple Waves 124 Using the Region Allocation Routines 125 *f'" '-Ifo Managing the Translation Lookaside Buffer 126 NU6-06-0030-001G of October 21, 1996 Contents PART IV Ultra 64 Graphics '"%.*,.,;? "It 11. Graphics Microcode 131 ^m^Mf MicrocodeFunctionality 132 .,^»Jl3. gspFast3D 132 Jr ^'"ll gspF3DNoN 132 f ^%?, fjjjj. JP~ gspLine3D 132 ffr gsp Turbo 3D 132 fp_ ^||#' gspSprite2D 133 -||, . ~«ig:«^ : gsp Sup er 3D 133 RSP to RDP command pasting 4t»4^., "^ 12. RSP Graphics Programming 135 RSP Overview^||" ;; Display ||st Forrr$at,<,^ 137 Segmented Mei|:pfy"an^!>the RSP Memory Map 138 Interaction1'Between the mP and R4300 Memory Caching 139 '' Display List Processmg,.C;:J|f J:£&nnecting Display Lists 141 Branching Display Lists 142 Ending Display Lists 142 A Few|Words about Optimal Display Lists 142 Matrix State 144 Insert a Matrix 145 y a Matrix 145 A$ .f*wm>-- P°P '"'W; ljl|, MA"' i||Perspective Normalization 145 ^|;fl 'Mote on Coordinate Systems and Big Numbers 146 Few Words About Matrix Precision 147 , J§A : Vertex State 149 Texture State 150 Clipping and Culling 152 vt " Contents Vertex Lighting State 156 RSP Microcode 156 Normal Vector Normalizatiori .157 Ambient and Directional |£ghtmj|5;- 157 Specular Highlights 161 ;M-'- ::::i --' '" Reflection Mapping 165 !i 'i0$0 Vertex Fog State 169 Primitives 171 Controlling the RDP S|p||474 13. RDP Programming 175 RDP Pipeline Blocks 176 One-Cycle~per-Pixei Mode 177 Twof«£ycles^pfi el : |-i'ix Mode 178 : Fill'H|de ipO" Copy Mode 180 RDP Global Sta^|||j|F Cycle Type 181 Synchronization 181 ,|pan Buffer Coherency 182 RS: Rasterizer 184 Scissfiing 184 TX: Texture Engine 186 Texture Tiles 186 : ir^ „|%| Multiple Tile Textures 187 Texture image Types and Format 188 Texture Loading 188 Color-Indexed Textures 190 Texture-Sampling Modes 191 Synchronization 192 TF: Texture Filter 193 Filter Types 193 Color Space Conversion 194 NU6-06-0030-001G of October 21, 1996 vii Contents CC: Color Combiner 195 Color and Alpha Combiner Inputs Sources tfP CC Internal Color Registers 197 One-Cycle Mode 198 JP^Sk Two-Cycle Mode 200 |f Custom Modes 200 l&^afft 1ft Chroma Key 201 r BL: Blender 203 ^ ^§# Surface Types 203 J Antialiasing Modes ,|Q4 BL Internal Color Registers 2(B \i Alpha Compare 205 Using Fqgf;v>t0i;| .. : Depth Spree 2f|S||a^ L MI: MemoryTrjterfac'e 210' '||| Image Location and Forjiat 210 Jjfl Color 211 4|pP" .,:^|Sipiering 211 14. ; Texture Mapping 213 Graphics ^Binary Interface for Texture 216 Primitive Commands 216 %, Tile Related Commands 216 r Load Commands 216 s ., S ync C omm an d 216 :f| ; ^Iptlode Commands 216 :if' Ex|piple Display List 218 . Texture Image Space 219 VIII Contents Tile Attributes 221 Format 221 Size 221 Line 222 Tmem Address 222 Palette 222 Mirror Enable S,T 222 MaskS/T 223 ^ '"^11 Shift S/T 223 "Ilia,... r SL,TL 224 J ''^lllfe,^ SH,TH 224 Clamp S,T 224 Tile Descr4pt6?;|;c)ading 225 Texture-ili ip eline||;2||lR ;j: : ,,_ Tile Selection 228 Functionality 228 ,#' LOD Disableli?228' #i |r || LOD Enabled 229 %1IP Mapping 232 l||gnification 233 Textur&Memory 239 Memory Organization 239 Texel Formatting 247 Texture Loading 248 Ijxamples 255 .Restrictions 259 If Texture Types and Modes 259 Alignment 259 - Tiles 260 Coordinate Range 260 Applications 261 Multiple Tile Effects 261 Appendix A: LoadBlock Line Limits 264 NU6-06-0030-001 G of October 21 , 1 996 ix ! Contents 15. Texture Rectangles (Hardware Sprites) 269 Sampling Overview- 271 Simple Texture Effects 279 Texture Types 288 Multi-Tile Effects 292 f||| Tiling Large Images 297 'W^^My' Color Index Frame Buffer 298 Z-Bufferrng Texture Rectangles 299 "%#h* 16. Antialiasing and Blending :;|Q1 Antialiasing 302 ' Coverage Unit 306 Stepper 30$ :, Z t w&< Blender 310^~''"-% Color BJlnd Ha|pvlr|§|310 Fog 3lff Coverage Calculation.J;314 .Ki^Alpha Compare Calculation 315 : , • Blender ADD Mode 317 Cdlpr Image Format 318 Ima'lppAlignment Requirements 320 Z Calcl|a|ion 320 ,. Z Image format 322 Z Accuracy 325 iipSftfcieo Filter 326 Contenis ' ;; :?? Blender Modes and Assumptions 327 ' t||f^|l Opaque Surface Antialiased Z-Buffer Algorithm, -QP^SURF 327 Transparent Surfaces, XLU_Sl^E 329 Transparent Lines, XLU_L|p'" "3%J _ Texture Edge Mode, TEX|||?GE j|32 Decal Surfaces, OPA_DECAL, XLU_.DECAl| 333 Decal Lines, DEC_LINE 334 '%^.^;0 Interpenetration, fjAJNTER, Xl85#ItER 335 Particle System Mode, PCL_SURf 336 Blender Modes Trim Table . 337 Creating New Blender Modes : I|l5 Visualizjj#g;Coverage 346 17. Sprites Jp9 ll^.^ AppHca§i|n. Progpm Irft^fiface (API) 351 Making Sprites 35WS M Manipulating. Spiitp r 351 .MMy Drawing Sprites 353 £$$v "D^a Structures and Attributes 354 Bitmap Structure 354 Sprite Structure 354 Attributes 355 Tricks and Techniques 358 Sparse Sprites 358 ,. , : st:e|iis&.. ^"''^ll Early-Ending Sprites 358 H Variable Size Bitmaps 358 Exp 1 o s i ons 358 *-<t&a®~ Bitmap Re-use 358 Sprite Re-use 359 Examples 360 ; Backgrounds 360 Text (Fonts) 360 Simple Game 360 NU6-06-0030-001G of October 21, 1996 xi Contents 18. Sprite Microcode 361 Sprite Microcode Functionality 362 Sprite Microcode API 363 PART V Ultra 64 Audio ll^lt^ •' 19. The Audio Library 369 '^S/ . Generating Audio Output 372 S ampledSoundPlayb ackfj| \ 373 Representing Sound 373 373? % Play ing Sounds " %<k. Sequenced Sound Playback 376 Representrng.the Sequence 376 Representing instruments 377 Playing^equene^^ : 'B^^ Loops mWquence PlayelS 380 Controllers in Sequence Players 381 ThejSynthesis Driver' ''3§2 Jp ; Initializing the Driver 382 Building and Executing Command Lists 383 S\TitKfesis Driver Sound Data Callbacks 383 Assigning. Players to the Driver 384 jpM Allocating and Controlling Voices 384 : M Effects and Effect Busses 385 . Creating Your Own Effects 386 '"' :tt-vj§ ! Itarameter Description 388 "'*/• jpurnrnary of Driver Functions 393 -iMtfritrng Your Own Player 394 Initializing the Player 394 Implementing a Voice Handler 395 :: :::: : ;: g||.