path: root/lib/libgfxd/README.md

## Installing
Run `make` for a single-threaded build, or `make MT=y` for a multi-threaded
build. Copy `libgfxd.a` to your lib directory, and `gfxd.h` to your include
directory.

## Example usage
Example source code:
```
#include <stdio.h>
#include <gfxd.h>

static int macro_fn(void)
{
	/* Print a tab before each macro, and a comma and newline after each
	   macro */
	gfxd_puts("\t");
	gfxd_macro_dflt(); /* Execute the default macro handler */
	gfxd_puts(",\n");

	return 0;
}

int main()
{
	/* Read from stdin and write to stdout */
	gfxd_input_fd(fileno(stdin));
	gfxd_output_fd(fileno(stdout));

	/* Override the default macro handler to make the output prettier */
	gfxd_macro_fn(macro_fn);

	/* Select F3DEX as the target microcode */
	gfxd_target(gfxd_f3dex);

	/* Set the input endianness to big endian, and the word size to 4 */
	gfxd_endian(gfxd_endian_big, 4);

	/* Print an opening brace */
	gfxd_puts("{\n");

	/* Execute until the end of input, or until encountering an invalid
	   command */
	gfxd_execute();

	/* Print a closing brace */
	gfxd_puts("}\n");
}
```

Example input (binary):
```
0xe7000000, 0x00000000,
0xfc127e03, 0xfffffdf8,
0xb900031d, 0xc8112078,
0xb6000000, 0x000e0000,
0xb7000000, 0x00012000,
0xfa000000, 0xffffffff,
0x040030bf, 0x000002e0,
0xb1000204, 0x00020604,
0xb1080a0c, 0x000a0e0c,
0xb10a1012, 0x000a120e,
0xb1140200, 0x00140016,
0xb8000000, 0x00000000,
```

Example output:
```
{
	gsDPPipeSync(),
	gsDPSetCombineLERP(TEXEL0, 0, SHADE, 0, 0, 0, 0, 1, COMBINED, 0, PRIMITIVE, 0, 0, 0, 0, COMBINED),
	gsDPSetRenderMode(G_RM_FOG_SHADE_A, G_RM_AA_ZB_OPA_SURF2),
	gsSPClearGeometryMode(G_LIGHTING | G_TEXTURE_GEN | G_TEXTURE_GEN_LINEAR),
	gsSPSetGeometryMode(G_CULL_BACK | G_FOG),
	gsDPSetPrimColor(0, 0, 0xFF, 0xFF, 0xFF, 0xFF),
	gsSPVertex(0x000002E0, 12, 0),
	gsSP2Triangles(0, 1, 2, 0, 1, 3, 2, 0),
	gsSP2Triangles(4, 5, 6, 0, 5, 7, 6, 0),
	gsSP1Quadrangle(5, 8, 9, 7, 0),
	gsSP1Quadrangle(10, 1, 0, 11, 0),
	gsSPEndDisplayList(),
}
```

## Input/output methods
The input consists of any number of `Gfx` packets, and the output is the
decompiled macros in plain-text. The endianness and microcode type of the input
can be set using `gfxd_endian` and `gfxd_target`.

Several methods of doing I/O are available. No method is selected by default,
meaning there will be no input, and any output will be discarded.

---

##### `void gfxd_input_buffer(const void *buf, int size)`
##### `void gfxd_output_buffer(char *buf, int size)`
Use the buffer pointed to by `buf`, of `size` bytes.

---

##### `void gfxd_input_fd(int fd)`
##### `void gfxd_output_fd(int fd)`
Use `read()` / `write()` with the provided file descriptor, `fd`.

---

##### `typedef int gfxd_input_fn_t(void *buf, int count)`
##### `typedef int gfxd_output_fn_t(const char *buf, int count)`
##### `void gfxd_input_callback(gfxd_input_fn_t *fn)`
##### `void gfxd_output_callback(gfxd_output_fn_t *fn)`
Use the provided callback function, `fn`. `fn` should copy at most `count`
bytes to/from `buf`, and return the number of bytes actually copied. The input
callback should return 0 to signal end of input.

## Handlers
The macro handler function is responsible for writing the output of each
decompiled macro. The default macro handler is `gfxd_macro_dflt`, but this can
be changed with `gfxd_macro_fn`. The new handler can extend the default
function by calling `gfxd_macro_dflt` within it, or it can override it
completely.

---

