encounter/nod-rs
1
0
Fork 0
mirror of https://github.com/encounter/nod-rs.git synced 2025-12-12 14:46:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation updates

Browse Source
This commit is contained in:
Luke Street
2025-03-31 23:33:07 -06:00
parent 9d8cd980b8
commit 4b4564207a
13 changed files with 184 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
nod/src/disc/writer.rs
View File

@@ -16,17 +16,9 @@ use crate::{
wii::{HASHES_SIZE, SECTOR_DATA_SIZE},
},
util::{aes::decrypt_sector_b2b, array_ref, array_ref_mut, lfg::LaggedFibonacci},
write::{DiscFinalization, DiscWriterWeight, ProcessOptions},
write::{DataCallback, DiscFinalization, DiscWriterWeight, ProcessOptions},
};
/// A callback for writing disc data.
///
/// The callback should write all data to the output stream before returning, or return an error if
/// writing fails. The second and third arguments are the current bytes processed and the total
/// bytes to process, respectively. For most formats, this has no relation to the written disc size,
/// but can be used to display progress.
pub type DataCallback<'a> = dyn FnMut(Bytes, u64, u64) -> io::Result<()> + 'a;
/// A trait for writing disc images.
pub trait DiscWriter: DynClone {
/// Processes the disc writer to completion.

6
nod/src/io/ciso.rs
View File

@@ -15,8 +15,8 @@ use crate::{
SECTOR_SIZE,
reader::DiscReader,
writer::{
BlockProcessor, BlockResult, CheckBlockResult, DataCallback, DiscWriter, check_block,
par_process, read_block,
BlockProcessor, BlockResult, CheckBlockResult, DiscWriter, check_block, par_process,
read_block,
},
},
io::{
@@ -31,7 +31,7 @@ use crate::{
read::{box_to_bytes, read_arc_at},
static_assert,
},
write::{DiscFinalization, DiscWriterWeight, FormatOptions, ProcessOptions},
write::{DataCallback, DiscFinalization, DiscWriterWeight, FormatOptions, ProcessOptions},
};
pub const CISO_MAP_SIZE: usize = SECTOR_SIZE - 8;

4
nod/src/io/gcz.rs
View File

@@ -15,7 +15,7 @@ use crate::{
disc::{
SECTOR_SIZE,
reader::DiscReader,
writer::{BlockProcessor, BlockResult, DataCallback, DiscWriter, par_process, read_block},
writer::{BlockProcessor, BlockResult, DiscWriter, par_process, read_block},
},
io::block::{Block, BlockKind, BlockReader, GCZ_MAGIC},
read::{DiscMeta, DiscStream},
@@ -25,7 +25,7 @@ use crate::{
read::{read_arc_slice_at, read_at},
static_assert,
},
write::{DiscFinalization, DiscWriterWeight, FormatOptions, ProcessOptions},
write::{DataCallback, DiscFinalization, DiscWriterWeight, FormatOptions, ProcessOptions},
};
/// GCZ header (little endian)

8
nod/src/io/iso.rs
View File

@@ -3,15 +3,11 @@ use std::{io, io::BufRead};
use crate::{
Result, ResultContext,
common::Format,
disc::{
SECTOR_SIZE,
reader::DiscReader,
writer::{DataCallback, DiscWriter},
},
disc::{SECTOR_SIZE, reader::DiscReader, writer::DiscWriter},
io::block::{Block, BlockKind, BlockReader},
read::{DiscMeta, DiscStream},
util::digest::DigestManager,
write::{DiscFinalization, DiscWriterWeight, ProcessOptions},
write::{DataCallback, DiscFinalization, DiscWriterWeight, ProcessOptions},
};
#[derive(Clone)]

4
nod/src/io/tgc.rs
View File

@@ -16,7 +16,7 @@ use crate::{
fst::Fst,
gcn::{read_dol, read_fst},
reader::DiscReader,
writer::{DataCallback, DiscWriter},
writer::DiscWriter,
},
io::block::{Block, BlockKind, BlockReader, TGC_MAGIC},
read::{DiscMeta, DiscStream, PartitionOptions, PartitionReader},
@@ -25,7 +25,7 @@ use crate::{
read::{read_arc_at, read_arc_slice_at, read_at, read_with_zero_fill},
static_assert,
},
write::{DiscFinalization, DiscWriterWeight, FormatOptions, ProcessOptions},
write::{DataCallback, DiscFinalization, DiscWriterWeight, FormatOptions, ProcessOptions},
};
/// TGC header (big endian)

