sdljava.video
Class SDLVideo

java.lang.Object
  sdljava.video.SDLVideo

public class SDLVideo
extends java.lang.Object

Please see the SDL Documention project page here

NOTE: The following methods are not yet implemented:

• SDL_XXX_YUV* functions (Overlay support is planned but not yet implemented)

See Also:

SDLSurface, SDLPixelFormat

Field Summary

static int	SDL_ALPHA_OPAQUE Transparency definitions: These define alpha as the opacity of a surface
static int	SDL_ALPHA_TRANSPARENT Transparency definitions: These define alpha as the opacity of a surface
static long	SDL_ANYFORMAT Allows any pixel-format (Display surface)
static long	SDL_ASYNCBLIT Surface uses asynchronous blits if possible
static int	SDL_DISABLE Hide the cursor.
static long	SDL_DOUBLEBUF Surface is double buffered (Display surface)
static int	SDL_ENABLE Show the cursor
static long	SDL_FULLSCREEN Surface is full screen (Display Surface)
static long	SDL_HWACCEL Surface blit uses hardware acceleration
static long	SDL_HWPALETTE Surface has exclusive palette
static long	SDL_HWSURFACE Surface is stored in video memory
static long	SDL_NOFRAME No window caption or edge frame
static long	SDL_OPENGL Surface has an OpenGL context (Display Surface)
static long	SDL_OPENGLBLIT Surface supports OpenGL blitting (Display Surface).
static long	SDL_PREALLOC Surface uses preallocated memory
static int	SDL_QUERY Is the cursor visible?
static long	SDL_RESIZABLE Surface is resizable (Display Surface)
static long	SDL_RLEACCEL Colorkey blitting is accelerated with RLE
static long	SDL_SRCALPHA Surface blit uses alpha blending
static long	SDL_SRCCOLORKEY Surface use colorkey blitting
static long	SDL_SWSURFACE Surface is stored in system memory

Constructor Summary

private

SDLVideo()

Method Summary

