[ Introduction ]
PixelToaster is a library for C++ programmers who want to write their own
software rendering routines, instead of using hardware accelerated
rendering with OpenGL or Direct3D.
To use PixelToaster, all you need to do is "open" a display at the desired
resolution, then each frame, render into an array of pixels and "update"
your pixels to the display.
[ Installation ]
* Windows:
PixelToaster for Windows requires DirectX 9.0.
First you must make sure you have the latest DirectX Runtime installed.
Visual C++ Users:
- Install the latest DirectX SDK so you have its headers and libs
- If you are using Visual C++ Express, you need to install the
Platform SDK if you havent already. Follow the instructions on
the Visual C++ Express site.
- If you plan on building PixelToaster from the command line (nmake)
make sure you add the appropriate DirectX directories to your LIB
and INCLUDE environment variables
- To use the solution file, just open PixelToaster.sln select the
example project you want to build (right click, make active project),
and press F5 to build & run. For speed, switch to "Release"
- The solution file only supports the latest Visual Studio 2005,
so if you have an earlier version of Visual C++, you'll need to use
nmake or create your own solution/project files.
- To use nmake, open "Visual Studio XXXX Command Prompt" to get a cmd
line with the path and environment fully setup, then type:
nmake -f makefile.visualc
MinGW Users:
- You *DO NOT* need to install the DirectX SDK
- Make sure your MinGW installation includes the Windows and DirectX
headers. The easiest way to do this is to simply install the entire
MinGW package instead of the smaller pieces. The full package
contains everything you need to build PixelToaster.
- Go to the command line and type:
mingw32-make -f makefile.mingw
- All the example programs will be built for you
- You can use PixelToaster with Dev-C++ or any other IDE
on top of MinGW, just as long as you setup your own project files.
* UNIX: FreeBSD, Linux and Mac OS X
The supported display on FreeBSD and Linux is XWindows,
on Mac OS X Cocoa/OpenGL is used.
To compile the example programs, just use make:
make -f makefile.linux
make -f makefile.bsd
make -f makefile.apple
Pick the correct line based on your platform obviously,
I like to speed things up a bit my using a symbolic link:
For example on Mac OS X, I just go:
ln -s makefile.apple makefile
make
So everything is easy from this point on:
make test
make profile
make all
make docs
make clean
In order to make docs, you'll need to have doxygen installed:
http://www.doxygen.org
Alternatively, you can browse the docs for the latest release online:
http://www.pixeltoaster.com
Have fun!
[ How to Use PixelToaster ]
The API of PixelToaster is so easy to use, just look at the example programs
and you'll get the idea quickly.
However, what isnt obvious at first, is exactly what to do with the pixels!
Obviously, I cant teach software rendering in a few pages, but here is a quick
tutorial to get you started...
[ Pixels in Memory ]
Pixels are laid out in memory sequentially from top to bottom, left to right.
You can visualize this by rearranging each line of the image into a single chain,
each line bolted on at the end of the one above it, in one long line.
Lets say we have an image of dimensions 320x240, that is:
width = 320
height = 240
Pixel pixels[320*240];
Coordinate (0,0) is the top-left of the screen, and (319,239) is the bottom right.
Your x coordinate needs to be in range [0,319] and your y coordinate needs to be
in range [0,239]
We can find the index of a pixel given its (x,y) coordinates as follows:
int index = x + y * width;
So we can set get this pixel as follows:
pixel[index] = Pixel( 0, 0, 1 ); // set to blue
If you think about this closely, you are starting from the top-left of the screen,
advancing past all the whole lines above the line you want (y*width). This gets
you to the start of the line you want, so all if you have to do now is add "x"
and you have the index of the pixel at (x,y).
[ Pixel Format ]
You have the choice of working in truecolor or floating point color.
Truecolor has 32bit integer pixels with byte size rgb color components,
while floating point color has 128bits per pixel, with floating point values
for red, green, blue and alpha!
All things being equal, floating point is obviously slower than truecolor,
if for no reason other than requiring 4X the memory bandwidth! However, the
increased dynamic range and high precision of floating point make it a very
interesting format to work in.
[ Working in Floating Point Color ]
Floating point pixels made up of four floating point values:
struct FloatingPointPixel
{
float r,g,b,a;
};
You set the color of a pixel by setting its components.
The alpha value is for padding to 128bits. You can ignore it, or use it for
any purpose you like. It makes a nice z-buffer for a software renderer, or
alpha channel for compositing.
Each component is in range [0.0, 1.0f]
0.0f is minimum intensity (dark), while 1.0f is maximum intensity.
At the moment, values outside this range are automatically clamped.
In the future, these values will be used to indicate "high dynamic range"
to high contrast displays!
Here are some examples:
black = (0,0,0)
white = (1,1,1)
red = (1,0,0)
green = (0,1,0)
blue = (0,0,1)
really bright white = (1000000,1000000,1000000) ... !!!
[ Working in TrueColor ]
In truecolor, pixels are packed into 32bit integer values, like this:
[x][r][g][b]
r,g,b are the red, green and blue color components making up the color.
the x component is padding so the pixel takes up 32 bits.
Each component is in the range [0,255] with 0 being lowest intensity,
and 255 being maximum intensity.
therefore:
black is (0,0,0) -> 0x00000000
bright red is (255,0,0) -> 0x00FF0000
bright green is (0,255,0) -> 0x0000FF00
bright blue = (0,0,255) -> 0x000000FF
You can unpack and manually using masking and shift operations:
integer8 r = ( pixel & 0x00FF0000 ) >> 16;
integer8 g = ( pixel & 0x0000FF00 ) >> 8;
integer8 b = ( pixel & 0x000000FF );
And repack them again with shifts:
integer32 repacked = ( r << 16 ) | ( g << 8 ) | b;
Alternatively, you can treat your array of pixels as an array of
TrueColorPixel structs and use its union to access pixels:
TrueColorPixel pixel;
pixel.r = 128;
pixel.g = 10;
pixel.b = 192;
This is much easier! Just remember that each r,g,b value can only
in the range [0,255] when working with it - if you go outside this range
the color will wrap around from light to dark and vice versa.
[ Example Programs ]
* ExampleFloatingPoint
- how to open a display in floating point color and get pixels on the screen
* ExampleTrueColor
- the same thing, but in truecolor
* ExampleFullscreen
- how to open a fullscreen display
- fullscreen output is currently only supported in windows (DirectX 9.0)
and Mac OS X.
* ExampleKeyboardAndMouse
- how to receive keyboard and mouse events from a display
* ExampleTimer
- how to use the high resolution timer
* ExampleImage
- how to load a TGA image and display it
* ExampleMultiDisplay
- how to work with multiple displays (windowed only)
[ Licence ]
PixelToaster Framebuffer Library.
Copyright © 2004-2007 Glenn Fiedler
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
Glenn Fiedler
gaffer@gaffer.org