refactor a bunch of stuff, add Platform, amiga & adf features

Author: dbalsom

.clippy.toml

@@ -1 +1 @@
-# All my preferences are no longer supported :(
+# Moved to cargo.toml

CHANGELOG.md

@@ -2,19 +2,25 @@
 
 ### Features:
 
-- Added a convenience wrapper, StandardFormatParam, for use with parsing user input into StandardFormat
-- Added silly visualization functions to map a Pixmap to a DiskImage. See the png2disk crate for usage.
-- Added DiskCh, DiskChs and DiskChsn iterators for walking geometries of a StandardFormat
-- Added a StandardSectorView interface that provides Read + Write + Seek traits for a DiskImage
+- Added a `Platform` enumeration that defines the computing platform a disk image is intended for.
+- Added a `TrackSchema` enumeration that defines the specific format of a disk track
+- Added `ParserReadOptions` and `ParserWriteOptions` parameters to `ImageFileParser` to eventually better control
+  disk image reading and writing.
+- Added a convenience wrapper, `StandardFormatParam`, for use with parsing user input into `StandardFormat`s
+- Added silly visualization functions to map a Pixmap to a `DiskImage`. See the png2disk crate for usage.
+- Added `DiskCh`, `DiskChs` and `DiskChsn` iterators for walking through sector layouts conforming to a `StandardFormat`
+- Added a `StandardSectorView` interface wrapper that provides `Read` + `Write` + `Seek` traits for a `DiskImage`
 - Added basic FAT support and example
 - Added progress reporting for MFI loader.
+- Added support for high density MFI images.
 - Added support for WEAK chunk in PRI images.
 - Added support for PFI (PCE Flux Image) images
 - Added support for visualization of bitstream errors
 - Added offset fields to track interface functions to support tracks with duplicate sector IDs
-- Implemented DiskChsnQuery struct to enable optional matching of Sector ID fields when scanning, reading, or writing
+- Implemented `DiskChsnQuery` struct to enable optional matching of Sector ID fields when scanning, reading, or writing
   a sector.
-    - Type aliased to SectorIdQuery
+    - Type aliased to `SectorIdQuery`
+- Added several feature flags to fine-tune desired fluxfox functionality and dependencies
 
 ### Bugfixes:
 
@@ -28,25 +34,39 @@
 
 ### Breaking changes:
 
-- read_sector operations no longer require a mutable reference.
-- Several changes to DiskCh* structs and trait implementations.
-- Moved common type imports to fluxfox::prelude
-- Removed get_* prefixes from API per Rust style guidelines.
-- Removed Invalid variant of StandardFormat. Removed From<> and implemented TryFrom<usize>
-- All add_track_* API functions now return a mutable reference to the new track on success
+- Removed `default_sector_size` from `DiskDescriptor`.
+- `add_track_bitstream` now takes a `BitStreamTrackParams` reference.
+- `add_track_fluxstream` now takes a `FluxStreamTrackParams` reference.
+- `add_track_metasector` now takes a `MetaSectorTrackParams` reference.
+- `load_image` and `save_image` methods of `ImageFileParser` now take a `ParserReadOptions` and `ParserWriteOptions`
+  reference, respectively.
+- `ImageWriter` now takes a reference to `DiskImage` in `new` instead of `write`.
+- `track_stream` and `track_stream_mut` methods of `Track` were renamed to `stream` and `stream_mut`.
+- `read_track` and `read_track_raw` methods of `Track` were renamed to `read` and `read_raw`.
+- Renamed `DiskConsistency` to `DiskAnalysis`, and `TrackConsistency` to `TrackAnalysis`.
+    - "Consistency" was a somewhat imprecise and confusing term.
+    - `track_consistency` was renamed to `analysis`
+- Renamed many 'Disk*' enums to 'Track*' to be more clear that these parameters may vary per track.
+    - `DiskDensity` -> `TrackDensity`
+    - `DiskDataEncoding` -> `TrackDataEncoding`
+    - `DiskDataRate` -> `TrackDataRate`
+- `BiosParameterBlock2` and `BiosParameterBlock2` now implement `try_from<StandardFormat>` instead of
+  `from<StandardFormat>` to support non-pc `StandardFormat`s
+- `read_sector()` method of `DiskImage` and `Track` no longer requires a mutable reference.
+- Several changes to `DiskCh*` structs and trait implementations.
+- Moved common type imports to `fluxfox::prelude`
+- Removed `get_*` prefixes from API per Rust style guidelines.
+- Removed the `Invalid` variant of `StandardFormat`. Replaced `From<usize>` with`TryFrom<usize>`
+- All `add_track_*` API functions now return a mutable reference to the new `Track` on success
 - Track API changes
