sdljava.video
Class SDLSurface

java.lang.Object
  sdljava.video.SDLSurface

public class SDLSurface
extends java.lang.Object

Graphical Surface Structure

SDL_Surface's represent areas of "graphical" memory, memory that can be drawn to. The video framebuffer is returned as a SDL_Surface by SDL_SetVideoMode and SDL_GetVideoSurface

This class encapsulates the SDL C structure SDL_Surface. It also defines methods for each function found in SDL_video.h which takes an SDL_Surface as an argument.

Also see the documentation here: SDL_Surface

Version:

$Id: SDLSurface.java,v 1.31 2005/01/26 02:52:52 ivan_ganza Exp $

Author:

Ivan Z. Ganza

See Also:

SDLPixelFormat

Field Summary

(package private) GL	gl Reference to GL context (can be null if GL mode is not being used)
(package private) java.nio.ByteBuffer	pixelData Direct byte buffer reference to the pixel data (null until first time getPixelData is called)
(package private) SDL_Surface	swigSurface Handle to the SWIG SDL_Surface

Constructor Summary

SDLSurface(SDL_Surface swigSurface)
Creates a new SDLSurface instance.

Method Summary

int	blitSurface(SDLRect src, SDLSurface dstSurface, SDLRect dst) This performs a fast blit from the source surface to the destination surface.
int	blitSurface(SDLSurface dstSurface)
int	blitSurface(SDLSurface dstSurface, SDLRect dst)
SDLSurface	convertSurface(SDLPixelFormat fmt, long flags) Creates a new surface of the specified format, and then copies and maps the given surface to it so the blit of the converted surface will be as fast as possible.
SDLSurface	displayFormat() This function takes a surface and copies it to a new surface of the pixel format and colors of the video framebuffer, suitable for fast blitting onto the display surface.
SDLSurface	displayFormatAlpha() This function takes a surface and copies it to a new surface of the pixel format and colors of the video framebuffer (if possible), suitable for fast alpha blitting onto the display surface.
void	fillRect(long color) Fill the entire surface area with color
void	fillRect(SDLRect dstrect, long color) This function performs a fast fill of the given rectangle with 'color' The given rectangle is clipped to the destination surface clip area and the final fill rectangle is saved in the passed in pointer.
protected void	finalize() Free SDL_Surface (native world) data.
void	flip() On hardware that supports double-buffering, this function sets up a flip and returns.
void	freeSurface() Frees (deletes) a SDL_Surface
SDLRect	getClipRect()
long	getFlags() Get the flags set in this surface
SDLPixelFormat	getFormat()
GL	getGL() Get the OPEN GL Context.
int	getHeight() Get the heigh of this surface
int	getPitch()
java.nio.ByteBuffer	getPixelData() Returns a direct byte buffer which referes to the pixel data of this surface
SDL_Surface	getSwigSurface() Get the swig proxy
int	getWidth() Get the width of this surface
void	glSwapBuffers() SWAP The GL Buffer
boolean	isAnyFormat() Get if this surface allows any pixel format
boolean	isAsyncBlit() Get if this surface uses asynchronous blits
boolean	isColorKeyBlit() Get if this surface uses colorkey blitting
boolean	isDoubleBuffered() Get if this surface is double buffered
boolean	isFullScreen() Get if this surface is a full screen surface
boolean	isHardwareAccelerated() Get if this surface's blit uses hardware acceleration
boolean	isHardwarePalette() Get if this surface has exclusive palette
boolean	isHardwareSurface() Get if this surface is stored in video memory
boolean	isNoFrame() Get if this window has no window caption or edge frame
boolean	isOpenGL() Get if this surface has an OpenGL context (Display Surface)
boolean	isOpenGLBlit() Get if this surface supports OpenGL blitting
boolean	isPreAlloc() Get if this surface uses pre-allocated memory
boolean	isResizable() Get if this surface is resizable
boolean	isRLEAccelerated() Get if colorkey blitting is acceleration with RLE
boolean	isSoftwareSurface() Get if this surface is stored in system memory
boolean	isSrcAlphaBlit() Get if this surface's blit uses alpha blending
boolean	lockSurface() SDL_LockSurface() sets up a surface for directly accessing the pixels.
long	mapRGB(int r, int g, int b) Maps an RGB triple to an opaque pixel value for a given pixel format If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.
long	mapRGBA(int r, int g, int b, int a) Maps an RGBA quadruple to a pixel value for a given pixel format If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.
boolean	mustLock() Get if the surface needs to be locked before access
void	saveBMP(java.lang.String path) Save this surface as a BMP to the given path
void	setAlpha(long flag, int alpha) This function sets the alpha value for the entire surface, as opposed to using the alpha component of each pixel.
void	setClipRect(SDLRect rect) Sets the clipping rectangle for the destination surface in a blit.
void	setColorKey(long flag, long key) Sets the color key (transparent pixel) in a blittable surface and enables or disables RLE blit acceleration.
void	setColors(SDLColor[] colors) Sets a portion of the colormap for the given 8-bit surface.
boolean	setPalette(int flags, SDLColor[] colors) Sets a portion of the palette for the given 8-bit surface.
java.lang.String	toString() Return a string represenation of this object
void	unlockSurface() Unlock the surface.
void	updateRect() Update the entire screen, calls updateRect(0,0,0,0)
void	updateRect(int x, int y, long w, long h) Makes sure the given area is updated on the given screen.
void	updateRect(SDLRect r) Makes sure the given area is updated on the given screen.
boolean	wmToggleFullScreen() Toggles fullscreen mode

