gfxd-sys 0.1.1

Rust bindings for libgfxd, the N64 display list decompiler library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

/* SPDX-FileCopyrightText: © 2025 Decompollaborate */
/* SPDX-License-Identifier: MIT */

//! Inspect information from the current macro.
//!
//! 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.
//!
//! [`gfxd_execute`]: crate::execution::gfxd_execute

use crate::ffi;

use crate::arg_type::ArgType;

use crate::ptr::NonNullConst;

extern "C" {
    /// Returns the offset in the input data of the current macro.
    ///
    /// The offset starts at zero when [`gfxd_execute`] is called.
    ///
    /// [`gfxd_execute`]: crate::execution::gfxd_execute
    pub fn gfxd_macro_offset() -> ffi::c_int;

    /// Returns the number of `Gfx` packets within the current macro.
    pub fn gfxd_macro_packets() -> ffi::c_int;

    /// Run `fn` for each individual sub-packet the current macro is made up
    /// of.
    ///
    /// During execution of `fn`, the current sub-packet becomes the current
    /// macro that is used by other macro information functions.
    ///
    /// If the current macro is made up of only a single packet it is processed
    /// as a single sub-packet, there is no need to check if the current macro
    /// is a multi-packet macro.
    ///
    /// If at any point `fn` returns a value other than 0, the remaining
    /// sub-packets are skipped and the return value of `fn` is returned.
    ///
    /// If `fn` is [`None`] no processing is done and 0 is returned.
    pub fn gfxd_foreach_pkt(fn_: Option<unsafe extern "C" fn() -> ffi::c_int>) -> ffi::c_int;

    /// 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()`.
    pub fn gfxd_macro_data() -> NonNullConst<ffi::c_void>;

    /// Returns a number that uniquely identifies the current macro.
    ///
    /// The number will be one of the constants in [`MacroId`].
    ///
    /// [`MacroId`]: crate::macro_id::MacroId
    pub fn gfxd_macro_id() -> ffi::c_int;

    /// Returns the name of the current macro.
    ///
    /// If the macro does not have a name (i.e. it's invalid), [`None`] 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`].
    pub fn gfxd_macro_name() -> Option<NonNullConst<ffi::c_char>>;

    /// Returns the number of arguments to the current macro.
    ///
    /// Does not include a dynamic display list pointer if one has been
    /// specified.
    pub fn gfxd_arg_count() -> ffi::c_int;

    /// Returns a number that identifies the type of the argument with index
    /// `arg_num`.
    ///
    /// The number will be one of the constants in [`ArgType`].
    pub fn gfxd_arg_type(arg_num: ffi::c_int) -> ffi::c_int;

    /// 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.
    pub fn gfxd_arg_name(arg_num: ffi::c_int) -> NonNullConst<ffi::c_char>;

    /// Returns the data format of the argument with index `arg_num`.
    ///
    /// The return value will be [`gfxd_argfmt_i`] for `i32`, [`gfxd_argfmt_u`]
    /// for [`u32`], or [`gfxd_argfmt_f`] for `f32`.
    ///
    /// When accessing the value of the argument with [`gfxd_arg_value`], the
    /// member with the corresponding type should be used.
    pub fn gfxd_arg_fmt(arg_num: ffi::c_int) -> ffi::c_int;

    /// Returns a pointer to the value of the argument with index `arg_num`.
    ///
    /// The value is a union of type `gfxd_value_t`
    pub fn gfxd_arg_value(arg_num: ffi::c_int) -> NonNullConst<gfxd_value_t>;

    /// 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, [`None`] is
    /// returned.
    pub fn gfxd_value_by_type(
        type_: ArgType,
        idx: ffi::c_int,
    ) -> Option<NonNullConst<gfxd_value_t>>;

    /// 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.
    pub fn gfxd_arg_valid(arg_num: ffi::c_int) -> ffi::c_int;
}

pub const gfxd_argfmt_i: u32 = ArgFmt::gfxd_argfmt_i as u32;
pub const gfxd_argfmt_u: u32 = ArgFmt::gfxd_argfmt_u as u32;
pub const gfxd_argfmt_f: u32 = ArgFmt::gfxd_argfmt_f as u32;
#[repr(u32)]
#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
pub enum ArgFmt {
    gfxd_argfmt_i = 0,
    gfxd_argfmt_u = 1,
    gfxd_argfmt_f = 2,
}

#[repr(C)]
#[derive(Copy, Clone)]
pub union gfxd_value_t {
    pub i: i32,
    pub u: u32,
    pub f: f32,
}