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 pipeline_map;
144mod resident;
145mod reversible53;
146mod transcode_stage_error;
147
148pub use j2k::J2kProgressionOrder as EncodeProgressionOrder;
149
150/// One separable single-level 2D 5/3 transform result.
151#[derive(Debug, PartialEq)]
152pub struct Dwt53TwoDimensional<T> {
153    /// Low-horizontal, low-vertical band.
154    pub ll: Vec<T>,
155    /// High-horizontal, low-vertical band.
156    pub hl: Vec<T>,
157    /// Low-horizontal, high-vertical band.
158    pub lh: Vec<T>,
159    /// High-horizontal, high-vertical band.
160    pub hh: Vec<T>,
161    /// Width of horizontally low-pass bands.
162    pub low_width: usize,
163    /// Height of vertically low-pass bands.
164    pub low_height: usize,
165    /// Width of horizontally high-pass bands.
166    pub high_width: usize,
167    /// Height of vertically high-pass bands.
168    pub high_height: usize,
169}
170
171/// One separable single-level 2D 9/7 transform result.
172#[derive(Debug, PartialEq)]
173pub struct Dwt97TwoDimensional<T> {
174    /// Low-horizontal, low-vertical band.
175    pub ll: Vec<T>,
176    /// High-horizontal, low-vertical band.
177    pub hl: Vec<T>,
178    /// Low-horizontal, high-vertical band.
179    pub lh: Vec<T>,
180    /// High-horizontal, high-vertical band.
181    pub hh: Vec<T>,
182    /// Width of horizontally low-pass bands.
183    pub low_width: usize,
184    /// Height of vertically low-pass bands.
185    pub low_height: usize,
186    /// Width of horizontally high-pass bands.
187    pub high_width: usize,
188    /// Height of vertically high-pass bands.
189    pub high_height: usize,
190}
191
192pub use dct53_2d::{dct8x8_blocks_then_dwt53_float, dct8x8_blocks_to_dwt53_float_linear};
193pub use dct97_2d::dct8x8_blocks_then_dwt97_float;
194pub use dct97_2d::{dct8x8_blocks_then_dwt97_float_with_scratch, Dct97GridScratch};
195pub use dct_grid::{DctGridError, DctTransformError};
196pub use htj2k97_codeblock_error::{Htj2k97CodeBlockAxis, Htj2k97CodeBlockOptionsError};
197pub use htj2k97_codeblock_oracle::{
198    htj2k97_subband_delta, htj2k97_subband_total_bitplanes, validate_htj2k97_codeblock_options,
199};
200pub use jpeg_to_htj2k::{
201    jpeg_to_htj2k, jpeg_to_htj2k_batch, BatchTranscodeReport, EncodedTranscode,
202    EncodedTranscodeBatch, Htj2kEncodeError, Htj2kEncodeErrorKind, JpegTileBatchInput,
203    JpegToHtj2kCoefficientPath, JpegToHtj2kEncodeOptions, JpegToHtj2kError, JpegToHtj2kOptions,
204    JpegToHtj2kTranscoder, TranscodeBatchProfileRequest, TranscodeBatchProfileRow,
205    TranscodeComponentReport, TranscodeReport, TranscodeTimingReport,
206    TranscodeValidationClassification, TranscodeValidationMetrics,
207    JPEG_TO_HTJ2K_LOSSY_97_QUANTIZATION_SCALE,
208};
209pub use pipeline_map::{
210    TranscodePipelineMap, TranscodePipelineStageKind, TranscodePipelineStageReport,
211    TranscodeResidentStageRecommendation, TranscodeStageProcessor,
212};
213pub use resident::{
214    ResidentBufferRef, ResidentCodestreamBuffer, ResidentColorModel, ResidentComponentGeometry,
215    ResidentDctCoefficientOrder, ResidentDctGridLayout, ResidentDwtSubband, ResidentDwtSubbandKind,
216    ResidentDwtSubbandLayout, ResidentHandoffError, ResidentJpegDctGrid, ResidentSampleInfo,
217    ResidentSampling,
218};
219pub use transcode_stage_error::TranscodeStageError;
j2k_transcode/lib.rs

j2k_transcode/
lib.rs
