The checked API,
as it executes today.

pub struct TranscodeOffer {
    /// Confirmed configuration of the retained encoder job.
    pub encoder: EncodeOffer,
    /// Samples and interpretation delivered to that encoder after conversion.
    pub output: PixelDescriptor,
    /// Descriptive source metadata treatment.
    pub metadata: MetadataTransfer,
    /// Whether the output retains an opaque source color profile. Preserving
    /// such a profile does not certify its descriptive contents as PII-free.
    /// `None` means uninspected or otherwise unknown; a strict exclusion policy
    /// requires `Some(false)` from the retained executing route.
    pub retains_opaque_profile: Option<bool>,
    /// Managed row/conversion storage retained by this route after selection.
    /// Alternatives may share these same allocations; do not sum their offers.
    /// Excludes common input storage and unqualified native workspace.
    pub admitted_bytes: usize,
    /// Qualified upper bound for additional codec/conversion workspace outside
    /// managed storage, if known. `None` means unknown, never zero. Estimates
    /// are not upper bounds. Encoded staging and caller-owned source storage
    /// must also be included before claiming a whole-operation bound.
    pub workspace_upper_bound: Option<u64>,
    /// Output schedule of this same retained executing route.
    /// `None` remains unknown. Finish-first alone never proves a wait bound.
    /// The adapter must retain the qualified route through execution and check
    /// its output before publication; a decision record is not transferable proof.
    pub output_schedule: Option<super::OutputScheduleOffer>,
}

pub struct OutputScheduleOffer {
    /// Mechanism executed if this route is selected.
    pub schedule: OutputSchedule,
    /// Actual compressed-output store; None means no staging evidence.
    pub staging: Option<super::StagingFacts>,
    /// Qualified upper bound on all route-retained memory during destination
    /// waits: source, codec, conversion, metadata, scratch and compressed data.
    /// Include caller input retained by the route's borrows. Excludes unrelated
    /// caller state and the destination's own allocations. None is unknown.
    /// This is not peak-operation memory, disk use, or a measured estimate.
    pub wait_retained_upper_bound: Option<u64>,
}

impl<R: PolicyResolver> BoundPolicy<R> {
    pub const fn new(requirements: PolicySet, resolver: R) -> Self;

    pub fn into_parts(self) -> (PolicySet, R);
}

pub trait OperationPolicy: sealed::Sealed {
    type Error: Error + Send + Sync + 'static;

    fn requirements(&self) -> Option<PolicySet>;

    fn decide(&mut self, question: Question<'_>) -> Result<Decision, At<Self::Error>>;
}

Required methods: requirements, decide. Other methods have defaults; read them before relying on their behavior.

impl<R: PolicyResolver> BoundPolicy<R> {
    pub const fn new(requirements: PolicySet, resolver: R) -> Self;

    pub fn into_parts(self) -> (PolicySet, R);
}

pub trait PolicyResolver {
    type Error: Error + Send + Sync + 'static;

    fn resolve(&mut self, question: Question<'_>) -> Result<Decision, At<Self::Error>>;
}

Required methods: resolve. Other methods have defaults; read them before relying on their behavior.

impl PolicySet {
    pub const fn new() -> Self;

    pub const fn prefer_lossless(mut self, enabled: bool) -> Self;

    pub const fn require_metadata(mut self, treatment: MetadataTransfer) -> Self;

    pub const fn allow_opaque_profiles(mut self, allowed: bool) -> Self;

    pub const fn with_workspace_limit(mut self, bytes: u64) -> Self;

    pub const fn allow_assumed_chroma_siting(mut self, allowed: bool) -> Self;

    pub const fn require_extended_range(mut self, required: bool) -> Self;

    pub const fn require_output_schedule(mut self, schedule: super::OutputSchedule) -> Self;