##### `int gfxd_macro_dflt()`
The default macro handler. Outputs the macro name, dynamic display list pointer
if one has been specified, and then each argument in order using the function
registered using `gfxd_arg_fn` (`gfxd_arg_dflt` by default), and returns zero.
Because it is designed to be extended, it only outputs the macro text, without
any whitespace or punctuation before or after. When this function is used as
the sole macro handler, it will output the entire display list on one line
without any separation between macros, which is probably not what you want.

---

##### `void gfxd_macro_fn(gfxd_macro_fn_t *fn)`
Set `fn` to be the macro handler function. `fn` can be null, in which case the
handler is reset to the default.

---

##### `void gfxd_arg_dflt(int arg_num)`
The default argument handler for `gfxd_macro_dflt`. For the argument with index
`arg_num`, calls `gfxd_arg_callbacks`, and prints the argument value if the
callback returns zero, or if there is no callback for the given argument.

---

##### `void gfxd_arg_fn(gfxd_arg_fn_t *fn)`
Set `fn` to be the argument handler function, called by `gfxd_macro_dflt`,
for each argument in the current macro, not counting the dynamic display list
pointer if one has been specified. `fn` can be null, in which case the handler
is reset to the default. This only affects the output of `gfxd_macro_dflt`, and
has no observable effect if `gfxd_macro_dflt` is overridden (not extended).

## Argument callbacks
Callbacks can be registered that will be executed when an argument of a certain
type is encountered. The default argument handler `gfxd_arg_dflt` will execute
callbacks as needed using `gfxd_arg_callbacks`. If a callback returns non-zero,
`gfxd_arg_dflt` will not output anything. This is to allow callbacks to
override the default argument output. Otherwise, `gfxd_arg_dflt` will output
the argument value after the callback function's output.

---

##### `int gfxd_arg_callbacks(int arg_num)`
Examines the argument with index `arg_num` and executes the callback function
for that argument type, if such a callback is supported and has been
registered. This function returns the value that was returned by the callback
function. If no callback function has been registered for the argument type,
zero is returned.

Most argument callbacks have some extra parameters containing information that
might be relevant to the argument that triggered the callback. The extra
information is extracted only from the current macro, as gfxd does not retain
any context information from previous or subsequent macros. If any of the extra
parameter values is not available in the current macro, the value for that
parameter is substituted with `-1` for signed parameters, and zero for unsigned
parameters.

---

##### `typedef int gfxd_tlut_fn_t(uint32_t tlut, int32_t idx, int32_t count)`
##### `void gfxd_tlut_callback(gfxd_tlut_fn_t *fn)`
Set the callback function for palette arguments. The argument type is
`gfxd_Tlut`. The palette index is in `idx` and the number of colors in `count`.

---

##### `typedef int gfxd_timg_fn_t(uint32_t timg, int32_t fmt, int32_t siz, int32_t width, int32_t height, int32_t pal)`
##### `void gfxd_timg_callback(gfxd_timg_fn_t *fn)`
Set the callback function for texture arguments. The argument type is
`gfxd_Timg`. The image format is in `fmt` and `siz`, the dimensions in `width`
and `height`, and the palette index in `pal`.

---

##### `typedef int gfxd_cimg_fn_t(uint32_t cimg, int32_t fmt, int32_t siz, int32_t width)`
##### `void gfxd_cimg_callback(gfxd_cimg_fn_t *fn)`
Set the callback function for frame buffer arguments. The argument type is
`gfxd_Cimg`. The image format is in `fmt` and `siz`, and the horizontal
resolution in `width`.

---

##### `typedef int gfxd_zimg_fn_t(uint32_t zimg)`
##### `void gfxd_zimg_callback(gfxd_zimg_fn_t *fn)`
Set the callback function for depth buffer arguments. The argument type is
`gfxd_Zimg`.

---

##### `typedef int gfxd_dl_fn_t(uint32_t dl)`
##### `void gfxd_dl_callback(gfxd_dl_fn_t *fn)`
Set the callback function for display list arguments. The argument type is
`gfxd_Dl`.

---

##### `typedef int gfxd_mtx_fn_t(uint32_t mtx)`
##### `void gfxd_mtx_callback(gfxd_mtx_fn_t *fn)`
Set the callback function for matrix arguments. The argument type is
`gfxd_Mtxptr`.

---

##### `typedef int gfxd_lookat_fn_t(uint32_t lookat, int32_t count)`
##### `void gfxd_lookat_callback(gfxd_lookat_fn_t *fn)`
Set the callback function for lookat array arguments. The argument type is
`gfxd_Lookatptr`. The number of lookat structures (1 or 2) is in `count`. 

---

