Type definitions

Home » N64 Homebrew » N64 SDK » Type definitions

There are many different type definitions used in N64 programming that you need to know in order to work your way through the code. This page will be modified as time goes on, so please contact me if you want something included.

In the C programming language that the Nintendo 64 uses, there are various types of variables. You have the int (integer), float, char and so on. However the N64 uses many custom types in order to work properly and aren’t easy to understand without having their reference. This page will show a list of the various typedefs that can be used for N64 homebrew applications.

Most of these are defined in the file gbi.h, which if you installed the SDK in your root as noted in the development environment page, should be located at C:\ultra\usr\include\PR\gbi.h.

Mtx: 4×4 Matrix

File: gbi.h
Rows: 1135-1140

Used for defining 4×4 matrices.

typedef long Mtx_t[4][4];
typedef union {
    Mtx_t		m;
    long long int	force_structure_alignment;
} Mtx;

The values for the matrix are held in Mtx.m (which is the Mtx_t type defined earlier), the long long int is there just to make sure that it fills the right length.

Gfx: Graphics display list

File: gbi.h
Rows: 1484-1698

This is quite a complicated so I’ll split it into sections and fill it out as the need rises. The Gfx type is used to hold display lists of many types.

General definition

typedef union {
	Gwords		words;
	Gdma		dma;
	Gtri		tri;
	Gline3D		line;
	Gpopmtx		popmtx;
	Gsegment	segment;
	GsetothermodeH	setothermodeH;
	GsetothermodeL	setothermodeL;
	Gtexture	texture;
	Gperspnorm	perspnorm;
	Gsetimg		setimg;
	Gsetcombine	setcombine;
	Gsetcolor	setcolor;
	Gfillrect	fillrect;
	Gsettile	settile;
	Gloadtile	loadtile;
	Gsettilesize	settilesize;
	Gloadtlut	loadtlut;
        long long int	force_structure_alignment;
} Gfx;

This section brings all of the Gfx types into one, allowing it to represent any of the included types. Below we’ll be looking at each one individually.

Gwords

Gdma

Gtri

Gline3D

Gpopmtx

Gsegment

GsetothermodeH

GsetothermodeL

Gtexture

Gperspnorm

Gsetimg

Gsetcombine

Gsetcolor

Gfillrect

Gsettile

Gloadtile

Gsettilesize

Gloadtlut

NUContData

File: nusys.h
Rows: 515-521
NUContData is a data type that uses NuSystem to get the data from the controller.

typedef struct st_ContData {
    u16	button;
    s8	stick_x;	
    s8	stick_y;
    u8	errno;
    u16	trigger;
} NUContData;

Here are what they mean:

• button is the data for each of the physical buttons, A, B, C, Z, L, R, START and D-PAD.
• stick_x is the left to right value of the joystick
• stick_y is the down to up value of the joystick
• errno is the error number
• trigger displays any triggers. Active on button press, not button hold.

Vtx: Vertices

File: gbi.h
Rows: 1066-1093

Vertices are the corners of any 3D model, and the ones on the Nintendo 64 are encoded using these type definitions. The Vtx type defines a vector or more commonly, an array of vectors. The first typedef (Vtx_t) is for vertices where the color is defined, and the 2nd is for vectors where the normal is defined.

typedef struct {
	short		ob[3];	/* x, y, z coordinates*/
	unsigned short	flag;
	short		tc[2];	/* texture coordinates */
	unsigned char	cn[4];	/* 3 color & alpha */
} Vtx_t;

typedef struct {
	short		ob[3];	/* x, y, z coordinates */
	unsigned short	flag;
	short		tc[2];	/* texture coordinates */
	signed char	n[3];	/* normal */
	unsigned char   a;      /* alpha  */
} Vtx_tn;

typedef union {
    Vtx_t		v;  /* Use this one for colors  */
    Vtx_tn              n;  /* Use this one for normals */
    long long int	force_structure_alignment;
} Vtx;

VP: Viewport

File: gbi.h
Rows: 1176-1185

The viewport is the ‘window’ by which the player sees the 3D world in the game. The Vp typedef calls in Vp_t so they are essentially one in the same.

typedef struct {
	short	vscale[4];  /* scale, 2 bits fraction */
	short	vtrans[4];  /* translate, 2 bits fraction */
} Vp_t;

typedef union {
    Vp_t		vp;
    long long int	force_structure_alignment;
} Vp;

vscale (the scale factor) and vtrans (the move factor) are the screen coordinates, each with four variables within it: x, y, z and alignment.

From my experiments (might seem obvious), it seems as though vscale determines the size of the viewport while vtrans is the position. If vscale is set to 0, the image will be so small it will appear invisible, and if vtrans is set to 0 then the viewport will align to the top-left corner of the screen.

From my tests, the best thing to do here is to set both vscale and vtrans to SCREEN_WD*2, SCREEN_HT*2, G_MAXZ/2, 0 as shown below; but generally speaking it’s best to work on it in terms of SCREEN_WD, SCREEN_HT and G_MAXZ (maximum z-buffer). The width and height values are usually set to 320×240

static Vp vp = {
    SCREEN_WD*2, SCREEN_HT*2, G_MAXZ/2, 0,	/* Size of the viewport, this is fullscreen  */
    SCREEN_WD*2, SCREEN_HT*2, G_MAXZ/2, 0,	/* Position, this makes the screen centre on the middle  */
};