    pub const fn with_output_wait_limit(mut self, bytes: u64) -> Self;
}

Selected methods · 6 more in the full contract.

pub struct DecisionRecord {
    /// Globally unique question identity (zero only if identity allocation failed).
    pub question: u64,
    /// What prompted this decision, including on refusal or callback failure.
    pub context: DecisionContext,
    /// Number of executable alternatives supplied before mandatory admission.
    pub offered: u8,
    /// Number of alternatives that passed mandatory admission.
    pub admitted: u8,
    /// Union of missing/contradicted evidence across excluded alternatives.
    /// A selected route satisfies these requirements; rejected alternatives may not.
    pub unmet_requirements: UnmetRequirements,
    /// Selected contract, including its original request preference index.
    pub selected: Option<Selection>,
    /// True when a callback returned `UsePreset`. A `PolicySet` passed directly
    /// as the operation policy selects without delegation and records false.
    pub used_preset: bool,
    /// Selection or refusal category.
    pub code: DecisionCode,
}

impl PendingPlan {
    pub fn new(execution: Selected, current: Context) -> Result<Self, At<PlanError>>;

    pub fn accept(&mut self, selected: Selected, current: Context) -> Result<(), At<PlanError>>;

    pub fn remaining(&self) -> impl Iterator<Item = Kind> + '_;

    pub fn finish(self, current: Context) -> Result<Plan, At<PlanError>>;
}

pub enum Input<'a, S = NoSource> {
    /// The driver itself reads this immutable view on every pass.
    Raster(zenpixels::PixelSlice<'a>),
    /// An external source; exact replay requires admitted owned staging.
    Source(S),
}

pub fn encode_passes<E, S, D, R, Q>(
    encoder: E,
    input: Input<'_, S>,
    writer: D,
    resolver: R,
    replay: Q,
    options: Options,
    stop: Option<&dyn zencodec::Pulse>,
) -> Result<Completed, At<Failure>>
where
    E: MultiPassEncoder,
    S: PassSource,
    D: Destination,
    R: OperationPolicy,
    Q: ReplayResolver;

Selected methods · 6 more in the full contract.

pub trait MultiPassEncoder: Sized {
    type Error: Error + Send + Sync + 'static;

    fn begin_passes(
        &mut self,
        desc: &Description,
        access: OutputAccess,
    ) -> Result<PassPlan, Self::Error>;

    fn pull_rows(
        &mut self,
        rows: &mut dyn PassRows,
        stop: Option<&dyn zencodec::Pulse>,
    ) -> Result<PassProgress, Self::Error>;

    fn pending_output(&self) -> &[u8];

    fn consume_output(&mut self, n: usize);

    fn finish_output(self) -> Result<OutputFinish<EncodeOutput>, Self::Error>;
}

Required methods: begin_passes, pull_rows, pending_output, consume_output, finish_output. Other methods have defaults; read them before relying on their behavior.

impl PolicySet {
    pub const fn new() -> Self;

    pub const fn prefer_lossless(mut self, enabled: bool) -> Self;

    pub const fn require_metadata(mut self, treatment: MetadataTransfer) -> Self;

    pub const fn allow_opaque_profiles(mut self, allowed: bool) -> Self;

    pub const fn with_workspace_limit(mut self, bytes: u64) -> Self;

    pub const fn allow_assumed_chroma_siting(mut self, allowed: bool) -> Self;

    pub const fn require_extended_range(mut self, required: bool) -> Self;

    pub const fn require_output_schedule(mut self, schedule: super::OutputSchedule) -> Self;

    pub const fn with_output_wait_limit(mut self, bytes: u64) -> Self;
}

Selected methods · 6 more in the full contract.

pub struct DecisionRecord {
    /// Globally unique question identity (zero only if identity allocation failed).
    pub question: u64,
    /// What prompted this decision, including on refusal or callback failure.
    pub context: DecisionContext,
    /// Number of executable alternatives supplied before mandatory admission.
    pub offered: u8,
    /// Number of alternatives that passed mandatory admission.
    pub admitted: u8,
    /// Union of missing/contradicted evidence across excluded alternatives.
    /// A selected route satisfies these requirements; rejected alternatives may not.
    pub unmet_requirements: UnmetRequirements,
    /// Selected contract, including its original request preference index.
    pub selected: Option<Selection>,
    /// True when a callback returned `UsePreset`. A `PolicySet` passed directly
    /// as the operation policy selects without delegation and records false.
    pub used_preset: bool,
    /// Selection or refusal category.
    pub code: DecisionCode,
}

pub trait DecodeJob<'a>: Sized {
    fn try_set_policy(
        &mut self,
        policy: crate::DecodePolicy,
    ) -> Result<(), crate::UnsupportedOperation>;

