niff2gfx Converter


Operation of niff2gfx
Features
Command Line Execution
Options
Indirect Filename Specifications
Output Specifications
GBI Output Specification
Limitations
Specification of CC Setting When mat_type Is MAT_TYPE_NIFF
Programming Cautions
Revision History

Operation of niff2gfx

Features

This converter converts NIFF data formatted source files to GBI display-list formatted C source files. It has the following features:


Command Line Execution

When niff2gfx -h is executed from the command line, the following is displayed.


NIFF to N64 GBI format convertor. version 1.3.6
supported format revisions: NIFF 1.0
usage: niff2gfx [option] infile outfile
  infile  ... NIFF format file.
  outfile ... N64 Displaylist C source file.
option:
  -q               quiet mode.
  -verbose         verbose mode.
  -header fname, -d fname
                   set output header filename.
  -label str       set label string.(label string = str)
  -scale fval      set convert scale.(scale = (float)fval)
  -niffinfo fname  NIFF information onto file fname.
  -nocomdef        common define,typedef block no output.
  -regmask val     prevent RDP register assignment.
  -vtxshare val    vertex share on set minimum match length.
  -vtxcache val    vertex cache size(default 32).
  -vtxload val     vertex cache load limit(default 32).
  -strictflat      flat normal output to 3 vertices at all times.
  -noalignpad      prevent alignment of 8-byte order no padding.
  -outobj name     output object by name.(default: all objects)
  -outmask val     prevent output dataclass assignment.
  -nogeomclr       geometry mode no clear.
  -preview val     preview type value.(default: 0x1c)
  -binary, -b      output gfx in binary file.
  -rotorder val    default rotation order.(default: 0x010203)
  -vtxseg val      Vtx segment number.(default: 5)
  -imgseg val      image data segment number.(default: 6)
  -tlutseg val     TLUT data segment number.(default: 7)
  -nomodify        disable modify vertex.
  -strictcidx      CIDX pixel/bits follow 'tex_type'.
  -noreduct        CIDX no color reduction.
  -nullanim        output null animation data.
  -?, -h           help
  @fname           indirect option file.


Options

-header fname, -d fname     set output header filename
This switch outputs definition parts of code such as #define and typedef as a separate header file. Following -header, above, please specify a file name to hold the header to be output.

-label str     set label string. (label string = str)
The converter outputs all objects in the file that is given as the input. These objects are output as a table that becomes an interface to the game machine. The table is also used for the scale value, object total and other define macro names specified at the same time. That base label name is given.

-scale fval     set convert scale. (svale = (float)fval)
This specifies the scale value at conversion time. In N64, the vertex value is described in the Vtx table as a signed 16-bit integer. So depending on the original model data, rounding off can destroy the original form. In this case, please specify the option. The default is set at 20x.

Also, because niffdraw.c performs reverse scaling based on the scale value output to the header, use of the N64 Previewer (or other accessory viewer software) does not affect the scale of the displayed shape.

-niffinfo fname     NIFF information on to file fname
This outputs information when a NIFF file is read. Specify a hyphen ('-') as the filename to write to standard output.

-nocomdef     common define,typedef block no output
The converter outputs a lot of header information at the front of the output file (or to the output header file specified with the -header option), but common information unrelated to the model data is suppressed. This is convenient when using numerous conversion files in a single compiler environment.

-regmask val     prevent RDP register assignment
This suppresses output of the RDP register settings in the display list to be output. A 6-bit integer is assigned to the parameter val. Each bit has the following function:

-vtxshare val   vertex share on set minimum match length
This specifies a minimum for sharing a vertex buffer. In order to boost the vertex calculation performance in the RCP at conversion time, niff2gfx makes as much of a consecutive transfer of the vertex buffer as possible. As a result, the same vertex information is output many times to the vertex table. At this time, vertex buffers that have already been output are viewed to evaluate whether a continuous part can be shared. For example, say 10 vertices are to be output as a vertex table. Normally 10 Vtx are simply output, but when -vtxshare 5 is set if, previously, there was a continuous part of 5 of these 10 vertices, then a past vertex buffer is used to issue the vertex transfer instruction (gsSPVertex). Note that at this time the number of vertex transfer instructions increases to 2.

-vtxcache val     vertex cache size(default 32)
This changes the microcode vertex cache. With gspF3DEX the vertex cache size is 32. But it increases to 64 with gspF3DLX.Rej, and 80 with gspF3DLP. When these other microcodes are used, please use this option to increase the vertex cache size for conversions. The default size is 32.

