Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: aaaaaa123456789/libplum
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: v0.3
Choose a base ref
...
head repository: aaaaaa123456789/libplum
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: master
Choose a head ref

Commits on Jan 10, 2022

  1. Fix link on tutorial

    aaaaaa123456789 committed Jan 10, 2022
    Copy the full SHA
    84e6a2f View commit details

Commits on Jan 13, 2022

  1. Copy the full SHA
    63013cb View commit details
  2. Copy the full SHA
    4c5e2c4 View commit details
  3. Copy the full SHA
    b891a85 View commit details

Commits on Jan 14, 2022

  1. Copy the full SHA
    b9acaf9 View commit details
  2. Copy the full SHA
    aee37c5 View commit details
  3. Update README

    aaaaaa123456789 committed Jan 14, 2022
    Copy the full SHA
    e6c6614 View commit details
  4. Remove unnecessary function pointer typedef

    Some people might argue that typedefs make function pointers more
    readable. What's worse, those people might be right.
    But in the end, this repository doesn't use typedefs anywhere, and
    creating one just for this return value to avoid a longer signature
    doesn't seem correct.
    Besides, removing the typedef makes the callback's signature visible
    at the caller's site, since it is assigned to a variable.
    aaaaaa123456789 committed Jan 14, 2022
    Copy the full SHA
    a2ec4a0 View commit details
  5. Add some checks to defs.h to ensure that the library isn't built as o…

    …ld C, C++, or with disabled features
    aaaaaa123456789 committed Jan 14, 2022
    Copy the full SHA
    056abb9 View commit details
  6. Copy the full SHA
    f309a18 View commit details

