N64® Functions Menu

al - Audio Library Functions
gDP - DP GBI Macros
gdSP - General GBI Macros
gSP - SP GBI Macros
gt - Turbo Microcode RDP
gu - Graphics Utilities
Math - Math Functions
nuSys - NuSystem
os - N64 Operating System
sp - Sprite Library Functions
uh - Host to Target IO
64DD - N64 Disk Drive

Nintendo® Confidential

## gspS2DEX Microcode

The S2DEX microcode has been developed to use Super NES-like sprite and background (BG) functions on the Nintendo 64. Due to these functions, it is easier to create a game using sprites. Also, by treating drawing objects as sprites and BG, you can make your N64 programming similar to conventional sprite game programming.
The S2DEX microcode is designed specifically for processing 2D expressions. Therefore, 3D primitive drawing for Fast3D and F3DEX is not supported. However, the several primitives can be drawn using S2DEX Microcode. Please see the "S2DEX Microcode" section of your N64 Programming Manual for the details.
There are not many similarities between S2DEX and the older Sprite2D microcode. S2DEX is not an upgrade to Sprite2D; it is a brand new microcode. Also, sprite libraries such as spInit cannot be used in combination with S2DEX because sprite libraries use 3D microcode. The S2DEX library is completely different from the sprite library.
As already mentioned, S2DEX is not capable of drawing 3D primitives. However, S2DEX has a microcode self-loading function that is supported by F3DEX (release 1.20 or later). Therefore, it is possible for S2DEX to draw 3D primitives by loading F3DEX microcode. However, to use S2DEX to draw 3D primitives by loading F3DEX microcode, you must be have Release version 1.22 or later of the F3DEX microcode and Release version 2.0i or later of the N64 Operating System Library.

### DEBUG Information Output Function

There are two types of S2DEX microcode. One is installed for master ROM, and the other is for debugging. Please see the "S2DEX Microcode" section of your N64 Programming Manual for the details.

### Passing Commands from RSP to RDP

The S2DEX microcode supports only the fifo versions (as does the F3DEX series). However, a larger fifo buffer is required by S2DEX than is required by F3DEX. While this buffer had to be 0x300 bytes or larger for the F3DEX series, it has to be at least 0x800 bytes for S2DEX. Therefore, if you want the fifo buffer to be shared by the F3DEX series and S2DEX, it must be at least 0x800 bytes to fulfill the S2DEX requirements. The exact fifo size required varies depending on the microcode command. The minimum fifo size is 0x180 bytes for Fast3D.

### Compatibility with F3DEX

The GBI of S2DEX was derived from F3DEX, so there is no compatibility with the GBI of Fast3D. When you use S2DEX, you need to define F3DEX_GBI, as you do with F3DEX, before including ultra64.h.
Also, to use the GBI of S2DEX, you need to include the header file gs2dex.h (in the PR subdirectory). Insert the #include directive after the #include directive for ultra64.h.

### S2DEX GBI Compared to F3DEX GBI

Simply put, S2DEX does not support GBIs that deal with 3D primitives, 4x4 matrices, and light definition.
The following list refers to the gSP* and gDP* macros only, but the same applies to the gsSP* and gsDP* macros.

### GBI Macros Used by Both S2DEX and F3DEX

The following GBI macros are fully supported by both S2DEX and F3DEX:
DL Process Control

- gSPDisplayList(*)
- gSPBranchList
- gSPEndDisplayList

Setting Up Segment

- gSPSegment(*)

Loading Microcode

- gSPLoadUcode*

Scissoring

- gDPSetScissor
- gDPSetScissorFrac

Setting RDP Mode

- gSPSetOtherMode
- gDPSetCycleType
- gDPSetTexturePersp
- gDPSetTextureDetail
- gDPSetTextureLOD
- gDPSetTextureLUT
- gDPSetTextureFilter
- gDPSetTextureConvert
- gDPSetCombineKey
- gDPSetColorDither
- gDPSetAlphaDither
- gDPSetBlendMask
- gDPSetAlphaCompare
- gDPSetDepthSource
- gDPSetRenderMode
- gDPSetColorImage
- gDPSetDepthImage
- gDPSetTextureImage
- gDPSetCombineMode

Setting Color Values

- gDPSetEnvColor
- gDPSetBlendColor
- gDPSetFogColor
- gDPSetFillColor
- gDPSetPrimColor
- gDPSetPrimDepth
- gDPSetConvert
- gDPSetKeyR
- gDPSetKeyGB

Loading to TMEM

- gDPSetTileSize
- gDPLoadTile
- gDPSetTile
- gDPLoadTextureBlock*
- gDPLoadMultiBlock*
- gDPLoadTextureTile*
- gDPLoadMultiTile*
- gDPLoadTLUT_pal16
- gDPLoadTLUT_pal256

Primitives