-vtxload val     vertex cache load limit(default 32)
This specifies the number of vertices that can be transferred, at once, with gsSPVertex. This was done for compatibility with gsFast3D. Please do not use this option, because in the present version of the converter the gSPModifyVertex instruction cannot be suppressed.

-strictflat    flat normal output to 3 vertices always
Usually the converter outputs 1 vertex with face normal, and outputs the other 2 vertices with just the normal for the vertex. According to the microcode specifications during flat shading, only one of the three vertices needs to express the normal, but for automatic creation of ST values for reflection mapping, all three vertices need to be normal. Thus, it is necessary to set normal to three vertices only when reflection mapping with flat shading. This option affects these settings.

-noalignpad     prevent 8-byte alignment (no padding)
The converter normally inserts u64 size dummy words in order to maintain 64bit alignment when data is output. This option suppresses dummy word output.

-outobj name     output object(s) by name
By default all objects are output by name, so you can use this option when you want to output only a specific object by name. You can also use this option to specify multiple objects to be output by name.

-outmask val     prevent output dataclass assignment
This restricts the types of data that are output. An 8-bit integer is assigned to the parameter val. Each bit is mapped as follows: When each bit is 1, output of that bit's data class is prohibited. If bit4 is 1, then bit5 and bit6 are also always 1.

-nogeomclr     geometry mode no clear
The converter makes Gfx in Shape units, but the default always has gSPClearGeoMode(-1) in the beginning, so the geometry mode is initialized. This option prevents output of this initialization code.

-binary, -b    output gfx in binary file
By default, the converter outputs a C source file for the file specified by "outfile." When this option (-binary) is specified, a binary file for Quick Preview is output.

-preview val     preview val type (default: 0)
This option was previously used to change the view of the Previewer. However, with the introduction of version 1.30, this option is meaningless - since the Previewer no longer references this value.

-rotorder val     set the default rotation order
In NIFF, when there is no animation link, no decision is made about the order of animation. The result is that rotation order can change for every object, and major restrictions are placed on application programming. This option can be used to set the rotation order for objects that do not hold animation. The original default is 0x010203.

-vtxseg val    Vtx segment number. (default: 5)
This specifies the segment number of the vertex buffer referenced by the output Gfx. The default is 5.

-imgseg val    Image data segment number. (default: 6)
This specifies the segment number of the texture image referenced by the output Gfx. The default value is 6.

-tlutseg val    TLUT data segment number. (default: 7)
This specifies the segment number of the texture LUT that is referenced by the output Gfx. The default value is 7.

-nomodify    disable modify vertex.
Prevents gsSPModifyVertex from reusing the vertex buffer. This must be specified when deform is enabled.

-strictcidx    CIDX pixel/bits follow 'tex_type'.
When converting, if the image specified as an 8-bit color index texture is less than 16 colors, optimization is usually attempted as a 4-bit texture. However, by specifying this option, the optimization is prohibited and the texture pattern is output by the bit width specified by NIFF.

-noreduct     CIDX no color reduction.

-nullanim     output null animation data.
If there is no effective animation data in the object, NULL is output to the Animation List. Links to the animation will be created by referring the NULL from the object. nullanim can be used when the animation data is taken from different files. However, it can not be used from the nd since it does not support the Animation List NULL.

@fname     indirect option file
fname is taken to be an indirect filename and interpreted as something described by a command line parameter. For details concerning indirect filenames, please see the "Indirect Filename Specifications" section below.

-?, -h     help
This outputs simple explanations that describe command line settings and options


Indirect Filename Specifications

Example 1
command line:
  % niff2gfx @ind cube.niff mdl_a.c

"ind" file:
  -header a.h -strictflat

converter parsing...:
  % niff2gfx -header a.h -strictflat cube.niff mdl_a.c

Example 2
command line:
  % niff2gfx @ind

"ind" file:
  # option
  -header model.h
  -regmask 0x5		# no CycleMode & CC mode
  # input file
  cube.niff
  # output file
  model.c

converter parsing...:
  % niff2gfx -header model.h -regmask 0x5 cube.niff model.c

Example 3
command line:
  % niff2gfx @opt @file

"opt" file:
  # option
  -header model.h
  -regmask 0x5		# no CycleMode & CC mode

"file" file:
  cube.niff model.c

converter parsing...:
  Same as in Example 2


Output Specifications

GBI Output Specification