    fn try_with_policy(
        mut self,
        policy: crate::DecodePolicy,
    ) -> Result<Self, crate::UnsupportedOperation>;
}

Selected methods · 25 more in the full contract.

Required methods: with_pulse, with_limits, probe, output_info, decoder, push_decoder, streaming_decoder, animation_frame_decoder. Other methods have defaults; read them before relying on their behavior.

pub trait EncodeJob: Sized {
    fn try_set_policy(
        &mut self,
        policy: crate::EncodePolicy,
    ) -> Result<(), crate::UnsupportedOperation>;

    fn try_with_policy(
        mut self,
        policy: crate::EncodePolicy,
    ) -> Result<Self, crate::UnsupportedOperation>;
}

Selected methods · 23 more in the full contract.

Required methods: with_pulse, with_limits, with_metadata, encoder, animation_frame_encoder. Other methods have defaults; read them before relying on their behavior.

impl ImageOutput {
    pub fn interpretation(&self) -> &ImageInterpretation;

    pub fn source_frame(&self) -> Option<&Arc<FrameInterpretation>>;

    pub fn map(&self) -> Result<Box<dyn MappedImage + '_>, At<OutputError>>;

    pub fn with_pixels<T>(
        &self,
        consume: impl FnOnce(PixelSlice<'_>) -> T,
    ) -> Result<T, At<OutputError>>;
}

Selected methods · 4 more in the full contract.

impl ImageOutput {
    pub fn replace_packed_color<P: PackedImageOwner + 'static>(
        self,
        owner: P,
    ) -> Result<Self, At<OutputError>>;
}

pub enum ColorTarget {
    /// Preserve the current sample color space, not original-file provenance.
    Current,
    /// Convert to this named color space.
    Named(Cicp),
    /// Convert to this ICC profile, requiring a suitable supplied CMS.
    Icc(Arc<[u8]>),
}

pub struct RenderRequest {
    /// Required output color space.
    pub target: ColorTarget,
    /// Required packed pixel descriptor, including alpha interpretation.
    pub required: PixelDescriptor,
    /// Oriented canvas coordinates. None requests the full oriented canvas.
    pub region: Option<Rect>,
    /// Explicit conversion behavior, including clipping and channel loss.
    pub conversion: ConvertOptions,
}

impl<'a> Renderer<'a> {
    pub fn new(storage: StorageBudget) -> Self;

    pub fn with_request(mut self, request: RenderRequest) -> Self;

    pub fn with_cms(mut self, cms: &'a dyn PluggableCms) -> Self;

    pub fn render_first<C: Collection, R: OperationPolicy>(
        &self,
        images: &mut CheckedCollection<C, R>,
    ) -> Result<Option<Outcome<ImageOutput>>, At<CollectionOperationError>>;

    pub fn render_selected<C: Collection, R: OperationPolicy>(
        &self,
        images: &mut CheckedCollection<C, R>,
        image: &ImageId,
    ) -> Result<Outcome<ImageOutput>, At<CollectionOperationError>>;

    pub fn render<R: OperationPolicy + ?Sized>(
        &self,
        image: ImageOutput,
        policy: &mut R,
        pulse: Option<&dyn zencodec::Pulse>,
    ) -> Result<Outcome<ImageOutput>, At<RenderFailure>>;
}

Selected methods · 3 more in the full contract.

impl<C: Collection, R: OperationPolicy> CheckedCollection<C, R> {
    pub fn open(
        pulse: SharedPulse,
        resolver: R,
        open: impl FnOnce(SharedPulse) -> Result<C, Cause>,
    ) -> Result<Self, At<CollectionOperationError>>;

    pub fn with_policy_set(mut self, preset: PolicySet) -> Self;

    pub fn images(&mut self) -> Result<C::Cursor, At<CollectionOperationError>>;

    pub fn children(&mut self, image: &ImageId) -> Result<C::Cursor, At<CollectionOperationError>>;

    pub fn next(
        &mut self,
        cursor: &mut C::Cursor,
    ) -> Result<Option<ImageId>, At<CollectionOperationError>>;

    pub fn describe(
        &mut self,
        image: &ImageId,
    ) -> Result<ImageDescription, At<CollectionOperationError>>;

    pub fn first_image(
        &mut self,
        request: &ImageRequest,
    ) -> Result<Option<Outcome<ImageOutput>>, At<CollectionOperationError>>;

