sdljava.video
public class SDLSurface extends Object
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 $
See Also: SDLPixelFormat
Field Summary | |
---|---|
GL | gl
Reference to GL context (can be null if GL mode is not being used)
|
ByteBuffer | pixelData
Direct byte buffer reference to the pixel data (null until first time getPixelData is called)
|
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, SDLRect dst) |
int | blitSurface(SDLSurface dstSurface) |
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(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.
|
void | fillRect(long color)
Fill the entire surface area with color
|
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
Frees the resources used by a previously created 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() |
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(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.
|
String | toString()
Return a string represenation of this object
|
void | unlockSurface()
Unlock the surface.
|
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.
|
void | updateRect()
Update the entire screen, calls updateRect(0,0,0,0)
|
boolean | wmToggleFullScreen()
Toggles fullscreen mode
Toggles the application between windowed and fullscreen mode, if supported. |
SDLSurface
instance.
Parameters: surfaceHandle The swig proxy
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
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)
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
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
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
Parameters: color a long
value
Throws: SDLException if an error occurs
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
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
Returns: The Flags set in this surface
Returns: The Pixel Format of this service (see SDLPixelFormat structure)
See Also: SDLPixelFormat
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
Returns: The Height of this surface (in pixels)
Returns: The Pitch of this surface
Returns: a ByteBuffer
value
Returns: The SWIG Proxy instance
Returns: The Width of this surface (in pixels)
Returns: if this surface allows any pixel format
Returns: if this surface uses asynchronous blits
Returns: if this surface uses colorkey blitting
Returns: if this surface is double buffered
Returns: if this surface is a full screen surface
Returns: if this surface's blit uses hardware acceleration
Returns: if this surface has exclusive palette
Returns: if this surface is stored in video memory
Returns: if this window has no window caption or edge frame
Returns: if this surface has an OpenGL context (Display Surface)
Returns: if this surface supports OpenGL blitting
Returns: if this surface uses pre-allocated memory
Returns: if this surface is resizable
Returns: if colorkey blitting is acceleration with RLE
Returns: if this surface is stored in system memory
Returns: a boolean
value
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
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
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
Returns: if the surface needs to be locked before access
Parameters: path a String
value
Throws: SDLException if an error occurs
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
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
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
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.
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
Returns: a String represenation of this object
Throws: SDLException if an error occurs
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
Parameters: r a Rectangle
value
Throws: SDLException if an error occurs
Throws: SDLException if an error occurs
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