All images are passed using reference counted handles so that they are automatically cleaned up when the last handle is freed. Only having one way to pass images hidden behind a referebce counted handle type removes the burden of remembering if you passed it as a value, reference, pointer, shared pointer or unique pointer. There's just one way to pass images, using the safe handles. By using global methods for all image operations, accidentally calling a method on a null objects can be caught safely instead of triggering undefined behaviour with random crashes. Always passing by reference for convenience however costs a little bit more to allocate, so don't create and destroy sub-images all the time.
The most basic image format used for 8-bit gray-scale images using 0 for black and 255 for white. Can be displayed by drawing it using draw_copy onto a color image for automatic conversion.
If 8-bit precision is not enough but you still want the determinism of using integers, there's also a 16-bit monochrome image. Just like 8-bit images, the visible range is 0 to 255 when converting automatically, but the 16-bit image has a higher range up to 65535 (2¹⁶ - 1).
32-bit floating-point images offer more flexibility for advanced image filtering, but does not have the same determinism as integer formats. Avoid exact equality comparisons using floating-point numbers, because it's always an approximation and the rounding method may differ between CPU models.
A 32-bit color image format using 4 channels with 8 bits in each. The alpha channel can be used to represent opacity or any other information needed.
Then there's the aligned image types AlignedImageU8, AlignedImageU16, AlignedImageF32 and AlignedImageRgbaU8. Aligned images are created from the constructors by default because new images are always aligned for SIMD vectorization. Aligned integer images (AlignedImageU8, AlignedImageU16 and AlignedImageRgbaU8) use DSR_DEFAULT_ALIGNMENT to be compatible with the largest supported SIMD vector capable of processing all element types, called the X vector (F32xX, I32xX, U32xX, U16xX, U8xX). Aligned float images (AlignedImageF32) use DSR_FLOAT_ALIGNMENT to be compatible with the largest supported floating-point SIMD vector, called the F vector (F32xF). The F vector size is as least as large as the X vector size, so floating-point images aligned for the F vector are also aligned for the X vectors. Non-aligned images are created as sub-images pointing to existing pixel buffers without cloning.
The ordered image type OrderedImageRgbaU8 is aligned just like AlignedImageU8 but also ensures that the pack order is RGBA on every platform, which makes it easy to manuipulate using pointers. AlignedImageRgbaU8 can however be dynamically set to different internal pack orders using the constructor image_create_RgbaU8_native, which is used by the window's canvas.
image_load_RgbaU8 can be used to load an RGBA image from a file. If you only need one channel, then use image_get_red on the result to extract the first channel from a gray-scale image.
image_save can be used to save an RGBA image to a file.