    pub fn decode(
        &mut self,
        image: &ImageId,
        request: &ImageRequest,
    ) -> Result<Outcome<ImageOutput>, At<CollectionOperationError>>;

    pub fn decode_with<E: Into<Cause>>(
        &mut self,
        image: &ImageId,
        request: &ImageRequest,
        transform: impl FnOnce(ImageOutput, &dyn crate::Pulse) -> Result<ImageOutput, E>,
    ) -> Result<Outcome<ImageOutput>, At<CollectionOperationError>>;

    pub fn report(&self) -> &OperationReport;

    pub fn is_finished(&self) -> bool;
}

Selected methods · 1 more in the full contract.

pub trait Encoder: Sized {
    type Error: core::error::Error + Send + Sync + 'static;

    fn begin_declared(
        &mut self,
        _declaration: &crate::encode::EncodeDeclaration<'_>,
    ) -> Result<crate::encode::EncodePlan, Self::Error>;

    fn begin_output(
        &mut self,
        width: u32,
        height: u32,
        descriptor: PixelDescriptor,
        access: crate::output_patch::OutputAccess,
    ) -> Result<crate::encode::OutputTiming, Self::Error>;

    fn pull_rows(
        &mut self,
        _rows: &mut dyn crate::encode::EncodeRows,
        _pulse: Option<&dyn crate::Pulse>,
    ) -> Result<crate::encode::PullProgress, Self::Error>;

    fn finish_output(self) -> Result<crate::output_patch::OutputFinish<EncodeOutput>, Self::Error>;
}

Selected methods · 11 more in the full contract.

Required methods: reject, encode. Other methods have defaults; read them before relying on their behavior.

impl OutputTiming {
    pub const fn with_patches(mut self) -> Self;

    pub const fn patches_at_finish(&self) -> bool;
}

Selected methods · 3 more in the full contract.

impl<E: VideoEncoder, M: Muxer, D: Destination, R: OperationPolicy> StagedEncode<E, M, D, R> {
    pub fn new(
        encoder: E,
        mux: M,
        destination: D,
        resolver: R,
        storage: StorageBudget,
        pulse: Option<&dyn zencodec::Pulse>,
    ) -> Result<Self, At<Failure>>;

    pub fn with_staging(
        encoder: E,
        mux: M,
        destination: D,
        resolver: R,
        staging: Staging,
        pulse: Option<&dyn zencodec::Pulse>,
    ) -> Result<Self, At<Failure>>;

    pub fn with_policy_set(mut self, preset: PolicySet) -> Self;

    pub fn report(&self) -> &OperationReport;

    pub fn is_failed(&self) -> bool;

    pub fn push(
        &mut self,
        input: Frame,
        pulse: Option<&dyn zencodec::Pulse>,
    ) -> Result<(), At<Failure>>;

    pub fn push_converted(
        &mut self,
        input: Frame,
        target: &FrameInterpretation,
        conversion: FrameConversionOffer,
        execute: impl FnOnce(Frame) -> Result<Frame, Cause>,
        pulse: Option<&dyn zencodec::Pulse>,
    ) -> Result<(), At<Failure>>;

    pub fn finish(mut self, pulse: Option<&dyn zencodec::Pulse>) -> Result<Completed, At<Failure>>;
}

Selected methods · 2 more in the full contract.

pub fn encode<E: Encoder, S: Source, W: Write, R: OperationPolicy>(
    encoder: E,
    source: S,
    writer: W,
    resolver: R,
    options: Options,
    pulse: Option<&dyn zencodec::Pulse>,
) -> Result<Completed, At<Failure>>;

pub fn encode_to_destination<E: Encoder, S: Source, D: Destination, R: OperationPolicy>(
    encoder: E,
    source: S,
    writer: D,
    resolver: R,
    options: Options,
    pulse: Option<&dyn zencodec::Pulse>,
) -> Result<Completed, At<Failure>>;

Selected methods · 11 more in the full contract.

pub trait Source {
    type Error: Error + Send + Sync + 'static;

    fn description(&self) -> Description;

    fn mechanism(&self) -> OutputSource;

