sdljava.video

Class SDLVideo

public class SDLVideo extends Object

Please see the SDL Documention project page here

NOTE: The following methods are not yet implemented:

See Also: SDLSurface SDLPixelFormat

Field Summary
static intSDL_ALPHA_OPAQUE
Transparency definitions: These define alpha as the opacity of a surface
static intSDL_ALPHA_TRANSPARENT
Transparency definitions: These define alpha as the opacity of a surface
static longSDL_ANYFORMAT
Allows any pixel-format (Display surface)
static longSDL_ASYNCBLIT
Surface uses asynchronous blits if possible
static intSDL_DISABLE
Hide the cursor.
static longSDL_DOUBLEBUF
Surface is double buffered (Display surface)
static intSDL_ENABLE
Show the cursor
static longSDL_FULLSCREEN
Surface is full screen (Display Surface)
static longSDL_HWACCEL
Surface blit uses hardware acceleration
static longSDL_HWPALETTE
Surface has exclusive palette
static longSDL_HWSURFACE
Surface is stored in video memory
static longSDL_NOFRAME
No window caption or edge frame
static longSDL_OPENGL
Surface has an OpenGL context (Display Surface)
static longSDL_OPENGLBLIT
Surface supports OpenGL blitting (Display Surface).
static longSDL_PREALLOC
Surface uses preallocated memory
static intSDL_QUERY
Is the cursor visible?
static longSDL_RESIZABLE
Surface is resizable (Display Surface)
static longSDL_RLEACCEL
Colorkey blitting is accelerated with RLE
static longSDL_SRCALPHA
Surface blit uses alpha blending
static longSDL_SRCCOLORKEY
Surface use colorkey blitting
static longSDL_SWSURFACE
Surface is stored in system memory
Constructor Summary
SDLVideo()
Method Summary
static SDLSurfacecreateRGBSurface(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 SDLSurfacecreateRGBSurfaceFrom(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

Creates an SDL_Surface from the provided pixel data.

static GammaTablegetGammaRamp()
Retrieve the current values of the gamma translation tables.
static SDLColorgetRGB(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 SDLColorgetRGBA(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 SDLVideoInfogetVideoInfo()
This function returns information about the video hardware.
static SDLSurfacegetVideoSurface()
This function returns the current display surface.
static SDLSurfaceloadBMP(String path)
Load a surface from a BMP file located at path.
static longmapRGB(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 longmapRGBA(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 voidsetGamma(float red, float green, float blue)
Set the gamma correction for each of the color channels.
static voidsetGammaRamp(int[] red, int[] green, int[] blue)
Set the gamma translation table for the red, green, and blue channels of the video hardware.
static SDLSurfacesetVideoMode(int width, int height, int bpp, long flags)
Set up a video mode with the specified width, height and bits-per-pixel.
static StringvideoDriverName()
Obtain the name of the video driver
static intvideoModeOK(int width, int height, int bpp, int flags)
Check to see if a particular video mode is supported.
static voidwarpMouse(int x, int y)
Set the position of the mouse cursor (generates a mouse motion event).
static HashMapwmGetCaption()
Gets the window tile and icon name.
static SDLGrabModewmGrabInput(SDLGrabMode mode)
Grabs mouse and keyboard input.
static booleanwmIconifyWindow()
Iconify/Minimise the window

If the application is running in a window managed environment SDL attempts to iconify/minimise it.

static voidwmSetCaption(String title, String icon)
Sets the window tile and icon name.
static voidwmSetIcon(SDLSurface icon, short mask)
Sets the icon for the display window.

Field Detail

SDL_ALPHA_OPAQUE

public static final int SDL_ALPHA_OPAQUE
Transparency definitions: These define alpha as the opacity of a surface

SDL_ALPHA_TRANSPARENT

public static final int SDL_ALPHA_TRANSPARENT
Transparency definitions: These define alpha as the opacity of a surface

SDL_ANYFORMAT

public static final long SDL_ANYFORMAT
Allows any pixel-format (Display surface)

SDL_ASYNCBLIT

public static final long SDL_ASYNCBLIT
Surface uses asynchronous blits if possible

SDL_DISABLE

public static final int SDL_DISABLE
Hide the cursor.

See Also: SDLVideo

SDL_DOUBLEBUF

public static final long SDL_DOUBLEBUF
Surface is double buffered (Display surface)

SDL_ENABLE

public static final int SDL_ENABLE
Show the cursor

See Also: SDLVideo

SDL_FULLSCREEN

public static final long SDL_FULLSCREEN
Surface is full screen (Display Surface)

SDL_HWACCEL

public static final long SDL_HWACCEL
Surface blit uses hardware acceleration

SDL_HWPALETTE

public static final long SDL_HWPALETTE
Surface has exclusive palette

SDL_HWSURFACE

public static final long SDL_HWSURFACE
Surface is stored in video memory

SDL_NOFRAME

public static final long SDL_NOFRAME
No window caption or edge frame

SDL_OPENGL

public static final long SDL_OPENGL
Surface has an OpenGL context (Display Surface)

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.

SDL_PREALLOC

public static final long SDL_PREALLOC
Surface uses preallocated memory

SDL_QUERY

public static final int SDL_QUERY
Is the cursor visible?

See Also: SDLVideo

SDL_RESIZABLE

public static final long SDL_RESIZABLE
Surface is resizable (Display Surface)

SDL_RLEACCEL

public static final long SDL_RLEACCEL
Colorkey blitting is accelerated with RLE

SDL_SRCALPHA

public static final long SDL_SRCALPHA
Surface blit uses alpha blending

SDL_SRCCOLORKEY

public static final long SDL_SRCCOLORKEY
Surface use colorkey blitting

SDL_SWSURFACE

public static final long SDL_SWSURFACE
Surface is stored in system memory

Constructor Detail

SDLVideo

private SDLVideo()

Method Detail

createRGBSurface

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

getGammaRamp

public static GammaTable getGammaRamp()
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

getRGB

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

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

getVideoInfo

public static SDLVideoInfo getVideoInfo()
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

getVideoSurface

public static SDLSurface getVideoSurface()
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

loadBMP

public static SDLSurface loadBMP(String path)
Load a surface from a BMP file located at path.

Returns: the new surface

Throws: SDLException If an error occurs

UNKNOWN: The filesystem path of the file with the image data in BMP format

mapRGB

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

setGamma

public static void setGamma(float red, float green, float blue)
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

setGammaRamp

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

Returns: a boolean value

Throws: SDLException If an error occurs

setVideoMode

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

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

videoDriverName

public static String videoDriverName()
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)
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

warpMouse

public static void warpMouse(int x, int y)
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

wmGetCaption

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

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

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

wmSetCaption

public static void wmSetCaption(String title, String icon)
Sets the window tile and icon name.

Parameters: title the window title icon the icon name

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