Saving Pictures

Saving pictures

The original SaveBuffer and SaveImage only wrote BMP files, whatever the name of the file was. Here the end of the file name picks the format, and an optional last argument, a text of settings, picks how the file is made. Old calls work as before, except that a name that ends in .png has been a PNG since the early versions, and the other endings below are new.

Ending	Format	Settings that count	Metadata
.bmp, or any other ending	BMP, 32 bit with alpha	none	none
.png	PNG, with an alpha channel only if a pixel is see-through	compression	Exif (eXIf chunk) and a Software text
.jpg, .jpeg	JPEG, baseline or progressive (no alpha)	quality, subsampling, progressive	Exif (APP1 segment)
.webp	WebP, lossy or lossless	quality, lossless	Exif (EXIF chunk)
.jxl	JPEG XL, lossy or lossless	quality, distance, lossless, effort	Exif (Exif box)
.tga	TGA	rle	none
.dds	DDS, uncompressed or block compressed (BC1 to BC5, BC7), with or without mip maps	format, mipmaps, levels, srgb	none
.avif	not written, the result is 0

AVIF can be read but not written: the AV1 encoder is the biggest part of an AVIF library and would about double the size of every program, which is why it is left out of the build. Convert to WebP or JPEG XL instead.

The same 640x360 screenshot (921,738 bytes as BMP), cut to the area that shows the differences and saved with different settings, then loaded again. Lossless files are the same as the original, the lossy ones lose detail where it is sharp (JPEG at quality 40 shows blocks and smeared colors):

Settings

The settings are one text of name=value pairs, separated by commas, semicolons or spaces. Names are not case sensitive, and a name without a value (progressive) means =1. A setting that the format of the file does not use is ignored, so one text can be used for several files. A name that does not exist or a value that is not allowed is reported once on the console and ignored, the rest still counts.

Setting	Values	Default	Meaning
quality	0 to 100	90	JPEG, WebP (lossy) and JPEG XL (lossy): higher is better and bigger. JPEG XL turns it into a distance the way cjxl does, and 100 is lossless.
subsampling	444, 422, 420 (also 4:2:0)	420	JPEG: how much of the color is kept. 444 keeps all of it (sharp colored edges, big files), 420 a quarter.
progressive	0 or 1	0	JPEG: the file is made of scans that show the whole picture blurry first and sharpen it, which viewers show while a file is still loading.
lossless	0 or 1	0	WebP and JPEG XL: no loss at all. For JPEG XL lossless=0 keeps it lossy even at quality=100.
distance	0 to 25	from quality	JPEG XL: the lossy distance directly, 1 is visually lossless and 0 is lossless. Wins over quality.
effort	1 to 9	5	JPEG XL: how long the encoder searches. 1 is fastest, 9 gives the smallest files.
compression	0 to 9	6	PNG: 0 stores the pixels without compression, 1 is the fastest and 9 the smallest file.
rle	0 or 1	1	TGA: run length encoding.
format	rgba8, bgra8, bgr8, rgb565, r8, rg8, bc1 (dxt1), bc2 (dxt3), bc3 (dxt5), bc4, bc5, bc7	rgba8	DDS: how the pixels are stored. r8, bc4 keep red, rg8, bc5 red and green; the others keep all colors, and the formats with alpha (rgba8, bgra8, bc2, bc3, bc7) keep that too (bc1 has a hole for pixels that are mostly see-through).
mipmaps	0 or 1	0	DDS: store all mip maps down to 1x1, each made by averaging 2x2 pixels of the one before.
levels	1 to 16	1	DDS: store at most this many levels (the picture itself is the first), so levels=3 is a picture and two smaller ones. It wins over mipmaps.
srgb	0 or 1	0	DDS: mark the colors as sRGB, which needs a DX10 header (bgr8 becomes bgra8). rgb565, r8, rg8, bc4 and bc5 have no sRGB form.
metadata	0 or 1	1	Whether the file says which program made it.

SaveBuffer FrontBuffer(), "shot.png"                                   ; lossless, default compression
SaveBuffer FrontBuffer(), "shot.jpg", "quality=95,subsampling=444"      ; sharp colors
SaveBuffer FrontBuffer(), "web.jpg", "quality=70,progressive=1"         ; small, shows blurry first
SaveBuffer FrontBuffer(), "shot.webp", "lossless=1"
SaveBuffer FrontBuffer(), "shot.jxl", "distance=1,effort=7"             ; visually lossless
SaveBuffer FrontBuffer(), "plain.png", "metadata=0, compression=9"

DDS files

format picks what is stored, and the others only add to it. Uncompressed formats keep every pixel as it is (rgb565 loses the low bits), the block compressed ones cut the picture into 4x4 pixel blocks of 8 or 16 bytes, which is 4 to 8 times smaller than rgba8 and loses some detail where a block has many different colors. They stay compressed on the graphics card when the file is loaded again with LoadTexture. The BC1 to BC3 encoders put the colors of a block on a line and refine its ends a few times. bc7 tries three of its eight modes for every block and writes the closest: mode 6 (one pair of RGBA ends), mode 5 (alpha apart from the color) and, for opaque blocks, mode 1 (two groups of pixels out of 64 ways to split a block). It is a good deal better than BC1 and BC3 on opaque pictures, but not as good as an encoder that tries all modes, and for blocks with a changing alpha BC3 can come out closer. It is meant for exports, not for the slowest and best result. Sizes of a picture that are not a multiple of 4 repeat the edge pixels inside the last blocks.

Files that older programs can read use the plain header (DXT1, DXT3, DXT5, BC4U, BC5U and masks for the uncompressed ones). A DX10 header is written where there is no other way: bc7, rg8 and srgb=1.

SaveImage img, "sprite.dds"                                  ; RGBA8, no loss
SaveImage img, "sprite.dds", 0, "format=bc3, mipmaps=1"      ; small, with mip maps
SaveTexture tex, "albedo.dds", 0, "format=bc7, srgb=1, mipmaps"
SaveBuffer ImageBuffer(img), "mask.dds", "format=bc4"        ; red channel only

Metadata

Files carry Exif metadata with the description and the software set to Generated by <title>, where the title is the one of AppTitle and BlitzLLVM until the program sets one. PNG files have it as eXIf chunk and as a Software text chunk too, because some programs only read the text. JPEG, WebP and JPEG XL files have the Exif block that image viewers show as the camera/software information. BMP, TGA and DDS have no place for it. metadata=0 leaves it out.

On another thread

Encoding takes time that a game may not have in a frame. On a test machine a 1920x1080 screenshot took about 60 ms as JPEG, 80 ms to 2 seconds as PNG (compression=1 to 9), 165 ms as lossy WebP and 80 ms to 3 seconds as JPEG XL (effort=3 to a lossless effort=7). AsyncSaving True (or BLITZLLVM_ASYNC_SAVE=1 in the environment) makes the save commands only read the pixels, and a worker thread encodes and writes the file. SavesPending and SavesFailed tell how it is going, and a program that ends waits for its saves. It is off by default, so a save has written its file when the command returns.

Libraries

The WebP and JPEG XL files are written by the same shared libraries that read them (libwebp, libjxl) next to the program, which are looked up when the first such file is saved. If one is missing the save gives 0 and the console says so once.