    fn read_rows(
        &mut self,
        first: u32,
        rows: PixelSliceMut<'_>,
        pulse: Option<&dyn zencodec::Pulse>,
    ) -> Result<(), Self::Error>;
}

Selected methods · 3 more in the full contract.

Required methods: description, read_rows. Other methods have defaults; read them before relying on their behavior.

pub struct Description {
    /// Width in samples.
    pub width: u32,
    /// Total rows.
    pub height: u32,
    /// Complete sample descriptor accepted by the configured encoder.
    pub descriptor: PixelDescriptor,
    /// Original color context carried on every source and encoder row view.
    pub color_context: Option<Arc<ColorContext>>,
    /// Optional assertion about current canonical samples, checked before push.
    /// `Some` is strict: unsupported layouts refuse before startup, including
    /// full-storage CMYK claims. `None` does not restrict sample depth.
    /// It does not prove the encoder preserves samples or bound native memory.
    pub exact_depth: Option<ExactDepth>,
}

impl<'a> Raster<'a> {
    pub const fn new(pixels: PixelSlice<'a>) -> Self;
}

impl Options {
    pub fn new(storage: StorageBudget, max_output_bytes: u64) -> Self;

    pub fn with_batch_rows(mut self, rows: NonZeroU32) -> Self;

    pub fn with_policy_set(mut self, preset: PolicySet) -> Self;

    pub fn with_disk_staging(
        mut self,
        mut file: File,
        replay_bytes: NonZeroUsize,
    ) -> io::Result<Self>;
}

Selected methods · 1 more in the full contract.

pub struct Failure {
    /// Boundary that failed.
    pub stage: Stage,
    /// Confirmed destination appends, including partial writes.
    pub emitted: u64,
    /// Confirmed overwritten bytes, separate from appended extent.
    pub patched_bytes: u64,
    /// Bounded policy history, including after later source/codec/I/O failure.
    pub report: Box<OperationReport>,
    cause: Cause,
}

pub fn resolve_output_schedule<R: OperationPolicy + ?Sized>(
    facts: OutputScheduleFacts,
    offers: &[OutputScheduleOffer],
    resolver: &mut R,
    preset: PolicySet,
    pulse: Option<&dyn crate::Pulse>,
) -> Result<(usize, DecisionRecord), At<PolicyFailure>>;

pub struct OutputScheduleOffer {
    /// Mechanism executed if this route is selected.
    pub schedule: OutputSchedule,
    /// Actual compressed-output store; None means no staging evidence.
    pub staging: Option<super::StagingFacts>,
    /// Qualified upper bound on all route-retained memory during destination
    /// waits: source, codec, conversion, metadata, scratch and compressed data.
    /// Include caller input retained by the route's borrows. Excludes unrelated
    /// caller state and the destination's own allocations. None is unknown.
    /// This is not peak-operation memory, disk use, or a measured estimate.
    pub wait_retained_upper_bound: Option<u64>,
}

pub struct OutputScheduleFacts {
    /// Actual configured encoder's byte availability after begin.
    pub timing: OutputTiming,
    /// Actual source acquisition/ownership mechanism.
    pub source: OutputSource,
}

impl PolicySet {
    pub const fn new() -> Self;

    pub const fn prefer_lossless(mut self, enabled: bool) -> Self;

    pub const fn require_metadata(mut self, treatment: MetadataTransfer) -> Self;

    pub const fn allow_opaque_profiles(mut self, allowed: bool) -> Self;

    pub const fn with_workspace_limit(mut self, bytes: u64) -> Self;

    pub const fn allow_assumed_chroma_siting(mut self, allowed: bool) -> Self;

    pub const fn require_extended_range(mut self, required: bool) -> Self;

    pub const fn require_output_schedule(mut self, schedule: super::OutputSchedule) -> Self;

    pub const fn with_output_wait_limit(mut self, bytes: u64) -> Self;
}

Selected methods · 6 more in the full contract.

impl Staging {
    pub fn memory(budget: StorageBudget) -> Self;

    pub fn disk(mut file: File, limits: DiskLimits, replay: StorageBudget) -> Result<Self, Cause>;