The GBI output from one NIFF file creates Vtx and Gfx by a unit of Shape. The texture image and TLUT are placed in a single buffer so that they can be used and shared by all Shapes.

The texture read-in code is created based on the NIFF TextDataArea and the ST value of the attachable face of the texture. Because StData is dependent on the tile information used by N64, at conversion time ST values are scaled and Vtx buffers created in accordance to the size of the texture being applied.

Because there are scenes where Tri and Prim colors are both present, Tri colors are set using the Environment Color Register. Both PrimColReg and EnvColReg can change the color value, irrespective of the material specification for their use.

The texture image supports a total of 9 types: RGBA 32-bit, RGBA 16-bit, index color 8-bit, index color 4-bit, and 1A (16-bit, 8-bit, and 4-bit), and I (8-bit and 4-bit).

To implement a hierarchical object, the object's transform matrix information and link information are stored using a unique data structure called 'nd' along with constant value-based independent data structures. To get all this done, the machine-use codes ndman.c and nddisp.c are necessary.

The Anm node is used for the object structure's transform data only in the case of ANM_TYPE_STATIC. When the transform's rotation information is output by the converter, a Radian to Degree conversion is performed and output to pass the radian value from NIFF.

The low-order 8 bits of the Obj area's obj_pri are evaluated and stored in the priority register of the object structure. Color reduction is automatically performed when the Tex area texture type is CI and the number of colors used by the image exceeds 256 for an 8-bit color index texture, or 16 for a 4-bit color index texture.

First, the colors used by the image are reduced to 16-bits (RGBA5551). The colors are then sorted in order from the most-used. either the first 256 colors are set in the palette for an 8-bit CI texture or the first 16 colors are set in the palette for a 4-bit CI texture. Since alpha is effective for only 1 bit, it is transparent when the original data is 0, and opaque when the original data is a value other than 0.

If there is no match for a color in the palette, the sum of the difference of squares is calculated for each RGB component and the smallest is selected.

If -noreduct is specified and there are too many colors, the conversion is aborted.


Limitations


Specification of CC setting when mat_type is MAT_TYPE_NIFF

Resource Usage Rules

The converter analyzes NIFF data and uses a number of RDP registers.

The RDP register's Primitive Color register is allocated to PrimColor, while the Environment Color register is allocated to TriColor, and color changes are assigned to the registers.

Determining Color Combiner Mode

The color combiner mode is determined based on the MAT_SHADE_LIGHT* of mat_shade_type and the following bits of mat_color_type0:

	MAT_CC_NIFF_VTX        = 0x00000001
	MAT_CC_NIFF_TRI        = 0x00000002
	MAT_CC_NIFF_PRIM       = 0x00000004
	MAT_CC_NIFF_TEX0       = 0x00000008
	MAT_CC_NIFF_TEX1       = 0x00000010
	MAT_CC_NIFF_TRI_ALPHA  = 0x00020000
	MAT_CC_NIFF_PRIM_ALPHA = 0x00040000
	MAT_CC_NIFF_TEX0_ALPHA = 0x00080000

The following bits are not referenced:

	MAT_CC_NIFF_VTX_ALPHA  = 0x00010000
	MAT_CC_NIFF_TEX1_ALPHA = 0x00100000

Each bit is assigned separately, so there are a variety of modes. These are determined in the following way:

First of all, the color combiner expression is evaluated with the following formula:

		(Wch - Xch) * Ych + Zch
Wch, Xch, Ych, and Zch are virtual color channels, and they are determined by different bits in mat_color_type0.

Ych is determined by MAT_CC_NIFF_VTX, _TEX0_ALPHA, _PRIM_ALPHA, _TRI_ALPHA, and _VTX_ALPHA.

VTX_A TRI_A PRIM_A TEX0_A VTX
Ych
0
0
0
0
0
Shade color
0
0
0
0
1
Vertex color
0
0
0
1
*
Texel0 alpha
0
0
1
*
*
Primitive alpha
0
1
*
*
*
Env alpha
1
*
*
*
0
Shade alpha
1
*
*
*
1
Vertex alpha

In the above table an asterisk (*) refers to an undefined value. In short, _VTX_ALPHA, _TRI_ALPHA, _PRIM_ALPHA, _TEX0_ALPHA, and _VTX are evaluated in order to set one of the above-mentioned modes.

Shade color expresses the color value inferred from calculating SP from the lighting setting and the model's shade.

