sdl.video
Class SDLPixelFormat

java.lang.Object
  |
  +--sdl.video.SDLPixelFormat

public class SDLPixelFormat

extends java.lang.Object

SDLPixelFormat describes the structure of pixels in SDLSurface.m_Pixels.

The following description is taken from the SDL documentation on SDL_PixelFormat. I have translated into java, and made some modifications to use jsdl.

A SDLPixelFormat describes the format of the pixel data stored at the m_Pixels field of a SDLSurface. Every surface stores a SDLPixelFormat in the format field.

If you wish to do pixel level modifications on a surface, then understanding how SDL stores its color information is essential.

8-bit pixel formats are the easiest to understand. Since its an 8-bit format, we have 8 m_BitsPerPixel and 1 m_BytesPerPixel. Since m_BytesPerPixel is 1, all pixels are represented by a single byte (TODO: actually, how _is_ this handled, since bytes are signed...) which contains an index into m_Palette.colors. So, to determine the color of a pixel in a 8-bit surface: we read the color index from surface.m_Pixels and we use that index to read the SDLColor structure from surface.m_Format.m_Palette.m_Colors. Like so:

 SDLSurface surface;
 SDLPixelFormat fmt;
 SDLColor color;
 int index;
 
 .
 .
 
 
 // Create surface
 .
 .
 fmt=surface.m_Format;

 // Check the bitdepth of the surface 
 if(fmt.m_BitsPerPixel!=8){
   throw new RuntimeException("Not an 8-bit surface.\n");
 }
 
 //Get the topleft pixel
 index=surface.m_Pixels[0];
 color=fmt.m_Palette.m_Colors[index];
 
 System.out.println("Pixel Color-> Red: " + color.m_Red + 
                    ", Green: " + color.m_Green" +
                    ", Blue: " + color.m_Blue + 
                    ". Index: " + index);
 .
 .
 

Pixel formats above 8-bit are an entirely different experience. They are considered to be "TrueColor" formats and the color information is stored in the pixels themselves, not in a palette. The mask, shift and loss fields tell us how the color information is encoded. The mask fields allow us to isolate each color component, the shift fields tell us the number of bits to the right of each component in the pixel value and the loss fields tell us the number of bits lost from each component when packing 8-bit color component in a pixel.

 // Extracting color components from a 32-bit color value
 SDLPixelFormat fmt;
 SDLSurface surface;
 int temp, pixel;
 int red, green, blue, alpha;
 .
 .
 .
 fmt=surface.format;
 // pixel is a 32bit integer, but m_Pixels are bytes.
 // (not sure if I need to worry about endian'ism )
 pixel=surface.m_Pixels[0] | (surface.m_Pixels[1]<<8) | (surface.m_Pixels[2]<<16);
 
 // Get Red component
 temp=pixel&fmt.m_RMask; // Isolate red component
 temp=temp>>fmt.m_RShift;  // Shift it down to 8-bit 
 temp=temp<<fmt.m_RLoss;   // Expand to a full 8-bit number 
 red=temp;
 
 // Get Green component 
 temp=pixel&fmt.m_GMask; // Isolate green component
 temp=temp>>fmt.m_GShift;// Shift it down to 8-bit 
 temp=temp<<fmt.m_GLoss; // Expand to a full 8-bit number
 green=temp;
 
 // Get Blue component 
 temp=pixel&fmt.m_BMask; // Isolate blue component
 temp=temp>>fmt.m_BShift;// Shift it down to 8-bit 
 temp=temp<<fmt.m_BLoss; // Expand to a full 8-bit number
 blue=temp;
 
 // Get Alpha component
 temp=pixel&fmt.m_AMask; // Isolate alpha component 
 temp=temp>>fmt.m_AShift;// Shift it down to 8-bit 
 temp=temp<<fmt.m_ALoss; // Expand to a full 8-bit number
 alpha=temp;
 
 System.out.println("Pixel Color -> R: " + red + 
                    ",  G: " + green + ", B: " + blue +
                    ", A: " + alpha);
 .
 .
 .
 

See Also:

libSDL documentation on SDL_PixelFormat

Field Summary

byte	m_ALoss Number of low-order bits ignored by the alpha component.
byte	m_Alpha
int	m_AMask Binary mask to retrieve alpha component.
byte	m_AShift Bit offset of the alpha component.
byte	m_BitsPerPixel Number of bits used to represent each pixel in a surface.
byte	m_BLoss Number of low-order bits ignored by the blue component.
int	m_BMask Binary mask to retrieve blue component.
byte	m_BShift Bit offset of the blue component.
byte	m_BytesPerPixel The number of bytes used to represent each pixel in a surface.
int	m_ColorKey
byte	m_GLoss Number of low-order bits ignored by the green component.
int	m_GMask Binary mask to retrieve green component.
byte	m_GShift Bit offset of the green component.
SDLPalette	m_Palette Palette, if using a paletted format.
byte	m_RLoss Number of low-order bits ignored by the red component.
int	m_RMask Binary mask to retrieve red component.
byte	m_RShift Bit offset of the red component.

Constructor Summary

SDLPixelFormat(int handle)

Method Summary

void	freePixelFormat()
int	getHandle()
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

m_Palette

public SDLPalette m_Palette

Palette, if using a paletted format.

m_BitsPerPixel

public byte m_BitsPerPixel

Number of bits used to represent each pixel in a surface. Usually 8, 16, 24 or 32.

m_BytesPerPixel

public byte m_BytesPerPixel

The number of bytes used to represent each pixel in a surface. Usually one to four.

m_RMask

public int m_RMask

Binary mask to retrieve red component.

m_GMask

public int m_GMask

Binary mask to retrieve green component.

m_BMask

public int m_BMask

Binary mask to retrieve blue component.

m_AMask

public int m_AMask

Binary mask to retrieve alpha component.

m_RShift

public byte m_RShift

Bit offset of the red component.

m_GShift

public byte m_GShift

Bit offset of the green component.

m_BShift

public byte m_BShift

Bit offset of the blue component.

m_AShift

public byte m_AShift

Bit offset of the alpha component.

m_RLoss

public byte m_RLoss

Number of low-order bits ignored by the red component. Usually 0.

m_GLoss

public byte m_GLoss

Number of low-order bits ignored by the green component. Usually 0, or 1 in 15bit color mode.

m_BLoss

public byte m_BLoss

Number of low-order bits ignored by the blue component. Usually 0.

m_ALoss

public byte m_ALoss

Number of low-order bits ignored by the alpha component. Usually 0.

m_ColorKey

public int m_ColorKey

m_Alpha

public byte m_Alpha

Constructor Detail

SDLPixelFormat

public SDLPixelFormat(int handle)

Method Detail

getHandle

public int getHandle()

freePixelFormat

public void freePixelFormat()

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object