Methods inherited from class java.lang.Object

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

Field Detail

swigSurface

SDL_Surface swigSurface

Handle to the SWIG SDL_Surface

pixelData

java.nio.ByteBuffer pixelData

Direct byte buffer reference to the pixel data (null until first time getPixelData is called)

gl

GL gl

Reference to GL context (can be null if GL mode is not being used)

Constructor Detail

SDLSurface

public SDLSurface(SDL_Surface swigSurface)

Creates a new SDLSurface instance.

Parameters:

surfaceHandle - The swig proxy

Method Detail

getWidth

public int getWidth()

Get the width of this surface

Returns:

The Width of this surface (in pixels)

getHeight

public int getHeight()

Get the heigh of this surface

Returns:

The Height of this surface (in pixels)

getFlags

public long getFlags()

Get the flags set in this surface

Returns:

The Flags set in this surface

getPitch

public int getPitch()

Returns:

The Pitch of this surface

getFormat

public SDLPixelFormat getFormat()

Returns:

The Pixel Format of this service (see SDLPixelFormat structure)

See Also:

SDLPixelFormat

getSwigSurface

public SDL_Surface getSwigSurface()

Get the swig proxy

Returns:

The SWIG Proxy instance

getGL

public GL getGL()
         throws SDLException

Get the OPEN GL Context. Returns an instance of GL suitable for drawing to if this surface was configured with SDL_OPENGL

When SDL has implemented multi-window support this method will return the GL instance properly configured to draw to the surface

Returns:

a GL value

Throws:

SDLException - if an error occurs

updateRect

public void updateRect(int x,
                       int y,
                       long w,
                       long h)
                throws SDLException

Makes sure the given area is updated on the given screen. The rectangle must be confined within the screen boundaries (no clipping is done).

This method should not be called while 'screen' is locked

Parameters:

x - an int value

y - an int value

w - an int value

h - an int value

Throws:

SDLException - if an error occurs

updateRect

public void updateRect(SDLRect r)
                throws SDLException

Makes sure the given area is updated on the given screen. The rectangle must be confined within the screen boundaries (no clipping is done).

Parameters:

r - a Rectangle value

Throws:

SDLException - if an error occurs

updateRect

public void updateRect()
                throws SDLException

Update the entire screen, calls updateRect(0,0,0,0)

