mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-19 08:38:14 +01:00
Re-do image decoders' call sequence state machine
This commit is contained in:
1 parent
a2e3a5a272
commit
8d03a67e6e
12 files changed
+606
-511
No files matched your search
@@ -0,0 +1,48 @@
|
||||
# Metadata
|
||||
|
||||
Files can also contain metadata (e.g. for image files, EXIF information, color
|
||||
profiles and time stamps). By default, Wuffs' decoders skip over metadata, but
|
||||
calling `set_report_metadata` will opt in to having `decode_etc` methods return
|
||||
early when encountering metadata in the file. Calling `set_report_metadata` can
|
||||
be done multiple times, each with a different
|
||||
[FourCC](/doc/note/base38-and-fourcc.md) code such as `0x49434350` "ICCP" or
|
||||
`0x584D5020` "XMP ", to indicate what sorts of metadata the caller is
|
||||
interested in. Conversely, when the parser encounters metadata (and returns a
|
||||
"@metadata reported" [status](/doc/note/statuses.md)), call `tell_me_more` to
|
||||
see what sort of metadata it is.
|
||||
|
||||
Some metadata is short and `tell_me_more` will also fill in its `minfo: nptr
|
||||
more_information` out parameter with "parsed metadata". For example, Gamma
|
||||
Correction metadata is a single numerical value and Primary Chromaticities
|
||||
metadata is only eight numbers. From C++ code, call the `metadata_parsed__gama`
|
||||
or `metadata_parsed__chrm` methods to retrieve these value.
|
||||
|
||||
Some metadata is long (or at least variable length) and needs processing by a
|
||||
separate parser. For example, processing XMP metadata usually involves some
|
||||
sort of XML parser, regardless of what particular image format that XMP
|
||||
metadata was embedded in. Wuffs decoders will return "raw metadata" instead of
|
||||
parsing it themselves. Raw metadata is further sub-divided into two categories:
|
||||
"raw passthrough" and "raw transform". Either way, note that raw metadata might
|
||||
also be arranged in multiple (non-contiguous) chunks of the source data.
|
||||
|
||||
"Raw passthrough" means that the bytes in the wire format can be sent "as is"
|
||||
to the separate parser. Call `tell_me_more` in a loop (the `dst: io_writer`
|
||||
argument will be ignored) and `metadata_raw_passthrough__range` to identify a
|
||||
range (a chunk) of the input stream. Divert the bytes in that range to the
|
||||
separate parser (which should advance the `io_buffer` to the end of that range)
|
||||
and repeat the loop as long as `tell_me_more` returned a "$even more
|
||||
information" status.
|
||||
|
||||
"Raw transform" means that the bytes in the wire format have to be further
|
||||
processed (e.g. decompressed) before sending them on to the separate parser.
|
||||
That processing is done by the decoder callee, not the caller. Pass a writable
|
||||
`dst io_buffer` to `tell_me_more` (where writable means that it has a positive
|
||||
`writer_length`) and implementations should fill in that buffer with
|
||||
post-transformed (e.g. decompressed) data to send onwards. Like any
|
||||
`io_transformer`-like coroutine, this should be in a loop, as it may suspend
|
||||
with "$short read" and "$short write" statuses.
|
||||
|
||||
Either way, break the loop (after handling the `dst` and `minfo` out
|
||||
parameters) when `tell_me_more` returns a NULL status, meaning ok, when the
|
||||
metadata is complete. Afterwards, call the original action (e.g. `decode_etc`)
|
||||
again to resume after the "@metadata reported" detour.
|
||||
Reference in new issue
Block a user