133 lines
6.9 KiB
Markdown
133 lines
6.9 KiB
Markdown
# Decoder foundation
|
|
|
|
Import `image_codec/api` (dependency alias `image_codec`). Standalone tests
|
|
pass `--module-path image_codec=src` and
|
|
`--module-path std="$ZIRAN_ROOT/std"`. The named standard
|
|
library path separates this package's `image` module from `std/image`.
|
|
|
|
## Result and ownership
|
|
|
|
`DecodeResult` contains `is_ok`, `image: std/image.Image`, `metadata:
|
|
ImageMetadata`, and `error: DecodeError`. Check `is_ok` before reading output.
|
|
`DecodeFailure(error)` returns no pixels. `AllocateImage(metadata,limits,token)`
|
|
returns a fallible, zero-filled, tight RGBA8 image; it does no decoding. The
|
|
owned Vec storage uses one bulk `VecResizeBounded(storage,bytes,bytes)` and drops
|
|
automatically. Its backing capacity equals the requested byte count, including
|
|
non-power-of-two images; allocator overhead/RSS are not covered by this bound.
|
|
Cancellation is checked before/after allocation. Move a result or its image once;
|
|
explicitly clone for an independent copy. No alternate pixel type is defined.
|
|
|
|
`BorrowedBytes { data: []u8 }` and `BorrowBytes(data)` borrow input synchronously.
|
|
`ByteRange(input,offset,count)` checks signed bounds before slicing and returns
|
|
`(BorrowedBytes, DecodeError)`. Ziran's mutable slice is not const: the caller
|
|
keeps backing storage alive and unchanged until every decoder/view returns.
|
|
|
|
`Plane` owns `storage: Vec(u8)` and describes `width`, `height`, byte `stride`
|
|
and `sample_bytes`. `PlaneView` has the same layout and borrowed `data: []u8`.
|
|
A plane holds one component, with 1-byte or little endian 2-byte samples.
|
|
`ValidatePlane(view,limits)` checks layout, span and dimension/working-byte
|
|
limits; it does not infer subsampling or bit depth. Construct a view from live
|
|
caller-owned storage. Current `VecSlice` cannot borrow arbitrary pointer-backed
|
|
Vec fields, so no unsafe automatic pointer-to-plane view helper is promised.
|
|
|
|
`OutputBuffer { data: []u8, stride: s64 }` borrows caller-owned RGBA8 output.
|
|
`ValidateOutput(output,width,height,limits)` allows padding and requires
|
|
`(height-1)*stride + width*4` bytes. `CopyImageToOutput(image*,output,limits,token)`
|
|
leaves padding untouched, validates before writing, and checks cancellation per
|
|
row. Source and destination must not overlap. Cancellation during work can
|
|
leave complete rows written; pre-cancellation and invalid layout write nothing.
|
|
This borrowed buffer never becomes the owned `DecodeResult.image`.
|
|
|
|
## Limits and metadata
|
|
|
|
`DefaultLimits()` sets 256 MiB input, 32768 per dimension, 67108864 pixels,
|
|
256 MiB output, 512 MiB engine scratch, 1 MiB metadata, 4096 source frames,
|
|
one decoded frame and one worker. Caps are positive except
|
|
`max_metadata_bytes`, which may be zero. Zero never means unlimited.
|
|
`ValidateLimits`, `ValidateInputSize`, `ValidateDimensions`, `ValidateMetadata`
|
|
and `ValidateDecodedFrames` return structured errors.
|
|
`ValidatePixelDimensions(width,height,limits)` checks the limits, positive
|
|
dimensions, `max_width`/`max_height` and `max_pixels` with a widened s64
|
|
product. It assumes no sample storage, so planar or YUV engines apply their own
|
|
output byte budget. `ValidateDimensions` calls it, then requires tight RGBA8
|
|
`width*height*4 <= max_output_bytes`.
|
|
`RequiredSpan(width,height,sample_bytes,stride)` checks multiplication overflow.
|
|
Scratch, metadata, input and output are separate budgets, not a process RSS
|
|
guarantee. Providers reserve engine scratch and enforce container/metadata caps
|
|
before allocation.
|
|
|
|
`ImageMetadata` describes transformed output width/height, source bit depth,
|
|
alpha presence, source premultiplication, source `frame_count`, optional CICP
|
|
color fields guarded by `color_known`, and retained `metadata_bytes`.
|
|
Zero source depth/frame count means unknown. Color fields matter only when
|
|
`color_known` is true. `frame_count` is the source total; `max_decoded_frames`
|
|
bounds requested work. A two-frame source can return one frame under defaults.
|
|
No ICC/EXIF payload, HDR rendering, animation playback, transform interpretation
|
|
or color conversion is implemented by these records. Engines explicitly reject
|
|
unsupported features.
|
|
|
|
## Workers and cancellation
|
|
|
|
`DecodeOptions { limits, cancellation: *Cancellation, workers: *WorkerBudget,
|
|
color_mode }` is made with `DefaultOptions()`. `ValidateOptions` checks limits,
|
|
the optional worker budget, color mode, then cancellation. Null cancellation
|
|
means none; null workers means serial caller execution. Both pointed-to values
|
|
must outlive every operation using them.
|
|
|
|
`Cancellation { requested: bool }`, `Cancel(token*)` and
|
|
`CancellationError(token*)` provide cooperative checkpoints. This state is
|
|
single-threaded and non-atomic. Threaded engines adapt their atomic tokens or
|
|
serialize access; they cannot read/write this flag concurrently.
|
|
|
|
`NewWorkerBudget(limits)` counts every execution lane including the caller.
|
|
`AcquireWorker`/`ReleaseWorker` enforce the cap and update `peak_workers`.
|
|
`ReserveWorkingBytes`/`ReleaseWorkingBytes` track scratch and
|
|
`peak_working_bytes`. Failed reservations leave counts unchanged. Providers
|
|
release successful leases on every exit. These accounting helpers launch no
|
|
threads and supply no allocator or locks. Concurrent access needs provider
|
|
synchronization.
|
|
|
|
## Providers and errors
|
|
|
|
`DecodeProcedure` is an ordinary procedure type:
|
|
|
|
```zi
|
|
(input: BorrowedBytes, metadata: ImageMetadata,
|
|
options: *DecodeOptions) -> DecodeResult
|
|
```
|
|
|
|
A container codec can expose its own parsing facade and adapt to this procedure
|
|
without a global plugin registry. `DecodeRGBA8` handles already decoded tight
|
|
RGBA8 bytes, checks exact length, depth 8, straight alpha, limits and cancellation,
|
|
and returns independent owned pixels. It leases one worker when supplied.
|
|
`StrictColor` is supported. `FastColor` and other source representations return
|
|
`UnsupportedCapability`. It does not identify or decode encoded formats.
|
|
|
|
`DecodeError { code: s32, offset: s64 }` carries a byte offset or -1 when unknown.
|
|
Use `Error(code,offset)` and `ErrorText(code)`. Codes are `DecodeOK`,
|
|
`InvalidLimits`, `InvalidInput`, `TruncatedInput`, `MalformedInput`,
|
|
`UnsupportedCapability`, `LimitExceeded`, `OutputTooSmall`, `DecodeCancelled`,
|
|
`AllocationFailed`, `WorkerBudgetExceeded`, `InputOutputFailed` and
|
|
`CorrectnessMismatch`. Unknown codes return "unknown error" text.
|
|
`DecodeFailure(Error(DecodeOK))` becomes `InvalidInput`.
|
|
|
|
Native tests inject one failed allocation and verify `AllocationFailed`, empty
|
|
output and one bulk allocation attempt. Limit/overflow failures also pass.
|
|
This is deterministic allocator fault injection, not OS out-of-memory recovery;
|
|
Go may terminate on physical exhaustion.
|
|
|
|
## Example
|
|
|
|
```zi
|
|
#import "image_codec/api"
|
|
options := DefaultOptions()
|
|
workers := NewWorkerBudget(options.limits)
|
|
options.workers = *workers
|
|
metadata: ImageMetadata
|
|
metadata.width = 1; metadata.height = 1
|
|
metadata.source_bit_depth = 8; metadata.frame_count = 1
|
|
rgba: [4]u8 = .[20, 40, 60, 255]
|
|
result := DecodeRGBA8(BorrowBytes(rgba[:]), metadata, *options)
|
|
// Check result.is_ok; result.image owns pixels until moved or dropped.
|
|
```
|