ssbh_lib 0.19.0

Reading and writing SSBH file formats in Rust
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

//! The [Nufx] format stores data about the shader programs used for rendering.
//! These files typically use the ".nufxlb" suffix like "nuc2effectlibrary.nufxlb".
//! [Nufx] files reference required attributes from [Mesh](crate::formats::mesh::Mesh) files and required parameters from [Matl](crate::formats::matl::Matl) files.

use crate::{SsbhArray, SsbhString, SsbhString8, Version};
use binrw::BinRead;
#[cfg(feature = "serde")]
use serde::{Deserialize, Serialize};
use ssbh_write::SsbhWrite;

// TODO: Just use named fields instead.
// TODO: Test rebuilding with ssbh_batch after changes.
/// A shader effects library that describes shader programs and their associated inputs.
/// Compatible with file version 1.0 and 1.1.
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))]
#[derive(Debug, BinRead, SsbhWrite, Clone, PartialEq)]
#[br(import(major_version: u16, minor_version: u16))]
pub enum Nufx {
    // TODO: Add support for named enum fields to SsbhWrite.
    #[br(pre_assert(major_version == 1 &&  minor_version == 0))]
    V0(NufxV0),

    #[br(pre_assert(major_version == 1 &&  minor_version == 1))]
    V1(NufxV1),
}

impl Version for Nufx {
    fn major_minor_version(&self) -> (u16, u16) {
        match self {
            Nufx::V0(_) => (1, 0),
            Nufx::V1(_) => (1, 1),
        }
    }
}

#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))]
#[derive(Debug, BinRead, SsbhWrite, Clone, PartialEq)]
pub struct NufxV0 {
    pub programs: SsbhArray<ShaderProgramV0>,
    pub unk_string_list: SsbhArray<UnkItem>,
}

#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))]
#[derive(Debug, BinRead, SsbhWrite, Clone, PartialEq)]
pub struct NufxV1 {
    pub programs: SsbhArray<ShaderProgramV1>,
    pub unk_string_list: SsbhArray<UnkItem>,
}

/// A required vertex attribute.
/// The [name](#structfield.name) and [attribute_name](#structfield.attribute_name) should match the values for a corresponding [AttributeV10][crate::formats::mesh::AttributeV10].
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))]
#[derive(Debug, BinRead, SsbhWrite, Clone, PartialEq)]
pub struct VertexAttribute {
    pub name: SsbhString,
    pub attribute_name: SsbhString,
}

/// A required material parameter. The [param_id](#structfield.param_id) and [parameter_name](#structfield.parameter_name) match one of the variants in [ParamId](crate::formats::matl::ParamId).
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))]
#[derive(Debug, BinRead, SsbhWrite, Clone, PartialEq)]
#[ssbhwrite(pad_after = 8)]
pub struct MaterialParameter {
    // TODO: These values are identical to the matl ones but there are some missing variants.
    pub param_id: u64,
    #[br(pad_after = 8)]
    pub parameter_name: SsbhString8,
}

/// Describes the shaders used for each of the stages in the rendering pipeline.
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))]
#[derive(Debug, BinRead, SsbhWrite, Clone, PartialEq)]
pub struct ShaderStages {
    pub vertex_shader: SsbhString,
    pub unk_shader1: SsbhString, // The missing stages could be tesselation, etc.
    pub unk_shader2: SsbhString,
    pub geometry_shader: SsbhString,
    pub pixel_shader: SsbhString,
    pub compute_shader: SsbhString,
}

/// Describes the name and associated information for a set of compiled shaders linked into a program.
/// Each [ShaderProgramV0] has a corresponding shader program object in the underlying rendering API such as OpenGL, Vulkan, etc.
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))]
#[derive(Debug, BinRead, SsbhWrite, Clone, PartialEq)]
pub struct ShaderProgramV0 {
    /// The unique identifier of the shader program, including its [render_pass](#structfield.render_pass).
    pub name: SsbhString,
    /// Programs are grouped into passes to determine the render order.
    /// Possible values for Smash Ultimate are "nu::Final", "nu::Opaque", "nu::Sort", "nu::Near", and "nu::Far".
    pub render_pass: SsbhString,
    /// The shaders to compile and link for this program.
    pub shaders: ShaderStages,
    /// The required parameters from the [Matl](crate::formats::matl::Matl) materials.
    pub material_parameters: SsbhArray<MaterialParameter>,
}

/// Describes the name and associated information for a set of compiled shaders linked into a program.
/// Each [ShaderProgramV1] has a corresponding shader program object in the underlying rendering API such as OpenGL, Vulkan, etc.
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))]
#[derive(Debug, BinRead, SsbhWrite, Clone, PartialEq)]
pub struct ShaderProgramV1 {
    /// The unique identifier of the shader program, including its [render_pass](#structfield.render_pass).
    pub name: SsbhString,
    /// Programs are grouped into passes to determine the render order.
    /// Possible values for Smash Ultimate are "nu::Final", "nu::Opaque", "nu::Sort", "nu::Near", and "nu::Far".
    pub render_pass: SsbhString,
    /// The shaders to compile and link for this program.
    pub shaders: ShaderStages,
    /// The required attributes from the [MeshObject](crate::formats::mesh::MeshObject) such as "Position0".
    pub vertex_attributes: SsbhArray<VertexAttribute>,
    /// The required parameters from the [MatlEntry](crate::formats::matl::MatlEntryV16) such as "RasterizerState0".
    pub material_parameters: SsbhArray<MaterialParameter>,
}

#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))]
#[derive(Debug, BinRead, SsbhWrite, Clone, PartialEq)]
pub struct UnkItem {
    pub name: SsbhString,
    pub unk1: SsbhArray<SsbhString>,
}