Commits on Jan 15, 2022

  1. Add warning flags to make debug, and refactor to not print any warn…

    …ings (#4)
    
    * Add warning flags to `make debug`, and refactor to not print any warnings
    * Add `-fanalyzer` to `make debug`
    * Address PR comments
    Rangi42 authored Jan 15, 2022
    Copy the full SHA
    d309485 View commit details
  2. Copy the full SHA
    a7732d1 View commit details
  3. Update warning flags

    aaaaaa123456789 committed Jan 15, 2022
    Copy the full SHA
    d73dac9 View commit details
  4. Copy the full SHA
    7db9687 View commit details
  5. Remove aligned writes and simplify unaligned writes

    Compilers are not taking advantage of the optimization opportunity, and
    these functions make the code more complex for no real gain.
    Unaligned writes can use the bytewrite macro to be shorter.
    aaaaaa123456789 committed Jan 15, 2022
    Copy the full SHA
    90e24db View commit details
  6. Copy the full SHA
    764f77f View commit details
  7. Simplify this check

    aaaaaa123456789 committed Jan 15, 2022
    Copy the full SHA
    7de1440 View commit details

Commits on Jan 19, 2022

  1. Copy the full SHA
    ae04c28 View commit details
  2. Copy the full SHA
    4636d66 View commit details
  3. Copy the full SHA
    109d37e View commit details
  4. Copy the full SHA
    dc135bd View commit details
  5. Copy the full SHA
    41f87cc View commit details
  6. Copy the full SHA
    2c01168 View commit details

Commits on Jan 20, 2022

  1. Copy the full SHA
    2bdb87e View commit details
  2. Copy the full SHA
    c66050c View commit details
  3. Copy the full SHA
    3e6fd55 View commit details

Commits on Jan 21, 2022

  1. Copy the full SHA
    dcb401b View commit details
  2. Update changelog

    aaaaaa123456789 committed Jan 21, 2022
    Copy the full SHA
    d90c627 View commit details

Commits on Jan 22, 2022

  1. Copy the full SHA
    a909b00 View commit details
  2. Copy the full SHA
    23e1c82 View commit details
  3. Copy the full SHA
    d2fc1f9 View commit details
  4. Copy the full SHA
    121d9be View commit details
  5. Fix PNG compression

    aaaaaa123456789 committed Jan 22, 2022
    Copy the full SHA
    d15765a View commit details
  6. Copy the full SHA
    e64cad6 View commit details
  7. Copy the full SHA
    3b3a4c1 View commit details
  8. Copy the full SHA
    ebcbfdf View commit details
  9. Copy the full SHA
    492c785 View commit details

Commits on Jan 23, 2022

  1. Copy the full SHA
    0264c24 View commit details

Commits on Jan 24, 2022

  1. Copy the full SHA
    294423c View commit details
  2. Copy the full SHA
    e3f47d1 View commit details
  3. Copy the full SHA
    34608d8 View commit details
  4. Update documentation for plum_load_image to indicate the true cause…

    …s for `PLUM_ERR_IMAGE_TOO_LARGE`
    aaaaaa123456789 committed Jan 24, 2022
    Copy the full SHA
    60f912a View commit details
  5. Copy the full SHA
    e10cee6 View commit details

Commits on Jan 25, 2022

  1. Copy the full SHA
    ec181e7 View commit details

Commits on Jan 29, 2022

  1. Copy the full SHA
    568e8c1 View commit details
  2. Copy the full SHA
    94e1fbf View commit details

Commits on Jan 30, 2022

  1. Copy the full SHA
    6183bea View commit details
  2. Copy the full SHA
    223b896 View commit details

Commits on Jan 31, 2022

  1. Make sure this works properly under uncommon integer overflow rules

    While every tool I've ever heard of will implement this operation
    correctly, it's technically signed overflow and thus undefined behavior.
    Surprisingly, ubsan doesn't catch it...
    aaaaaa123456789 committed Jan 31, 2022
    Copy the full SHA
    309edf0 View commit details
  2. Copy the full SHA
    beb60b4 View commit details
Showing with 3,826 additions and 2,954 deletions.
  1. +15 −3 Makefile
  2. +31 −2 README.md
  3. +1 −0 docs/README.md
  4. +7 −3 docs/alpha.md
  5. +1 −1 docs/building.md
  6. +74 −0 docs/changelog.md
  7. +5 −5 docs/colors.md
  8. +14 −7 docs/constants.md
  9. +8 −3 docs/conventions.md
  10. +72 −25 docs/formats.md
  11. +172 −96 docs/functions.md
  12. +6 −5 docs/macros.md
  13. +2 −1 docs/memory.md
  14. +25 −1 docs/metadata.md
  15. +27 −25 docs/modes.md
  16. +4 −2 docs/overview.md
  17. +10 −11 docs/slideshow.c
  18. +10 −9 docs/slideshow2.c
  19. +35 −11 docs/structs.md
  20. +114 −104 docs/tutorial.md
  21. +138 −0 docs/untrusted.md
  22. +2 −2 docs/version.md
  23. +10 −3 header/enum.h
  24. +4 −3 header/func.h
  25. +1 −1 header/libplum.h
  26. +8 −1 header/struct.h
  27. +12 −12 merge.sh
  28. +21 −21 src/allocator.c
  29. +72 −75 src/bmpread.c
  30. +102 −139 src/bmpwrite.c
  31. +73 −93 src/color.c
  32. +53 −0 src/data.h
  33. +21 −8 src/defs.h
  34. +0 −120 src/fractions.c
  35. +142 −0 src/framebounds.c
  36. +31 −27 src/framebuffer.c
  37. +156 −0 src/frameduration.c
  38. +25 −29 src/gifcompress.c
  39. +166 −175 src/gifread.c
  40. +128 −101 src/gifwrite.c
  41. +51 −57 src/huffman.c
  42. +14 −10 src/inline.h
  43. +88 −95 src/jpegarithmetic.c
  44. +26 −33 src/jpegcomponents.c
  45. +33 −26 src/jpegcompress.c
  46. +20 −29 src/jpegdct.c
  47. +24 −30 src/jpegdecompress.c
  48. +42 −37 src/jpeghierarchical.c
  49. +37 −46 src/jpeghuffman.c
  50. +67 −122 src/jpegread.c
  51. +112 −81 src/jpegreadframe.c
  52. +108 −0 src/jpegtables.c
  53. +67 −69 src/jpegwrite.c
  54. +63 −61 src/load.c
  55. +39 −26 src/metadata.c
  56. +18 −22 src/misc.c
  57. +8 −35 src/multibyte.h
  58. +33 −20 src/newstruct.c
  59. +128 −106 src/palette.c
  60. +80 −94 src/pngcompress.c
  61. +49 −73 src/pngdecompress.c
  62. +97 −102 src/pngread.c
  63. +81 −126 src/pngreadframe.c
  64. +142 −118 src/pngwrite.c
  65. +92 −85 src/pnmread.c
  66. +132 −155 src/pnmwrite.c
  67. +125 −101 src/proto.h
  68. +177 −0 src/sort.c
  69. +54 −55 src/store.c
  70. +21 −16 src/struct.h
18 changes: 15 additions & 3 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,10 +1,22 @@
CC ?= gcc
OUTPUT ?= libplum.so
OPTFLAGS = -march=native -mtune=native
DEBUGFLAGS =

CFLAGS = -Ofast -fomit-frame-pointer -fno-asynchronous-unwind-tables -fno-exceptions -Wl,-S -Wl,-x -Wl,--gc-sections \
$(OPTFLAGS)
CFLAGS = -std=c17 -Ofast -fomit-frame-pointer -fno-asynchronous-unwind-tables -fno-exceptions -Wl,-S -Wl,-x -Wl,--gc-sections $(OPTFLAGS)

DEBUGFLAGS = -Wall -Wextra -pedantic -Wnull-dereference -Wshadow -Wundef -Wunused -Wwrite-strings -Wno-sign-compare -Wno-implicit-fallthrough \
-Wno-parentheses -Wno-dangling-else -Wno-type-limits

ifneq (,$(findstring gcc,$(CC)))
DEBUGFLAGS += -Wduplicated-branches -Wduplicated-cond -Wlogical-op -Wshift-overflow=2 -fanalyzer -fanalyzer-verbosity=0 \
-Wno-analyzer-use-of-uninitialized-value
else
ifneq (,$(findstring clang, $(CC)))
DEBUGFLAGS += -Wno-keyword-macro -fsanitize=undefined -Wno-tautological-constant-out-of-range-compare
endif
endif

.PHONY: all clean basefiles debug

all: basefiles
$(CC) -shared -fPIC $(CFLAGS) build/libplum.c -o build/$(OUTPUT)
33 changes: 31 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# libplum

This is a C library designed to read and write common image file formats, and handle the resulting image data.
The library currently supports the BMP, GIF, PNG/APNG, JPEG and PNM (netpbm) formats; for more details, check the
[corresponding documentation page](docs/formats.md).

The main goal of the library is simplicity of use.
File formats are automatically detected, freeing the programmer from the burder of knowing in advance which formats to
@@ -11,6 +13,7 @@ The library has no dependencies besides the standard ISO C17 library functions,
in any application.

Please make sure to check the [documentation](docs/README.md) for further information.
A good starting point is the [tutorial](docs/tutorial.md).

Everything in this repository is released to the public domain under [the Unlicense](LICENSE).

@@ -19,8 +22,8 @@ Everything in this repository is released to the public domain under [the Unlice
To build the source files for inclusion in other projects, use `make basefiles`; this simply requires common POSIX
command-line tools (like a Bash shell).
This will generate the `build/libplum.c` and `build/libplum.h` files.
To build a binary for the library on top of the files mentioned above, use `make`; this requires a C17 compiler, and
will generate the `build/libplum.so` file on top of the files mentioned above.
To build a binary for the library (together with the files mentioned above), use `make`; this requires a C17 compiler,
and will generate the `build/libplum.so` file in addition to the source files.

To use the library, `#include "libplum.h"` from your code.
You may compile `libplum.c` along the rest of your code (provided you're using a C17-conformant compiler in your
@@ -37,6 +40,32 @@ For further information, please check the [documentation](docs/README.md).
source archive will contain documentation suitable for that version of the library.
If you're using an older version of the library, please refer to that documentation if needed.)

## Repository layout

The `src` directory contains all the C files of the project.
These files are concatenated in filename order into `build/libplum.c` at build time; the headers they include will be
copied into the output at the point of first inclusion.
Private headers (that is, headers that are not exposed in `libplum.h`) are also in this directory.

The `header` directory contains all public header files; the final public header, `build/libplum.h`, is generated from
`header/libplum.h` by recursively copying all included files at the point of first inclusion.
(Files in `header/` are not allowed to reference files from other directories.)

Other directories are self-explanatory: `docs` contains documentation and sample code, and `build` will be generated
by the build process to contain build artifacts.

## Acknowledgements

Thanks to [Rangi42](https://github.com/Rangi42) for her help reviewing much of the code and making a number of style
improvements and API suggestions.

Thanks to [nyanpasu64](https://github.com/nyanpasu64) for their help setting up the initial fuzzer setup, from which
the current setup (available in the [`fuzz`](https://github.com/aaaaaa123456789/libplum/tree/fuzz) branch) was
implemented.

Thanks to [ISSOtm](https://github.com/ISSOtm) for his help reviewing and correcting the shell script that generates
the `libplum.c` and `libplum.h` files.

## FAQ

**Q:** Does this library support the <insert format here> image format?
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -17,5 +17,6 @@ All documentation for the current version of the library can be found here.
- [Loading and storing modes](modes.md)
- [C++ helper methods](methods.md)
- [Supported file formats](formats.md)
- [Handling untrusted input](untrusted.md)
- [Library versioning](version.md)
- [Changelog](changelog.md)
10 changes: 7 additions & 3 deletions docs/alpha.md
Original file line number Diff line number Diff line change
@@ -25,8 +25,6 @@ Ordering is pure ASCII (that is, all uppercase letters come before all lowercase
- [`PLUM_BLUE_MASK_32` constant](constants.md#color-mask-constants)
- [`PLUM_BLUE_MASK_32X` constant](constants.md#color-mask-constants)
- [`PLUM_BLUE_MASK_64` constant](constants.md#color-mask-constants)
- [`PLUM_BUFFER` constant](constants.md#special-loading-and-storing-modes)
- [`PLUM_CALLBACK` constant](constants.md#special-loading-and-storing-modes)
- [`PLUM_COLOR_16` constant](constants.md#loading-flags)
- [`PLUM_COLOR_32` constant](constants.md#loading-flags)
- [`PLUM_COLOR_32X` constant](constants.md#loading-flags)
@@ -54,7 +52,6 @@ Ordering is pure ASCII (that is, all uppercase letters come before all lowercase
- [`PLUM_ERR_OUT_OF_MEMORY` constant](constants.md#errors)
- [`PLUM_ERR_TOO_MANY_COLORS` constant](constants.md#errors)
- [`PLUM_ERR_UNDEFINED_PALETTE` constant](constants.md#errors)
- [`PLUM_FILENAME` constant](constants.md#special-loading-and-storing-modes)
- [`PLUM_GREEN_16` macro](macros.md#color-macros)
- [`PLUM_GREEN_32` macro](macros.md#color-macros)
- [`PLUM_GREEN_32X` macro](macros.md#color-macros)
@@ -71,12 +68,17 @@ Ordering is pure ASCII (that is, all uppercase letters come before all lowercase
- [`PLUM_IMAGE_NONE` constant](constants.md#image-types)
- [`PLUM_IMAGE_PNG` constant](constants.md#image-types)
- [`PLUM_IMAGE_PNM` constant](constants.md#image-types)
- [`PLUM_MAX_MEMORY_SIZE` constant](constants.md#special-loading-and-storing-modes)
- [`PLUM_METADATA_BACKGROUND` constant](constants.md#metadata-node-types)
- [`PLUM_METADATA_COLOR_DEPTH` constant](constants.md#metadata-node-types)
- [`PLUM_METADATA_FRAME_AREA` constant](constants.md#metadata-node-types)
- [`PLUM_METADATA_FRAME_DISPOSAL` constant](constants.md#metadata-node-types)
- [`PLUM_METADATA_FRAME_DURATION` constant](constants.md#metadata-node-types)
- [`PLUM_METADATA_LOOP_COUNT` constant](constants.md#metadata-node-types)
- [`PLUM_METADATA_NONE` constant](constants.md#metadata-node-types)
- [`PLUM_MODE_BUFFER` constant](constants.md#special-loading-and-storing-modes)
- [`PLUM_MODE_CALLBACK` constant](constants.md#special-loading-and-storing-modes)
- [`PLUM_MODE_FILENAME` constant](constants.md#special-loading-and-storing-modes)
- [`PLUM_NO_STDINT` macro](macros.md#feature-test-macros)
- [`PLUM_NUM_DISPOSAL_METHODS` constant](constants.md#number-of-constants)
- [`PLUM_NUM_ERRORS` constant](constants.md#number-of-constants)
@@ -148,11 +150,13 @@ Ordering is pure ASCII (that is, all uppercase letters come before all lowercase
- [`plum_palette_buffer_size` function](functions.md#plum_palette_buffer_size)
- [`plum_pixel_buffer_size` function](functions.md#plum_pixel_buffer_size)
- [`plum_realloc` function](functions.md#plum_realloc)
- [`plum_rectangle` struct tag](structs.md#plum_rectangle)
- [`plum_reduce_palette` function](functions.md#plum_reduce_palette)
- [`plum_remove_alpha` function](functions.md#plum_remove_alpha)
- [`plum_rotate_image` function](functions.md#plum_rotate_image)
- [`plum_sort_colors` function](functions.md#plum_sort_colors)
- [`plum_sort_palette` function](functions.md#plum_sort_palette)
- [`plum_sort_palette_custom` function](functions.md#plum_sort_palette_custom)
- [`plum_store_image` function](functions.md#plum_store_image)
- [`plum_validate_image` function](functions.md#plum_validate_image)
- [`plum_validate_palette_indexes` function](functions.md#plum_validate_palette_indexes)
2 changes: 1 addition & 1 deletion docs/building.md
Original file line number Diff line number Diff line change
@@ -77,7 +77,7 @@ Otherwise, add a `#define PLUM_NO_STDINT` definition and `typedef` definitions f
(The library **requires** 64-bit integer types: if you cannot define the `uint64_t` type, you cannot use the library.)
This can be done in a separate header, like so:

```c
``` c
/* C89-only helper to substitute the missing <stdint.h> header */
#ifndef HELPER_LIBPLUM_H

74 changes: 74 additions & 0 deletions docs/changelog.md
Original file line number Diff line number Diff line change
@@ -2,6 +2,80 @@

Note: releases are listed from latest to oldest.

## Version 1.2 (29 October 2022)

- Added `PLUM_METADATA_FRAME_AREA` metadata node when reading GIF, APNG and PNM files, preserving the sizes of the
frames read in
- Updated image generators for GIF, APNG and PNM formats, to handle `PLUM_METADATA_FRAME_AREA` metadata when possible
- Fixed alignment errors when `alignof(jmp_buf) > alignof(max_align_t)`
- Fixed undefined behavior when reading PNG files due to array index overflow after signed to unsigned conversion
- Fixed memory leak on `plum_realloc` failure
- Corrected a mistake in the documentation for `plum_store_image`
- Improved the performance of sorting operations (such as color sorting when generating a palette)

## Version 1.1 (9 May 2022)

- Fixed palette reduction for palettes with more than 128 colors
- Fixed invalid memory accesses in PNG file generation that could occur if `uint_fast8_t` was as wide as (or wider
than) `ptrdiff_t`
- Fixed and improved the shell script that generates the `libplum.c` and `libplum.h` files, making it more resilient
to unusual environments (such as paths with spaces in them)
- Allowed loading PNG and APNG files with invalid background or transparent colors (which are now ignored)
- Allowed loading JPEG files containing extraneous data after the end marker
- Added support for JPEG files without explicit Huffman tables (using the recommended tables from the standard),
following the behavior of many common JPEG viewers
- Prevented bitmasked BMP files with completely empty bitmasks from loading (erroring out with `PLUM_ERR_NO_DATA`)
- Adjusted frame durations when generating animations to accumulate rounding errors into subsequent frames, preserving
the average frame rate of longer animations

## Version 1.0 (14 February 2022)

- Fixed `plum_sort_palette` ensuring that no colors are exchanged in the image
- Fixed handling of simultaneous local and global palettes in GIF images where the local palette was a superset of the
global palette
- Fixed some rare cases of JPEG component detection and handling
- Added new function `plum_sort_palette_custom` (with its corresponding documentation)
- Renamed the `user` member of the `plum_image` struct to `userdata`
- Added and documented new `PLUM_MAX_MEMORY_SIZE` constant
- Renamed `size` argument of `plum_load_image` and `plum_store_image` to `size_mode`
- Renamed `PLUM_FILENAME`, `PLUM_BUFFER` and `PLUM_CALLBACK` constants to `PLUM_MODE_FILENAME`, `PLUM_MODE_BUFFER` and
`PLUM_MODE_CALLBACK` (the older constants are currently still available, but undocumented, for compatibility)
- Added new documentation page on handling untrusted images

## Version 0.4 (1 February 2022)

- Fixed a bug when loading APNG files with reduced frames
- Fixed emitting GIF files with transparent pixels
- Fixed a bug in the GIF compressor that would generate invalid compressed frame data when a code size increase and
reduction occured at the same time
- Fixed a file descriptor leak that would keep an open `FILE *` if a `PLUM_ERR_FILE_ERROR` error was raised while
reading from a file
- Fixed a bug that prevented non-vertically-flipped BMP files from ever loading
- Fixed read-past-the-end bug when loading monochrome BMP files with a width that is a multiple of 8
- Added safeguards to prevent internal `longjmp` misuse when generating image files
- Ensured that the `PLUM_FILENAME`, `PLUM_BUFFER` and `PLUM_CALLBACK` constants are always `size_t` as documented
- Enforced the size limitation on the value returned by a callback when using the `PLUM_CALLBACK` loading/storing mode
- Added a validation for `PLUM_BUFFER` arguments to `plum_load_image`, ensuring that the buffer's `data` member isn't
a null pointer
- Handled out-of-palette background colors when generating a GIF file, ensuring that they would never cause the
process to fail (the background is ignored instead if there are no available palette slots)
- Improved the GIF loader to account for looping extensions that don't appear at the beginning of the file (as long as
there is at most one per file)
- Added some warning flags for debug builds, and cleared some warnings that would be raised by them
- Added and improved some safety checks that detect maliciously-crafted and other pathological files
- Added detection for empty BMP and GIF files (erroring out with `PLUM_ERR_NO_DATA` instead of
`PLUM_ERR_INVALID_FILE_FORMAT`)
- Allowed decompressing BMP files that end their last line with a row end marker (and maybe no data end marker)
- Improved PNG compression by fixing a lookback bug in the compressor and adjusting the lookback length
- Prevented BMP images with a height of `0x80000000` from loading, since this is a negative 32-bit value that has no
positive counterpart (erroring out with `PLUM_ERR_INVALID_FILE_FORMAT`)
- Ensured that GIF frames are always read with a non-zero duration (frames with an instant duration will contain a
duration of 1 nanosecond in the `PLUM_METADATA_FRAME_DURATION` metadata node, as documented)
- Added and documented a restriction requiring `size_t` to be at least 32 bits wide
- Updated documentation for `plum_load_image` to indicate that a `PLUM_ERR_IMAGE_TOO_LARGE` error may also occur if
the image's overall dimensions are too large
- Some minor documentation updates and code cleanup

## Version 0.3 (10 January 2022)

- New functions: `plum_load_image_limited`, `plum_check_limited_image_size`, `plum_append_metadata`
10 changes: 5 additions & 5 deletions docs/colors.md
Original file line number Diff line number Diff line change
@@ -9,17 +9,17 @@
Regardless of the actual formats used for color and pixel data in image files, the library uses a number of standard
color formats and converts to and from those formats respectively when loading and generating image files.
The user chooses which color format to use via an argument when loading an image (or a struct member when creating one
manually); therefore, while the library supports processing data in all supported color formats, users only need to
choose one and use the one they prefer.
manually); therefore, while the library can process data in all supported color formats, users only need to choose one
and use the one they prefer.

All color formats contain red, green, blue and alpha channels.
There is no dedicated support for grayscale or no transparency formats; images using those formats will be converted
There is no dedicated support for grayscale or no-transparency formats; images using those formats will be converted
to RGBA when loaded.

All color formats use fixed-width integers for color values.
The channels are always in RGBA order from least significant to most significant bit; in other words, the red channel
always takes up the least significant bits and the alpha channel always takes up the most significant bits.
There are no unused bits, and the three color channels always have the same bit width.
There are no unused bits, and the three color channels (red, green and blue) always have the same bit width.

There are [helper macros][macros] available to generate color values out of their components and extract those
components from a color value.
@@ -83,7 +83,7 @@ The palette itself stores colors in whichever color format is set for the image
member).

An image uses indexed-color mode if its `palette` member (and therefore, the corresponding `palette16`, `palette32`
and `palette64` members, which alias `palette`) is not null.
and `palette64` members, which alias `palette`) is not a null pointer.
In this case, the `max_palette_index` member determines the maximum valid index value (and thus implicitly the size of
the palette); note that this maximum is _inclusive_, so that a `max_palette_index` of 3 indicates a palette with four
colors (with indexes ranging between 0 and 3).
21 changes: 14 additions & 7 deletions docs/constants.md
Original file line number Diff line number Diff line change
@@ -34,11 +34,16 @@ These constants are of `size_t` type, and they don't belong to an `enum`.
Their values are the highest possible values of that type, and therefore they are extremely unlikely to collide with
actual buffer sizes.

- `PLUM_FILENAME`: indicates that the `buffer` argument is a `char *` value containing a filename.
- `PLUM_BUFFER`: indicates that the `buffer` argument is a [`struct plum_buffer *`][buffer] value that describes (or
will describe) a memory buffer and its size.
- `PLUM_CALLBACK`: indicates that the `buffer` argument is a [`struct plum_callback *`][callback] value, containing a
callback function that will be called to read or write data.
- `PLUM_MODE_FILENAME`: indicates that the `buffer` argument is a `char *` value containing a filename.
- `PLUM_MODE_BUFFER`: indicates that the `buffer` argument is a [`struct plum_buffer *`][buffer] value that describes
(or will describe) a memory buffer and its size.
- `PLUM_MODE_CALLBACK`: indicates that the `buffer` argument is a [`struct plum_callback *`][callback] value,
containing a callback function that will be called to read or write data.

Additionally, the `PLUM_MAX_MEMORY_SIZE` constant represents the maximum size that will be interpreted as a true size
instead of a special loading/storing mode.
(A value of `size_mode` no larger than this constant will be treated as the size of the buffer pointed to by
`buffer`.)

For more information, see the [Loading and storing modes][loading-modes] page.

@@ -79,6 +84,8 @@ These constants are used to specify the type of a metadata node.
- `PLUM_METADATA_FRAME_DURATION`: node containing the duration of each frame in an animation.
- `PLUM_METADATA_FRAME_DISPOSAL`: node indicating the action that must be taken on an animation's frame buffer after
an animation frame has been rendered and displayed for the required amount of time.
- `PLUM_METADATA_FRAME_AREA`: node containing the true dimensions and coordinates of the frames that comprise a
multi-frame file.

For more information, see the [Metadata][metadata] page.

@@ -123,7 +130,7 @@ Naturally, when flags are combined with a bitwise OR (`|`), the "zero" member (w
default and can be left out.
Groups also have a mask member, which can be used to mask out that group's bits (for checking, etc.)

Note that, since members of this struct are meant to be combined via bitwise OR (`|`), their values are **not**
Note that, since members of this enumeration are meant to be combined via bitwise OR (`|`), their values are **not**
consecutive.

**Color format flags:** these flags are used to determine the image's or the color buffer's color format.
@@ -143,7 +150,7 @@ See the [Color formats][colors] page for more information.
[indexed-color mode][indexed] or not.
Some modes will load the image in direct-color mode (i.e., without a palette) or indexed-color mode (i.e., with a
palette) depending on the image data; in those cases, the image's `palette` member can be used to determine what mode
the image is using (`NULL` for direct-color mode or non-`NULL` for indexed-color mode).
the image is using (null pointer for direct-color mode or non-null for indexed-color mode).

- `PLUM_PALETTE_NONE` (zero): don't use indexed-color mode at all.
If the image has a palette, it will be removed on load.
Loading