##### `typedef int gfxd_light_fn_t(uint32_t light, int32_t count)`
##### `void gfxd_light_callback(gfxd_light_fn_t *fn)`
Set the callback function for light array arguments. The argument type is
`gfxd_Lightptr`. The number of light structures is in `count`.

---

##### `typedef int gfxd_seg_fn_t(uint32_t seg, int32_t num)`
##### `void gfxd_seg_callback(gfxd_seg_fn_t *fn)`
Set the callback function for segment base arguments. The argument type is
`gfxd_Segptr`. The segment number is in `num`.

---

##### `typedef int gfxd_vtx_fn_t(uint32_t vtx, int32_t num)`
##### `void gfxd_vtx_callback(gfxd_vtx_fn_t *fn)`
Set the callback function for vertex array arguments. The argument type is
`gfxd_Vtxptr`. The number of vertex structures is in `num`.

---

##### `typedef int gfxd_vp_fn_t(uint32_t vp)`
##### `void gfxd_vp_callback(gfxd_vp_fn_t *fn)`
Set the callback function for viewport arguments. The argument type is
`gfxd_Vp`.

---

##### `typedef int gfxd_uctext_fn_t(uint32_t text, uint32_t size)`
##### `void gfxd_uctext_callback(gfxd_uctext_fn_t *fn)`
Set the callback function for microcode text arguments. The argument type is
`gfxd_Uctext`. The size of the text segment is in `size`.

---

##### `typedef int gfxd_ucdata_fn_t(uint32_t data, uint32_t size)`
##### `void gfxd_ucdata_callback(gfxd_ucdata_fn_t *fn)`
Set the callback function for microcode data arguments. The argument type is
`gfxd_Ucdata`. The size of the data segment is in `size`.

---

##### `typedef int gfxd_dram_fn_t(uint32_t dram, uint32_t size)`
##### `void gfxd_dram_callback(gfxd_dram_fn_t *fn)`
Set the callback function for generic pointer arguments. The argument type is
`gfxd_Dram`. The size of the data is in `size`.

## General settings
These functions control general input and output settings.

---

##### `void gfxd_target(gfxd_ucode_t ucode)`
Select `ucode` as the target microcode. `ucode` can be `gfxd_f3d`, `gfxd_f3db`,
`gfxd_f3dex`, `gfxd_f3dexb`, or `gfxd_f3dex2`. The microcode must be selected
before `gfxd_execute`, as no microcode is selected by default.

---

##### `void gfxd_endian(int endian, int wordsize)`
Select `endian` as the endianness of the input, and `wordsize` as the size of
each word in number of bytes. `endian` can be `gfxd_endian_big`,
`gfxd_endian_little`, or `gfxd_endian_host` (the endianness of the host
machine). `wordsize` can be 1, 2, 4, or 8. Big endian is selected by default,
with a word size of 4.

---

##### `void gfxd_dynamic(const char *arg)`
Enable or disable the use of dynamic `g` macros instead of static `gs` macros,
and select the dynamic display list pointer argument to be used. `arg` will be
used by `gfxd_macro_dflt` as the first argument to dynamic macros. If `arg` is
null, dynamic macros are disabled, and `gs` macros are used. Also affects the
result of `gfxd_macro_name`, as it will return either the dynamic or static
version of the macro name as selected by this setting.

---

##### `void gfxd_enable(int cap)`
##### `void gfxd_disable(int cap)`
Enable or disable the feature specified by `cap`. Can be one of the following;
- `gfxd_stop_on_invalid`: Stop execution when encountering an invalid macro.
Enabled by default.
- `gfxd_stop_on_end`: Stop execution when encountering a `SPBranchList` or
`SPEndDisplayList`. Enabled by default.
- `gfxd_emit_dec_color`: Print color components as decimal instead of
hexadecimal. Disabled by default.
- `gfxd_emit_q_macro`: Print fixed-point conversion `q` macros for fixed-point
values. Disabled by default.
- `gfxd_emit_ext_macro`: Emit non-standard macros. Some commands are valid
(though possibly meaningless), but have no macros associated with them, such as
a standalone `G_RDPHALF_1`. When this feature is enabled, such a command will
produce a non-standard `gsDPHalf1` macro instead of a raw hexadecimal command.
Also enables some non-standard multi-packet texture loading macros. Disabled by
default.

---

##### `void gfxd_udata_set(void *ptr)`
##### `void *gfxd_udata_get(void)`
Set or get a generic pointer that can be used to pass user-defined data in and
out of callback functions.

## Execution
Decompilation is started using the `gfxd_execute` function. When gfxd is
executing (i.e. after `gfxd_execute` has been entered, and before it returns),
the general settings and the I/O settings should not be changed.