    pub fn facts(&self) -> StagingFacts;
}

Selected methods · 4 more in the full contract.

pub struct DiskLimits {
    /// Total packet and addition bytes appended after the scratch origin.
    pub max_bytes: u64,
    /// Maximum number of staged packets.
    pub max_packets: usize,
    /// Maximum side-data entries on each packet, including empty entries.
    pub max_additions_per_packet: usize,
}

pub struct Failure {
    /// Failed boundary.
    pub stage: Stage,
    /// Confirmed destination appends, excluding spool writes and patch overwrites.
    /// Failed final patches can also leave partial overwrites; inspect the cause.
    pub emitted: u64,
    /// Decisions up to this failure.
    pub report: Box<OperationReport>,
    cause: Cause,
}

pub trait VideoEncoder {
    type Error: core::error::Error + Send + Sync + 'static;

    fn output_config(&self) -> Option<&CodecConfig>;

    fn output_fidelity(&self) -> Option<zencodec::encode::Fidelity>;
}

Selected methods · 3 more in the full contract.

Required methods: send, receive, end_input, output_config. Other methods have defaults; read them before relying on their behavior.

pub enum Refusal {
    /// Encoder cannot declare its container configuration before input.
    ConfigurationUnavailable,
    /// Configuration does not describe video.
    VideoConfigurationRequired,
    /// Conversion's bounded facts disagree with its full target.
    OfferMismatch,
    /// Conversion returned different interpretation or timing.
    ConversionMismatch,
    /// Encoder promised pending output but did not return a packet.
    ReceivePendingWithoutPacket,
    /// Encoder ended before the caller finished input.
    EarlyEnd,
    /// Encoder changed the configuration or fidelity bound at preparation.
    ConfigurationChanged,
    /// Encoder requested input after end_input.
    InputAfterEnd,
    /// Encoder returned an empty or taken packet.
    EmptyPacket,
    /// Operation previously failed or unwound.
    Terminal,
    /// No input frame completed policy admission. Empty output is unsupported.
    NoAdmittedFrames,
    /// The legacy preset setter was called after input had been accepted.
    PolicyChangedAfterInput,
}

pub trait Muxer {
    type Error: core::error::Error + Send + Sync + 'static;

    fn begin_exact_timing(
        &mut self,
        tracks: &[TrackInfo],
        hint: MuxHint,
    ) -> Result<MuxTiming, SessionError<Self::Error>>;

    fn write_packet(
        &mut self,
        packet: Packet,
        pulse: Option<&dyn zencodec::Pulse>,
    ) -> Result<(), SessionError<Self::Error>>;
}

Selected methods · 5 more in the full contract.

Required methods: begin, write_packet, pending_output, consume_output, take_output, finish. Other methods have defaults; read them before relying on their behavior.

impl<M: Muxer, D: Destination> PreparedOutput<M, D> {
    pub fn new(
        mux: M,
        destination: D,
        tracks: &[TrackInfo],
        pulse: Option<&dyn zencodec::Pulse>,
    ) -> Result<Self, Failure>;

    pub const fn timing(&self) -> MuxTiming;

    pub fn facts(&self) -> DestinationFacts;

    pub fn publish(self, pulse: Option<&dyn zencodec::Pulse>) -> Result<Output<M, D>, Failure>;
}

Selected methods · 1 more in the full contract.

impl<M: Muxer, D: Destination> Output<M, D> {
    pub fn new(
        mux: M,
        destination: D,
        tracks: &[TrackInfo],
        pulse: Option<&dyn zencodec::Pulse>,
    ) -> Result<Self, Failure>;

    pub fn with_container_timing(
        mux: M,
        destination: D,
        tracks: &[TrackInfo],
        pulse: Option<&dyn zencodec::Pulse>,
    ) -> Result<Self, Failure>;

    pub fn facts(&self) -> DestinationFacts;

    pub const fn stats(&self) -> &Stats;

    pub fn send(
        &mut self,
        packet: Packet,
        pulse: Option<&dyn zencodec::Pulse>,
    ) -> Result<(), Failure>;

    pub fn finish(mut self, pulse: Option<&dyn zencodec::Pulse>) -> Result<Stats, Failure>;
}

Selected methods · 6 more in the full contract.

impl<W: Write + Seek> SeekBack<W> {
    pub fn new(mut writer: W) -> io::Result<Self>;
}

impl<T: AsRef<[u8]>> OutputFinish<T> {
    pub fn new(tail: T, patches: Vec<Patch>) -> Self;

