sdl.video
Class SDLSurface

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

public class SDLSurface

extends java.lang.Object

Represents a chunk of memory that may be drawn on.

There are three layers to this memory: The Java level buffer, the SDL level buffer, and if the SDLSurface represents a screen, a onscreen video buffer.

m_Pixels contains the Java level buffer. Call updateRawPixels() to update the SDL level buffer with the contents of the Java level buffer. It is nesecary to do this before calling functions that manipulate the SDL level buffer, such as blitSurface(), updateRect(), flip(), saveToBMP(), convertSurface(), fillRect() and possibly others.

Call flip() or updateRect() to transfer the SDL level buffer to the onscreen video buffer. You can call updateRawPixelsAndAllArea() to update both the SDL buffer and the onscreen video buffer in one step.

The easiest way to create a new pixel is with the convenience routine

     mapRGB(red,green,blue);
 

Addressing a pixel in the SDL buffer is done as follows

   int byteCount= surface.m_Format.m_BytesPerPixel 
   int realStartByteOffset = (surface.m_Pitch * y + (x*byteCount))
 

See Also:

SDLPixelFormat

Field Summary

static boolean	DBG
SDLRect	m_ClipRect Not sure...
int	m_Flags Flags passed to Video.createRGBSurface().
SDLPixelFormat	m_Format Pixel format used by this surface.
int	m_Height Height in pixels
short	m_Pitch Bytes per scanline.
byte[]	m_Pixels Java-level pixel buffer.
int	m_Width Width in pixels.

Constructor Summary

SDLSurface(int handle)
Do not use directly, use Video.createRGBSurface() instead.

SDLSurface(java.lang.String fileNameBMP)

Method Summary

void	blitSurface(SDLRect src, SDLSurface destSurface, SDLRect dest) Blit pixels from this to destSurface.
SDLSurface	convertSurface(SDLPixelFormat format, int flags) Convert a surface from one pixel format to another, and as change flags.
SDLOverlay	createYUVOverlay(int width, int height, int format)
int	displayFormat()
SDLSurface	displayFormatAlpha()
boolean	fillRect(int x, int y, int width, int height, int color) Fills specified rectangle with color
boolean	fillRect(SDLRect rect, int color) Fills specified rectangle with color.
protected void	finalize()
int	flip() Using hardware accelaration if possible, transfer the SDL level buffer onto the onscreen video buffer.
void	freeSurface() Deallocate this surface.
SDLRect	getClipRect()
int	getHandle() Returns the handle for this surface.
int	mapRGB(byte red, byte green, byte blue) Returns a system dependant integer pixel value based on the RGB values.
boolean	saveToBMP(java.lang.String fileName) Dump this surface to a Microsoft Windows Bitmap file.
int	setAlpha(int flags, byte alpha)
void	setClipRect(int x, int y, int w, int h)
void	setClipRect(SDLRect rect)
int	setColor(SDLColor[] color, int firstColor, int nbColors)
void	setColorKey(int flags, int colorKey)
java.lang.String	toString()
void	updateRawPixels() Transfer the bytes stored in m_Pixels[] to the low level SDL representation.
void	updateRawPixelsAndAllArea() Calls updateRawPixels(), then updateRect(0,0,m_Width,m_Height).
void	updateRect(int x, int y, int w, int h) Update the screen with the pixels in the SDL level pixel buffer.

Methods inherited from class java.lang.Object

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

Field Detail

m_Flags

public int m_Flags

Flags passed to Video.createRGBSurface().

m_Format

public SDLPixelFormat m_Format

Pixel format used by this surface.

m_Width

public int m_Width

Width in pixels.

m_Height

public int m_Height

Height in pixels

m_Pitch

public short m_Pitch

Bytes per scanline.

m_Pixels

public byte[] m_Pixels

Java-level pixel buffer. Call updateRawPixels() to transfer it to the SDL-level pixel buffer. Size should be m_Height*m_Pitch, if I'm not mistaken.

See Also:

updateRawPixels()

