brres-sys

在librii的g3d的JSON导出导入层之上实现Rust层。重要的是，像纹理数据和顶点数据这样的大型缓冲区实际上并没有在JSON中编码，而是直接作为二进制块传递。这使得JSON文件保持轻量。

公开以下Rust接口

pub struct CBrresWrapper<'a> {
    pub json_metadata: &'a str,
    pub buffer_data: &'a [u8],
    // ...
}

impl<'a> CBrresWrapper<'a> {
	// .bin -> .json
    pub fn from_bytes(buf: &[u8]) -> anyhow::Result<Self>;
    // .json -> .bin
    pub fn write_bytes(json: &str, buffer: &[u8]) -> anyhow::Result<Self>;
}

这封装了以下C接口，仍然可以使用（例如，用于其他语言绑定）。

// include/brres_sys.h
struct CResult {
	const char* json_metadata;
	uint32_t len_json_metadata;
	const void* buffer_data;
	uint32_t len_buffer_data;
	void (*freeResult)(struct CResult* self);
	void* opaque;
};
uint32_t brres_read_from_bytes(CResult* result, const void* buf,
                               uint32_t len);
uint32_t brres_write_bytes(CResult* result, const char* json,
                          uint32_t json_len, const void* buffer,
                          uint32_t buffer_len);
void brres_free(CResult* result);

内部API文档

1. 测试

每个BRRES格式都经过验证，以产生1:1字节数据相同的输出，即使是中间表示（见下文）。测试可以在tests文件夹中找到。

2. BRRES子文件

* SrtAnim 目前为只读；BinaryArchive 目前包含可读写的 BinarySrt。

librii为每种文件类型提供两个结构

1. 二进制表示：设计为与格式的1:1映射。直接编辑此内容可能需要大量记录并容易出错。然而，即使是损坏的模型通常也可以在这里解析。
2. 中间表示：足够简单以涵盖所有官方生成的模型，但并非更简单。易于编辑；有很多验证。可能在用jank工具创建的社区模型上失败。

将BRRES文件解析为二进制表示形式（BinaryArchive）

std::expected<librii::g3d::BinaryArchive, std::string> parsed_brres = librii::g3d::BinaryArchive::read(reader, transaction);
if (!parsed_brres) {
    return std::unexpected(std::format("Failed to parse BRRES with error: {}", parsed_brres.error()));
}

将BinaryArchive解包为中间表示形式（Archive）

std::expected<librii::g3d::Archive, std::string> archive = librii::g3d::Archive::from(*parsed_brres);
if (!archive) {
    return std::unexpected(std::format("Failed to unpack BRRES file with error: {}", archive.error()));
}
librii::g3d::Archive data(std::move(*archive));
for (const auto &model : data.models) {
    printf("%s\n", std::format("Model: {} with {} materials", model.name, model.materials.size()).c_str());
}

3. MDL0子文件

特别提供MDL0（BinaryModel，Model）的信息

*** BinaryTev通常被一个包含仅BinaryTev设置的TEV字段的gx::LowLevelGxMaterial实例所取代。

*** 纹理链接总是重新计算。如果一个模型有无效的纹理链接，只需通过BinaryModel传递数据即可纠正。

**** 不支持调色板。

建议您在可能的情况下始终使用中间表示形式。 G3dMaterialData直接满足LowLevelGxMaterial，这使得它与librii::gl的着色器编译器兼容。当然，一个BinaryMaterial + BinaryTev（以部分gx::LowLevelGxMaterial的形式）组合可以通过启用TEV合并的MatIO的函数fromBinMat(...) -> gx::LowLevelGxMaterial进行渲染。

示例用法（低级API）

例如以下惯用的C代码

#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>

#include "include/brres_sys.h"

int main() {
	uint8_t my_brres_file[] = { /* ... */ }; // Initialize with actual .brres file data

	CResult result = {};
	uint32_t ok = brres_read_from_bytes(&result, my_brres_file, sizeof(my_brres_file));

	if (!ok) {
		printf("Failed to read .brres: %*.s\n", (size_t)result.len_json_metadata, result.json_metadata);
		brres_free(&result); // Free the error message
		return 1;
	}

	// Write JSON metadata to a file
	FILE *json_file = fopen("output.json", "wb");
	if (json_file == NULL) {
		perror("Failed to open output.json for writing");
		brres_free(&result);
		return 1;
	}

	size_t written = fwrite(result.json_metadata, 1, result.len_json_metadata, json_file);
	if (written != result.len_json_metadata) {
		perror("Failed to write all JSON metadata to output.json");
		fclose(json_file);
		brres_free(&result);
		return 1;
	}

	fclose(json_file);

	// Write binary buffer data to a file
	FILE *bin_file = fopen("output.bin", "wb");
	if (bin_file == NULL) {
		perror("Failed to open output.bin for writing");
		brres_free(&result);
		return 1;
	}

	written = fwrite(result.buffer_data, 1, result.len_buffer_data, bin_file);
	if (written != result.len_buffer_data) {
		perror("Failed to write all buffer data to output.bin");
		fclose(bin_file);
		brres_free(&result);
		return 1;
	}

	fclose(bin_file);
	brres_free(&result);

	return 0;
}