doc: add more "decode an image" docs/comments

This commit is contained in:
Nigel Tao committed 2023-07-15 13:26:45 +10:00
1 parent 2644620770
commit 129d8008a2
3 files changed
+57 -6

No files matched your search

+8
View File
@@ -207,6 +207,14 @@ See the [BUILD](/BUILD.md) instructions.
The [Note](/doc/note) directory also contains various short articles.
# Non-C/C++ Languages
- [dev0x13/pywuffs](https://github.com/dev0x13/pywuffs) holds Python bindings
for Wuffs the Library.
- Bindings for Go, Rust and other languages are tracked as [issue
#38](https://github.com/google/wuffs/issues/38).
# Status
Version 0.3. The API and ABI aren't stabilized yet. The compiler undoubtedly
+29 -5
View File
@@ -1,15 +1,39 @@
# Getting Started
If you just want to **decode an image**:
- [example/toy-aux-image](/example/toy-aux-image/toy-aux-image.cc) demonstrates
the high-level `wuffs_aux::DecodeImage` C++ function (for decoding still
images, not animated images) and links to more documentation.
- [example/convert-to-nia](/example/convert-to-nia/convert-to-nia.c)
demonstrates the low-level C API, which is more complicated but (1) handles
animation, (2) handles asynchronous I/O, (3) handles metadata and (4) does no
dynamic memory allocation, so it can run under a `SECCOMP_MODE_STRICT`
sandbox. Wuffs is already a memory-safe language, but this provides defense
in depth and can make the security audit trivial.
- [script/print-image-metadata.cc](/script/print-image-metadata.cc)
demonstrates extracting image metadata like ICC color profiles (in raw form).
In all of these cases, you don't need to first configure or build any Wuffs
code. You can just run a C/C++ compiler, like this (for an unoptimized build):
`g++ example/toy-aux-image/toy-aux-image.cc -o my-toy-aux-image`
If you want a fast (optimized) build, pass `-O3` or equivalent to your C/C++
compiler, or from the Wuffs root directory, run this:
`./build-example.sh example/toy-aux-image`
---
If you're looking to **use the Wuffs standard library** generally, e.g. you
want to safely decode some gzip'ed data in your C program, see the [Wuffs the
Library](/doc/wuffs-the-library.md) document and the [other examples](/example)
instead of this document.
If you're looking to **write your own Wuffs code** outside of its standard
library, e.g. you want to safely decode your own custom file format, see the
[Wuffs the Language](/doc/wuffs-the-language.md) document and the
[/hello-wuffs-c](/hello-wuffs-c) example instead of this document.
If you're looking to just **use the Wuffs standard library**, e.g. you want to
safely decode some gzip'ed data in your C program, see the [Wuffs the
Library](/doc/wuffs-the-library.md) document and the [other examples](/example)
instead of this document.
If you're looking to **modify the Wuffs language**, it's probably best to ask
the [mailing list](https://groups.google.com/forum/#!forum/wuffs).
+20 -1
View File
@@ -17,7 +17,8 @@
/*
toy-aux-image demonstrates using the wuffs_aux::DecodeImage C++ function to
decode an in-memory compressed image. In this example, the compressed image is
hard-coded to a specific JPEG image.
hard-coded to a specific image: a JPEG encoding of the first frame of the
test/data/muybridge.gif animated image.
To run:
@@ -149,6 +150,24 @@ size_t g_src_len = 0x224;
static std::string //
decode() {
// Call wuffs_aux::DecodeImage, which is the entry point to Wuffs' high-level
// C++ API for decoding images. This API is easier to use than Wuffs'
// low-level C API but the low-level one (1) handles animation, (2) handles
// asynchronous I/O, (3) handles metadata and (4) does no dynamic memory
// allocation, so it can run under a `SECCOMP_MODE_STRICT` sandbox.
// Obviously, if you don't need any of those features, then these simple
// lines of code here suffices.
//
// This example program doesn't explicitly use Wuffs' low-level C API but, if
// you're curious to learn more, the wuffs_aux::DecodeImage implementation in
// internal/cgen/auxiliary/*.cc uses it, as does the example/convert-to-nia C
// program. There's also documentation at doc/std/image-decoders.md
//
// If you also want metadata like EXIF orientation and ICC color profiles,
// script/print-image-metadata.cc has some example code. It uses Wuffs'
// low-level API but it's a C++ program to use Wuffs' shorter convenience
// methods: `decoder->decode_frame_config(NULL, &src)` instead of C's
// `wuffs_base__image_decoder__decode_frame_config(decoder, NULL, &src)`.
wuffs_aux::DecodeImageCallbacks callbacks;
wuffs_aux::sync_io::MemoryInput input(&g_src_array[0], g_src_len);
wuffs_aux::DecodeImageResult result =