-    - Implemented DiskChsnQuery struct for optional matching of Sector ID fields
-    - Added bit offset field to track sector read and write functions to support tracks with duplicate sector IDs
-- Factored common sector attributes into SectorAttributes struct. Affects SectorDescriptor and SectorMapEntry.
-- Renamed RwSectorScope::DataBlock to RwSectorScope::DataElement
-- Changed DiskCh::seek_next_track() to take a mutable reference to self.
-- Renamed render_track_weak_bits() to render_track_map() which can render track maps
-  defined by RenderMapType
-
-### Dependency updates:
-
-- thiserror = "2.0"
-- regex = "1.11"
+    - Implemented `DiskChsnQuery` struct for optional matching of Sector ID fields
+    - Added an optional bit offset field to track `read_sector`, `scan_sector` and `write_sector` methods to support
+      tracks with duplicate sector IDs
+- Factored common sector attributes into `SectorAttributes` struct. Affects `SectorDescriptor` and `SectorMapEntry`.
+- Renamed `RwSectorScope::DataBlock` to `RwSectorScope::DataElement` for internal naming consistency
+- Changed `DiskCh::seek_next_track()` to take a mutable reference to self.
+- Replaced `render_track_weak_bits()` with `render_track_map()` which can render different kinds of track masks
+  defined by `RenderMapType`
 
 ## 0.1.0 (2024-11-07)
 

Cargo.lock

@@ -17,41 +17,78 @@ keywords.workspace = true
 repository.workspace = true
 license.workspace = true
 
+# Workspace definition
+# ----------------------------------------------------------------------------------------------------------------------
+[workspace]
+members = [
+    "examples/async",
+    "examples/serde_demo",
+    "examples/imginfo",
+    "examples/imgdump",
+    "examples/imgviz",
+    "crates/png2disk",
+    "crates/ffedit",
+    "crates/fftool",
+    "crates/ff_egui_app",
+    "crates/ff_egui_lib",
+    "examples/fat"
+]
+
+# Required dependencies
+# ----------------------------------------------------------------------------------------------------------------------
 [dependencies]
 bit-vec = "0.8"
-bitflags = "2.6.0"
+bitflags = "2.6"
 binrw = "0.14"
 thiserror = "2.0"
 logger = "0.4"
 env_logger = "0.11"
-regex = "1.10"
-log = "0.4.22"
-rand = "0.8.5"
-sha1_smol = "1.0.1"
+regex = "1.11"
+log = "0.4"
+rand = "0.8"
+sha1_smol = "1.0"
+dyn-clone = "1.0"
+strum = { version = "0.26", features = ["derive"] }
+
+# Optional dependencies
+# ----------------------------------------------------------------------------------------------------------------------
 
-# Dependencies for optional features
 # Num-traits and num-derive are used by retrocompressor ('td0' feature)
-num-traits = { version = "0.2.14", optional = true }
+num-traits = { version = "0.2", optional = true }
 num-derive = { version = "0.4", optional = true }
 
 # tiny-skia is used by visualization functions ('viz' feature)
 tiny-skia = { version = "0.11", optional = true }
 
 # flate2 is required for MFI decompression ('mfi' feature)
 flate2 = { version = "1.0", optional = true }
-histogram = "0.11"
-plotly = { version = "0.10", optional = true }
+
+# histogram is required for flux timing detection / PLL initialization
+histogram = { version = "0.11", optional = true }
+
+# plotly is used for plotting flux timings
+plotly = { version = "0.11", optional = true }
+
+# serde is used for serialization / deserialization of app state and disk images ('serde' feature)
 serde = { version = "1.0", optional = true }
