Writing PPM Image Files in C
-------------------------------------------------------------------
< intro >
PPM is probably the simplest image format that is somewhat decently
supported by image viewers.
While it's not efficient or useful for storing and sharing images,
its simplicity makes it a quick way to produce an image from your
C programs (or any other language) in like 20 lines of code.
This saves a lot of time when you want to quickly put together a
program that renders an image and it's also more appealing to both
newbyes and experts than having to mess with an image library.
It's especially neat when your write the PPM output directly to
stdout and pipe it into an image viewer, such as imagemagick's
display (./myprogram | display), which is how I used it in a
raytracer I recently wrote.
< index >
/p1 Specification
/p2 Creating and displaying a sample PPM image in bash
/p3 Walkthrough of a C function to write PPM files
/p4 Full example code using the function from ppm03
< p1 >
It starts with a header plain text string that contains:
- A magic string "P6"
- The width of the image in pixels
- The height of the image in pixels
- The maximum color value (must be less or equal than 0xffff).
Each element of the header is separated by whitespace (either
spaces, tab, CR, LF) and the header ends with a single whitespace
character.
For example the header for a 640x480 image with 255 colors would be
"P6 640 480 255\n".
The header is followed by the binary pixel data.
The order of the pixel data is as straightforward as it gets: rows
are written from top to bottom, and each row contains the pixels'
r, g, b values from left to right.
The r, g, b values are 1 byte each if the maximum color value is
less or equal than 0xff, otherwise they are 2 bytes.
So, if we make a 2x2 checkerboard of white and black pixels in a
255 colors image, the data will look like this:
ff ff ff 00 00 00 00 00 00 ff ff ff
< p2 >
Now that we know the PPM format, we can easily produce said image
and display it:
And of course, we can pipe the file directly into display:
===================================================================
$ printf "P6 2 2 255
\xff\xff\xff\x00\x00\x00\x00\x00\x00\xff\xff\xff" \
| display -sample 50x50 -
===================================================================
Note that the "sample 50x50 -" parameters are purely to make this
2x2px image visible since it's so small, with a normal picture
just piping into "display" will be enough.
< p3 >
Now that we have mastered the PPM format, writing a C function to
produce a ppm file is trivial.
I strongly recommend you go and try writing the program yourself,
it's a good excercise and it's more fun than getting spoonfed.
If you aren't a complete beginner at C you can skip to the bottom
of the file (p4) to see the full code which should be self
explanatory.
First of all, let's define ourselves some type shortcuts:
===================================================================
typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned long u32;
Our function will take:
- A file stream to write the image to
- An array of floats defining the rgb values for the pixels with
values between 0.0f and 1.0f. This is in the same order as the
pixel data in the ppm format.
- Width and height. These will be u16, so we will only accept
image up to 65535x65535.
It will return zero for success or non-zero values for errors.
We will only use 255 colors to avoid having to specify the color
depth every time.
Writing the header is a simple fprintf (include stdio.h):
===================================================================
fprintf(f, "P6 %u %u 255\n", w, h);
===================================================================
Iterating the pixel array can be done with simple pointer math:
===================================================================
for (i = 0; i < (u32)w * (u32)h; ++i)
{
/* do stuff */
Notice how I prevent overflows by clamping the floats to 1.f using
the min macro. We could also do this for underflows but I don't
think they're as common.
My min macro (the brackets are for safety):
===================================================================
#define min(a, b) ((a) < (b) ? (a) : (b))
===================================================================
Now we can fwrite the pixel:
===================================================================
fwrite(color, 1, 3, f);
===================================================================
Where 1 is the size of each element (1 byte).
< p4 >
Here's an example program that generates a checkerboard and
writes it to stdout using our function with full error checking:
