j2k_metal/encode/
types.rs

1// SPDX-License-Identifier: Apache-2.0
2
3use j2k::EncodedJ2k;
4#[cfg(target_os = "macos")]
5use j2k_core::PixelFormat;
6#[cfg(target_os = "macos")]
7use metal::Buffer;
8use std::time::Duration;
9
10use super::MetalEncodedJ2k;
11
12#[cfg(target_os = "macos")]
13#[derive(Debug, Clone, Copy)]
14/// Metal buffer and layout metadata for one lossless J2K encode tile.
15pub struct MetalLosslessEncodeTile<'a> {
16    /// Source Metal buffer containing Gray or RGB pixels.
17    pub buffer: &'a Buffer,
18    /// Byte offset of the first source pixel in `buffer`.
19    pub byte_offset: usize,
20    /// Width of the valid input region in pixels.
21    pub width: u32,
22    /// Height of the valid input region in pixels.
23    pub height: u32,
24    /// Number of bytes between consecutive input rows.
25    pub pitch_bytes: usize,
26    /// Encoded image width in pixels.
27    pub output_width: u32,
28    /// Encoded image height in pixels.
29    pub output_height: u32,
30    /// Pixel format of the source buffer.
31    pub format: PixelFormat,
32}
33
34#[cfg(not(target_os = "macos"))]
35#[derive(Debug, Clone, Copy)]
36/// Placeholder lossless encode tile type for non-macOS builds.
37pub struct MetalLosslessEncodeTile<'a> {
38    _private: core::marker::PhantomData<&'a ()>,
39}
40
41#[derive(Debug, Clone, PartialEq, Eq)]
42/// Residency decisions used by a lossless Metal encode.
43pub struct MetalLosslessEncodeResidency {
44    /// Whether coefficient preparation ran on Metal.
45    pub coefficient_prep_used: bool,
46    /// Whether packetization ran on Metal.
47    pub packetization_used: bool,
48    /// Whether codestream assembly stayed resident on Metal.
49    pub codestream_assembly_used: bool,
50}
51
52#[derive(Debug, Clone, PartialEq, Eq)]
53/// Lossless Metal encode output with host codestream bytes and timings.
54///
55/// API note: this diagnostic report is constructed by this crate. It is not
56/// `#[non_exhaustive]`, but adapter releases may add diagnostic fields as the
57/// resident encode path gains more profiling detail.
58pub struct MetalLosslessEncodeOutcome {
59    /// Encoded J2K codestream.
60    pub encoded: EncodedJ2k,
61    /// Whether the input buffer had to be copied or padded.
62    pub input_copy_used: bool,
63    /// Residency decisions for the encode stages.
64    pub resident: MetalLosslessEncodeResidency,
65    /// Time spent copying or padding the input.
66    pub input_copy_duration: Duration,
67    /// End-to-end encode duration for this tile.
68    pub encode_duration: Duration,
69    /// GPU-only duration when timestamp data is available.
70    pub gpu_duration: Option<Duration>,
71    /// Time spent validating the encoded output.
72    pub validation_duration: Duration,
73    /// Time spent materializing buffer-backed codestream bytes into host bytes.
74    pub host_readback_duration: Duration,
75}
76
77/// Metal lossless encode report for buffer-backed codestream output.
78pub struct MetalLosslessBufferEncodeOutcome {
79    /// Encoded codestream stored in a Metal buffer.
80    pub encoded: MetalEncodedJ2k,
81    /// Whether the input buffer had to be copied or padded.
82    pub input_copy_used: bool,
83    /// Residency decisions for the encode stages.
84    pub resident: MetalLosslessEncodeResidency,
85    /// Time spent copying or padding the input.
86    pub input_copy_duration: Duration,
87    /// End-to-end encode duration for this tile.
88    pub encode_duration: Duration,
89    /// GPU-only duration when timestamp data is available.
90    pub gpu_duration: Option<Duration>,
91    /// Time spent validating the encoded output.
92    pub validation_duration: Duration,
93}
94
95/// Tuning knobs for resident Metal lossless J2K/HTJ2K tile batch encode.
96#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
97pub struct MetalLosslessEncodeConfig {
98    /// Requested maximum number of tiles submitted concurrently.
99    ///
100    /// `None` uses the crate default and still clamps by the memory budget.
101    pub gpu_encode_inflight_tiles: Option<usize>,
102    /// Resident encode memory budget in bytes.
103    ///
104    /// `None` uses `min(10 GiB, hw_memsize * 0.40)` when host memory can be
105    /// discovered.
106    pub gpu_encode_memory_budget_bytes: Option<usize>,
107}
108
109/// Batched lossless encode request over Metal-resident tiles.
110///
111/// Collapses the former per-permutation entry points: pick the input
112/// staging mode and batch tuning here, then submit through
113/// [`crate::submit_lossless_batch`], [`crate::submit_lossless_batch_to_metal`],
114/// or [`crate::encode_lossless_batch_with_report`].
115#[derive(Clone, Copy)]
116pub struct MetalLosslessEncodeBatchRequest<'a, 'b> {
117    /// Metal-resident tiles to encode.
118    pub tiles: &'a [MetalLosslessEncodeTile<'b>],
119    /// How tile samples reach the encoder's padded staging layout.
120    pub staging: MetalEncodeInputStaging,
121    /// Batch tuning knobs (inflight tiles, memory budget).
122    pub config: MetalLosslessEncodeConfig,
123}
124
125/// How tile samples reach the encoder's padded staging layout.
126#[derive(Debug, Clone, Copy, PartialEq, Eq)]
127pub enum MetalEncodeInputStaging {
128    /// Copy the tile into freshly padded staging storage.
129    CopyAndPad,
130    /// The tile is already padded and contiguous; encode it in place.
131    AlreadyPaddedContiguous,
132}
j2k_metal/encode/types.rs

j2k_metal/encode/
types.rs