- gDPFillRectangle
- gDPScisFillRectangle
- gSPTextureRectangle
- gSPScisTextureRectangle
- gsSPTextureRectangleFlip

Sync Processing

- gDPFullSync
- gDPTileSync
- gDPPipeSync
- gDPLoadSync

No-ops

- gSPNoOp
- gDPNoOp
- gDPNoOpTag

Note that for S2DEX, the number of segments when using gSPSegment is 16 and the number of DL links when using gSPDisplayList is 18 (the same as F3DEX).

### GBI Macros Not Supported in S2DEX

The following GBI macros are not supported in S2DEX:
Setting View

- gSPViewport
- gSPClipRatio
- gSPPerspNormalize

Matrix Operation

- gSPMatrix
- gSPPopMatrix
- gSPInsertMatrix
- gSPForceMatrix

Vertex Operation

- gSPVertex
- gSPModifyVertex

Conditional Branch

- gSPCullDisplayList
- gSPBranchLessZ*

Polygon Type Setting

- gSPSetGeometryMode
- gSPClearGeometryMode
- gSPTexture
- gSPTextureL

Primitives

- gSP1Triangle
- gSP2Triangles
- gSP1Quadrangle
- gSPLine3D
- gSPLineW3D

Lighting

- gSPNumLights
- gSPLight
- gSPLightColor
- gSPSetLights[0-7]
- gSPLookAt*
- gDPSetHilite1Tile
- gDPSetHilite2Tile

Fog

- gSPFogFactor
- gSPFogPosition

For Old Sprite2D Use

- gSPSprite2DBase
- gSPSprite2DScaleFlip
- gSPSprite2DDraw

### GBI Macros New with S2DEX

For detailed information on the following new macros and the data structures that they use, please see the "S2DEX Microcode" area of the N64 Programming Manual.
BG Drawing GBI Macros

- gSPBgRectCopy
- gSPBgRect1Cyc

Sprite Drawing GBI Macros

- gSPObjRectangle
- gSPObjRectangleR
- gSPObjSprite

2D Matrix Operation GBI Macros

- gSPObjMatrix
- gSPObjSubMatrix

Drawing Mode Setting GBI Macro

- gSPObjRenderMode

Load Texture Processing GBI Macro

- gSPObjLoadTxtr

Compound Commands GBI Macros

- gSPObjLoadTxRect
- gSPObjLoadTxRectR
- gSPObjLoadTxSprite

Conditional Branching GBI Macros

- gSPSetStatus
- gSPSelectDL
- gSPSelectBranchDL

For information about precautions that should be taken when using the macros listed above, please see the "S2DEX Microcode" section of the N64 Programming Manual.
New Emulation Functions
You can use the following functions to use the CPU to emulate S2DEX GBI macros.

- guS2DEmuGBgRect1Cyc
- guS2DEmuSetScissor

Other Important New Functions
Use the following function to initialize the S2DEX microcode's uObjBg structure (uObjBg_t)

- guS2DInitBg

### Debugging with S2DEX_D Microcode

There are two versions of S2DEX microcode; one version for debugging and another version for release. The relationship between the two microcodes is the same as the relationship between libultra_rom.a and libultra_d.a.
The debug version of the microcode (S2DEX_D) is slower than the release version, and it has the following additional features:

- It outputs the display list processing log.
- If bad input or undefined commands are encountered, it stops the RSP and reports the problem to the CPU.

Investigation of problems, such as finding the cause of a runaway RSP, will become easier by checking the display list processing log.
To use S2DEX_D, you must prepare an output buffer for the RSP display list processing log. The size must be the same as the display list, and must be 8-byte aligned. Once the area is reserved, provide the pointer data of the first address of the area to data_size, which is a member variable of the OSTask structure. This member variable is a remnant of the N64 Operating System Library version 1.0, it is used as a log output buffer. This address must not be the Segment address. When gspS2DEX.fifo_d.o activates as microcode, it is stored in the address specified by the process log. For details concerning the processing log’s display methods, please refer to the function ucDebugGfxLogPrint in the sample program uc_assert.c. Also, for details concerning the decision making process for stopping the RSP, please refer to ucCheckAssert in the same file.
Note that the OSTask structure’s member variable yield_data_size was used to set the log buffer in S2DEX 0.75, but this was switched to data_size in S2DEX 0.76 and later. Please note that the display function ucDebugGfxLogPrint has also been corrected.

### Installation

For information on how to install S2DEX microcode, please see the "S2DEX Microcode" section of the N64 Programming Manual.

Nintendo® Confidential Warning: all information in this document is confidential and covered by a non-disclosure agreement. You are responsible for keeping this information confidential and protected. Nintendo will vigorously enforce this responsibility.
Copyright © 1998
Nintendo of America Inc. All rights reserved
Nintendo and N64 are registered trademarks of Nintendo
Last updated March 1998