sdljava.video

Class SDLSurface

public class SDLSurface extends 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
GLgl
Reference to GL context (can be null if GL mode is not being used)
ByteBufferpixelData
Direct byte buffer reference to the pixel data (null until first time getPixelData is called)
SDL_SurfaceswigSurface
Handle to the SWIG SDL_Surface
Constructor Summary
SDLSurface(SDL_Surface swigSurface)
Creates a new SDLSurface instance.
Method Summary
intblitSurface(SDLRect src, SDLSurface dstSurface, SDLRect dst)
This performs a fast blit from the source surface to the destination surface.
intblitSurface(SDLSurface dstSurface, SDLRect dst)
intblitSurface(SDLSurface dstSurface)
SDLSurfaceconvertSurface(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.
SDLSurfacedisplayFormat()
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.
SDLSurfacedisplayFormatAlpha()
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.
voidfillRect(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.
voidfillRect(long color)
Fill the entire surface area with color
protected voidfinalize()
Free SDL_Surface (native world) data.
voidflip()
On hardware that supports double-buffering, this function sets up a flip and returns.
voidfreeSurface()
Frees (deletes) a SDL_Surface

Frees the resources used by a previously created SDL_Surface.

SDLRectgetClipRect()
longgetFlags()
Get the flags set in this surface
SDLPixelFormatgetFormat()
GLgetGL()
Get the OPEN GL Context.
intgetHeight()
Get the heigh of this surface
intgetPitch()
ByteBuffergetPixelData()
Returns a direct byte buffer which referes to the pixel data of this surface
SDL_SurfacegetSwigSurface()
Get the swig proxy
intgetWidth()
Get the width of this surface
voidglSwapBuffers()
SWAP The GL Buffer
booleanisAnyFormat()
Get if this surface allows any pixel format
booleanisAsyncBlit()
Get if this surface uses asynchronous blits
booleanisColorKeyBlit()
Get if this surface uses colorkey blitting
booleanisDoubleBuffered()
Get if this surface is double buffered
booleanisFullScreen()
Get if this surface is a full screen surface
booleanisHardwareAccelerated()
Get if this surface's blit uses hardware acceleration
booleanisHardwarePalette()
Get if this surface has exclusive palette
booleanisHardwareSurface()
Get if this surface is stored in video memory
booleanisNoFrame()
Get if this window has no window caption or edge frame
booleanisOpenGL()
Get if this surface has an OpenGL context (Display Surface)
booleanisOpenGLBlit()
Get if this surface supports OpenGL blitting
booleanisPreAlloc()
Get if this surface uses pre-allocated memory
booleanisResizable()
Get if this surface is resizable
booleanisRLEAccelerated()
Get if colorkey blitting is acceleration with RLE
booleanisSoftwareSurface()
Get if this surface is stored in system memory
booleanisSrcAlphaBlit()
Get if this surface's blit uses alpha blending
booleanlockSurface()
SDL_LockSurface() sets up a surface for directly accessing the pixels.
longmapRGB(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.
longmapRGBA(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.
booleanmustLock()
Get if the surface needs to be locked before access
voidsaveBMP(String path)
Save this surface as a BMP to the given path
voidsetAlpha(long flag, int alpha)
This function sets the alpha value for the entire surface, as opposed to using the alpha component of each pixel.
voidsetClipRect(SDLRect rect)
Sets the clipping rectangle for the destination surface in a blit.
voidsetColorKey(long flag, long key)
Sets the color key (transparent pixel) in a blittable surface and enables or disables RLE blit acceleration.
voidsetColors(SDLColor[] colors)
Sets a portion of the colormap for the given 8-bit surface.
booleansetPalette(int flags, SDLColor[] colors)
Sets a portion of the palette for the given 8-bit surface.
StringtoString()
Return a string represenation of this object
voidunlockSurface()
Unlock the surface.
voidupdateRect(int x, int y, long w, long h)
Makes sure the given area is updated on the given screen.
voidupdateRect(SDLRect r)
Makes sure the given area is updated on the given screen.
voidupdateRect()
Update the entire screen, calls updateRect(0,0,0,0)
booleanwmToggleFullScreen()
Toggles fullscreen mode

Toggles the application between windowed and fullscreen mode, if supported.

Field Detail

gl

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

pixelData

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

swigSurface

SDL_Surface swigSurface
Handle to the SWIG SDL_Surface

Constructor Detail

SDLSurface

public SDLSurface(SDL_Surface swigSurface)
Creates a new SDLSurface instance.

Parameters: surfaceHandle The swig proxy

Method Detail

blitSurface

public int blitSurface(SDLRect src, SDLSurface dstSurface, SDLRect dst)
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)

blitSurface

public int blitSurface(SDLSurface dstSurface)

convertSurface

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

displayFormat

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

UNKNOWN: SDLException If an error occurs

displayFormatAlpha

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

UNKNOWN: SDLException If an error occurs

fillRect

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

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

UNKNOWN: SDLException If an error occurs

fillRect

public void fillRect(long color)
Fill the entire surface area with color

Parameters: color a long value

Throws: SDLException if an error occurs

finalize

protected void finalize()
Free SDL_Surface (native world) data.

flip

public void flip()
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

freeSurface

public void freeSurface()
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

getClipRect

public SDLRect getClipRect()

getFlags

public long getFlags()
Get the flags set in this surface

Returns: The Flags set in this surface

getFormat

public SDLPixelFormat getFormat()

Returns: The Pixel Format of this service (see SDLPixelFormat structure)

See Also: SDLPixelFormat

getGL

public GL getGL()
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

getHeight

public int getHeight()
Get the heigh of this surface

Returns: The Height of this surface (in pixels)

getPitch

public int getPitch()

Returns: The Pitch of this surface

getPixelData

public ByteBuffer getPixelData()
Returns a direct byte buffer which referes to the pixel data of this surface

Returns: a ByteBuffer value

getSwigSurface

public SDL_Surface getSwigSurface()
Get the swig proxy

Returns: The SWIG Proxy instance

getWidth

public int getWidth()
Get the width of this surface

Returns: The Width of this surface (in pixels)

glSwapBuffers

public void glSwapBuffers()
SWAP The GL Buffer

isAnyFormat

public boolean isAnyFormat()
Get if this surface allows any pixel format

Returns: if this surface allows any pixel format

isAsyncBlit

public boolean isAsyncBlit()
Get if this surface uses asynchronous blits

Returns: if this surface uses asynchronous blits

isColorKeyBlit

public boolean isColorKeyBlit()
Get if this surface uses colorkey blitting

Returns: if this surface uses colorkey blitting

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

isHardwareAccelerated

public boolean isHardwareAccelerated()
Get if this surface's blit uses hardware acceleration

Returns: if this surface's blit uses hardware acceleration

isHardwarePalette

public boolean isHardwarePalette()
Get if this surface has exclusive palette

Returns: if this surface has exclusive palette

isHardwareSurface

public boolean isHardwareSurface()
Get if this surface is stored in video memory

Returns: if this surface is stored in video memory

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

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

isPreAlloc

public boolean isPreAlloc()
Get if this surface uses pre-allocated memory

Returns: if this surface uses pre-allocated memory

isResizable

public boolean isResizable()
Get if this surface is resizable

Returns: if this surface is resizable

isRLEAccelerated

public boolean isRLEAccelerated()
Get if colorkey blitting is acceleration with RLE

Returns: if colorkey blitting is acceleration with RLE

isSoftwareSurface

public boolean isSoftwareSurface()
Get if this surface is stored in system memory

Returns: if this surface is stored in system memory

isSrcAlphaBlit

public boolean isSrcAlphaBlit()
Get if this surface's blit uses alpha blending

Returns: a boolean value

lockSurface

public boolean lockSurface()
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

mapRGB

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

mustLock

public boolean mustLock()
Get if the surface needs to be locked before access

Returns: if the surface needs to be locked before access

saveBMP

public void saveBMP(String path)
Save this surface as a BMP to the given path

Parameters: path a String value

Throws: SDLException if an error occurs

setAlpha

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

setColorKey

public void setColorKey(long flag, long key)
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

setColors

public void setColors(SDLColor[] colors)
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.

setPalette

public boolean setPalette(int flags, SDLColor[] colors)
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

toString

public String toString()
Return a string represenation of this object

Returns: a String represenation of this object

unlockSurface

public void unlockSurface()
Unlock the surface.

Throws: SDLException if an error occurs

updateRect

public void updateRect(int x, int y, long w, long h)
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)
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()
Update the entire screen, calls updateRect(0,0,0,0)

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