gfxd_rs/

customizer.rs

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

use core::{
    convert::TryInto as _,
    num::{NonZeroU16, NonZeroU32},
    slice,
};
use gfxd_sys::{ffi, ptr::NonNullConst};

use crate::{
    lib_data::LibData, Address, LightsNum, LookatCount, MacroInfo, MacroPrinter, Printer, TexFmt,
    TexSiz, TlutCount,
};

/// Customize the output for each `Gfx` macro, and extract data from each macro.
///
/// This allows extending or replacing the normal functionality of `gfxd` by
/// registering callbacks for each specific situation.
///
/// Each callback is passed a reference of either [`MacroInfo`], [`Printer`],
/// and/or [`MacroPrinter`] which allows to inspect the contents of the current
/// macro or write output to the output buffer.
///
/// There are 3 major groups for the registered callbacks:
/// - [`before_after_execution_callback`]: Callbacks that will be called before
///   and after the current `gfxd` execution.
/// - [`macro_fn`]: Replace or extend the behavior for each specific macro.
/// - Argument callbacks: Callbacks that will be executed when certain types
///   of macros are encountered.
///
/// [`before_after_execution_callback`]: Customizer::before_after_execution_callback
/// [`macro_fn`]: Customizer::macro_fn
// 'cls is short for closure
#[allow(clippy::type_complexity)]
pub struct Customizer<'cls> {
    // These two callbacks are called only once during the whole disassembly,so
    // it would be nice if they were FnOnce, but I couldn't get it to work.
    before_execution: Option<&'cls mut dyn FnMut(&mut Printer)>,
    after_execution: Option<&'cls mut dyn FnMut(&mut Printer)>,

    macro_fn: Option<&'cls mut dyn FnMut(&mut MacroPrinter, &mut MacroInfo) -> MacroFnRet>,
    arg_fn: Option<&'cls mut dyn FnMut(&mut MacroPrinter, &mut MacroInfo, i32)>,

    tlut_fn: Option<
        &'cls mut dyn FnMut(
            &mut Printer,
            &mut MacroInfo,
            Address,
            Option<u8>,
            TlutCount,
        ) -> DoDefaultOutput,
    >,
    timg_fn: Option<
        &'cls mut dyn FnMut(
            &mut Printer,
            &mut MacroInfo,
            Address,
            TexFmt,
            TexSiz,
            u8,
            u8,
            u8,
        ) -> DoDefaultOutput,
    >,
    cimg_fn: Option<
        &'cls mut dyn FnMut(
            &mut Printer,
            &mut MacroInfo,
            Address,
            TexFmt,
            TexSiz,
            u16,
        ) -> DoDefaultOutput,
    >,
    zimg_fn: Option<&'cls mut dyn FnMut(&mut Printer, &mut MacroInfo, Address) -> DoDefaultOutput>,
    dl_fn: Option<&'cls mut dyn FnMut(&mut Printer, &mut MacroInfo, Address) -> DoDefaultOutput>,
    mtx_fn: Option<&'cls mut dyn FnMut(&mut Printer, &mut MacroInfo, Address) -> DoDefaultOutput>,
    lookat_fn: Option<
        &'cls mut dyn FnMut(&mut Printer, &mut MacroInfo, Address, LookatCount) -> DoDefaultOutput,
    >,
    light_fn: Option<&'cls mut dyn FnMut(&mut Printer, &mut MacroInfo, Address) -> DoDefaultOutput>,
    lightsn_fn: Option<
        &'cls mut dyn FnMut(&mut Printer, &mut MacroInfo, Address, LightsNum) -> DoDefaultOutput,
    >,
    seg_fn:
        Option<&'cls mut dyn FnMut(&mut Printer, &mut MacroInfo, Address, u8) -> DoDefaultOutput>,
    vtx_fn:
        Option<&'cls mut dyn FnMut(&mut Printer, &mut MacroInfo, Address, i32) -> DoDefaultOutput>,
    vp_fn: Option<&'cls mut dyn FnMut(&mut Printer, &mut MacroInfo, Address) -> DoDefaultOutput>,
    uctext_fn: Option<
        &'cls mut dyn FnMut(&mut Printer, &mut MacroInfo, Address, NonZeroU32) -> DoDefaultOutput,
    >,
    ucdata_fn: Option<
        &'cls mut dyn FnMut(&mut Printer, &mut MacroInfo, Address, NonZeroU32) -> DoDefaultOutput,
    >,
    dram_fn: Option<
        &'cls mut dyn FnMut(&mut Printer, &mut MacroInfo, Address, NonZeroU16) -> DoDefaultOutput,
    >,
}