m_ClipRect

public SDLRect m_ClipRect

Not sure... is this ever used?

DBG

public static boolean DBG

Constructor Detail

SDLSurface

public SDLSurface(int handle)

Do not use directly, use Video.createRGBSurface() instead. Contructs an empty SDLSurface from the low level SDL_Surface referenced by handle. should be non-public?

SDLSurface

public SDLSurface(java.lang.String fileNameBMP)
           throws java.io.FileNotFoundException

Method Detail

getHandle

public int getHandle()

Returns the handle for this surface. Used mostly by low level functions.

freeSurface

public void freeSurface()

Deallocate this surface. This should be called to ensure the SDL level buffer gets freed.

updateRect

public void updateRect(int x,
                       int y,
                       int w,
                       int h)

Update the screen with the pixels in the SDL level pixel buffer. To update the screen with the data in the Java level pixel buffer, call updateRawPixels() first, or call updateRawPixelsAndAllArea() instead.

Only valid for screen surfaces

See Also:

flip(), updateRawPixels(), updateRawPixelsAndAllArea()

updateRawPixels

public void updateRawPixels()

Transfer the bytes stored in m_Pixels[] to the low level SDL representation. Call updateRawPixels() after modifying m_Pixels[] and before calling blitSurface(), updateRect() or flip().

Only valid for screen surfaces

See Also:

updateRawPixelsAndAllArea(), blitSurface(SDLRect, SDLSurface, SDLRect), updateRect(int, int, int, int), flip()

updateRawPixelsAndAllArea

public void updateRawPixelsAndAllArea()

Calls updateRawPixels(), then updateRect(0,0,m_Width,m_Height).

Only valid for screen surfaces

blitSurface

public void blitSurface(SDLRect src,
                        SDLSurface destSurface,
                        SDLRect dest)

Blit pixels from this to destSurface.

Parameters:

src - region to blit from this.

destSurface - SDLSurface to blit to.

dest - region to place blit on destSurface

mapRGB

public int mapRGB(byte red,
                  byte green,
                  byte blue)

Returns a system dependant integer pixel value based on the RGB values. Maps the RGB color value to the specified pixel format and returns the pixel value as a 32-bit int. If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned. If the specified pixel format has an alpha component it will be returned as all 1 bits (fully opaque).

 Color c=Color.magenta;
 int pixel = mapRGB(c.getRed(), c.getGreen(), c.getBlue());
 

Returns:

A pixel value best approximating the given RGB color value for a given pixel format. If the pixel format bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored (e.g., with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).

setColorKey

public void setColorKey(int flags,
                        int colorKey)

setAlpha

public int setAlpha(int flags,
                    byte alpha)

setColor

public int setColor(SDLColor[] color,
                    int firstColor,
                    int nbColors)

displayFormat

public int displayFormat()

flip

public int flip()

Using hardware accelaration if possible, transfer the SDL level buffer onto the onscreen video buffer.

Only valid for screen surfaces

TODO: could this return boolean instead?

Returns:

0 if successful, -1 on failure

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

saveToBMP

public boolean saveToBMP(java.lang.String fileName)

Dump this surface to a Microsoft Windows Bitmap file.

setClipRect

public void setClipRect(SDLRect rect)

setClipRect

public void setClipRect(int x,
                        int y,
                        int w,
                        int h)

getClipRect

public SDLRect getClipRect()

convertSurface

public SDLSurface convertSurface(SDLPixelFormat format,
                                 int flags)

Convert a surface from one pixel format to another, and as change flags.

fillRect

public boolean fillRect(SDLRect rect,
                        int color)

Fills specified rectangle with color.

fillRect

public boolean fillRect(int x,
                        int y,
                        int width,
                        int height,
                        int color)

Fills specified rectangle with color

displayFormatAlpha

public SDLSurface displayFormatAlpha()

createYUVOverlay

public SDLOverlay createYUVOverlay(int width,
                                   int height,
                                   int format)

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

java.lang.Throwable