Throws:

SDLException - if an error occurs

flip

public void flip()
          throws SDLException

On hardware that supports double-buffering, this function sets up a flip and returns. The hardware will wait for vertical retrace, and then swap video buffers before the next video surface blit or lock will return. On hardware that doesn not support double-buffering, this is equivalent to calling SDL_UpdateRect(screen, 0, 0, 0, 0);

The SDL_DOUBLEBUF flag must have been passed to SDL_SetVideoMode() when setting the video mode for this function to perform hardware flipping.

Throws:

SDLException - if an error occurs

setColors

public void setColors(SDLColor[] colors)
               throws SDLException

Sets a portion of the colormap for the given 8-bit surface. If 'surface' is not a palettized surface, this function does nothing, returning 0. If all of the colors were set as passed to SDL_SetColors(), it will return 1. If not all the color entries were set exactly as given, it will return 0, and you should look at the surface palette to determine the actual color palette.

When 'surface' is the surface associated with the current display, the display colormap will be updated with the requested colors. If SDL_HWPALETTE was set in SDL_SetVideoMode() flags, SDL_SetColors() will always return 1, and the palette is guaranteed to be set the way you desire, even if the window colormap has to be warped or run under emulation.

Throws:

SDLException

setPalette

public boolean setPalette(int flags,
                          SDLColor[] colors)
                   throws SDLException

Sets a portion of the palette for the given 8-bit surface.

Palettized (8-bit) screen surfaces with the SDL_HWPALETTE flag have two palettes, a logical palette that is used for mapping blits to/from the surface and a physical palette (that determines how the hardware will map the colors to the display). SDL_BlitSurface always uses the logical palette when blitting surfaces (if it has to convert between surface pixel formats). Because of this, it is often useful to modify only one or the other palette to achieve various special color effects (e.g., screen fading, color flashes, screen dimming).

This function can modify either the logical or physical palette by specifying SDL_LOGPAL or SDL_PHYSPAL the in the flags parameter.

When surface is the surface associated with the current display, the display colormap will be updated with the requested colors. If SDL_HWPALETTE was set in SDL_SetVideoMode flags, SDL_SetPalette will always return 1, and the palette is guaranteed to be set the way you desire, even if the window colormap has to be warped or run under emulation.

The color components of a SDL_Color structure are 8-bits in size, giving you a total of 2563 = 16777216 colors.

Parameters:

flags - an int value

colors - a SDLColor[] value

Returns:

If surface is not a palettized surface, this function does nothing, returning false. If all of the colors were set as passed to SDL_SetPalette, it will return true. If not all the color entries were set exactly as given, it will return false, and you should look at the surface palette to determine the actual color palette.

Throws:

SDLException - if an error occurs

lockSurface

public boolean lockSurface()
                    throws SDLException

SDL_LockSurface() sets up a surface for directly accessing the pixels. Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write to and read from 'surface->pixels', using the pixel format stored in 'surface->format'. Once you are done accessing the surface, you should use SDL_UnlockSurface() to release it.

Not all surfaces require locking. If SDL_MUSTLOCK(surface) evaluates to 0, then you can read and write to the surface at any time, and the pixel format of the surface will not change. In particular, if the SDL_HWSURFACE flag is not given when calling SDL_SetVideoMode(), you will not need to lock the display surface before accessing it.

No operating system or library calls should be made between lock/unlock pairs, as critical system locks may be held during this time.

Returns:

if the surface could be locked

Throws:

SDLException - if an error occurs

unlockSurface

public void unlockSurface()
                   throws SDLException

Unlock the surface.

Throws:

SDLException - if an error occurs

saveBMP

public void saveBMP(java.lang.String path)
             throws SDLException

Save this surface as a BMP to the given path

Parameters:

path - a String value

Throws:

SDLException - if an error occurs

setColorKey

public void setColorKey(long flag,
                        long key)
                 throws SDLException

Sets the color key (transparent pixel) in a blittable surface and enables or disables RLE blit acceleration.