+
+# typetag is used for serialization / deserialization of dyn trait objects ('serde' feature)
 typetag = { version = "0.2", optional = true }
+
 wasm-bindgen-futures = { version = "0.4", optional = true }
 
+# fluxfox_fat is used for reading FAT12/16/32 filesystems if 'fat' feature is enabled
 fluxfox_fat = { git = "https://github.com/dbalsom/fluxfox_fat.git", package = "fatfs", branch = "bpb_fix", default-features = false, features = ["std", "alloc", "log_level_debug"], optional = true }
 
+# Native dependencies
+# ----------------------------------------------------------------------------------------------------------------------
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
 zip = { version = "2.1", default-features = false, features = ["bzip2", "deflate", "deflate64", "lzma", "time", "zstd"], optional = true }
 tar = { version = "0.4", optional = true }
 tokio = { version = "1", optional = true, features = ["full"] }
 
+# Wasm32 dependencies
+# ----------------------------------------------------------------------------------------------------------------------
 [target.'cfg(target_arch = "wasm32")'.dependencies]
 getrandom = { version = "0.2", features = ["js"] }
 zip = { version = "2.1", default-features = false, features = ["deflate", "deflate64", "lzma"], optional = true }
@@ -61,49 +98,66 @@ tar = { version = "0.4", optional = true }
 wasm-bindgen = { version = "0.2", optional = true }
 wasm-bindgen-futures = { version = "0.4", optional = true }
 
+# Dev dependencies
+# ----------------------------------------------------------------------------------------------------------------------
 [dev-dependencies]
-sha1 = "0.10.6"
+sha1 = "0.10"
 hex = "0.4"    # or the latest version
 
-[workspace]
-members = [
-    "examples/async",
-    "examples/serde_demo",
-    "examples/imginfo",
-    "examples/imgdump",
-    "examples/imgviz",
-    "crates/png2disk",
-    "crates/ffedit",
-    "crates/fftool",
-    "crates/ff_egui_app", 
-    "crates/ff_egui_lib"
-, "examples/fat"]
-
 [features]
-default = ["viz", "zip", "tar", "mfi", "td0", "fat"]
+default = ["viz", "zip", "tar", "mfi", "fat", "flux", "ibmpc", "amiga"]
 wasm = ["async", "wasm-bindgen", "wasm-bindgen-futures"]
 serde = ["dep:serde", "dep:typetag", "bit-vec/serde_std", "bitflags/serde"]
 tokio-async = ["async", "tokio"]
 async = []
+# ibmpc feature enables IBM PC-specific disk image support (not fully factored out at the moment)
+ibmpc = ["td0"]
+# amiga feature enables Amiga-specific disk image support
+amiga = ["adf"]
+# viz feature enables visualization functions - will pull in tiny-skia dependency for drawing
 viz = ["dep:tiny-skia"]
+# zip feature enables reading zipped images, as well as reading/writing zip files from FileSystem interfaces
 zip = ["dep:zip"]
+# tar feature enables reading tar files from FileSystem interfaces
 tar = ["dep:tar"]
-mfi = ["dep:flate2"]
-td0 = ["dep:num-traits", "dep:num-derive"]
+# fat feature enables reading FAT12/16/32 filesystems. This will pull in fluxfox_fat dependency
 fat = ["dep:fluxfox_fat"]
+# flux feature enables reading flux images. This will pull in histogram dependency
+flux = ["dep:histogram"]
+# plotly feature enables export of flux timings to plotly (perhaps this should not be internal to fluxfox?)
 plot = ["dep:plotly"]
 