impl Customizer<'_> {
    pub(crate) fn apply_callbacks(&mut self) {
        self.apply_out_callback();
        self.apply_user_macro_callbacks();
        self.apply_user_arg_callbacks();
    }

    fn apply_out_callback(&mut self) {
        // Write to an out buffer
        extern "C" fn output_callback(
            buf: NonNullConst<ffi::c_char>,
            count: ffi::c_int,
        ) -> ffi::c_int {
            // Retrieve the out_buf from the user data pointer.
            let lib_data = LibData::get().expect("Welp. Maybe race condition?");

            // SAFETY: We just have to trust the length of the data is correct.
            let raw_slice = unsafe { slice::from_raw_parts(buf.as_ptr().cast(), count as _) };

            // SAFETY: gfxd doesn't use non-ascii characters, and everything
            // else should be generated by the user, which should be UTF-8
            // already, since that's the only thing the API supports.
            let data_str = unsafe { core::str::from_utf8_unchecked(raw_slice) };

            // Push the output into our buffer.
            lib_data.write_to_buf(data_str);

            // We read the whole buffer.
            count
        }

        // Write the disassembly output to out_buf.
        // We pass it around by passing it as a user data pointer (LibData).
        unsafe {
            gfxd_sys::io::gfxd_output_callback(Some(output_callback));
        }
    }

    fn apply_user_macro_callbacks(&mut self) {
        if self.macro_fn.is_some() {
            extern "C" fn callback() -> ffi::c_int {
                let lib_data = LibData::get().expect("Welp. Maybe race condition?");

                let ret = if let Some(closure) = &mut lib_data.get_customizer_mut().macro_fn {
                    let mut printer = MacroPrinter::new();
                    let mut info = MacroInfo::new();
                    (closure)(&mut printer, &mut info)
                } else {
                    panic!("macro_fn closure was None?")
                };

                ret.into_ret()
            }
            unsafe {
                gfxd_sys::handlers::gfxd_macro_fn(Some(callback));
            }
        } else {
            unsafe {
                gfxd_sys::handlers::gfxd_macro_fn(None);
            }
        }

        if self.arg_fn.is_some() {
            extern "C" fn callback(arg_num: ffi::c_int) {
                let lib_data = LibData::get().expect("Welp. Maybe race condition?");

                if let Some(closure) = &mut lib_data.get_customizer_mut().arg_fn {
                    let mut printer = MacroPrinter::new();
                    let mut info = MacroInfo::new();
                    (closure)(&mut printer, &mut info, arg_num);
                } else {
                    panic!("arg_fn closure was None?")
                }
            }
            unsafe {
                gfxd_sys::handlers::gfxd_arg_fn(Some(callback));
            }
        } else {
            unsafe {
                gfxd_sys::handlers::gfxd_arg_fn(None);
            }
        }
    }

    fn apply_user_arg_callbacks(&mut self) {
        if self.tlut_fn.is_some() {
            extern "C" fn callback(tlut: u32, idx: i32, count: i32) -> ffi::c_int {
                let lib_data = LibData::get().expect("Welp. Maybe race condition?");

                let ret = if let Some(closure) = &mut lib_data.get_customizer_mut().tlut_fn {
                    let mut printer = Printer::new();
                    let mut info = MacroInfo::new();
                    let timg = Address(tlut);
                    #[allow(clippy::cast_possible_truncation)]
                    let index = if idx == -1 { None } else { Some(idx as u8) };
                    let tlut_count = TlutCount::new(count);
                    (closure)(&mut printer, &mut info, timg, index, tlut_count)
                } else {
                    panic!("tlut_fn closure was None?")
                };

                ret.into_ret()
            }
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_tlut_callback(Some(callback));
            }
        } else {
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_tlut_callback(None);
            }
        }

        if self.timg_fn.is_some() {
            extern "C" fn callback(
                timg: u32,
                fmt: i32,
                siz: i32,
                width: i32,
                height: i32,
                pal: i32,
            ) -> ffi::c_int {
                let lib_data = LibData::get().expect("Welp. Maybe race condition?");

                let ret = if let Some(closure) = &mut lib_data.get_customizer_mut().timg_fn {
                    let mut printer = Printer::new();
                    let mut info = MacroInfo::new();
                    let timg = Address(timg);
                    let tex_fmt = TexFmt::new(fmt);
                    let tex_siz = TexSiz::new(siz);
                    #[allow(clippy::cast_possible_truncation)]
                    let width = width as _;
                    #[allow(clippy::cast_possible_truncation)]
                    let height = height as _;
                    #[allow(clippy::cast_possible_truncation)]
                    let pal = pal as _;
                    (closure)(
                        &mut printer,
                        &mut info,
                        timg,
                        tex_fmt,
                        tex_siz,
                        width,
                        height,
                        pal,
                    )
                } else {
                    panic!("timg_fn closure was None?")
                };

                ret.into_ret()
            }
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_timg_callback(Some(callback));
            }
        } else {
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_timg_callback(None);
            }
        }

        if self.cimg_fn.is_some() {
            extern "C" fn callback(cimg: u32, fmt: i32, siz: i32, width: i32) -> ffi::c_int {
                let lib_data = LibData::get().expect("Welp. Maybe race condition?");

                let ret = if let Some(closure) = &mut lib_data.get_customizer_mut().cimg_fn {
                    let mut printer = Printer::new();
                    let mut info = MacroInfo::new();
                    let cimg = Address(cimg);
                    let tex_fmt = TexFmt::new(fmt);
                    let tex_siz = TexSiz::new(siz);
                    #[allow(clippy::cast_possible_truncation)]
                    let width = width as _;
                    (closure)(&mut printer, &mut info, cimg, tex_fmt, tex_siz, width)
                } else {
                    panic!("cimg_fn closure was None?")
                };

                ret.into_ret()
            }
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_cimg_callback(Some(callback));
            }
        } else {
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_cimg_callback(None);
            }
        }

        if self.zimg_fn.is_some() {
            extern "C" fn callback(zimg: u32) -> ffi::c_int {
                let lib_data = LibData::get().expect("Welp. Maybe race condition?");

                let ret = if let Some(closure) = &mut lib_data.get_customizer_mut().zimg_fn {
                    let mut printer = Printer::new();
                    let mut info = MacroInfo::new();
                    let zimg = Address(zimg);
                    (closure)(&mut printer, &mut info, zimg)
                } else {
                    panic!("zimg_fn closure was None?")
                };

                ret.into_ret()
            }
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_zimg_callback(Some(callback));
            }
        } else {
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_zimg_callback(None);
            }
        }

        if self.dl_fn.is_some() {
            extern "C" fn callback(dl: u32) -> ffi::c_int {
                let lib_data = LibData::get().expect("Welp. Maybe race condition?");

                let ret = if let Some(closure) = &mut lib_data.get_customizer_mut().dl_fn {
                    let mut printer = Printer::new();
                    let mut info = MacroInfo::new();
                    let dl = Address(dl);
                    (closure)(&mut printer, &mut info, dl)
                } else {
                    panic!("dl_fn closure was None?")
                };

                ret.into_ret()
            }
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_dl_callback(Some(callback));
            }
        } else {
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_dl_callback(None);
            }
        }

        if self.mtx_fn.is_some() {
            extern "C" fn callback(mtx: u32) -> ffi::c_int {
                let lib_data = LibData::get().expect("Welp. Maybe race condition?");

                let ret = if let Some(closure) = &mut lib_data.get_customizer_mut().mtx_fn {
                    let mut printer = Printer::new();
                    let mut info = MacroInfo::new();
                    let mtx = Address(mtx);
                    (closure)(&mut printer, &mut info, mtx)
                } else {
                    panic!("mtx_fn closure was None?")
                };

                ret.into_ret()
            }
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_mtx_callback(Some(callback));
            }
        } else {
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_mtx_callback(None);
            }
        }

        if self.lookat_fn.is_some() {
            extern "C" fn callback(lookat: u32, count: i32) -> ffi::c_int {
                let lib_data = LibData::get().expect("Welp. Maybe race condition?");

                let ret = if let Some(closure) = &mut lib_data.get_customizer_mut().lookat_fn {
                    let mut printer = Printer::new();
                    let mut info = MacroInfo::new();
                    let lookat = Address(lookat);
                    let count = LookatCount::new(count);
                    (closure)(&mut printer, &mut info, lookat, count)
                } else {
                    panic!("lookat_fn closure was None?")
                };

                ret.into_ret()
            }
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_lookat_callback(Some(callback));
            }
        } else {
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_lookat_callback(None);
            }
        }

        if self.light_fn.is_some() {
            extern "C" fn callback(light: u32) -> ffi::c_int {
                let lib_data = LibData::get().expect("Welp. Maybe race condition?");

                let ret = if let Some(closure) = &mut lib_data.get_customizer_mut().light_fn {
                    let mut printer = Printer::new();
                    let mut info = MacroInfo::new();
                    let light = Address(light);
                    (closure)(&mut printer, &mut info, light)
                } else {
                    panic!("light_fn closure was None?")
                };

                ret.into_ret()
            }
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_light_callback(Some(callback));
            }
        } else {
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_light_callback(None);
            }
        }

        if self.lightsn_fn.is_some() {
            extern "C" fn callback(lightsn: u32, num: i32) -> ffi::c_int {
                let lib_data = LibData::get().expect("Welp. Maybe race condition?");

                let ret = if let Some(closure) = &mut lib_data.get_customizer_mut().lightsn_fn {
                    let mut printer = Printer::new();
                    let mut info = MacroInfo::new();
                    let lightsn = Address(lightsn);
                    let num = LightsNum::new(num);
                    (closure)(&mut printer, &mut info, lightsn, num)
                } else {
                    panic!("lightsn_fn closure was None?")
                };

                ret.into_ret()
            }
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_lightsn_callback(Some(callback));
            }
        } else {
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_lightsn_callback(None);
            }
        }

        if self.seg_fn.is_some() {
            extern "C" fn callback(seg: u32, num: i32) -> ffi::c_int {
                let lib_data = LibData::get().expect("Welp. Maybe race condition?");

                let ret = if let Some(closure) = &mut lib_data.get_customizer_mut().seg_fn {
                    let mut printer = Printer::new();
                    let mut info = MacroInfo::new();
                    let seg = Address(seg);
                    #[allow(clippy::cast_possible_truncation)]
                    let num = num as _;
                    (closure)(&mut printer, &mut info, seg, num)
                } else {
                    panic!("seg_fn closure was None?")
                };

                ret.into_ret()
            }
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_seg_callback(Some(callback));
            }
        } else {
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_seg_callback(None);
            }
        }

        if self.vtx_fn.is_some() {
            extern "C" fn callback(vtx: u32, num: i32) -> ffi::c_int {
                let lib_data = LibData::get().expect("Welp. Maybe race condition?");

                let ret = if let Some(closure) = &mut lib_data.get_customizer_mut().vtx_fn {
                    let mut printer = Printer::new();
                    let mut info = MacroInfo::new();
                    let vtx = Address(vtx);
                    (closure)(&mut printer, &mut info, vtx, num)
                } else {
                    panic!("vtx_fn closure was None?")
                };

                ret.into_ret()
            }
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_vtx_callback(Some(callback));
            }
        } else {
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_vtx_callback(None);
            }
        }

        if self.vp_fn.is_some() {
            extern "C" fn callback(vp: u32) -> ffi::c_int {
                let lib_data = LibData::get().expect("Welp. Maybe race condition?");

                let ret = if let Some(closure) = &mut lib_data.get_customizer_mut().vp_fn {
                    let mut printer = Printer::new();
                    let mut info = MacroInfo::new();
                    let vp = Address(vp);
                    (closure)(&mut printer, &mut info, vp)
                } else {
                    panic!("vp_fn closure was None?")
                };

                ret.into_ret()
            }
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_vp_callback(Some(callback));
            }
        } else {
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_vp_callback(None);
            }
        }

        if self.uctext_fn.is_some() {
            extern "C" fn callback(uctext: u32, size: NonZeroU32) -> ffi::c_int {
                let lib_data = LibData::get().expect("Welp. Maybe race condition?");

                let ret = if let Some(closure) = &mut lib_data.get_customizer_mut().uctext_fn {
                    let mut printer = Printer::new();
                    let mut info = MacroInfo::new();
                    let uctext = Address(uctext);
                    (closure)(&mut printer, &mut info, uctext, size)
                } else {
                    panic!("uctext_fn closure was None?")
                };

                ret.into_ret()
            }
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_uctext_callback(Some(callback));
            }
        } else {
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_uctext_callback(None);
            }
        }

        if self.ucdata_fn.is_some() {
            extern "C" fn callback(ucdata: u32, size: NonZeroU32) -> ffi::c_int {
                let lib_data = LibData::get().expect("Welp. Maybe race condition?");

                let ret = if let Some(closure) = &mut lib_data.get_customizer_mut().ucdata_fn {
                    let mut printer = Printer::new();
                    let mut info = MacroInfo::new();
                    let ucdata = Address(ucdata);
                    (closure)(&mut printer, &mut info, ucdata, size)
                } else {
                    panic!("ucdata_fn closure was None?")
                };

                ret.into_ret()
            }
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_ucdata_callback(Some(callback));
            }
        } else {
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_ucdata_callback(None);
            }
        }

        if self.dram_fn.is_some() {
            extern "C" fn callback(dram: u32, size: NonZeroU32) -> ffi::c_int {
                let lib_data = LibData::get().expect("Welp. Maybe race condition?");

                let ret = if let Some(closure) = &mut lib_data.get_customizer_mut().dram_fn {
                    let mut printer = Printer::new();
                    let mut info = MacroInfo::new();
                    let dram = Address(dram);
                    let size_raw = size
                        .get()
                        .try_into()
                        .expect("This value should be less than 0x4096");
                    #[allow(clippy::shadow_unrelated)]
                    let size = unsafe { NonZeroU16::new_unchecked(size_raw) };
                    (closure)(&mut printer, &mut info, dram, size)
                } else {
                    panic!("dram_fn closure was None?")
                };

                ret.into_ret()
            }
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_dram_callback(Some(callback));
            }
        } else {
            unsafe {
                gfxd_sys::argument_callbacks::gfxd_dram_callback(None);
            }
        }
    }
}

