From 129d8008a255e88b734ef3cc073266f7158c0183 Mon Sep 17 00:00:00 2001 From: Nigel Tao Date: Sat, 15 Jul 2023 12:56:40 +1000 Subject: [PATCH] doc: add more "decode an image" docs/comments --- README.md | 8 ++++++ doc/getting-started.md | 34 ++++++++++++++++++++++---- example/toy-aux-image/toy-aux-image.cc | 21 +++++++++++++++- 3 files changed, 57 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 06c35796..681b6ce4 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/doc/getting-started.md b/doc/getting-started.md index b1e6c784..1a357073 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -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). diff --git a/example/toy-aux-image/toy-aux-image.cc b/example/toy-aux-image/toy-aux-image.cc index 74356c55..b3d7313a 100644 --- a/example/toy-aux-image/toy-aux-image.cc +++ b/example/toy-aux-image/toy-aux-image.cc @@ -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 =