+# Disk Image File Format Features
+# ----------------------------------------------------------------------------------------------------------------------
+# mfi feature enables reading MFI images. This will pull in flate2 dependency for compression/decompression
+mfi = ["dep:flate2", "flux"]
+# td0 feature enables reading TD0 images. This will pull in num-traits and num-derive dependencies and LZW/LZHUF
+# routines for compression/decompression
+td0 = ["dep:num-traits", "dep:num-derive"]
+# adf feature enables reading Amiga ADF images. This does not require an additional format parser, instead it is used to
+# enable reading/writing StandardFormat::Amiga880k images in the `raw` parser and StandardSectorView, as well as
+# advertising the ADF extension.
+adf = []
+
+# Clippy lint control
+# ----------------------------------------------------------------------------------------------------------------------
 [lints.clippy]
+# We will eventually take this advice, but not now
 too-many-arguments = "allow"
+# Sometimes adding + 0 helps line things up. There's no harm in it
 identity_op = "allow"
 
+# Build profiles
+# ----------------------------------------------------------------------------------------------------------------------
 [profile.release]
+# Most aggressive LTO profile
 lto = "thin"
 
 [profile.release.package.ff_egui_app]
-opt-level = 2 # fast and small wasm
+# Fast and small wasm
+opt-level = 2
 
-# Optimize all dependencies even in debug builds:
+# Optimize all dependencies even in debug builds
 [profile.dev.package."*"]
 opt-level = 2
 

Cargo.toml

@@ -21,7 +21,7 @@ eframe = { version = "0.29", default-features = false, features = [
 egui_extras = { version = "0.29", default-features = false, features = ["http", "image"] }
 image = { version = "0.25", default-features = false, features = ["png"] }
 log = "0.4"
-fluxfox = { path = "../..", default-features = false, features = ["serde", "zip", "tar", "mfi", "wasm", "viz", "fat"] }
+fluxfox = { path = "../..", default-features = false, features = ["serde", "zip", "tar", "mfi", "wasm", "viz", "fat", "ibmpc", "amiga"] }
 fluxfox_egui = { path = "../ff_egui_lib" }
 
 # We don't need tiny_skia's png support since egui is pulling in image anyway.

crates/ff_egui_app/Cargo.toml

@@ -25,10 +25,7 @@
     --------------------------------------------------------------------------
 */
 use fluxfox::prelude::*;
-use fluxfox_egui::{
-    widgets::data_table::{DataRange, DataTableWidget},
-    SectorSelection,
-};
+use fluxfox_egui::{widgets::data_table::DataTableWidget, SectorSelection};
 use std::sync::{Arc, RwLock};
 
 #[derive(Default)]

crates/ff_egui_app/src/windows/sector_viewer.rs

@@ -27,7 +27,6 @@
 use fluxfox::prelude::*;
 use fluxfox_egui::{
     widgets::data_table::{DataRange, DataTableWidget},
-    SectorSelection,
     TrackSelection,
 };
 use std::sync::{Arc, RwLock};
@@ -68,7 +67,7 @@ impl TrackViewer {
             }
         };
 
-        let rtr = match track_ref.read_track(None) {
+        let rtr = match track_ref.read(None) {
             Ok(rtr) => rtr,
             Err(e) => {
                 log::error!("Error reading sector: {:?}", e);

crates/ff_egui_app/src/windows/track_viewer.rs

@@ -36,9 +36,9 @@ pub struct DiskInfoWidget {
     pub filename: Option<String>,
     pub resolution: DiskDataResolution,
     pub geometry: DiskCh,
-    pub rate: DiskDataRate,
-    pub encoding: DiskDataEncoding,
-    pub density: DiskDensity,
+    pub rate: TrackDataRate,
+    pub encoding: TrackDataEncoding,
+    pub density: TrackDensity,
 }
 
 impl DiskInfoWidget {

crates/ff_egui_lib/src/widgets/disk_info.rs

@@ -102,7 +102,7 @@ pub(crate) fn run(global: &GlobalOptions, params: &args::ConvertParams) -> Resul
 
     // Create an output buffer
     let mut out_buffer = Cursor::new(Vec::new());
-    match output_format.save_image(&mut in_disk, &mut out_buffer) {
+    match output_format.save_image(&mut in_disk, &ParserWriteOptions::default(), &mut out_buffer) {
         Ok(_) => {
             let out_inner: Vec<u8> = out_buffer.into_inner();
             match std::fs::write(params.out_file.clone(), out_inner) {