*EXPLAINED* GRRLIB_DrawImg and Color

I have what I believe to the a complete GRRLIB download which includes all the Doxygen documentation. However in my opinion it still leaves some questions unanswered and I have not really found a good source to answer them. The definition of the GRRLIB_DrawImg function is as follows:

Quote
GRRLIB_Doc
void GRRLIB_DrawImg ( const f32 xpos,
const f32 ypos,
const GRRLIB_texImg * tex,
const f32 degrees,
const f32 scaleX,
const f32 scaleY,
const u32 color
)

Draw a texture.

Parameters:

xpos Specifies the x-coordinate of the upper-left corner.
ypos Specifies the y-coordinate of the upper-left corner.
tex The texture to draw.
degrees Angle of rotation.
scaleX Specifies the x-coordinate scale. -1 could be used for flipping the texture horizontally.
scaleY Specifies the y-coordinate scale. -1 could be used for flipping the texture vertically.
color Color in RGBA format.

What I don't understand is what does the color parameter actually do? As far as I know the texture definition actually carries the color of each pixel in the texture (as well as the alpha transparency value). This understanding seems to be supported by my own result when I use this function, in my own code, with color (24 or 32 bit) textures: The pixels get drawn in the colors of the texture (or blended with background if alpha is not 255). However in some code I have seen this value being used to evidently recolor the texture.

The other parameters of the function seem obvious to me but the last one eludes me. Can anyone shed some light on this parameter of this function?



Edited 2 time(s). Last edit at 04/15/2010 02:52PM by LordAshes.

The color is a 32bit value with the 4 color components (Red Green Blue Alpha). Each pixel on your texture gets multiplied with this color before it's applied. (Each component gets multiplied and then divided by 255 to be precise)

For example, if you have a white texture and draw it with the color 0xFF0000FF it will be drawn red.
If you have a picture and you want to make it appear more reddish then normal (maybe because it represents a monster/player that was just hit) you can draw it with 0xFF8080FF for a while.

So if you use 0xFFFFFFFF then the texture gets drawn it its unmodified colors. Whereas any components that are less than 0xFF will have less of that color present, correct? (Hence why drawing the texture with 0xFF0000FF leaves only the red component, correct?)

And the same applies for the Alpha channel? So drawing the texture with 0xFFFFFF77 would draw the texture in its original colors but partially belended with the background, yes?

BTW, am I missing part of the GRRLIB documentation where such things are explained? Is there some secret source that teaches this info or do you basically have to do a web search and hope someone already knows this info.



Edited 1 time(s). Last edit at 04/12/2010 03:25PM by LordAshes.

I haven't looked into GRRLIB, so I can't comment on the documentation, but in general the importance of good documentation is overlooked in the software industry...

GRRLIB must use GX under the hood (GX is the only graphics library), so based on what Daid said I'm guessing somewhere we have the following call:
GX_SetTevOp (GX_TEVSTAGE0, GX_MODULATE);

This sets the texture environment (TEV) operation; there can be several stages in a TEV, and the operation determines how the color is combined at each stage. GX_MODULATE means multiply the color and alpha channels, so as Daid said the input color component values (from the color parameter) are normalized and multiplied by the existing color component values (from the texture).

So if your texture has an alpha of 0xFF and you multiply it by a color that has an alpha of 0x77 = 119 ==> 119/255 = 0.47, the pixels output by the TEV will have an alpha of 0.47. The blending you describe happens after the TEV completes. When the output pixel is drawn into the EFB (embedded frame buffer), it's blended with the pixel that's already present. The standard blending algorithm is:
(1 - alpha) * current_color + alpha * new_color

So the blended pixel will be 47% of the new color (the texture color) plus 53% of the existing color (the background color).

Understanding GX will certainly help you understand all these libraries that are built on top of it. Unfortunately, GX documentation is about as bad as it gets, but don't panic.
1. Reading patents is legal. If you can find legal documentation describing how Nintendo's official GX library works, then it will help you understand the homebrew GX library.
2. GX is pretty similar to OpenGL. If you know how something works in OpenGL, then it's easier to understand in GX.

Finally, if you notice that documentation is lacking, I would encourage you to get in there and donate some documentation; that way the whole homebrew community can benefit.