Image loader/saver for the BEAM graphics library

🚧 This project is under active development. Do not used at the moment as it's not ready. Consult the develop branch for progress.

A helper library to complement the graphics library of the BEAM ecosystem and load images into ready-to-use textures.

It decodes and encodes PNG, JPEG, and BMP as a graphics:image(). It does not draw and it does not create a GPU texture. Upload pixels with graphics_texture:with_image/1.

{ok, Image} = graphics_image_png:load("sprite.png"),
{ok, Texture} = graphics_texture:with_image(Image).

Image = graphics_surface:image(Surface),
ok = graphics_image_png:save(Image, "screenshot.png").

decode/1 and encode/1 work on binaries. load/1 and save/2 are file wrappers. save/2 takes the image first, then the path.

Supported formats:

• PNG (graphics_image_png)
• JPEG (graphics_image_jpeg), quality 90, no alpha
• BMP (graphics_image_bmp), 24-bit on encode, no alpha

Pixels are row-major RGBA colors. X varies fastest, then Y. (0, 0) is the first pixel. The codec does not Y-flip. Gray, RGB, and palette sources expand to alpha 1.0.

The native backend is stb_image and stb_image_write. Building the NIF requires CMake.

Written by the Erlangsters community and released under the MIT license.

Using it in your project

With the Rebar3 build system, add the following to the rebar.config file of your project.

{deps, [
  {beam_graphics, {git, "https://github.com/erlangsters/beam-graphics.git", {tag, "master"}}},
  {beam_graphics_image, {git, "https://github.com/erlangsters/beam-graphics-image.git", {tag, "master"}}}
]}.

In practice, you want to replace the branch "master" with a specific tag to avoid breaking your project if incompatible changes are made.

Later

These stay out of the current slice:

• a sniffer graphics_image:load/1 that dispatches on magic bytes
• load_texture / with_texture (needs a live graphics context)
• GIF, WebP, HDR, TIFF, and animation
• a Y-flip option (the texture API does not flip)
• color space on the image (belongs on graphics_texture)
• JPEG quality arity and PNG filter or compression options
• 16-bit and float images
• a GPU-backed decode → graphics_texture:with_image → remote_image test