    pub fn validate(&self, emitted_bytes: u64) -> Result<u64, PatchError>;
}

impl OutputFinish {
    pub fn apply_to(self, file: &mut Vec<u8>) -> Result<(), PatchError>;
}

pub fn resolve_frame_route<R: OperationPolicy + ?Sized>(
    interpretation: &FrameInterpretation,
    timing: FrameTiming,
    output: FrameRouteState,
    offers: &[FrameRouteOffer],
    resolver: &mut R,
    preset: PolicySet,
    pulse: Option<&dyn crate::Pulse>,
) -> Result<(usize, DecisionRecord), At<PolicyFailure>>;

pub struct FrameRouteOffer {
    /// Qualified output continuity. Unsupported destination transitions must
    /// not appear in the choices, even when policy would select one.
    pub route: FrameRoute,
    /// Fidelity established by the prepared encoder configuration.
    pub fidelity: Option<Fidelity>,
    /// Effects and target of the retained conversion before this encoder.
    /// None means unqualified, not identity or sample preservation. Encoder
    /// fidelity alone never establishes end-to-end transcode fidelity.
    pub conversion: Option<FrameConversionOffer>,
    /// Actual retained destination evidence. None means unqualified; it does
    /// not imply forward-only, seekable, staged or safe encoder backpressure.
    pub destination: Option<DestinationFacts>,
    /// Actual compressed store; None means unqualified. Disk may block while
    /// raw encoder state is retained, independently of final writer access.
    pub staging: Option<StagingFacts>,
    /// Actual final-destination scheduling guarantee. None is unqualified.
    pub output_schedule: Option<super::OutputScheduleOffer>,
    /// Currently admitted encoded staging held by the operation. This excludes
    /// native input/reference/work buffers and is not a whole-operation bound.
    pub admitted_encoded_bytes: usize,
    /// Qualified additional codec/conversion workspace bound; unknown is not zero.
    pub workspace_upper_bound: Option<u64>,
}

pub struct DestinationFacts {
    /// The retained writer supports overwriting earlier output positions.
    pub seek_back: bool,
    /// The prepared container makes bytes available before finish.
    pub streams: bool,
    /// Finishing this layout requires overwriting previously emitted bytes.
    pub patches_at_finish: bool,
    /// The retained muxer guarantees exact supplied packet timing or fails.
    /// False means no such guarantee, not permission to discard timing.
    pub exact_timing: bool,
}

pub struct FrameConversionOffer {
    /// Interpretation and timing actually delivered to the encoder. Original
    /// input facts remain in the question; output epochs are independent.
    pub encoder_input: FrameFacts,
    /// True only for a qualified sample-preserving route; false includes
    /// arithmetic, quantization, clipping and unknown preservation.
    pub preserves_samples: bool,
    /// Whether conversion guarantees retention of extended-range values.
    /// This says nothing about the following encoder's precision or fidelity.
    pub preserves_extended_range: bool,
    /// Explicit fallback for undeclared siting. A declaration cannot be replaced.
    pub assumed_chroma_siting: Option<ChromaSiting>,
    /// Managed conversion storage retained/reserved for this selected route.
    /// Shared alternatives must not be summed. Native workspace is separate.
    pub admitted_bytes: usize,
}

pub struct FrameRouteState {
    /// Last frame accepted by this output operation, if any.
    pub previous: Option<FrameFacts>,
    /// Segments already completed by the adapter, whether staged or published.
    pub completed_segments: u64,
    /// Whether any output representation/header/body has escaped private
    /// staging. Zero body bytes alone must not establish that this is false.
    pub output_committed: bool,
}

pub enum AuxiliaryGrid {
    /// Registration has not been established. Equal dimensions do not change it.
    #[default]
    Unknown,
    /// Each auxiliary sample has the same center as the color sample at the
    /// same row and column, throughout the selected stored region. Dimensions
    /// must match color. This describes emitted samples, including any native
    /// upsampling; it does not authorize changing their numerical values.
    ColorSamples,
}

impl<'a> ValueSlice<'a> {
    pub fn new(
        bytes: &'a [u8],
        width: u32,
        height: u32,
        stride: usize,
        channel: ChannelType,
    ) -> Result<Self, At<OutputError>>;

    pub fn with_grid(mut self, grid: AuxiliaryGrid) -> Self;