impl Customizer<'_> {
    /// Create a new instance of the customizer.
    #[must_use]
    pub fn new() -> Self {
        Self {
            before_execution: None,
            after_execution: None,
            macro_fn: None,
            arg_fn: None,
            tlut_fn: None,
            timg_fn: None,
            cimg_fn: None,
            zimg_fn: None,
            dl_fn: None,
            mtx_fn: None,
            lookat_fn: None,
            light_fn: None,
            lightsn_fn: None,
            seg_fn: None,
            vtx_fn: None,
            vp_fn: None,
            uctext_fn: None,
            ucdata_fn: None,
            dram_fn: None,
        }
    }
}

impl<'cls> Customizer<'cls> {
    /// Register callbacks that are called before and after the execution of
    /// `gfxd`.
    ///
    /// Allows to do some setup work for the output buffer, like writing
    /// opening and closing braces.
    ///
    /// `before` is called before `gfxd` starts executing, so the output buffer
    /// will be empty at this point. `after` is called once `gfxd` finishes
    /// running, and it is the very last code that is run before returning the
    /// disassembled output to the user.
    ///
    /// Both callbacks are called only once.
    ///
    /// ## Examples
    ///
    /// ```rust
    /// use gfxd_rs::{Customizer, Printer};
    ///
    /// let mut before = |printer: &mut Printer| {
    ///     printer.write_str("{\n");
    /// };
    /// let mut after = |printer: &mut Printer| {
    ///     printer.write_str("}\n");
    /// };
    ///
    /// let mut customizer = Customizer::new();
    /// customizer.before_after_execution_callback(&mut before, &mut after);
    /// ```
    pub fn before_after_execution_callback<B, A>(
        &mut self,
        before: &'cls mut B,
        after: &'cls mut A,
    ) -> &mut Self
    where
        B: FnMut(&mut Printer),
        A: FnMut(&mut Printer),
    {
        self.before_execution = Some(before);
        self.after_execution = Some(after);

        self
    }