6
nod/src/io/wbfs.rs
View File

@@ -15,8 +15,8 @@ use crate::{
SECTOR_SIZE,
reader::DiscReader,
writer::{
BlockProcessor, BlockResult, CheckBlockResult, DataCallback, DiscWriter, check_block,
par_process, read_block,
BlockProcessor, BlockResult, CheckBlockResult, DiscWriter, check_block, par_process,
read_block,
},
},
io::{
@@ -30,7 +30,7 @@ use crate::{
lfg::LaggedFibonacci,
read::{read_arc_slice_at, read_at, read_box_slice_at},
},
write::{DiscFinalization, DiscWriterWeight, FormatOptions, ProcessOptions},
write::{DataCallback, DiscFinalization, DiscWriterWeight, FormatOptions, ProcessOptions},
};
#[derive(Debug, Clone, PartialEq, FromBytes, IntoBytes, Immutable, KnownLayout)]

4
nod/src/io/wia.rs
View File

@@ -20,7 +20,7 @@ use crate::{
fst::Fst,
reader::DiscReader,
wii::{HASHES_SIZE, SECTOR_DATA_SIZE},
writer::{BlockProcessor, BlockResult, DataCallback, DiscWriter, par_process, read_block},
writer::{BlockProcessor, BlockResult, DiscWriter, par_process, read_block},
},
io::{
block::{Block, BlockKind, BlockReader, RVZ_MAGIC, WIA_MAGIC},
@@ -40,7 +40,7 @@ use crate::{
},
static_assert,
},
write::{DiscFinalization, DiscWriterWeight, FormatOptions, ProcessOptions},
write::{DataCallback, DiscFinalization, DiscWriterWeight, FormatOptions, ProcessOptions},
};
const WIA_VERSION: u32 = 0x01000000;

56
nod/src/lib.rs
View File

@@ -1,16 +1,16 @@
#![allow(clippy::new_ret_no_self)]
#![warn(missing_docs)]
//! Library for traversing & reading Nintendo Optical Disc (GameCube and Wii) images.
//! Library for reading and writing Nintendo Optical Disc (GameCube and Wii) images.
//!
//! Originally based on the C++ library [nod](https://github.com/AxioDL/nod),
//! but does not currently support authoring.
//! but with extended format support and many additional features.
//!
//! Currently supported file formats:
//! - ISO (GCM)
//! - WIA / RVZ
//! - WBFS (+ NKit 2 lossless)
//! - CISO (+ NKit 2 lossless)
//! - NFS (Wii U VC)
//! - NFS (Wii U VC, read-only)
//! - GCZ
//! - TGC
//!
@@ -75,11 +75,16 @@
//! Converting a disc image to RVZ:
//!
//! ```no_run
//! use std::fs::File;
//! use std::io::{Seek, Write};
//! use nod::common::{Compression, Format};
//! use nod::read::{DiscOptions, DiscReader, PartitionEncryption};
//! use nod::write::{DiscWriter, DiscWriterWeight, FormatOptions, ProcessOptions};
//! use std::{
//! fs::File,
//! io::{Seek, Write},
//! };
//!
//! use nod::{
//! common::{Compression, Format},
//! read::{DiscOptions, DiscReader, PartitionEncryption},
//! write::{DiscWriter, DiscWriterWeight, FormatOptions, ProcessOptions},
//! };
//!
//! let open_options = DiscOptions {
//! partition_encryption: PartitionEncryption::Original,
@@ -88,11 +93,9 @@
//! preloader_threads: 4,
//! };
//! // Open a disc image.
//! let disc = DiscReader::new("path/to/file.iso", &open_options)
//! .expect("Failed to open disc");
//! let disc = DiscReader::new("path/to/file.iso", &open_options).expect("Failed to open disc");
//! // Create a new output file.
//! let mut output_file = File::create("output.rvz")
//! .expect("Failed to create output file");
//! let mut output_file = File::create("output.rvz").expect("Failed to create output file");
//!
//! let options = FormatOptions {
//! format: Format::Rvz,
@@ -100,8 +103,7 @@
//! block_size: Format::Rvz.default_block_size(),
//! };
//! // Create a disc writer with the desired output format.
//! let mut writer = DiscWriter::new(disc, &options)
//! .expect("Failed to create writer");
//! let mut writer = DiscWriter::new(disc, &options).expect("Failed to create writer");
//!
//! // Ideally we'd base this on the actual number of CPUs available.
//! // This is just an example.
@@ -121,29 +123,29 @@
//! digest_xxh64: true,
//! };
//! // Start processing the disc image.
//! let finalization = writer.process(
//! |data, _progress, _total| {
//! output_file.write_all(data.as_ref())?;
//! // One could display progress here, if desired.
//! Ok(())
//! },
//! &process_options
//! )
//! .expect("Failed to process disc image");
//! let finalization = writer
//! .process(
//! |data, _progress, _total| {
//! output_file.write_all(data.as_ref())?;
//! // One could display progress here, if desired.
//! Ok(())
//! },
//! &process_options,
//! )
//! .expect("Failed to process disc image");
//!
//! // Some disc writers calculate data during processing.
//! // If the finalization returns header data, seek to the beginning of the file and write it.
//! if !finalization.header.is_empty() {
//! output_file.rewind()
//! .expect("Failed to seek");
//! output_file.write_all(finalization.header.as_ref())
//! .expect("Failed to write header");
//! output_file.rewind().expect("Failed to seek");
//! output_file.write_all(finalization.header.as_ref()).expect("Failed to write header");
//! }
//! output_file.flush().expect("Failed to flush output file");
//!
//! // Display the calculated digests.
//! println!("CRC32: {:08X}", finalization.crc32.unwrap());
//! // ...
//! ```
pub mod build;
pub mod common;