    pub fn grid(&self) -> AuxiliaryGrid;

    pub fn as_strided_bytes(&self) -> &'a [u8];
}

pub fn project(
    image: &ImageOutput,
    region: Option<Rect>,
    storage: &StorageBudget,
    pulse: Option<&dyn zencodec::Pulse>,
) -> Result<ImageOutput, Cause>;

Selected methods · 1 more in the full contract.

pub fn resolve_image_conversion<R: OperationPolicy + ?Sized>(
    image: &ImageOutput,
    offers: &[ImageConversionOffer],
    resolver: &mut R,
    preset: PolicySet,
    pulse: Option<&dyn crate::Pulse>,
) -> Result<(usize, DecisionRecord), At<PolicyFailure>>;

pub struct ImageConversionOffer {
    /// Actual output pixel representation and compact color interpretation.
    /// Profiles/context must also satisfy the caller's configured target.
    pub output: PixelDescriptor,
    /// Stored output extent, before residual orientation.
    pub geometry: ImageGeometry,
    /// Residual orientation after this conversion; no inferred rotation.
    pub orientation: Orientation,
    /// A concrete chroma location assumed because the source did not declare
    /// one. None means no such assumption; an existing declaration is never
    /// overridden. Unknown is not a realizable assumed location.
    pub assumed_chroma_siting: Option<ChromaSiting>,
    /// True only when the route guarantees retention of extended-range values.
    /// False includes clipping, integer saturation and an unqualified guarantee;
    /// it is not a lossless-precision or HDR-rendering certificate.
    pub preserves_extended_range: bool,
    /// Managed destination and scratch capacity already reserved for this route.
    /// It need not be allocated or initialized until the callback accepts.
    /// Alternatives may share storage. Source/native workspace is excluded.
    pub admitted_bytes: usize,
    /// Qualified additional conversion workspace bound, if known. Unknown is
    /// not zero; this is not a whole-operation memory bound.
    pub workspace_upper_bound: Option<u64>,
}

impl PolicySet {
    pub const fn new() -> Self;

    pub const fn prefer_lossless(mut self, enabled: bool) -> Self;

    pub const fn require_metadata(mut self, treatment: MetadataTransfer) -> Self;

    pub const fn allow_opaque_profiles(mut self, allowed: bool) -> Self;

    pub const fn with_workspace_limit(mut self, bytes: u64) -> Self;

    pub const fn allow_assumed_chroma_siting(mut self, allowed: bool) -> Self;

    pub const fn require_extended_range(mut self, required: bool) -> Self;

    pub const fn require_output_schedule(mut self, schedule: super::OutputSchedule) -> Self;

    pub const fn with_output_wait_limit(mut self, bytes: u64) -> Self;
}

Selected methods · 6 more in the full contract.

impl StorageBudget {
    pub fn new(max_bytes: usize, max_objects: usize) -> Self;

    pub fn prepare_filled<T: Copy>(
        &self,
        len: usize,
        value: T,
    ) -> Result<PreparedStorage<T>, StorageError>;

    pub fn reserved_bytes(&self) -> usize;

    pub fn reserved_objects(&self) -> usize;
}

Selected methods · 7 more in the full contract.

impl<T: Copy> PreparedStorage<T> {
    pub fn allocate(self) -> Result<OwnedStorage<T>, StorageError>;
}

impl<'a> PlaneView<'a> {
    pub fn encoding(&self) -> SampleEncoding;

    pub fn stride_bytes(&self) -> usize;

    pub fn as_strided_samples(&self) -> PlaneSamples<'a>;

    pub fn row(&self, y: usize) -> Option<PlaneSamples<'a>>;

    pub fn code(&self, x: usize, y: usize) -> Option<u16>;
}

Selected methods · 3 more in the full contract.

impl ImageOutput {
    pub fn from_packed_owner<P: PackedImageOwner + 'static>(
        owner: P,
        auxiliaries: Vec<Auxiliary>,
        interpretation: ImageInterpretation,
    ) -> Result<Self, At<OutputError>>;

    pub fn from_frame_pixels<P: PackedImageOwner + 'static>(
        frame: Frame,
        owner: P,
        orientation: Orientation,
    ) -> Result<Self, At<OutputError>>;
}

Selected methods · 1 more in the full contract.