When G_LIGHTING is set to off in the GeometryMode settings, Vertex color is extracted from the color value used by the normal of the Vtx structure.

Note: When Ych is Shade Color, and when both LOCAL and GLOBAL are 0 (no lighting) in the MAT_SHADE_LIGHT_* settings of mat_shade_type, then the color combiner expression is changed to the following:

		(1.0 - Xch) * Wch + Zch
Also note that this special rule does not apply for the second cycle in 2 cycle mode.

Wch, Xch, and Zch are determined from MAT_CC_NIFF_TRI/_PRIM/_TEX0/_TEX1.

TRI T1/PRIM TEX0
Wch
Xch
Zch
0
0
0
1.0
0.0
0.0
0
0
1
Tex0
0.0
0.0
0
1
0
T1/Prim
0.0
0.0
0
1
1
Tex0
T1/Prim
T1/Prim
1
0
0
Env
0.0
0.0
1
0
1
Tex0
Env
Env
1
1
0
T1/Prim
Env
Env
1
1
1
Tex0
T1/Prim
Env

Tex0 indicates Texel0 color.

Prim indicates the Primitive Color Register.

Env indicates the Environment Color Register.

T1/Prim is determined from the states of TEXEL1/PRIMITIVE according to the following rule:

TEXEL1 PRIM T1/Prim Contents
0
0
0
----
0
1
1
Prim
1
*
1
TEXEL1

In 1 cycle mode, the above settings also apply to pipeline 2.
In 2 cycle mode, the above type of evaluation is not performed on mat_color_type1, and the values are substituted and output in the following way:

Shade color is replaced by Combine color
Shade Alpha is replaced by Combine Alpha

Determining Alpha Combiner Mode

Alpha combiner mode is determined based on the following mat_alpha_type0 bits:

	MAT_CC_NIFF_VTX_ALPHA  = 0x00010000
	MAT_CC_NIFF_TRI_ALPHA  = 0x00020000
	MAT_CC_NIFF_PRIM_ALPHA = 0x00040000
	MAT_CC_NIFF_TEX0_ALPHA = 0x00080000
	MAT_CC_NIFF_TEX1_ALPHA = 0x00100000

The following bits are not referenced:

	MAT_CC_NIFF_VTX  = 0x00000001
	MAT_CC_NIFF_TRI  = 0x00000002
	MAT_CC_NIFF_PRIM = 0x00000004
	MAT_CC_NIFF_TEX0 = 0x00000008
	MAT_CC_NIFF_TEX1 = 0x00000010

The alpha combiner expression is defined in the same way as the color combiner expression:

		(Wch - Xch) * Ych + Zch

The Wch, Xch, Ych, and Zch channels are determined based on the five effective flags described above, and according to the following rule:

VTX_A
TRI_A
T1/PRIM
TEX0_A
Wch
Xch
Ych
Zch
0
0
0
0
0.0
0.0
0.0
1.0
0
0
0
1
0.0
0.0
0.0
Tex0
0
0
1
0
0.0
0.0
0.0
T1/Prim
0
0
1
1
Tex0
0.0
T1/Prim
0.0
0
1
0
0
0.0
0.0
Env
0.0
0
1
0
1
Tex0
0.0
Env
0.0
0
1
1
0
T1/Prim
0.0
Env
0.0
0
1
1
1
Tex0
Env
T1/Prim
Env
1
0
0
0
0.0
0.0
0.0
Shade
1
0
0
1
Shade
0.0
Tex0
0.0
1
0
1
0
Shade
0.0
T1/Prim
0.0
1
0
1
1
Shade
T1/Prim
Tex0
T1/Prim
1
1
0
0
Shade
0.0
Env
0.0
1
1
0
1
Shade
Env
Tex0
Env
1
1
1
0
Shade
Env
T1/Prim
Env
1
1
1
1
Shade
T1/Prim
Tex0
Env

VTX_ALPHA becomes a control flag for ShadeColor.

T1/Prim is determined from the states of TEXEL1/PRIMITIVE according to the following rule:

TEXEL1_A PRIM_A T1/Prim Contents
0
0
0
----
0
1
1
Prim
1
*
1
TEXEL1

In 1 cycle mode, the above settings also apply to pipeline 2.
In 2 cycle mode, the above type of evaluation is not performed on mat_color_type1, and the output value for Shade Alpha is replaced by Combine alpha and output.


Programming Cautions


Copyright 1997-1999 NINTENDO Co., Ltd.
1998-1999 MONEGI CORPORATION
All rights reserved.