---

##### `int gfxd_execute()`
Start executing gfxd with the current settings. For each macro, the macro
handler registered with `gfxd_macro_fn` is called. Execution ends when the
input ends, the macro handler returns non-zero, when an invalid macro is
encountered and `gfxd_stop_on_invalid` is enabled, or when `SPBranchList` or
`SPEndDisplayList` is encountered and `gfxd_stop_on_end` is enabled. If
execution ends due to an invalid macro, `-1` is returned. If execution ends
because the macro handler returns non-zero, the return value from the macro
handler is returned. Otherwise zero is returned.

## Macro information
The following functions can be used to obtain information about the current
macro and its arguments. They should only be used in custom handlers and
callbacks from within `gfxd_execute`. If used elsewhere, their behavior is
undefined.

---

##### `int gfxd_macro_offset()`
Returns the offset in the input data of the current macro. The offset starts
at zero when `gfxd_execute` is called.

---

##### `int gfxd_macro_packets()`
Returns the number of `Gfx` packets within the current macro.

---

##### `const void *gfxd_macro_data()`
Returns a pointer to the input data for the current macro. The data is not
byte-swapped. The data has a length of `sizeof(Gfx) * gfxd_macro_packets()`.

---

##### `int gfxd_macro_id()`
Returns a number that uniquely identifies the current macro. The number will
be one of the constants in `gfxd.h`.

---

##### `const char *gfxd_macro_name()`
Returns the name of the current macro. If the macro does not have a name (i.e.
it's invalid), null is returned. If a dynamic display list pointer has been
specified, the dynamic `g` version is returned. Otherwise the static `gs`
version is returned. The returned pointer is invalidated by a subsequent call
to `gfxd_macro_name`.

---

##### `int gfxd_arg_count()`
Returns the number of arguments to the current macro, not including a dynamic
display list pointer if one has been specified.

---

##### `int gfxd_arg_type(int arg_num)`
Returns a number that identifies the type of the argument with index `arg_num`.
The number will be one of the constants in `gfxd.h`.

---

##### `const char *gfxd_arg_name(int arg_num)`
Returns the name of the argument with index `arg_num`. Argument names are not
canonical, nor are they needed for macro disassembly, but they can be useful
for informational and diagnostic purposes.

---

##### `int gfxd_arg_fmt(int arg_num)`
Returns the data format of the argument with index `arg_num`. The return value
will be `gfxd_argfmt_i` for `int32_t`, `gfxd_argfmt_u` for `uint32_t`, or
`gfxd_argfmt_f` for `float`. When accessing the value of the argument with
`gfxd_arg_value`, the member with the corresponding type should be used.

---

##### `const gfxd_value_t *gfxd_arg_value(int arg_num)`
Returns a pointer to the value of the argument with index `arg_num`. The value
is a union of type `gfxd_value_t` with the following layout;
```
typedef union
{
	int32_t		i;
	uint32_t	u;
	float		f;
} gfxd_value_t
```

---

##### `const gfxd_value_t *gfxd_value_by_type(int type, int idx)`
Returns a pointer to the value of the argument that is of `type`, and has order
`idx` in all arguments of that type. An `idx` of zero returns the first
argument that has the specified type. If there is no argument with the given
type and order, null is returned.

---

##### `int gfxd_arg_valid(int arg_num)`
Returns non-zero if the argument with index `arg_num` is "valid", for some
definition of valid. An invalid argument generally means that the disassembler
found inconsistencies in the input data, or that the data can not be reproduced
by the current macro type. The argument still has a value that can be printed,
though the value is not guaranteed to make any sense.

## Custom output
When the default handlers are overridden or extended, the custom handler
functions will want to do some output of their own. The following methods are
available for inserting custom text into the gfxd output.

---

##### `int gfxd_write(const void *buf, int count)`
Insert `count` bytes from the buffer at `buf` into the output. The number of
characters written is returned.

---

##### `int gfxd_puts(const char *str)`
Insert the null-terminated string at `str` into the output. The number of
characters written is returned.

---

##### `int gfxd_printf(const char *fmt, ...)`
Insert the printf-formatted string described by `fmt` and additional arguments
into the output. Limited to 255 characters. The number of characters written is
returned.

---

##### `int gfxd_print_value(int type, const gfxd_value_t *value)`
Insert the type-formatted value into the output. The type should be one of the
constants in `gfxd.h`. The number of characters written is returned. The
macro argument with index `n` can be printed with
`gfxd_print_value(gfxd_arg_type(n), gfxd_arg_value(n))`.