RLE acceleration can substantially speed up blitting of images with large horizontal runs of transparent pixels (i.e., pixels that match the key value). The key must be of the same pixel format as the surface, SDL_MapRGB is often useful for obtaining an acceptable value.

If flag is SDL_SRCCOLORKEY then key is the transparent pixel value in the source image of a blit.

If flag is OR'd with SDL_RLEACCEL then the surface will be draw using RLE acceleration when drawn with SDL_BlitSurface. The surface will actually be encoded for RLE acceleration the first time SDL_BlitSurface or SDL_DisplayFormat is called on the surface.

Parameters:

flag - an int value

key - an int value

Throws:

SDLException - if an error occurs

setAlpha

public void setAlpha(long flag,
                     int alpha)
              throws SDLException

This function sets the alpha value for the entire surface, as opposed to using the alpha component of each pixel. This value measures the range of transparency of the surface, 0 being completely transparent to 255 being completely opaque. An 'alpha' value of 255 causes blits to be opaque, the source pixels copied to the destination (the default). Note that per-surface alpha can be combined with colorkey transparency.

If 'flag' is 0, alpha blending is disabled for the surface. If 'flag' is SDL_SRCALPHA, alpha blending is enabled for the surface. OR:ing the flag with SDL_RLEACCEL requests RLE acceleration for the surface; if SDL_RLEACCEL is not specified, the RLE accel will be removed.

The 'alpha' parameter is ignored for surfaces that have an alpha channel.

Parameters:

flag - a long value

alpha - a short value

Throws:

SDLException - if an error occurs

setClipRect

public void setClipRect(SDLRect rect)
                 throws SDLException

Sets the clipping rectangle for the destination surface in a blit.

If the clip rectangle is NULL, clipping will be disabled. If the clip rectangle doesn't intersect the surface, the function will return SDL_FALSE and blits will be completely clipped. Otherwise the function returns SDL_TRUE and blits to the surface will be clipped to the intersection of the surface area and the clipping rectangle.

Note that blits are automatically clipped to the edges of the source and destination surfaces.

Parameters:

rect - a Rectangle value

Throws:

SDLException - if an error occurs

getClipRect

public SDLRect getClipRect()
                    throws SDLException

Throws:

SDLException

convertSurface

public SDLSurface convertSurface(SDLPixelFormat fmt,
                                 long flags)
                          throws SDLException

Creates a new surface of the specified format, and then copies and maps the given surface to it so the blit of the converted surface will be as fast as possible. If this function fails, an exception will be thrown.

The 'flags' parameter is passed to SDL_CreateRGBSurface() and has those semantics. You can also pass SDL_RLEACCEL in the flags parameter and SDL will try to RLE accelerate colorkey and alpha blits in the resulting surface.

This function is used internally by SDL_DisplayFormat().

Returns:

The converted surface (newly created)

Throws:

SDLException

blitSurface

public int blitSurface(SDLRect src,
                       SDLSurface dstSurface,
                       SDLRect dst)
                throws SDLException

This performs a fast blit from the source surface to the destination surface. It assumes that the source and destination rectangles are the same size. If either 'srcrect' or 'dstrect' are NULL, the entire surface (src or dst) is copied. The final blit rectangles are saved in 'srcrect' and 'dstrect' after all clipping is performed. If the blit is successful, it returns 0, otherwise it returns -1.

The blit function should not be called on a locked surface.