static SDLSurface	createRGBSurface(long flags, int width, int height, int depth, long rMask, long gMask, long bMask, long aMask) Allocate and free an RGB surface (must be called after SDL_SetVideoMode) If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
static SDLSurface	createRGBSurfaceFrom(int[] pixels, int width, int height, int depth, int pitch, long rMask, long gMask, long bMask, long aMask) Create an SDL_Surface from pixel data
static GammaTable	getGammaRamp() Retrieve the current values of the gamma translation tables.
static SDLColor	getRGB(int pixel, SDLPixelFormat fmt) Maps a pixel value into the RGB components for a given pixel format This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
static SDLColor	getRGBA(int pixel, SDLPixelFormat fmt) Maps a pixel value into the RGBA components for a given pixel format This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
static SDLVideoInfo	getVideoInfo() This function returns information about the video hardware.
static SDLSurface	getVideoSurface() This function returns the current display surface.
static SDLSurface	loadBMP(java.lang.String path) Load a surface from a BMP file located at path.
static long	mapRGB(SDLPixelFormat format, 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.
static long	mapRGBA(SDLPixelFormat format, 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.
static void	setGamma(float red, float green, float blue) Set the gamma correction for each of the color channels.
static void	setGammaRamp(int[] red, int[] green, int[] blue) Set the gamma translation table for the red, green, and blue channels of the video hardware.
static SDLSurface	setVideoMode(int width, int height, int bpp, long flags) Set up a video mode with the specified width, height and bits-per-pixel.
static java.lang.String	videoDriverName() Obtain the name of the video driver
static int	videoModeOK(int width, int height, int bpp, int flags) Check to see if a particular video mode is supported.
static void	warpMouse(int x, int y) Set the position of the mouse cursor (generates a mouse motion event).
static java.util.HashMap	wmGetCaption() Gets the window tile and icon name.
static SDLGrabMode	wmGrabInput(SDLGrabMode mode) Grabs mouse and keyboard input.
static boolean	wmIconifyWindow() Iconify/Minimise the window
static void	wmSetCaption(java.lang.String title, java.lang.String icon) Sets the window tile and icon name.
static void	wmSetIcon(SDLSurface icon, short mask) Sets the icon for the display window.

Methods inherited from class java.lang.Object

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

Field Detail

SDL_ALPHA_OPAQUE

public static final int SDL_ALPHA_OPAQUE

Transparency definitions: These define alpha as the opacity of a surface

See Also:

Constant Field Values

SDL_ALPHA_TRANSPARENT

public static final int SDL_ALPHA_TRANSPARENT

Transparency definitions: These define alpha as the opacity of a surface

See Also:

Constant Field Values

SDL_SWSURFACE

public static final long SDL_SWSURFACE

Surface is stored in system memory

See Also:

Constant Field Values

SDL_HWSURFACE

public static final long SDL_HWSURFACE

Surface is stored in video memory

See Also:

Constant Field Values

SDL_ASYNCBLIT

public static final long SDL_ASYNCBLIT

Surface uses asynchronous blits if possible

See Also:

Constant Field Values

SDL_ANYFORMAT

public static final long SDL_ANYFORMAT

Allows any pixel-format (Display surface)

See Also:

Constant Field Values

SDL_HWPALETTE

public static final long SDL_HWPALETTE

Surface has exclusive palette

See Also:

Constant Field Values

SDL_DOUBLEBUF

public static final long SDL_DOUBLEBUF

Surface is double buffered (Display surface)

See Also:

Constant Field Values

SDL_FULLSCREEN

public static final long SDL_FULLSCREEN

Surface is full screen (Display Surface)

See Also:

Constant Field Values

SDL_OPENGL

public static final long SDL_OPENGL

Surface has an OpenGL context (Display Surface)

See Also:

Constant Field Values

SDL_OPENGLBLIT

public static final long SDL_OPENGLBLIT

Surface supports OpenGL blitting (Display Surface). NOTE: This option is kept for compatibility only, and is not recommended for new code.

See Also:

Constant Field Values

SDL_RESIZABLE

public static final long SDL_RESIZABLE

Surface is resizable (Display Surface)

See Also:

Constant Field Values

SDL_NOFRAME

public static final long SDL_NOFRAME

No window caption or edge frame

See Also:

Constant Field Values

SDL_HWACCEL

public static final long SDL_HWACCEL

Surface blit uses hardware acceleration

See Also:

Constant Field Values

SDL_SRCCOLORKEY

public static final long SDL_SRCCOLORKEY

Surface use colorkey blitting

See Also:

Constant Field Values

SDL_RLEACCEL

public static final long SDL_RLEACCEL

Colorkey blitting is accelerated with RLE

See Also:

Constant Field Values

SDL_SRCALPHA

public static final long SDL_SRCALPHA

Surface blit uses alpha blending

See Also:

Constant Field Values

SDL_PREALLOC

public static final long SDL_PREALLOC

Surface uses preallocated memory

See Also:

Constant Field Values

SDL_QUERY

public static final int SDL_QUERY

Is the cursor visible?

See Also:

#showCursor(int), Constant Field Values

SDL_DISABLE

public static final int SDL_DISABLE

Hide the cursor.

See Also:

#showCursor(int), Constant Field Values

SDL_ENABLE

public static final int SDL_ENABLE

Show the cursor

See Also:

#showCursor(int), Constant Field Values

Constructor Detail

SDLVideo

private SDLVideo()

Method Detail

getVideoSurface

public static SDLSurface getVideoSurface()
                                  throws SDLException

This function returns the current display surface. If SDL is doing format conversion on the display surface, this function returns the publicly visible surface, not the real video surface.

Returns:

The current display surface

Throws:

SDLException - If an error occurs

getVideoInfo

public static SDLVideoInfo getVideoInfo()
                                 throws SDLException

This function returns information about the video hardware. If this is called before SDL_SetVideoMode(), the 'vfmt' member of the returned structure will contain the pixel format of the "best" video mode.

Returns:

Information about the Video Mode

Throws:

SDLException - If an error occurs

videoDriverName

public static java.lang.String videoDriverName()
                                        throws SDLException

Obtain the name of the video driver

Returns:

The name of the video driver or NULL if no driver has been initialized.

Throws:

SDLException - If an error occurs

videoModeOK

public static int videoModeOK(int width,
                              int height,
                              int bpp,
                              int flags)
                       throws SDLException

Check to see if a particular video mode is supported. It returns 0 if the requested mode is not supported under any bit depth, or returns the bits-per-pixel of the closest available mode with the given width and height. If this bits-per-pixel is different from the one used when setting the video mode, SDL_SetVideoMode() will succeed, but will emulate the requested bits-per-pixel with a shadow surface. The arguments to SDL_VideoModeOK() are the same ones you would pass to SDL_SetVideoMode()

Parameters:

width - The desired width

height - The desired height

bpp - The desired bits per pixel

flags - The desired flags

Returns:

0 if the requested mode is not supported under any bit depth, or returns the bits-per-pixel of the closest available mode with the given width and height. If this bits-per-pixel is different from the one used when setting the video mode, SDL_SetVideoMode() will succeed, but will emulate the requested bits-per-pixel with a shadow surface.

Throws:

SDLException - If an error occurs

setVideoMode

public static SDLSurface setVideoMode(int width,
                                      int height,
                                      int bpp,
                                      long flags)
                               throws SDLException

Set up a video mode with the specified width, height and bits-per-pixel.

If 'bpp' is 0, it is treated as the current display bits per pixel.

If SDL_ANYFORMAT is set in 'flags', the SDL library will try to set the requested bits-per-pixel, but will return whatever video pixel format is available. The default is to emulate the requested pixel format if it is not natively available.

If SDL_HWSURFACE is set in 'flags', the video surface will be placed in video memory, if possible, and you may have to call SDL_LockSurface() in order to access the raw framebuffer. Otherwise, the video surface will be created in system memory.

If SDL_ASYNCBLIT is set in 'flags', SDL will try to perform rectangle updates asynchronously, but you must always lock before accessing pixels. SDL will wait for updates to complete before returning from the lock.

If SDL_HWPALETTE is set in 'flags', the SDL library will guarantee that the colors set by SDL_SetColors() will be the colors you get. Otherwise, in 8-bit mode, SDL_SetColors() may not be able to set all of the colors exactly the way they are requested, and you should look at the video surface structure to determine the actual palette. If SDL cannot guarantee that the colors you request can be set, i.e. if the colormap is shared, then the video surface may be created under emulation in system memory, overriding the SDL_HWSURFACE flag.

If SDL_FULLSCREEN is set in 'flags', the SDL library will try to set a fullscreen video mode. The default is to create a windowed mode if the current graphics system has a window manager. If the SDL library is able to set a fullscreen video mode, this flag will be set in the surface that is returned.

If SDL_DOUBLEBUF is set in 'flags', the SDL library will try to set up two surfaces in video memory and swap between them when you call SDL_Flip(). This is usually slower than the normal single-buffering scheme, but prevents "tearing" artifacts caused by modifying video memory while the monitor is refreshing. It should only be used by applications that redraw the entire screen on every update.

If SDL_RESIZABLE is set in 'flags', the SDL library will allow the window manager, if any, to resize the window at runtime. When this occurs, SDL will send a SDL_VIDEORESIZE event to you application, and you must respond to the event by re-calling SDL_SetVideoMode() with the requested size (or another size that suits the application).

If SDL_NOFRAME is set in 'flags', the SDL library will create a window without any title bar or frame decoration. Fullscreen video modes have this flag set automatically.

This function returns the video framebuffer surface, or NULL if it fails.

If you rely on functionality provided by certain video flags, check the flags of the returned surface to make sure that functionality is available. SDL will fall back to reduced functionality if the exact flags you wanted are not available.

Parameters:

width - desired width

height - desired height

bpp - bits per pixel or 0 to use the current display bits per pixel

flags - The flags parameter is the same as the flags field of the SDL_Surface structure.

Returns:

The framebuffer surface

Throws:

SDLException - If an error occurs

setGamma

public static void setGamma(float red,
                            float green,
                            float blue)
                     throws SDLException

Set the gamma correction for each of the color channels. The gamma values range (approximately) between 0.1 and 10.0 If this function isn't supported directly by the hardware, it will be emulated using gamma ramps, if available.

Parameters:

red - The red value

green - The green value

blue - The blue value

Throws:

SDLException - If an error occurs

getGammaRamp

public static GammaTable getGammaRamp()
                               throws SDLException

Retrieve the current values of the gamma translation tables. You must pass in valid pointers to arrays of 256 16-bit quantities. Any of the pointers may be NULL to ignore that channel. If the call succeeds, it will return 0. If the display driver or hardware does not support gamma translation, or otherwise fails, this function will return -1.

Throws:

SDLException - If an error occurs

setGammaRamp

public static void setGammaRamp(int[] red,
                                int[] green,
                                int[] blue)
                         throws SDLException

Set the gamma translation table for the red, green, and blue channels of the video hardware. Each table is an array of 256 16-bit quantities, representing a mapping between the input and output for that channel. The input is the index into the array, and the output is the 16-bit gamma value at that index, scaled to the output color precision. You may pass NULL for any of the channels to leave it unchanged. If the call succeeds, it will return 0. If the display driver or hardware does not support gamma translation, or otherwise fails, this function will return -1.

Parameters:

red - an int[] value

green - an int[] value

blue - an int[] value

Throws:

SDLException - If an error occurs

mapRGB

public static long mapRGB(SDLPixelFormat format,
                          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:

format -

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 static long mapRGBA(SDLPixelFormat format,
                           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:

format -

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

getRGB

public static SDLColor getRGB(int pixel,
                              SDLPixelFormat fmt)
                       throws SDLException

Maps a pixel value into the RGB components for a given pixel format This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).

Parameters:

pixel - Pixel to get color value for

fmt - The pixel format to use

Returns:

The color information

Throws:

SDLException - If an error occurs

getRGBA

public static SDLColor getRGBA(int pixel,
                               SDLPixelFormat fmt)
                        throws SDLException

Maps a pixel value into the RGBA components for a given pixel format This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).

If the surface has no alpha component, the alpha will be returned as 0xff (100% opaque).

Parameters:

pixel - Pixel to get color value for

fmt - The pixel format to use

Returns:

The color information

Throws:

SDLException - If an error occurs

createRGBSurface

public static SDLSurface createRGBSurface(long flags,
                                          int width,
                                          int height,
                                          int depth,
                                          long rMask,
                                          long gMask,
                                          long bMask,
                                          long aMask)
                                   throws SDLException

Allocate and free an RGB surface (must be called after SDL_SetVideoMode) If the depth is 4 or 8 bits, an empty palette is allocated for the surface. If the depth is greater than 8 bits, the pixel format is set using the flags '[RGB]mask'. If the function runs out of memory, it will return NULL.

The 'flags' tell what kind of surface to create. SDL_SWSURFACE means that the surface should be created in system memory.

SDL_HWSURFACE means that the surface should be created in video memory, with the same format as the display surface. This is useful for surfaces that will not change much, to take advantage of hardware acceleration when being blitted to the display surface.

SDL_ASYNCBLIT means that SDL will try to perform asynchronous blits with this surface, but you must always lock it before accessing the pixels. SDL will wait for current blits to finish before returning from the lock.

SDL_SRCCOLORKEY indicates that the surface will be used for colorkey blits. If the hardware supports acceleration of colorkey blits between two surfaces in video memory, SDL will try to place the surface in video memory. If this isn't possible or if there is no hardware acceleration available, the surface will be placed in system memory.

SDL_SRCALPHA means that the surface will be used for alpha blits and if the hardware supports hardware acceleration of alpha blits between two surfaces in video memory, to place the surface in video memory if possible, otherwise it will be placed in system memory.

If the surface is created in video memory, blits will be _much_ faster, but the surface format must be identical to the video surface format, and the only way to access the pixels member of the surface is to use the SDL_LockSurface() and SDL_UnlockSurface() calls.

If the requested surface actually resides in video memory, SDL_HWSURFACE will be set in the flags member of the returned surface. If for some reason the surface could not be placed in video memory, it will not have the SDL_HWSURFACE flag set, and will be created in system memory instead.

Parameters:

flags - Flags for this surface

height - Desired width

height - Desired height

depth - Desidred depth (bits per pixel)

rMask - Red Mask

gMask - Green Mask

bMask - Blue Mask

aMask - Alpha Mask

Returns:

The newly created surface

Throws:

SDLException - If an error occurs

createRGBSurfaceFrom

public static SDLSurface createRGBSurfaceFrom(int[] pixels,
                                              int width,
                                              int height,
                                              int depth,
                                              int pitch,
                                              long rMask,
                                              long gMask,
                                              long bMask,
                                              long aMask)
                                       throws SDLException

Create an SDL_Surface from pixel data

Creates an SDL_Surface from the provided pixel data.

The data stored in pixels is assumed to be of the depth specified in the parameter list. The pixel data is not copied into the SDL_Surface structure so it should not be freed until the surface has been freed with a called to SDL_FreeSurface. pitch is the length of each scanline in bytes.

See SDL_CreateRGBSurface for a more detailed description of the other parameters.

Parameters:

pixels - an int[] value

width - an int value

height - an int value

depth - an int value

pitch - an int value

rMask - an int value

gMask - an int value

bMask - an int value

aMask - an int value

Returns:

a SDLSurface value

Throws:

SDLException - if an error occurs

loadBMP

public static SDLSurface loadBMP(java.lang.String path)
                          throws SDLException

Load a surface from a BMP file located at path.

Returns:

the new surface

Throws:

SDLException - If an error occurs

warpMouse

public static void warpMouse(int x,
                             int y)
                      throws SDLException

Set the position of the mouse cursor (generates a mouse motion event).

Parameters:

x - The x co-ordinate

y - The y co-ordinate

Throws:

SDLException - If an error occurs

wmSetCaption

public static void wmSetCaption(java.lang.String title,
                                java.lang.String icon)

Sets the window tile and icon name.

Parameters:

title - the window title

icon - the icon name

wmGetCaption

public static java.util.HashMap wmGetCaption()

Gets the window tile and icon name.

Returns:

A HashMap with the the keys title and icon set to the title and icon

wmSetIcon

public static void wmSetIcon(SDLSurface icon,
                             short mask)

Sets the icon for the display window.

Sets the icon for the display window. Win32 icons must be 32x32.

This function must be called before the first call to SDL_SetVideoMode.

The mask is a bitmask that describes the shape of the icon. If mask is NULL, the shape is determined by the colorkey or alpha channel of the icon, if any. If neither of those are present, the icon is made opaque (no transparency).

If mask is non-NULL, it points to a bitmap with bits set where the corresponding pixel should be visible. The format of the bitmap is as follows: Scanlines come in the usual top-down order. Each scanline consists of (width / 8) bytes, rounded up. The most significant bit of each byte represents the leftmost pixel. Example

SDL_WM_SetIcon(SDL_LoadBMP("icon.bmp"), NULL);

Note: using the mask param is currently not supported

Parameters:

icon - a SDLSurface value

mask - a short value

wmIconifyWindow

public static boolean wmIconifyWindow()

Iconify/Minimise the window

If the application is running in a window managed environment SDL attempts to iconify/minimise it. If SDL_WM_IconifyWindow is successful, the application will receive a SDL_APPACTIVE loss event (see SDL_ActiveEvent).

Returns:

If the window was iconifies

wmGrabInput

public static SDLGrabMode wmGrabInput(SDLGrabMode mode)

Grabs mouse and keyboard input.

Grabbing means that the mouse is confined to the application window, and nearly all keyboard input is passed directly to the application, and not interpreted by a window manager, if any.

When mode is SDL_GRAB_QUERY the grab mode is not changed, but the current grab mode is returned.

Parameters:

mode - a SDLGrabMode value

Returns:

a SDLGrabMode value