j2k_transcode/
lib.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! JPEG-to-HTJ2K coefficient-domain transcode workflow.
4
5mod accelerator_contracts;
6mod allocation;
7pub use self::accelerator_contracts::{
8    idct_blocks_to_signed_samples_rayon, CpuOnlyDctToWaveletStageAccelerator,
9    DctGridI16ToHtj2k97CodeBlockBatch, DctGridI16ToHtj2k97CodeBlockJob, DctGridToDwt53Job,
10    DctGridToDwt97Job, DctGridToHtj2k97CodeBlockJob, DctToWaveletStageAccelerator,
11    DctToWaveletStageCounterEvent, DctToWaveletStageCounters, EncodedHtJ2kCodeBlock,
12    Htj2k97CodeBlockOptions, IrreversibleQuantizationSubbandScales, J2kSubBandType,
13    PreencodedHtj2k97CodeBlock, PreencodedHtj2k97CompactBatch, PreencodedHtj2k97CompactBatchGroups,
14    PreencodedHtj2k97CompactCodeBlock, PreencodedHtj2k97CompactComponent,
15    PreencodedHtj2k97CompactImage, PreencodedHtj2k97CompactResolution,
16    PreencodedHtj2k97CompactSubband, PreencodedHtj2k97Component, PreencodedHtj2k97Resolution,
17    PreencodedHtj2k97Subband, PrequantizedHtj2k97CodeBlock, PrequantizedHtj2k97Component,
18    PrequantizedHtj2k97Image, PrequantizedHtj2k97Resolution, PrequantizedHtj2k97Subband,
19    RayonReversibleDwt53Accelerator, TranscodeStageDispatchMode,
20};
21
22/// Compatibility namespace for the accelerator contracts exported at the
23/// crate root.
24#[doc(hidden)]
25pub mod accelerator {
26    pub use crate::{
27        idct_blocks_to_signed_samples_rayon, CpuOnlyDctToWaveletStageAccelerator,
28        DctGridI16ToHtj2k97CodeBlockBatch, DctGridI16ToHtj2k97CodeBlockJob, DctGridToDwt53Job,
29        DctGridToDwt97Job, DctGridToHtj2k97CodeBlockJob, DctGridToReversibleDwt53Job,
30        DctToWaveletStageAccelerator, DctToWaveletStageCounterEvent, DctToWaveletStageCounters,
31        Dwt97BatchStageTimings, EncodedHtJ2kCodeBlock, Htj2k97CodeBlockOptions,
32        IrreversibleQuantizationSubbandScales, J2kSubBandType, PreencodedHtj2k97CodeBlock,
33        PreencodedHtj2k97CompactBatch, PreencodedHtj2k97CompactBatchGroups,
34        PreencodedHtj2k97CompactCodeBlock, PreencodedHtj2k97CompactComponent,
35        PreencodedHtj2k97CompactImage, PreencodedHtj2k97CompactResolution,
36        PreencodedHtj2k97CompactSubband, PreencodedHtj2k97Component, PreencodedHtj2k97Resolution,
37        PreencodedHtj2k97Subband, PrequantizedHtj2k97CodeBlock, PrequantizedHtj2k97Component,
38        PrequantizedHtj2k97Image, PrequantizedHtj2k97Resolution, PrequantizedHtj2k97Subband,
39        RayonReversibleDwt53Accelerator, ReversibleDwt53FirstLevel, TranscodeStageDispatchMode,
40        TranscodeStageError,
41    };
42}
43
44// These contracts occur in downstream crates' public signatures. Defining
45// them at the crate root preserves their canonical semver paths while their
46// implementations remain in the focused accelerator-contracts module.
47
48/// Direct DCT-grid to one-level reversible integer 5/3 projection job.
49#[derive(Debug, Clone, Copy)]
50pub struct DctGridToReversibleDwt53Job<'a> {
51    /// Natural-order, dequantized 8x8 DCT blocks.
52    pub dequantized_blocks: &'a [[i16; 64]],
53    /// Number of DCT block columns in `dequantized_blocks`.
54    pub block_cols: usize,
55    /// Number of DCT block rows in `dequantized_blocks`.
56    pub block_rows: usize,
57    /// Logical component width in samples.
58    pub width: usize,
59    /// Logical component height in samples.
60    pub height: usize,
61}
62
63/// One separable single-level reversible integer 5/3 transform result.
64#[derive(Debug, PartialEq, Eq)]
65pub struct ReversibleDwt53FirstLevel {
66    /// Low-horizontal, low-vertical band.
67    pub ll: Vec<i32>,
68    /// High-horizontal, low-vertical band.
69    pub hl: Vec<i32>,
70    /// Low-horizontal, high-vertical band.
71    pub lh: Vec<i32>,
72    /// High-horizontal, high-vertical band.
73    pub hh: Vec<i32>,
74    /// Width of horizontally low-pass bands.
75    pub low_width: usize,
76    /// Height of vertically low-pass bands.
77    pub low_height: usize,
78    /// Width of horizontally high-pass bands.
79    pub high_width: usize,
80    /// Height of vertically high-pass bands.
81    pub high_height: usize,
82}
83
84/// Backend-specific timing breakdown for a same-geometry 9/7 batch.
85#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
86pub struct Dwt97BatchStageTimings {
87    /// Host packing, buffer allocation, and upload time in microseconds.
88    pub pack_upload_us: u128,
89    /// Logical host-to-device transfers included in [`Self::pack_upload_us`].
90    pub pack_upload_transfers: usize,
91    /// Host-to-device bytes included in [`Self::pack_upload_us`].
92    pub pack_upload_bytes: u64,
93    /// Resident JPEG DCT-grid descriptors validated for this batch.
94    pub resident_dct_handoff_count: usize,
95    /// Time spent in the IDCT plus horizontal 9/7 row-lift stage.
96    pub idct_row_lift_us: u128,
97    /// Time spent in the vertical 9/7 column-lift stage.
98    pub column_lift_us: u128,
99    /// Resident DWT subband descriptors validated for this batch.
100    pub resident_dwt_handoff_count: usize,
101    /// Time spent quantizing 9/7 bands into HTJ2K code-block layout.
102    pub quantize_codeblock_us: u128,
103    /// Time spent HT-encoding resident code-block coefficients.
104    pub ht_encode_us: u128,
105    /// Resident HT cleanup-pass encode kernel time in microseconds.
106    pub ht_kernel_us: u128,
107    /// Resident HT status-buffer device-to-host readback time in microseconds.
108    pub ht_status_readback_us: u128,
109    /// Logical device-to-host status readbacks included in [`Self::ht_status_readback_us`].
110    pub ht_status_readback_transfers: usize,
111    /// Device-to-host status bytes included in [`Self::ht_status_readback_us`].
112    pub ht_status_readback_bytes: u64,
113    /// Resident HT encoded-byte compaction kernel time in microseconds.
114    pub ht_compact_us: u128,
115    /// Resident HT compacted encoded-byte device-to-host readback time in microseconds.
116    pub ht_output_readback_us: u128,
117    /// Logical device-to-host output readbacks included in [`Self::ht_output_readback_us`].
118    pub ht_output_readback_transfers: usize,
119    /// Device-to-host output bytes included in [`Self::ht_output_readback_us`].
120    pub ht_output_readback_bytes: u64,
121    /// Number of HT code-block encode kernel dispatches in this batch.
122    pub ht_codeblock_dispatches: usize,
123    /// Time spent reading and unpacking Metal band buffers into host outputs.
124    pub readback_us: u128,
125    /// Logical device-to-host transfers included in [`Self::readback_us`].
126    pub readback_transfers: usize,
127    /// Device-to-host bytes included in [`Self::readback_us`].
128    pub readback_bytes: u64,
129}
130
131mod dct53_2d;
132mod dct97_2d;
133mod dct_grid;
134#[cfg(feature = "dev-support")]
135#[doc(hidden)]
136pub mod dev_support;
137mod htj2k97_codeblock_error;
138mod htj2k97_codeblock_oracle;
139#[doc(hidden)]
140mod jpeg_to_htj2k;
141#[doc(hidden)]
142pub mod metrics;
143mod move_only;
144mod pipeline_map;
145mod resident;
146mod reversible53;
147mod transcode_stage_error;
148
149pub use j2k::J2kProgressionOrder as EncodeProgressionOrder;
150
151/// One separable single-level 2D 5/3 transform result.
152#[derive(Debug, PartialEq)]
153pub struct Dwt53TwoDimensional<T> {
154    /// Low-horizontal, low-vertical band.
155    pub ll: Vec<T>,
156    /// High-horizontal, low-vertical band.
157    pub hl: Vec<T>,
158    /// Low-horizontal, high-vertical band.
159    pub lh: Vec<T>,
160    /// High-horizontal, high-vertical band.
161    pub hh: Vec<T>,
162    /// Width of horizontally low-pass bands.
163    pub low_width: usize,
164    /// Height of vertically low-pass bands.
165    pub low_height: usize,
166    /// Width of horizontally high-pass bands.
167    pub high_width: usize,
168    /// Height of vertically high-pass bands.
169    pub high_height: usize,
170}
171
172/// One separable single-level 2D 9/7 transform result.
173#[derive(Debug, PartialEq)]
174pub struct Dwt97TwoDimensional<T> {
175    /// Low-horizontal, low-vertical band.
176    pub ll: Vec<T>,
177    /// High-horizontal, low-vertical band.
178    pub hl: Vec<T>,
179    /// Low-horizontal, high-vertical band.
180    pub lh: Vec<T>,
181    /// High-horizontal, high-vertical band.
182    pub hh: Vec<T>,
183    /// Width of horizontally low-pass bands.
184    pub low_width: usize,
185    /// Height of vertically low-pass bands.
186    pub low_height: usize,
187    /// Width of horizontally high-pass bands.
188    pub high_width: usize,
189    /// Height of vertically high-pass bands.
190    pub high_height: usize,
191}
192
193move_only::assert_move_only!(
194    ReversibleDwt53FirstLevel,
195    Dwt53TwoDimensional<f64>,
196    Dwt97TwoDimensional<f64>,
197);
198
199pub use dct53_2d::{dct8x8_blocks_then_dwt53_float, dct8x8_blocks_to_dwt53_float_linear};
200pub use dct97_2d::dct8x8_blocks_then_dwt97_float;
201pub use dct97_2d::{dct8x8_blocks_then_dwt97_float_with_scratch, Dct97GridScratch};
202pub use dct_grid::{DctGridError, DctTransformError};
203pub use htj2k97_codeblock_error::{Htj2k97CodeBlockAxis, Htj2k97CodeBlockOptionsError};
204pub use htj2k97_codeblock_oracle::{
205    htj2k97_subband_delta, htj2k97_subband_total_bitplanes, validate_htj2k97_codeblock_options,
206};
207pub use jpeg_to_htj2k::{
208    jpeg_to_htj2k, jpeg_to_htj2k_batch, BatchTranscodeReport, EncodedTranscode,
209    EncodedTranscodeBatch, Htj2kEncodeError, Htj2kEncodeErrorKind, JpegTileBatchInput,
210    JpegToHtj2kCoefficientPath, JpegToHtj2kEncodeOptions, JpegToHtj2kError, JpegToHtj2kOptions,
211    JpegToHtj2kTranscoder, TranscodeBatchProfileRequest, TranscodeBatchProfileRow,
212    TranscodeComponentReport, TranscodeReport, TranscodeTimingReport,
213    TranscodeValidationClassification, TranscodeValidationMetrics,
214    JPEG_TO_HTJ2K_LOSSY_97_QUANTIZATION_SCALE,
215};
216pub use pipeline_map::{
217    TranscodePipelineMap, TranscodePipelineStageKind, TranscodePipelineStageReport,
218    TranscodeResidentStageRecommendation, TranscodeStageProcessor,
219};
220pub use resident::{
221    ResidentBufferRef, ResidentCodestreamBuffer, ResidentColorModel, ResidentComponentGeometry,
222    ResidentDctCoefficientOrder, ResidentDctGridLayout, ResidentDwtSubband, ResidentDwtSubbandKind,
223    ResidentDwtSubbandLayout, ResidentHandoffError, ResidentJpegDctGrid, ResidentSampleInfo,
224    ResidentSampling,
225};
226pub use transcode_stage_error::TranscodeStageError;
j2k_transcode/lib.rs

j2k_transcode/
lib.rs
