j2k_types/dispatch/
accelerator.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! Low-level encode-stage accelerator integration contract.
4
5use alloc::vec::Vec;
6
7use super::{J2kEncodeDispatchReport, J2kEncodeStageResult};
8use crate::{
9    EncodedHtJ2kCodeBlock, EncodedHtJ2kCodeBlockSet, EncodedJ2kCodeBlock, J2kForwardDwt53Job,
10    J2kForwardDwt53Output, J2kForwardDwt97Job, J2kForwardDwt97Output, J2kForwardIctJob,
11    J2kForwardRctJob, J2kHtCodeBlockEncodeJob, J2kHtCodeBlockSetEncodeJob, J2kHtSubbandEncodeJob,
12    J2kPacketizationEncodeJob, J2kPacketizationProgressionOrder, J2kQuantizeSubbandJob,
13    J2kResidentHtj2kTileEncodeJob, J2kTier1CodeBlockEncodeJob,
14};
15
16/// Pixel deinterleave and level-shift job supplied to an accelerator.
17#[derive(Debug, Clone, Copy)]
18pub struct J2kDeinterleaveToF32Job<'a> {
19    /// Interleaved source pixel bytes.
20    pub pixels: &'a [u8],
21    /// Number of pixels to convert.
22    pub num_pixels: usize,
23    /// Number of interleaved components per pixel.
24    pub num_components: u16,
25    /// Source sample bit depth.
26    pub bit_depth: u8,
27    /// Whether source samples are signed.
28    pub signed: bool,
29}
30
31/// Combined pixel deinterleave, level-shift, and forward MCT job supplied to an accelerator.
32///
33/// The native encoder only offers this job for three-component inputs with MCT enabled.
34#[derive(Debug, Clone, Copy)]
35pub struct J2kDeinterleaveMctToF32Job<'a> {
36    /// Interleaved source pixel bytes.
37    pub pixels: &'a [u8],
38    /// Number of pixels to convert.
39    pub num_pixels: usize,
40    /// Source sample bit depth.
41    pub bit_depth: u8,
42    /// Whether source samples are signed.
43    pub signed: bool,
44    /// Whether to apply the reversible RCT (`true`) or irreversible ICT (`false`).
45    pub reversible: bool,
46}
47
48/// Validated image and coding context supplied before encode-stage dispatch.
49#[derive(Debug, Clone, Copy, PartialEq, Eq)]
50pub struct J2kEncodeContext {
51    /// Number of pixels in the encoded image or tile.
52    pub num_pixels: usize,
53    /// Number of interleaved source components.
54    pub num_components: u16,
55    /// Source sample bit depth.
56    pub bit_depth: u8,
57    /// Whether source samples are signed.
58    pub signed: bool,
59    /// Whether the codestream uses reversible coding.
60    pub reversible: bool,
61}
62
63/// HTJ2K tile-body encode job for a backend-resident full-tile path.
64#[derive(Debug, Clone, Copy)]
65pub struct J2kHtj2kTileEncodeJob<'a> {
66    /// Interleaved source pixel bytes.
67    pub pixels: &'a [u8],
68    /// Tile/image width in samples.
69    pub width: u32,
70    /// Tile/image height in samples.
71    pub height: u32,
72    /// Number of interleaved image components.
73    pub num_components: u16,
74    /// Source component bit depth.
75    pub bit_depth: u8,
76    /// Whether source samples are signed.
77    pub signed: bool,
78    /// Number of DWT decomposition levels.
79    pub num_decomposition_levels: u8,
80    /// Whether the codestream uses reversible coding.
81    pub reversible: bool,
82    /// Whether a multi-component transform should be applied.
83    pub use_mct: bool,
84    /// JPEG 2000 guard bits used to derive total coded bitplanes.
85    pub guard_bits: u8,
86    /// Code-block width in samples.
87    pub code_block_width: u32,
88    /// Code-block height in samples.
89    pub code_block_height: u32,
90    /// Packet progression order to emit.
91    pub progression_order: J2kPacketizationProgressionOrder,
92    /// Per-component sampling factors, as `(x_rsiz, y_rsiz)`.
93    pub component_sampling: &'a [(u8, u8)],
94    /// Quantization step sizes, as `(exponent, mantissa)`, in codestream order.
95    pub quantization_steps: &'a [(u16, u16)],
96}
97
98/// CPU-only encode accelerator that always falls back to native stages.
99#[derive(Debug, Default, Clone, Copy)]
100pub struct CpuOnlyJ2kEncodeStageAccelerator;
101
102/// Low-level JPEG 2000 encode-stage accelerator integration contract.
103pub trait J2kEncodeStageAccelerator {
104    /// Supply validated context before any encode-stage hook is invoked.
105    fn begin_encode(&mut self, _context: J2kEncodeContext) -> J2kEncodeStageResult<()> {
106        Ok(())
107    }
108
109    /// Report cumulative backend dispatches completed by this accelerator.
110    fn dispatch_report(&self) -> J2kEncodeDispatchReport {
111        J2kEncodeDispatchReport::default()
112    }
113
114    /// Report the exact maximum cleanup magnitude from the latest fused HT subband encode.
115    fn ht_subband_maximum_cleanup_magnitude(&self) -> Option<u64> {
116        None
117    }
118
119    /// Report the exact Part 15 magnitude bound from the latest complete HT tile encode.
120    fn ht_tile_required_magnitude_bound(&self) -> Option<u8> {
121        None
122    }
123
124    /// Optionally deinterleave interleaved pixel bytes into f32 component planes.
125    fn encode_deinterleave(
126        &mut self,
127        _job: J2kDeinterleaveToF32Job<'_>,
128    ) -> J2kEncodeStageResult<Option<Vec<Vec<f32>>>> {
129        Ok(None)
130    }
131
132    /// Optionally combine three-component deinterleave, level shift, and forward MCT.
133    fn encode_deinterleave_mct(
134        &mut self,
135        _job: J2kDeinterleaveMctToF32Job<'_>,
136    ) -> J2kEncodeStageResult<Option<Vec<Vec<f32>>>> {
137        Ok(None)
138    }
139
140    /// Optionally apply forward RCT in place.
141    fn encode_forward_rct(&mut self, _job: J2kForwardRctJob<'_>) -> J2kEncodeStageResult<bool> {
142        Ok(false)
143    }
144
145    /// Optionally apply forward ICT in place.
146    fn encode_forward_ict(&mut self, _job: J2kForwardIctJob<'_>) -> J2kEncodeStageResult<bool> {
147        Ok(false)
148    }
149
150    /// Optionally run a forward reversible 5/3 DWT.
151    fn encode_forward_dwt53(
152        &mut self,
153        _job: J2kForwardDwt53Job<'_>,
154    ) -> J2kEncodeStageResult<Option<J2kForwardDwt53Output>> {
155        Ok(None)
156    }
157
158    /// Optionally run a forward irreversible 9/7 DWT.
159    fn encode_forward_dwt97(
160        &mut self,
161        _job: J2kForwardDwt97Job<'_>,
162    ) -> J2kEncodeStageResult<Option<J2kForwardDwt97Output>> {
163        Ok(None)
164    }
165
166    /// Optionally quantize one subband.
167    fn encode_quantize_subband(
168        &mut self,
169        _job: J2kQuantizeSubbandJob<'_>,
170    ) -> J2kEncodeStageResult<Option<Vec<i32>>> {
171        Ok(None)
172    }
173
174    /// Optionally encode one classic Tier-1 code block.
175    fn encode_tier1_code_block(
176        &mut self,
177        _job: J2kTier1CodeBlockEncodeJob<'_>,
178    ) -> J2kEncodeStageResult<Option<EncodedJ2kCodeBlock>> {
179        Ok(None)
180    }
181
182    /// Optionally encode multiple classic Tier-1 code blocks in one backend dispatch.
183    fn encode_tier1_code_blocks(
184        &mut self,
185        _jobs: &[J2kTier1CodeBlockEncodeJob<'_>],
186    ) -> J2kEncodeStageResult<Option<Vec<EncodedJ2kCodeBlock>>> {
187        Ok(None)
188    }
189
190    /// Optionally encode one HTJ2K code block.
191    fn encode_ht_code_block(
192        &mut self,
193        _job: J2kHtCodeBlockEncodeJob<'_>,
194    ) -> J2kEncodeStageResult<Option<EncodedHtJ2kCodeBlock>> {
195        Ok(None)
196    }
197
198    /// Optionally encode multiple HTJ2K code blocks in one backend dispatch.
199    fn encode_ht_code_blocks(
200        &mut self,
201        _jobs: &[J2kHtCodeBlockEncodeJob<'_>],
202    ) -> J2kEncodeStageResult<Option<Vec<EncodedHtJ2kCodeBlock>>> {
203        Ok(None)
204    }
205
206    /// Optionally encode exact HT cleanup/refinement-set candidates in one dispatch.
207    #[doc(hidden)]
208    fn encode_ht_code_block_sets(
209        &mut self,
210        _jobs: &[J2kHtCodeBlockSetEncodeJob<'_>],
211    ) -> J2kEncodeStageResult<Option<Vec<EncodedHtJ2kCodeBlockSet>>> {
212        Ok(None)
213    }
214
215    /// Optionally quantize and encode one HTJ2K cleanup/refinement subband.
216    fn encode_ht_subband(
217        &mut self,
218        _job: J2kHtSubbandEncodeJob<'_>,
219    ) -> J2kEncodeStageResult<Option<Vec<EncodedHtJ2kCodeBlock>>> {
220        Ok(None)
221    }
222
223    /// Optionally encode the complete HTJ2K tile packet body.
224    fn encode_htj2k_tile(
225        &mut self,
226        _job: J2kHtj2kTileEncodeJob<'_>,
227    ) -> J2kEncodeStageResult<Option<Vec<u8>>> {
228        Ok(None)
229    }
230
231    /// Optionally encode a complete HTJ2K tile whose pixels remain backend-resident.
232    fn encode_resident_htj2k_tile(
233        &mut self,
234        _job: J2kResidentHtj2kTileEncodeJob<'_>,
235    ) -> J2kEncodeStageResult<Option<Vec<u8>>> {
236        Ok(None)
237    }
238
239    /// Return whether CPU code-block fallback should use internal rayon parallelism.
240    fn prefer_parallel_cpu_code_block_fallback(&self) -> bool {
241        false
242    }
243
244    /// Return whether callers may parallelize whole-tile CPU-only batch encode.
245    fn prefer_parallel_cpu_tile_encode(&self) -> bool {
246        false
247    }
248
249    /// Optionally packetize prepared packet contributions.
250    fn encode_packetization(
251        &mut self,
252        _job: J2kPacketizationEncodeJob<'_>,
253    ) -> J2kEncodeStageResult<Option<Vec<u8>>> {
254        Ok(None)
255    }
256}
257
258#[doc(hidden)]
259impl J2kEncodeStageAccelerator for CpuOnlyJ2kEncodeStageAccelerator {
260    fn prefer_parallel_cpu_code_block_fallback(&self) -> bool {
261        true
262    }
263
264    fn prefer_parallel_cpu_tile_encode(&self) -> bool {
265        true
266    }
267}
268
269#[cfg(test)]
270mod tests {
271    use super::{CpuOnlyJ2kEncodeStageAccelerator, J2kEncodeStageAccelerator};
272    use crate::J2kHtCodeBlockSetEncodeJob;
273
274    #[test]
275    fn legacy_accelerators_decline_explicit_ht_sets_by_default() {
276        let coefficients = [7_i32];
277        let jobs = [J2kHtCodeBlockSetEncodeJob {
278            coefficients: &coefficients,
279            width: 1,
280            height: 1,
281            total_bitplanes: 3,
282            cleanup_bitplane: 1,
283            target_coding_passes: 3,
284        }];
285        let mut accelerator = CpuOnlyJ2kEncodeStageAccelerator;
286
287        assert!(accelerator
288            .encode_ht_code_block_sets(&jobs)
289            .expect("default set hook")
290            .is_none());
291    }
292}
j2k_types/dispatch/accelerator.rs

j2k_types/dispatch/
accelerator.rs
