3.4 KiB
Decode API
All owning pixel results reuse std/image.Image through image-codec's
DecodeResult. Inspect is_ok and error before using the image. Inputs and
caller output buffers are synchronous borrows; keep their storage alive and
do not overlap input with output. Owned results survive input/library release.
webp/facade:WebpDecode(input,options) -> DecodeResultandWebpDecodeInto(input,output,options) -> WebpOutputResultuse the pinned native reference bridge. They preserve the first complete composed animation frame and report the source frame count.webp/authored_lossless:WebpAuthoredLosslessDecode(input,options,trace=null)andWebpAuthoredLosslessDecodeInto(input,output,options,trace=null)decode VP8L in Ziran, with no native fallback. Lossy VP8, animation, FastColor and reserved predictor modes 14/15 returnUnsupportedCapability.webp/authored:WebpAuthoredDecode(input,options)andWebpAuthoredDecodeInto(input,output,options)decode VP8L or keyframe VP8 with raw/compressed ALPH, using authored Ziran modules and no native fallback. Animation, FastColor and the reserved VP8 color-space bit returnUnsupportedCapability. VP8 reconstruction follows portable integer arithmetic. On extreme mutated coefficients the pinned native SIMD decoder can differ from its own portable C decoder; this provider is validated against the latter in those cases. Exhausted entropy partitions are rejected without synthesizing missing zero bits.webp/dynamic:OpenDynamicWebp(path),DynamicWebpDecode,DynamicWebpDecodeInto,CloseDynamicWebpload the same native ABI without static codec linkage. Keep a non-copied engine alive through its calls. Missing libraries/symbols return an unavailable engine and capability error.webp/riff:WebpHasSignature(input)tests the 12-byte RIFF/WEBP prefix for format dispatch, without requiring a complete body.WebpProbe(input,limits)validates bounded container structure without allocation. Its alpha bit is a source hint; successful pixel results also report any observed non-opaque alpha even when that hint was clear.
WebpDefaultOptions() retains the native 2147483647-byte input cap. Generic
DefaultOptions() retains image-codec's smaller default. Limits cover source
input, dimensions, pixels, output backing/span, metadata, source frames,
requested decoded frames and workers. Only strict default eight-bit RGBA output
is implemented; no ICC-managed color/HDR rendering is promised. Source color
information remains unknown when not established.
The authored provider reserves all dynamic scratch backing before allocation
and uses exact bounded Vec capacity. Its budget excludes fixed stack/static
state, runtime object/allocator overhead and RSS. The native ABI cannot enforce
its opaque allocator's scratch ceiling or interrupt a synchronous native call;
LibwebpCapabilities() reports these as unavailable. Both paths use one caller
execution lane and cooperate with cancellation around bounded work. Worker and
cancellation records are caller-owned single-thread state, not atomic objects.
Caller output validation precedes writes; padding is preserved. Cancellation
during work can leave output rows written. Failed owning calls return no image.
Worker leases and scratch reservations acquired by a call are released before
returning. An optional zero-initialized LosslessTrace accumulates actual format
events, not CPU time, memory measurements or allocation counts.