In short, i have searched high and low, far and wide, for documentation on getpixel().

I have a simple question which i'm assuming has a simple answer. how do i use it properly.

I'm working on a breakout clone, i have to test what color the block is. i created an integer named color. // color = getpixel(buffer, 2,0)
x/y coordinates are chosen b/c i know logically what their color is. I am just testing to see how i use getpixel() properly. logically, the color is black. however, my question finally is....
if getpixel returns an integer, how is that translated into RGB color?
I must have overlooked this and am at the point where the answer is right in front of me, but i'm completely blind to it :-)

Use getpixel then do this for anything othern than 8 bit:

if( color = makecol( 0, 0, 0))
  its black();

If you don't know how to use makecol, just click on the word.

Or you can just do what ML posted below me.

http://www.allegro.cc/manual/getpixel
http://www.allegro.cc/manual/getr
http://www.allegro.cc/manual/getg
http://www.allegro.cc/manual/getb
http://www.allegro.cc/manual/geta

thank you VERY much. i can't tell you how many times i've read the allegro documentation on getpixel() and it's variants. but they mean nothing as i've read them in frustration. thanks again for the help.

I don't mean to be telling you how to do your game, but I think you might get better performance by storing it as an INT on creation and using defines. I think I heard somewhere that getpixel is a relatively slow function, plus doing it this way seems cleaner to me. If you are only doing this for the testing purposes, then go ahead and do that, otherwise, consider the following.

I recommend this because making sure all of your blocks have exactly the right color at exactly the right position is tedious work on your part, and because multiple blocks could have the same pixel at the same positions yet look different or act different. Again, this is just my two-cents. If you prefer doing it the way you already are, feel free to do so.

Care to explain what's wrong with it?

I think his problem, Evert, was the link between the value that getpixel returns and the actual colour it corresponds to. From a newbie point of view you can understand this because getpixel is in a completely different section (primitives) to the section that deals with colours (true-colour and paletted). Maybe what the manual needs is more cross-references and linkage, e.g. colour->primitives->transparency/patterned.

Of course, if he just uses 8bit then that isn't a problem as you can just use the palette index and ignore colour conversions

@Neil: Allegro represents colors in a fairly standard way (using a palette for 8bpp and packed rgb values for everything else). Explaining such a standard way of doing things would probably go beyond the scope of a programming library documentation, and I think it's safe to assume that everybody who wants to use allegro either
a) is familiar with basic (graphics) programming concepts and procedures, or
b) is willing to read up on those

@OP: While getpixel() can do what you want it to, it is probably not wise to use it for this. IIUC, you want to use getpixel() to perform collision detection. While to the beginner this seems an intuitive and straightforward way to do things, it is not a "clean" nor a "fool-proof" way. Generally, you want to separate logic (objects and their interaction, movement, collision detection and response, physics etc.) from rendering (displaying objects on screen), so that the logic code never touches any graphics-related code, and the graphics code never changes any object data. So what you'd need is:
1. A tile grid to hold the blocks; this can be a simple 2d array of ints, 0 representing an empty spot, and any other value representing pre-defined constants (which may represent colors directly, or translate through a block type list, allowing for "special" blocks).
2. Functions to transform "world" coordinates (the ball and paddle positions) into "tile" coordinates and back. This is usually a matter of integer division and multiplication; if your tiles are power-of-2-sized, you can use bit shifts instead.
3. Whenever the ball moves, check if it crosses a tile boundary. If not, you don't need any collision detection at all (except for screen edges and paddle). If it does, check the type of the "new" tile position, and handle accordingly (destroy tile, create powerup, change ball velocity, etc.)
This is a lot faster than your original method, I'd estimate by a magnitude of several hundreds.

I wasn't saying that, I was simply saying if the manual was structured in such a way as linking together logical areas (e.g. pixels with colour) then more the better.

You have a point there.

thank you all for the help. I was unaware of how "slow" getpixel() would have been for the purpose i was intending to use if for. I have taken the advice of all and am rewriting code to accomodate. i'm so glad Allegro has a such a knowledged community willing to help.

for faster access you can use _getpixel() these bypass a lot of the protective code and stuff.

_getpixel and _putpixel always crashes my putey.

Can add a `See also:' reference to the colour formats description to getpixel, I suppose. I'll probably forget, so if someone wants to do this and post a patch on the AD mailing list (or the Development section of the forum), cheers (and credits) to them.

Post the smallest sample code that reproduces the crash.

Something like this?

[EDIT]
Submitted the diff to [AD] as well.

They don't accommodate for color depth. If your bitmap is anything but 8-bpp, you're doomed. Use _getpixel15(), _getpixel16() etc. instead, depending on bitmap color depth.
And they don't accommodate for clipping either, so be sure to check you're not trying to draw outside the bitmap.