The blit semantics for surfaces with and without alpha and colorkey are defined as follows:

 RGBA->RGB:
     SDL_SRCALPHA set:
        alpha-blend (using alpha-channel).
        SDL_SRCCOLORKEY ignored.
     SDL_SRCALPHA not set:
        copy RGB.
        if SDL_SRCCOLORKEY set, only copy the pixels matching the
        RGB values of the source colour key, ignoring alpha in the
        comparison.
 
 RGB->RGBA:
     SDL_SRCALPHA set:
        alpha-blend (using the source per-surface alpha value);
        set destination alpha to opaque.
     SDL_SRCALPHA not set:
        copy RGB, set destination alpha to source per-surface alpha value.
     both:
        if SDL_SRCCOLORKEY set, only copy the pixels matching the
        source colour key.
 
 RGBA->RGBA:
     SDL_SRCALPHA set:
        alpha-blend (using the source alpha channel) the RGB values;
        leave destination alpha untouched. [Note: is this correct?]
        SDL_SRCCOLORKEY ignored.
     SDL_SRCALPHA not set:
        copy all of RGBA to the destination.
        if SDL_SRCCOLORKEY set, only copy the pixels matching the
        RGB values of the source colour key, ignoring alpha in the
        comparison.
 
 RGB->RGB: 
     SDL_SRCALPHA set:
        alpha-blend (using the source per-surface alpha value).
     SDL_SRCALPHA not set:
        copy RGB.
     both:
        if SDL_SRCCOLORKEY set, only copy the pixels matching the
        source colour key.

 If either of the surfaces were in video memory, and the blit returns -2,
 the video memory was lost, so it should be reloaded with artwork and 
 re-blitted:
   while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
       while ( SDL_LockSurface(image) < 0 )
       Sleep(10);
       -- Write image pixels to image->pixels --
       SDL_UnlockSurface(image);
   }
 

This happens under DirectX 5.0 when the system switches away from your fullscreen application. The lock will also fail until you have access to the video memory again.

Parameters:

src - The source rectangle

dstSurface - The surface to blit to

dst - The destination rectangle

Returns:

If the blit is successful, it returns 0, otherwise it returns -1. If either of the surfaces were in video memory, and the blit returns -2, the video memory was lost, so it should be reloaded with artwork and re-blitted. (please see documentation here

Throws:

SDLException - if an error occurs

blitSurface

public int blitSurface(SDLSurface dstSurface,
                       SDLRect dst)
                throws SDLException

Throws:

SDLException

blitSurface

public int blitSurface(SDLSurface dstSurface)
                throws SDLException

Throws:

SDLException

fillRect

public void fillRect(SDLRect dstrect,
                     long color)
              throws SDLException

This function performs a fast fill of the given rectangle with 'color' The given rectangle is clipped to the destination surface clip area and the final fill rectangle is saved in the passed in pointer.

If 'dstrect' is NULL, the whole surface will be filled with 'color' The color should be a pixel of the format used by the surface, and can be generated by the SDL_MapRGB() function.

If there is a clip rectangle set on the destination (set via SDL_SetClipRect) then this function will clip based on the intersection of the clip rectangle and the dstrect rectangle and the dstrect rectangle will be modified to represent the area actually filled.

Parameters:

dstrect - The destination rect

color - The color to fill with

Throws:

SDLException - if an error occurs

fillRect

public void fillRect(long color)
              throws SDLException

Fill the entire surface area with color

Parameters:

color - a long value

Throws:

SDLException - if an error occurs

displayFormat

public SDLSurface displayFormat()
                         throws SDLException

This function takes a surface and copies it to a new surface of the pixel format and colors of the video framebuffer, suitable for fast blitting onto the display surface. It calls SDL_ConvertSurface()

If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and alpha value before calling this function.

If the conversion fails or runs out of memory an exception will be thrown.

Throws:

SDLException

displayFormatAlpha

public SDLSurface displayFormatAlpha()
                              throws SDLException

This function takes a surface and copies it to a new surface of the pixel format and colors of the video framebuffer (if possible), suitable for fast alpha blitting onto the display surface. The new surface will always have an alpha channel.

If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and alpha value before calling this function.

If the conversion fails or runs out of memory an exception will be thrown

Throws:

SDLException

isSoftwareSurface

public boolean isSoftwareSurface()

Get if this surface is stored in system memory

Returns:

if this surface is stored in system memory

isHardwareSurface

public boolean isHardwareSurface()

Get if this surface is stored in video memory

Returns:

if this surface is stored in video memory

isAsyncBlit

public boolean isAsyncBlit()

Get if this surface uses asynchronous blits

Returns:

if this surface uses asynchronous blits

isAnyFormat

public boolean isAnyFormat()

Get if this surface allows any pixel format

Returns:

if this surface allows any pixel format

isHardwarePalette

public boolean isHardwarePalette()

Get if this surface has exclusive palette

Returns:

if this surface has exclusive palette

isDoubleBuffered

public boolean isDoubleBuffered()

Get if this surface is double buffered

Returns:

if this surface is double buffered

isFullScreen

public boolean isFullScreen()

Get if this surface is a full screen surface

Returns:

if this surface is a full screen surface

isOpenGL

public boolean isOpenGL()

Get if this surface has an OpenGL context (Display Surface)

Returns:

if this surface has an OpenGL context (Display Surface)

isOpenGLBlit

public boolean isOpenGLBlit()

Get if this surface supports OpenGL blitting

Returns:

if this surface supports OpenGL blitting

isResizable

public boolean isResizable()

Get if this surface is resizable

Returns:

if this surface is resizable

isNoFrame

public boolean isNoFrame()

Get if this window has no window caption or edge frame

Returns:

if this window has no window caption or edge frame

isHardwareAccelerated

public boolean isHardwareAccelerated()

Get if this surface's blit uses hardware acceleration

Returns:

if this surface's blit uses hardware acceleration

isColorKeyBlit

public boolean isColorKeyBlit()

Get if this surface uses colorkey blitting

Returns:

if this surface uses colorkey blitting

isRLEAccelerated

public boolean isRLEAccelerated()

Get if colorkey blitting is acceleration with RLE

Returns:

if colorkey blitting is acceleration with RLE

isSrcAlphaBlit

public boolean isSrcAlphaBlit()

Get if this surface's blit uses alpha blending

Returns:

a boolean value

isPreAlloc

public boolean isPreAlloc()

Get if this surface uses pre-allocated memory

Returns:

if this surface uses pre-allocated memory

mapRGB

public long mapRGB(int r,
                   int g,
                   int b)
            throws SDLException

Maps an RGB triple to an opaque pixel value for a given pixel format 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).