35
nod/src/read.rs
View File

@@ -167,16 +167,15 @@ where T: Read + Seek + Send
///
/// This is the primary entry point for reading disc images.
#[derive(Clone)]
pub struct DiscReader {
inner: disc::reader::DiscReader,
}
#[repr(transparent)]
pub struct DiscReader(disc::reader::DiscReader);
impl DiscReader {
/// Opens a disc image from a file path.
pub fn new<P: AsRef<Path>>(path: P, options: &DiscOptions) -> Result<DiscReader> {
let io = block::open(path.as_ref())?;
let inner = disc::reader::DiscReader::new(io, options)?;
Ok(DiscReader { inner })
Ok(DiscReader(inner))
}
/// Opens a disc image from a [`DiscStream`]. This allows low-overhead, multithreaded
@@ -185,8 +184,8 @@ impl DiscReader {
/// See [`DiscStream`] for more information.
pub fn new_stream(stream: Box<dyn DiscStream>, options: &DiscOptions) -> Result<DiscReader> {
let io = block::new(stream)?;
let reader = disc::reader::DiscReader::new(io, options)?;
Ok(DiscReader { inner: reader })
let inner = disc::reader::DiscReader::new(io, options)?;
Ok(DiscReader(inner))
}
/// Opens a disc image from a [`Read`] + [`Seek`] stream that can be cloned.
@@ -217,27 +216,27 @@ impl DiscReader {
/// The disc's primary header.
#[inline]
pub fn header(&self) -> &DiscHeader { self.inner.header() }
pub fn header(&self) -> &DiscHeader { self.0.header() }
/// The Wii disc's region information.
///
/// **GameCube**: This will return `None`.
#[inline]
pub fn region(&self) -> Option<&[u8; REGION_SIZE]> { self.inner.region() }
pub fn region(&self) -> Option<&[u8; REGION_SIZE]> { self.0.region() }
/// Returns extra metadata included in the disc file format, if any.
#[inline]
pub fn meta(&self) -> DiscMeta { self.inner.meta() }
pub fn meta(&self) -> DiscMeta { self.0.meta() }
/// The disc's size in bytes, or an estimate if not stored by the format.
#[inline]
pub fn disc_size(&self) -> u64 { self.inner.disc_size() }
pub fn disc_size(&self) -> u64 { self.0.disc_size() }
/// A list of Wii partitions on the disc.
///
/// **GameCube**: This will return an empty slice.
#[inline]
pub fn partitions(&self) -> &[PartitionInfo] { self.inner.partitions() }
pub fn partitions(&self) -> &[PartitionInfo] { self.0.partitions() }
/// Opens a decrypted partition read stream for the specified partition index.
///
@@ -248,7 +247,7 @@ impl DiscReader {
index: usize,
options: &PartitionOptions,
) -> Result<Box<dyn PartitionReader>> {
self.inner.open_partition(index, options)
self.0.open_partition(index, options)
}
/// Opens a decrypted partition read stream for the first partition matching
@@ -261,28 +260,28 @@ impl DiscReader {
kind: PartitionKind,
options: &PartitionOptions,
) -> Result<Box<dyn PartitionReader>> {
self.inner.open_partition_kind(kind, options)
self.0.open_partition_kind(kind, options)
}
pub(crate) fn into_inner(self) -> disc::reader::DiscReader { self.inner }
pub(crate) fn into_inner(self) -> disc::reader::DiscReader { self.0 }
}
impl BufRead for DiscReader {
#[inline]
fn fill_buf(&mut self) -> io::Result<&[u8]> { self.inner.fill_buf() }
fn fill_buf(&mut self) -> io::Result<&[u8]> { self.0.fill_buf() }
#[inline]
fn consume(&mut self, amt: usize) { self.inner.consume(amt) }
fn consume(&mut self, amt: usize) { self.0.consume(amt) }
}
impl Read for DiscReader {
#[inline]
fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> { self.inner.read(buf) }
fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> { self.0.read(buf) }
}
impl Seek for DiscReader {
#[inline]
fn seek(&mut self, pos: io::SeekFrom) -> io::Result<u64> { self.inner.seek(pos) }
fn seek(&mut self, pos: io::SeekFrom) -> io::Result<u64> { self.0.seek(pos) }
}
/// Extra metadata about the underlying disc file format.

2
nod/src/util/mod.rs
View File

@@ -14,7 +14,7 @@ pub(crate) mod digest;
pub mod lfg;
pub(crate) mod read;
/// Copies from a buffered reader to a writer without extra allocations.
/// Copies from a [`BufRead`] to a [`Write`] without allocating a buffer.
pub fn buf_copy<R, W>(reader: &mut R, writer: &mut W) -> io::Result<u64>
where
R: BufRead + ?Sized,

27
nod/src/write.rs
View File

@@ -1,5 +1,7 @@
//! [`DiscWriter`] and associated types.
use std::io;
use bytes::Bytes;
use crate::{
@@ -70,13 +72,20 @@ pub struct ProcessOptions {
pub digest_xxh64: bool,
}
/// A callback for writing disc data.
///
/// The callback should write all data to the output stream before returning, or return an error if
/// writing fails. The second and third arguments are the current bytes processed and the total
/// bytes to process, respectively. For most formats, this has no relation to the written disc size,
/// but can be used to display progress.
pub type DataCallback<'a> = dyn FnMut(Bytes, u64, u64) -> io::Result<()> + 'a;
/// A constructed disc writer.
///
/// This is the primary entry point for writing disc images.
#[derive(Clone)]
pub struct DiscWriter {
inner: Box<dyn disc::writer::DiscWriter>,
}
#[repr(transparent)]
pub struct DiscWriter(Box<dyn disc::writer::DiscWriter>);
impl DiscWriter {
/// Creates a new disc writer with the specified format options.
@@ -101,31 +110,33 @@ impl DiscWriter {
Format::Wia | Format::Rvz => crate::io::wia::DiscWriterWIA::new(reader, &options)?,
format => return Err(Error::Other(format!("Unsupported write format: {format}"))),
};
Ok(DiscWriter { inner })
Ok(DiscWriter(inner))
}
/// Processes the disc writer to completion, calling the data callback, in order, for each block
/// of data to write to the output file. The callback should write all data before returning, or
/// return an error if writing fails.
///
/// See [`DataCallback`] for more information.
#[inline]
pub fn process(
&self,
mut data_callback: impl FnMut(Bytes, u64, u64) -> std::io::Result<()>,
mut data_callback: impl FnMut(Bytes, u64, u64) -> io::Result<()>,
options: &ProcessOptions,
) -> Result<DiscFinalization> {
self.inner.process(&mut data_callback, options)
self.0.process(&mut data_callback, options)
}
/// Returns the progress upper bound for the disc writer. For most formats, this has no
/// relation to the written disc size, but can be used to display progress.
#[inline]
pub fn progress_bound(&self) -> u64 { self.inner.progress_bound() }
pub fn progress_bound(&self) -> u64 { self.0.progress_bound() }
/// Returns the weight of the disc writer, which can help determine the number of threads to
/// dedicate for output processing. This may depend on the format's configuration, such as
/// whether compression is enabled.
#[inline]
pub fn weight(&self) -> DiscWriterWeight { self.inner.weight() }
pub fn weight(&self) -> DiscWriterWeight { self.0.weight() }
}
/// Data returned by the disc writer after processing.