    pub(crate) fn do_before(&mut self) {
        if let Some(closure) = &mut self.before_execution {
            let mut printer = Printer::new();
            (closure)(&mut printer);
        }
    }
    pub(crate) fn do_after(&mut self) {
        if let Some(closure) = &mut self.after_execution {
            let mut printer = Printer::new();
            (closure)(&mut printer);
        }
    }
}

impl<'cls> Customizer<'cls> {
    /// Replace the default macro handler.
    ///
    /// The user-defined macro handler may decide to extend the default
    /// behavior by writing custom output with [`write_str`] and calling the
    /// original macro handler by calling [`macro_dflt`].
    ///
    /// ## Example
    ///
    /// Make the output pretier
    ///
    /// ```rust
    /// use gfxd_rs::{Customizer, MacroPrinter};
    ///
    /// let mut macro_fn = |printer: &mut MacroPrinter, _info: &mut _| {
    ///     /* Print 4 spaces before each macro, and a comma and newline after each macro */
    ///     printer.write_str("    ");
    ///     let ret = printer.macro_dflt(); /* Execute the default macro handler */
    ///     printer.write_str(",\n");
    ///     ret
    /// };
    ///
    /// let mut customizer = Customizer::new();
    /// customizer.macro_fn(&mut macro_fn);
    /// ```
    ///
    /// [`write_str`]: MacroPrinter::write_str
    /// [`macro_dflt`]: MacroPrinter::macro_dflt
    pub fn macro_fn<F>(&mut self, callback: &'cls mut F) -> &mut Self
    where
        F: FnMut(&mut MacroPrinter, &mut MacroInfo) -> MacroFnRet,
    {
        self.macro_fn = Some(callback);

        self
    }

    /// Replace the default argument handler.
    ///
    /// The registered callback will be called by [`macro_dflt`] for each
    /// argument in the current macro, not counting the dynamic display list
    /// pointer if one has been specified.
    ///
    /// If the user has overriden the macro handler function and does not call
    /// [`macro_dflt`] in the replacement, then the given callback will never
    /// be called.
    ///
    /// [`macro_dflt`]: MacroPrinter::macro_dflt
    pub fn arg_fn<F>(&mut self, callback: &'cls mut F) -> &mut Self
    where
        F: FnMut(&mut MacroPrinter, &mut MacroInfo, i32),
    {
        self.arg_fn = Some(callback);

        self
    }
}

impl<'cls> Customizer<'cls> {
    /// Register a callback for TLUTs (Texture Look Up Table), a.k.a. palettes.
    ///
    /// The callback may return [`DoDefaultOutput::DoDefault`] to make `gfxd`
    /// to emit the default output for this argument, or
    /// [`DoDefaultOutput::Override`] to avoid emitting the default one and
    /// just use whatever the user printed.
    ///
    /// Emit any desired output by using the `Printer` argument, and inspect
    /// information about the current macro with the `MacroInfo` argument.
    ///
    /// The other arguments are:
    /// - the tlut address,
    /// - the palette index and
    /// - the number of colors.
    pub fn tlut_callback<F>(&mut self, callback: &'cls mut F) -> &mut Self
    where
        F: FnMut(&mut Printer, &mut MacroInfo, Address, Option<u8>, TlutCount) -> DoDefaultOutput,
    {
        self.tlut_fn = Some(callback);
        self
    }

    /// Register a callback for textures of any kind.
    ///
    /// The callback may return [`DoDefaultOutput::DoDefault`] to make `gfxd`
    /// to emit the default output for this argument, or
    /// [`DoDefaultOutput::Override`] to avoid emitting the default one and
    /// just use whatever the user printed.
    ///
    /// Emit any desired output by using the `Printer` argument, and inspect
    /// information about the current macro with the `MacroInfo` argument.
    ///
    /// The other arguments are:
    /// - the texture address,
    /// - the texture format,
    /// - the texture siz,
    /// - the width,
    /// - the height and
    /// - the palette index.
    pub fn timg_callback<F>(&mut self, callback: &'cls mut F) -> &mut Self
    where
        F: FnMut(
            &mut Printer,
            &mut MacroInfo,
            Address,
            TexFmt,
            TexSiz,
            u8,
            u8,
            u8,
        ) -> DoDefaultOutput,
    {
        self.timg_fn = Some(callback);
        self
    }

    /// Register a callback for framebuffers.
    ///
    /// The callback may return [`DoDefaultOutput::DoDefault`] to make `gfxd`
    /// to emit the default output for this argument, or
    /// [`DoDefaultOutput::Override`] to avoid emitting the default one and
    /// just use whatever the user printed.
    ///
    /// Emit any desired output by using the `Printer` argument, and inspect
    /// information about the current macro with the `MacroInfo` argument.
    ///
    /// The other arguments are:
    /// - the framebuffer address,
    /// - the framebuffer format,
    /// - the framebuffer siz and
    /// - the width.
    pub fn cimg_callback<F>(&mut self, callback: &'cls mut F) -> &mut Self
    where
        F: FnMut(&mut Printer, &mut MacroInfo, Address, TexFmt, TexSiz, u16) -> DoDefaultOutput,
    {
        self.cimg_fn = Some(callback);
        self
    }

    /// Register a callback for depthbuffers.
    ///
    /// The callback may return [`DoDefaultOutput::DoDefault`] to make `gfxd`
    /// to emit the default output for this argument, or
    /// [`DoDefaultOutput::Override`] to avoid emitting the default one and
    /// just use whatever the user printed.
    ///
    /// Emit any desired output by using the `Printer` argument, and inspect
    /// information about the current macro with the `MacroInfo` argument.
    ///
    /// The other arguments are:
    /// - the depthbuffer address.
    pub fn zimg_callback<F>(&mut self, callback: &'cls mut F) -> &mut Self
    where
        F: FnMut(&mut Printer, &mut MacroInfo, Address) -> DoDefaultOutput,
    {
        self.zimg_fn = Some(callback);
        self
    }

    /// Register a callback for display lists.
    ///
    /// The callback may return [`DoDefaultOutput::DoDefault`] to make `gfxd`
    /// to emit the default output for this argument, or
    /// [`DoDefaultOutput::Override`] to avoid emitting the default one and
    /// just use whatever the user printed.
    ///
    /// Emit any desired output by using the `Printer` argument, and inspect
    /// information about the current macro with the `MacroInfo` argument.
    ///
    /// The other arguments are:
    /// - the display list address.
    pub fn dl_callback<F>(&mut self, callback: &'cls mut F) -> &mut Self
    where
        F: FnMut(&mut Printer, &mut MacroInfo, Address) -> DoDefaultOutput,
    {
        self.dl_fn = Some(callback);
        self
    }

    /// Register a callback for matrices.
    ///
    /// The callback may return [`DoDefaultOutput::DoDefault`] to make `gfxd`
    /// to emit the default output for this argument, or
    /// [`DoDefaultOutput::Override`] to avoid emitting the default one and
    /// just use whatever the user printed.
    ///
    /// Emit any desired output by using the `Printer` argument, and inspect
    /// information about the current macro with the `MacroInfo` argument.
    ///
    /// The other arguments are:
    /// - the matrix address.
    pub fn mtx_callback<F>(&mut self, callback: &'cls mut F) -> &mut Self
    where
        F: FnMut(&mut Printer, &mut MacroInfo, Address) -> DoDefaultOutput,
    {
        self.mtx_fn = Some(callback);
        self
    }

    /// Register a callback for lookat arrays.
    ///
    /// The callback may return [`DoDefaultOutput::DoDefault`] to make `gfxd`
    /// to emit the default output for this argument, or
    /// [`DoDefaultOutput::Override`] to avoid emitting the default one and
    /// just use whatever the user printed.
    ///
    /// Emit any desired output by using the `Printer` argument, and inspect
    /// information about the current macro with the `MacroInfo` argument.
    ///
    /// The other arguments are:
    /// - the lookat array address and
    /// - the number of lookat structures.
    pub fn lookat_callback<F>(&mut self, callback: &'cls mut F) -> &mut Self
    where
        F: FnMut(&mut Printer, &mut MacroInfo, Address, LookatCount) -> DoDefaultOutput,
    {
        self.lookat_fn = Some(callback);
        self
    }

    /// Register a callback for lights.
    ///
    /// The callback may return [`DoDefaultOutput::DoDefault`] to make `gfxd`
    /// to emit the default output for this argument, or
    /// [`DoDefaultOutput::Override`] to avoid emitting the default one and
    /// just use whatever the user printed.
    ///
    /// Emit any desired output by using the `Printer` argument, and inspect
    /// information about the current macro with the `MacroInfo` argument.
    ///
    /// The other arguments are:
    /// - the light address.
    pub fn light_callback<F>(&mut self, callback: &'cls mut F) -> &mut Self
    where
        F: FnMut(&mut Printer, &mut MacroInfo, Address) -> DoDefaultOutput,
    {
        self.light_fn = Some(callback);
        self
    }

    /// Register a callback for lights N.
    ///
    /// The callback may return [`DoDefaultOutput::DoDefault`] to make `gfxd`
    /// to emit the default output for this argument, or
    /// [`DoDefaultOutput::Override`] to avoid emitting the default one and
    /// just use whatever the user printed.
    ///
    /// Emit any desired output by using the `Printer` argument, and inspect
    /// information about the current macro with the `MacroInfo` argument.
    ///
    /// The other arguments are:
    /// - the light address and
    /// - the number of diffuse lights.
    pub fn lightsn_callback<F>(&mut self, callback: &'cls mut F) -> &mut Self
    where
        F: FnMut(&mut Printer, &mut MacroInfo, Address, LightsNum) -> DoDefaultOutput,
    {
        self.lightsn_fn = Some(callback);
        self
    }

    /// Register a callback for segments.
    ///
    /// The callback may return [`DoDefaultOutput::DoDefault`] to make `gfxd`
    /// to emit the default output for this argument, or
    /// [`DoDefaultOutput::Override`] to avoid emitting the default one and
    /// just use whatever the user printed.
    ///
    /// Emit any desired output by using the `Printer` argument, and inspect
    /// information about the current macro with the `MacroInfo` argument.
    ///
    /// The other arguments are:
    /// - the segment address.
    pub fn seg_callback<F>(&mut self, callback: &'cls mut F) -> &mut Self
    where
        F: FnMut(&mut Printer, &mut MacroInfo, Address, u8) -> DoDefaultOutput,
    {
        self.seg_fn = Some(callback);
        self
    }

    /// Register a callback for vertices.
    ///
    /// The callback may return [`DoDefaultOutput::DoDefault`] to make `gfxd`
    /// to emit the default output for this argument, or
    /// [`DoDefaultOutput::Override`] to avoid emitting the default one and
    /// just use whatever the user printed.
    ///
    /// Emit any desired output by using the `Printer` argument, and inspect
    /// information about the current macro with the `MacroInfo` argument.
    ///
    /// The other arguments are:
    /// - the vertex address.
    pub fn vtx_callback<F>(&mut self, callback: &'cls mut F) -> &mut Self
    where
        F: FnMut(&mut Printer, &mut MacroInfo, Address, i32) -> DoDefaultOutput,
    {
        self.vtx_fn = Some(callback);
        self
    }

    /// Register a callback for viewports.
    ///
    /// The callback may return [`DoDefaultOutput::DoDefault`] to make `gfxd`
    /// to emit the default output for this argument, or
    /// [`DoDefaultOutput::Override`] to avoid emitting the default one and
    /// just use whatever the user printed.
    ///
    /// Emit any desired output by using the `Printer` argument, and inspect
    /// information about the current macro with the `MacroInfo` argument.
    ///
    /// The other arguments are:
    /// - the viewport address.
    pub fn vp_callback<F>(&mut self, callback: &'cls mut F) -> &mut Self
    where
        F: FnMut(&mut Printer, &mut MacroInfo, Address) -> DoDefaultOutput,
    {
        self.vp_fn = Some(callback);
        self
    }

    /// Register a callback for microcode text.
    ///
    /// The callback may return [`DoDefaultOutput::DoDefault`] to make `gfxd`
    /// to emit the default output for this argument, or
    /// [`DoDefaultOutput::Override`] to avoid emitting the default one and
    /// just use whatever the user printed.
    ///
    /// Emit any desired output by using the `Printer` argument, and inspect
    /// information about the current macro with the `MacroInfo` argument.
    ///
    /// The other arguments are:
    /// - the microcode text address and
    /// - the microcode text size.
    pub fn uctext_callback<F>(&mut self, callback: &'cls mut F) -> &mut Self
    where
        F: FnMut(&mut Printer, &mut MacroInfo, Address, NonZeroU32) -> DoDefaultOutput,
    {
        self.uctext_fn = Some(callback);
        self
    }

    /// Register a callback for microcode data.
    ///
    /// The callback may return [`DoDefaultOutput::DoDefault`] to make `gfxd`
    /// to emit the default output for this argument, or
    /// [`DoDefaultOutput::Override`] to avoid emitting the default one and
    /// just use whatever the user printed.
    ///
    /// Emit any desired output by using the `Printer` argument, and inspect
    /// information about the current macro with the `MacroInfo` argument.
    ///
    /// The other arguments are:
    /// - the microcode data address and
    /// - the microcode data size.
    pub fn ucdata_callback<F>(&mut self, callback: &'cls mut F) -> &mut Self
    where
        F: FnMut(&mut Printer, &mut MacroInfo, Address, NonZeroU32) -> DoDefaultOutput,
    {
        self.ucdata_fn = Some(callback);
        self
    }

    /// Register a callback for generic pointers.
    ///
    /// The callback may return [`DoDefaultOutput::DoDefault`] to make `gfxd`
    /// to emit the default output for this argument, or
    /// [`DoDefaultOutput::Override`] to avoid emitting the default one and
    /// just use whatever the user printed.
    ///
    /// Emit any desired output by using the `Printer` argument, and inspect
    /// information about the current macro with the `MacroInfo` argument.
    ///
    /// The other arguments are:
    /// - the generic pointer and
    /// - the data size.
    pub fn dram_callback<F>(&mut self, callback: &'cls mut F) -> &mut Self
    where
        F: FnMut(&mut Printer, &mut MacroInfo, Address, NonZeroU16) -> DoDefaultOutput,
    {
        self.dram_fn = Some(callback);
        self
    }
}

impl Default for Customizer<'_> {
    fn default() -> Self {
        Self::new()
    }
}

/// The return value of argument callbacks.
///
/// Decide if the argument callback should emit the default output or if it
/// should emit no output at all.
#[must_use]
pub enum DoDefaultOutput {
    /// Emit the default output.
    ///
    /// The user may still emit output before the default behavior.
    DoDefault,
    /// Do not emit the default output for this argument.
    Override,
}

impl DoDefaultOutput {
    #[inline]
    #[must_use]
    pub(crate) const fn into_ret(self) -> ffi::c_int {
        match self {
            Self::DoDefault => 0,
            Self::Override => 1,
        }
    }
}

/// Signal if `Gfx` packet processing should continue or stop after the current
/// macro has been processed.
#[must_use]
pub enum MacroFnRet {
    /// Continue processing the data stream.
    Continue,
    /// Stop processing the data stream, even if there's more data left to be
    /// processed.
    Stop,
}

impl MacroFnRet {
    #[inline]
    #[must_use]
    pub(crate) const fn into_ret(self) -> ffi::c_int {
        match self {
            Self::Continue => 0,
            Self::Stop => 1,
        }
    }
}