Parameters:

r -

g -

b -

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).

Throws:

SDLException - If an error occurs

mapRGBA

public long mapRGBA(int r,
                    int g,
                    int b,
                    int a)
             throws SDLException

Maps an RGBA quadruple to a pixel value for a given pixel format 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 no alpha component the alpha value will be ignored (as it will be in formats with a palette).

Parameters:

r -

g -

b -

a -

Returns:

A pixel value best approximating the given RGBA 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).

Throws:

SDLException - If an error occurs

getPixelData

public java.nio.ByteBuffer getPixelData()

Returns a direct byte buffer which referes to the pixel data of this surface

Returns:

a ByteBuffer value

freeSurface

public void freeSurface()
                 throws SDLException

Frees (deletes) a SDL_Surface

Frees the resources used by a previously created SDL_Surface. If the surface was created using SDL_CreateRGBSurfaceFrom then the pixel data is not freed.

Throws:

SDLException - if an error occurs

wmToggleFullScreen

public boolean wmToggleFullScreen()

Toggles fullscreen mode

Toggles the application between windowed and fullscreen mode, if supported. (X11 is the only target currently supported, BeOS support is experimental).

Returns:

If the toggle was successfull

glSwapBuffers

public void glSwapBuffers()

SWAP The GL Buffer

mustLock

public boolean mustLock()

Get if the surface needs to be locked before access

Returns:

if the surface needs to be locked before access

finalize

protected void finalize()

Free SDL_Surface (native world) data.

Overrides:

finalize in class java.lang.Object

toString

public java.lang.String toString()

Return a string represenation of this object

Overrides:

toString in class java.lang.Object

Returns:

a String represenation of this object