Ruby/SDL is Ruby extension library for SDL. This library enables you to create games, demo, or so on.
Ruby/SDL has following functions.
On ruby 1.9, strings have encoding information but many methods of Ruby/SDL ignore this information since SDL doesn't define the treatment of multibyte encodings. Only some methods use encoding information such as SDL::WM.set_caption and SDL::Kanji#put.
Please see items in this reference for more details.
You can enable/disable Ruby/SDL m17n support to use --enable-m17n/--disable-m17n when you run extconf.rb.
A Exception class for SDL specific errors. This class is subclass of StandardError.
Ruby/SDL version string.
Before SDL can be used in a program it must be initialized with SDL.init. SDL.init initializes all the subsystems that
the user requests (video, audio, joystick, timers and/or cdrom).
SDL.init(flags)Initializes SDL. This should be called before all other Ruby/SDL methods. The flags parameter specifies what
part(s) of SDL to initialize.
Raises SDL::Error on failure
SDL.quitThis method shots down all SDL subsystem and frees the resources allocated to them. Because this method is automatically called when ruby stops, you don't have to call this function normally.
You should know SDL and Ruby/SDL very well when you use this method.
SDL.inited_system(flags)SDL.initedSystem(flags)This method allows you to see which SDL subsytems have
been ((<initialized|SDL.init>)). ((|flags|)) is a bitwise OR'd
combination of the subsystems you wish to check (see SDL.init for a list of subsystem flags).
Returns a bitwised OR'd combination of the initialized subsystems.
EXAMPLE
# Here are several ways you can use SDL.inited_system # Get init data on all the subsystem subsystem_init = SDL.inited_system(SDL::INIT_EVERYTHING) if subsystem_init & SDL::INIT_VIDEO puts "video is initialized" else puts "video is not initialized" end # Just check for one specfic subsystem if SDL.inited_system(SDL::INIT_VIDEO) != 0 puts "Video is initialized" else puts "Video is not initialized " end # Check for two subsystem subsystem_mask = SDL::INIT_VIDEO|SDL::INIT_AUDIO; if SDL.inited_system(subsystem_mask) == subsystem_mask puts "Video and Audio initialized." else puts "Video and Audio not initialized" end
See Also
SDL.getenv(var)SDL.putenv(string)Add or Change the value of environmental variables. The argument string is of the form "name=value"
If you want to change SDL_WINDOWID or SDL_VIDEODRIVER environmental variable to modify the behavior of SDL in your program, you should use this function instead of ENV.
Raises SDL::Error on failure
EXAMPLE
# from http://moriq.tdiary.net/20051006.html
# Apollo with Ruby/SDL
require 'phi'
require 'sdl'
# Create form
form = Phi::Form.new
$terminated = false
form.on_close{ $terminated = true }
form.caption = "Ruby/SDL on Phi::Form"
# Create a panel on new form
panel = Phi::Panel.new(form)
panel.align = Phi::AL_LEFT
# Put SDL window on panel with WINDOWID hack
SDL.putenv("SDL_VIDEODRIVER=windib")
SDL.putenv("SDL_WINDOWID=#{panel.handle}")
form.show
# initialize SDL
SDL.init(SDL::INIT_VIDEO)
screen = SDL.setVideoMode(640, 480, 16, SDL::SWSURFACE)
# main loop
unless $terminated
while event = SDL::Event2.poll
case event
when SDL::Event2::KeyDown, SDL::Event2::Quit
exit
end
end
sleep 0.05
endSDL presents a very simple interface to the display framebuffer. The framebuffer is represented as an offscreen surface to which you can write directly. If you want the screen to show what you have written, call the update function which will guarantee that the desired portion of the screen is updated.
Before you call any of the SDL video functions, you must first call SDL.init(SDL::INIT_VIDEO), which initializes the video and events in the SDL library.
If you use both sound and video in your application, you need to call SDL.init(SDL::INIT_AUDIO | SDL::INIT_VIDEO) before opening the sound device, otherwise under Win32 DirectX, you won't be able to set full-screen display modes.
After you have initialized the library, you can start up the video display in a number of ways. The easiest way is to pick a common screen resolution and depth and just initialize the video, checking for errors. You will probably get what you want, but SDL may be emulating your requested mode and converting the display on update. The best way is to query, for the best video mode closest to the desired one, and then convert your images to that pixel format.
SDL currently supports any bit depth >= 8 bits per pixel. 8 bpp formats are considered 8-bit palettized modes, while 12, 15, 16, 24, and 32 bits per pixel are considered "packed pixel" modes, meaning each pixel contains the RGB color components packed in the bits of the pixel.
After you have initialized your video mode, you can take the surface that was returned, and write to it like any other framebuffer, calling the update routine as you go.
Graphical Surface class.
This class represent areas of "graphical" memory, memory that can be drawn to.
Video framebuffer class.
This class is subclass of SDL::Surface, and contents is shown in display.
The video framebuffer is returned by SDL::Screen.open and SDL::Screen.get.
Video Target information class.
The instance of this class is returned by SDL::Screen.info. It contains information on either the 'best' available mode (if called before SDL::Screen.open) or the current video mode.
This class has following methods.
SDL::VideoInfo#hw_availableSDL::VideoInfo#wm_availableSDL::VideoInfo#blit_hwSDL::VideoInfo#blit_hw_CCSDL::VideoInfo#blit_hw_ASDL::VideoInfo#blit_swSDL::VideoInfo#blit_sw_CCSDL::VideoInfo#blit_sw_ASDL::VideoInfo#blit_fillSDL::VideoInfo#video_memSDL::VideoInfo#bppSurface format information class. Please see Color, PixelFormat and Pixel value.
In Ruby/SDL, color is described as four elements of 8-bit unsigned interger(from 0 to 255), Red, Green, Blue and Alpha. In Ruby/SDL, this values are packed as unsigned n-bit integer(n=8,16,24,32). The rules of this conversion is called PixelFormat and converted n-bit integer is called pixel value. Each surface has one PixelFormat, and you can use SDL::Surface#format to get PixelFormat from surface object. You can also covert from or to pixel values calling SDL::PixelFormat#map_rgb, SDL::PixelFormat#map_rgba, SDL::PixelFormat#get_rgb and SDL::PixelFormat#get_rgba. You can use pixel value or 3 elements array or 4 elements array as color parameter. Return values are normally pixel values.
Not documented yet.
SDL.get_video_surfaceSDL.getVideoSurfaceSDL::Screen.getThis method returns the current display surface. If SDL is doing format conversion on the display surface, this method returns the publicly visible surface, not the real video surface.
Returns the instance of SDL::Screen.
Raises SDL::Error on failure
SDL.video_infoSDL.videoInfoSDL::Screen.infoThis function returns a information about the video hardware. If this is called before SDL::Screen.open, bpp attribute of the returned object will contain the pixel format of the "best" video mode.
Returns the instance of SDL::VideoInfo.
Raises SDL::Error on failure
See Also
SDL.video_driver_nameSDL.videoDriverNameSDL::Screen.driver_nameSDL::Screen.driverNameThe driver name is a simple one word identifier like "x11" or "windib".
Returns driver name as string.
Raises SDL::Error if video has not been initialized with SDL.init.
See Also
SDL.list_modes(flags)SDL.listModes(flags)SDL::Screen.list_modes(flags)SDL::Screen.listModes(flags)Return an array of available screen dimensions for the given format and video flags, sorted largest to smallest.
Returns nil if there are no dimensions available for a particular format, or true if any dimension is okay for the given format. The flag parameter is an OR'd combination of surface flags. The flags are the same as those used SDL::Screen.open and they play a strong role in deciding what modes are valid. For instance, if you pass SDL::HWSURFACE as a flag only modes that support hardware video surfaces will be returned.
EXAMPLE
# Get available fullscreen/hardware modes
modes = SDL::Screen.list_modes(SDL::FULLSCREEN|SDL::HWSURFACE)
# Check is there are any modes available
if modes == nil
puts "No modes available!"
exit 1
end
# Check is there are any modes available
if modes == true
puts "All resolutions available."
else
# Print valid modes
puts "Available Modes"
modes.each{|w, h| puts " #{w} x #{h}"}
end
See Also
SDL.check_video_mode(w,h,bpp,flags)SDL.checkVideoMode(w,h,bpp,flags)SDL::Screen.check_mode(w,h,bpp,flags)SDL::Screen.checkMode(w,h,bpp,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, height and requested surface flags (see SDL::Screen.open).
The bits-per-pixel value returned is only a suggested mode. You can usually request and bpp you want when setting the video mode and SDL will emulate that color depth with a shadow video surface.
EXAMPLE
puts "Checking mode 640x480@16bpp."
bpp = SDL::Screen.check_mode(640, 480, 16, SDL::HWSURFACE)
if bpp == 0
puts "Mode not available."
exit 1
end
puts "SDL Recomemends 640x480@#{bpp}bpp."
screen = SDL::Screen.open(640, 480, bpp, SDL_HWSURFACE)
See Also
SDL.setVideoMode(w,h,bpp,flags)SDL.set_video_mode(w,h,bpp,flags)SDL::Screen.open(w,h,bpp,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.
The flags parameter is the same as the SDL::Surface#flags OR'd combinations of the following values are valid.
Returns the framebuffer surface as instace of SDL::Screen.
Raises SDL::Error on failure
NOTES
Whatever flags SDL::Screen.open could satisfy are set in the Surface#flags of the returned surface.
The bpp parameter is the number of bits per pixel, so a bpp of 24 uses the packed representation of 3 bytes/pixel. For the more common 4 bytes/pixel mode, use a bpp of 32. Somewhat oddly, both 15 and 16 will request a 2 bytes/pixel mode, but different pixel formats.
See Also
SDL::Surface#lock, SDL::Surface#set_colors, SDL::Screen#flip, SDL::Screen
SDL::Screen#updateRect(x,y,w,h)SDL::Screen#update_rect(x,y,w,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).
If x, y, w and h are all 0, this method update the entire screen.
This method should not be called while screen is locked|Surface#lock.
See Also
SDL::Screen#update_rects(*rects)SDL::Screen#updateRects(*rects)Makes sure the given list of rectangles is updated on the given screen. Each rectangle parameter should be an array of 4 elements as [x, y, w, h]. The rectangles must all be confined within the screen boundaries (no clipping is done).
This method should not be called while screen(self), is locked.
See Also
SDL::Screen#flipOn 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't support double-buffering, this is equivalent to calling self.update_rect(0, 0, 0, 0)
Raises SDL::Error on failure
See Also
SDL::Surface#set_colors(colors,firstcolor)SDL::Surface#setColors(colors,firstcolor)Sets a portion of the colormap for the given 8-bit surface.
When self 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::Screen.open flags, this method will always return true, 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.
colors is array of colors, one color has three componets, R, G, B and each component is 8-bits in size.
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_SetColors modifies both palettes (if present), and is equivalent to calling SDL::Surface#set_palette with the flags set to (SDL::OGPAL | SDL::PHYSPAL).
If self is not a palettized surface, this method does nothing, returning false. If all of the colors were set as passed to this method, 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.
EXAMPLE
# Create a display surface with a grayscale palette
# Fill colors with color information
colors = Array.new(256){|i| [i, i, i]}
# Create display
screen = SDL::Screen.open(640, 480, 8, SDL::HWPALETTE)
# Set palette
screen.set_colors(colors, 0)
See Also
SDL::Surface#set_palette(flags,colors,firstcolor)SDL::Surface#setPalette(flags,colors,firstcolor)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::Surface.blit 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 method can modify either the logical or physical palette by specifing SDL::LOGPAL or SDL::PHYSPALthe in the flags parameter.
When self 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::Screen.open flags, this method will always return true, 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.
colors is array of colors, one color has three componets, R, G, B and each component is 8-bits in size.
If surface is not a palettized surface, this function does nothing, returning false. If all of the colors were set as passed to this method, 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.
EXAMPLE
# Create a display surface with a grayscale palette
# Fill colors with color information
colors = Array.new(256){|i| [i, i, i]}
# Create display
screen = SDL::Screen.open(640, 480, 8, SDL::HWPALETTE)
# Setpalette
screen.set_palette(SDL::LOGPAL|SDL::PHYSPAL, colors, 0)
See Also
SDL.set_gamma(redgamma,greengamma,bluegamma)SDL.setGamma(redgamma,greengamma,bluegamma)SDL::Screen.set_gamma(redgamma,greengamma,bluegamma)SDL::Screen.setGamma(redgamma,greengamma,bluegamma)Sets the "gamma function" for the display of each color component. Gamma controls the brightness/contrast of colors displayed on the screen. A gamma value of 1.0 is identity (i.e., no adjustment is made).
This function adjusts the gamma based on the "gamma function" parameter, you can directly specify lookup tables for gamma adjustment with SDL::Screen.set_gamma_ramp.
Raises SDL::Error on failure
NOTES
Not all display hardware is able to change gamma.
See Also
SDL.get_gamma_rampSDL.getGammaRampSDL::Screen.get_gamma_rampSDL::Screen.getGammaRampGets the gamma translation lookup tables currently used by the display. Each table is an array of 256 16bit unsigned integer values.
Returns an array of 3 elements of an array of 256 16bit unsigned integer.
Raises SDL::Error on failure
NOTES
Not all display hardware is able to change gamma.
See Also
SDL.set_gamma_ramp(table)SDL.setGammaRamp(table)SDL::Screen.set_gamma_ramp(tables)SDL::Screen.setGammaRamp(tables)Sets the gamma lookup tables for the display for each color component. tables parameter is same as SDL::Screen.get_gamma_ramp, 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.
This function adjusts the gamma based on lookup tables, you can also have the gamma calculated based on a "gamma function" parameter with SDL::Screen.set_gamma.
Raises SDL::Error on failure
SDL::Surface#map_rgb(r,g,b)SDL::Surface#mapRGB(r,g,b)SDL::PixelFormat#map_rgb(r,g,b)SDL::PixelFormat#mapRGB(r,g,b)Maps the RGB color value to the specified pixel format and returns the pixel value as a 32-bit integer. r, g, b should be more than and equal to 0, and less than or equal to 255.
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).
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 16-bit unsigned integer, and similarly a 8-bit unsigned integer for an 8-bpp format).
SDL::Surface#map_rgba(r,g,b,a)SDL::Surface#mapRGBA(r,g,b,a)SDL::PixelFormat#map_rgba(r,g,b,a)SDL::PixelFormat#mapRGBA(r,g,b,a)Maps the RGBA color value to the specified pixel format and returns the pixel value as a 32-bit integer. r, g, b should be more than and equal to 0, and less than or equal to 255.
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).
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 16-bit unsigned integer, and similarly a 8-bit unsigned integer for an 8-bpp format).
SDL::Surface#get_rgb(pixel)SDL::Surface#getRGB(pixel)SDL::PixelFormat#get_rgb(pixel)SDL::PixelFormat#getRGB(pixel)Get RGB component values from a pixel stored in the specified pixel format. It returns an array of 3 elements.
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]).
SDL::Surface#get_rgba(pixel)SDL::Surface#getRGBA(pixel)SDL::PixelFormat#get_rgba(pixel)SDL::PixelFormat#getRGBA(pixel)Get RGBA component values as array of four elements from a pixel stored in the specified 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).
SDL::Surface.new(flags,w,h,depth,Rmask,Gmask,Bmask,Amask)SDL::Surface.new(flags,w,h,format)Allocate an empty surface (must be called after SDL::Screen.open)
If depth is 8 bits an empty palette is allocated for the surface, otherwise a 'packed-pixel' format is created using the RGBAmask's provided (see SDL::PixelFormat). The flags specifies the type of surface that should be created, it is an OR'd combination of the following possible values.
Returns the instance of SDL::Surface.
Raises SDL::Error on failure
EXAMPLE
# Create a 32-bit surface with the bytes of
# each pixel in R,G,B,A order,
# as expected by OpenGL for textures
big_endian = ([1].pack("N") == [1].pack("L"))
if big_endian
rmask = 0xff000000
gmask = 0x00ff0000
bmask = 0x0000ff00
amask = 0x000000ff
else
rmask = 0x000000ff
gmask = 0x0000ff00
bmask = 0x00ff0000
amask = 0xff000000
end
surface = SDL::Surface.new(SDL::SWSURFACE, width, height, 32,
rmask, gmask, bmask, amask);
NOTES
Note: If an alpha-channel is specified (that is, if ((|Amask|)) is nonzero), then the SDL::SRCALPHA flag is automatically set. You may remove this flag by calling ((<SDL::Surface#set_alpha>)) after surface creation.
See Also
SDL::Surface.new_from, SDL::Screen.oepn, SDL::Surface#lock, SDL::Surface#set_alpha, SDL::Surface#set_color_key
SDL::Surface.new_from(pixels,w,h,depth,pitch,Rmask,Gmask,Bmask,Amask)Creates an SDL::Surface object from the provided pixel data.
The data stored in pixels(String object)
is assumed to be of the depth
specified in the parameter list. pitch is the length of each scanline in bytes.
See SDL::Surface.new for a more detailed description of the other parameters.
Returns the created surface.
Raises SDL::Error on failure
See Also
SDL::Surface#lockThis method sets up a surface for directly accessing the pixels. Between calls to SDL::Surface#lock and SDL::Surface#unlock you can write to and read from surface directly. Once you are done accessing the surface, you should use SDL::Surface#unlock to release it.
Not all surfaces require locking. If SDL::Surface#must_lock? returns false, then you can read and write to the surface at any time, and the pixel format of the surface will not change.
No operating system or library calls should be made between lock/unlock pairs, as critical system locks may be held during this time.
It should be noted, that since SDL 1.1.8 surface locks are recursive. This means that you can lock a surface multiple times, but each lock must have a match unlock.
surface.lock # Surface is locked # Direct pixel access on surface here surface.lock # More direct pixel access on surface surface.unlock # Surface is still locked # Note: Is versions < 1.1.8, the surface would have been # no longer locked at this stage surface.unlock # Surface is now unlocked
You shoud lock before colling following methods:
Raises SDL::Error, if the surface couldn't be locked.
NOTES
If SDL::Surface#auto_lock? returns true, you need not call this method because Ruby/SDL automatically locks surface when you call methods that need locking.
See Also
SDL::Surface#unlock, SDL::Surface#must_lock?, SDL.auto_lock?, SDL.auto_lock_on, SDL.auto_lock_off, SDL.auto_lock=
SDL::Surface#unlockSurfaces that were previously locked using SDL::Surfaces#lock must be unlocked with SDL::Surfaces#unlock. Surfaces should be unlocked as soon as possible.
It should be noted that since 1.1.8, surface locks are recursive.
See Also
SDL::Surface#must_lock?SDL::Surface#mustLock?See Also
SDL::Surface.load_bmp(filename)SDL::Surface.loadBMP(filename)Loads a surface from a named Windows BMP file.
Returns the new SDL::Surface object.
Raises SDL::Error on failure
See Also
SDL::Surface.load_bmp_from_io(io)SDL::Surface.loadBMPFromIO(io)Loads a surface from a ruby's IO object. IO object means the ruby object that has following methods:
For example, instances of IO class, StringIO class and Zlib::GZipReader class are IO object.
Returns the new SDL::Surface object.
Raises SDL::Error on failure
SDL::Surface#save_bmp(filename)SDL::Surface#saveBMP(filename)Saves the self surface as a Windows BMP file named filename.
Raises SDL::Error on failure
See Also
SDL::Surface#destroySDL::Surface#destroyed?See Also
SDL::Surface#set_color_key(flag,key)SDL::Surface#setColorKey(flag,key)Sets the color key (transparent pixel) in a blittable surface|Surface and enables or disables RLE blit acceleration. key parameter should be pixel value or color array.
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, if pixel value is used. In that case, SDL::PixelFormat#map_rgb is often useful for obtaining an acceptable value.
If flag is SDL_SRCCOLORKEY then key is the transparent pixel color 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::Surface.blit. The surface will actually be encoded for RLE acceleration the first time SDL::Surface.blit or SDL::Surface#display_format is called on the surface.
If flag is 0, this function clears any current color key.
Raises SDL::Error on failure
SDL::Surface#set_alpha(flags,alpha)SDL::Surface#setAlpha(flags,alpha)This method is used for setting the per-surface alpha value and/or enabling and disabling alpha blending.
The surface parameter specifies which surface whose alpha attributes you wish to adjust. flags is used to specify whether alpha blending should be used (SDL::SRCALPHA)
and whether the surface should use RLE
acceleration for blitting (SDL::RLEACCEL). flags can be an OR'd combination of these two options, one of these options or 0. If SDL::SRCALPHA is not passed as a flag
then all alpha information is ignored when
blitting the surface. The alpha parameter is the per-surface alpha value; a surface need not have an alpha channel to use per-surface alpha and blitting can still be accelerated with SDL::RLEACCEL.
Alpha effects surface blitting in the following ways:
RGBA->RGBA witout SDL::SRCALPHA
The RGBA data is copied to the destination surface. If SDL::SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.
RGB->RGB with SDL_SRCALPHA
The source is alpha-blended with the destination using the per-surface alpha value. If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.
RGB->RGB witout SDL_SRCALPHA
The RGB data is copied from the source. If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.
Raises SDL::Error on failure
NOTES
Note: This method and the semantics of SDL alpha blending have changed since version 1.1.4. Up until version 1.1.5, an alpha value of 0 was considered opaque and a value of 255 was considered transparent. This has now been inverted: 0 (SDL::ALPHA_TRANSPARENT) is now considered transparent and 255 (SDL::ALPHA_OPAQUE) is now considered opaque. The per-surface alpha value of 128 is considered a special case and is optimised, so it's much faster than other per-surface values.
Note that RGBA->RGBA blits (with SDL::SRCALPHA set) keep the alpha of the destination surface. This means that you cannot compose two arbitrary RGBA surfaces this way and get the result you would expect from "overlaying" them; the destination alpha will work as a mask.
Also note that per-pixel and per-surface alpha cannot be combined; the per-pixel alpha is always used if available
See Also
SDL::Surface#map_rgba, SDL::Surface#get_rgba, SDL::Surface#display_format, SDL::Surface.blit, SDL::Surface#alpha
SDL::Surface#set_clip_rect(x,y,w,h)SDL::Surface#setClipRect(x,y,w,h)Sets the clipping rectangle for a surface. When this surface is the destination of a blit, only the area within the clip rectangle will be drawn into.
The rectangle pointed to by rect will be clipped to the edges of the surface so that the clip rectangle for a surface can never fall outside the edges of the surface.
See Also
SDL::Surface#get_clip_rectSDL::Surface#getClipRectGets the clipping rectangle for a surface. When this surface is the destination of a blit, only the area within the clip rectangle is drawn into.
Returns 4 element array as [x, y, w, h].
See Also
SDL.blit_surface(src,srcX,srcY,srcW,srcH,dst,dstX,dstY)SDL.blitSurface(src,srcX,srcY,srcW,srcH,dst,dstX,dstY)SDL::Surface.blit(src,srcX,srcY,srcW,srcH,dst,dstX,dstY)This performs a fast blit from the source surface to the destination surface.
src is source surface, dst is destination surface, srcX, srcY, srcW, srcH is source rectangle, and dstX, dstY is destination point. If all of srcX, srcY, srcW, srcH is zero, the entire surface is copied.
The blit function should not be called on a locked surface.
The results of blitting operations vary greatly depending on whether SDL::SRCAPLHA is set or not. See SDL::Surface#set_alpha for an explaination of how this affects your results. Colorkeying and alpha attributes also interact with surface blitting, as the following pseudo-code should hopefully explain.
if source surface has SDL::SRCALPHA set
if source surface has alpha channel (that is, Amask != 0)
blit using per-pixel alpha, ignoring any colour key
elsif source surface has SDL::SRCCOLORKEY set
blit using the colour key AND the per-surface alpha value
else
blit using the per-surface alpha value
end
elsif source surface has SDL::SRCCOLORKEY se
blit using the colour key
else
ordinary opaque rectangular blit
end
If the blit is successful, it returns 0.
If either of the surfaces were in video memory, and the blit raises SDL::Surface::VideoMemoryLost, the video memory was lost, so it should be reloaded with artwork and re-blitted.
This happens under DirectX 5.0 when the system switches away from your fullscreen application. Locking the surface will also fail until you have access to the video memory again.
SDL::Surface#fill_rect(x,y,w,h,color)SDL::Surface#fillRect(x,y,w,h,color)This method performs a fast fill of the given rectangle with color.
Please see Color, PixelFormat and Pixel value to specify color. If the color value contains an alpha value then the destination is simply "filled" with that alpha information, no blending takes place.
If there is a clip rectangle set on the destination (set via SDL::Surface#set_clip_rect) 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.
Raises SDL::Error on failure
SDL::Surface#display_formatSDL::Surface#displayFormatThis method copies self to a new surface of the pixel format and colors of the video framebuffer, suitable for fast blitting onto the display surface.
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 you want an alpha channel, see SDL::Surface#display_format_alpha.
Returns converted surface object.
Raises SDL::Error if the conversion fails or runs out of memory.
SDL::Surface#display_format_alphaSDL::Surface#displaFormatAlphaThis method copies self to a new surface of the pixel format and colors of the video framebuffer plus an alpha channel, suitable for fast blitting onto the display surface.
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.
This function can be used to convert a colourkey to an alpha channel, if the SDL::SRCCOLORKEY flag is set on the surface. The generated surface will then be transparent (alpha=0) where the pixels match the colourkey, and opaque (alpha=255) elsewhere.
Returns converted surface object.
Raises SDL::Error if the conversion fails or runs out of memory.
SDL::Surface#flagsReturns the surface flags. The following are supported:
Returns OR'd compination of above constants.
See Also
SDL::Surface#formatSDL::Surface#wSee Also
SDL::Surface#hSee Also
SDL::Surface#pixelsNOTES
You must lock surface before calling this method.
See Also
SDL::PixelFormat#RmaskSDL::PixelFormat#GmaskSDL::PixelFormat#BmaskSDL::PixelFormat#AmaskSDL::PixelFormat#RlossSDL::PixelFormat#GlossSDL::PixelFormat#BlossSDL::PixelFormat#AlossSDL::PixelFormat#RshiftSDL::PixelFormat#GshiftSDL::PixelFormat#BshiftSDL::PixelFormat#AshiftSDL::Surface#colorkeySDL::Surface#alphaSee Also
SDL::PixelFormat#colorkeySDL::PixelFormat#alphaSee Also
SDL::Surface#bppSDL::PixelFormat#bppSDL::Surface#pitchReturns the number of bytes used for each scanline in a surface.
SDL::Surface#pixels returns pitch*SDL::Surface#h bytes string. Normally, this values is equal to SDL::Surface#bpp*SDL::Surface#w/8, but in some case the value is more than bpp*w/8 because some pudding bytes are used.
SDL::Surface.load(filename)Load image into an surface and returns surface object. If image format supports transparent color, colorkey is set into new surfafe.
Supoorted formats are BMP, PNM (PPM/PGM/PBM), XPM, XCF, PCX, GIF, JPEG, TIFF, TGA, PNG and LBM.
Raises SDL::Error on failure
You need SDL_image to use this method.
SDL::Surface.load_from_io(io)SDL::Surface.loadFromIO(io)Loads a surface from a ruby's IO object. IO object means the ruby object that has following methods:
If image format supports transparent color, colorkey is set into new surfafe. Supoorted formats are BMP, PNM (PPM/PGM/PBM), XPM, XCF, PCX, GIF, JPEG, TIFF, TGA, PNG and LBM.
Raises SDL::Error on failure
SDL::Surface#put_pixel(x, y, color)SDL::Surface#putPixel(x, y, color)SDL::Surface#[x, y] = colorWrites color pixel at (x, y).
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
SDL::Surface#get_pixel(x, y)SDL::Surface#getPixel(x, y)SDL::Surface#[x, y]Returns pixel value at (x, y).
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
SDL::Surface#put(src, x, y)Performs a fast blit from entire src surface to self at (x, y).
This means:
SDL::Surface.blit(src, 0, 0, src.w, src.h, self, x, y)
See Also
SDL::Surface#copy_rect(x,y,w,h)SDL::Surface#copyRect(x,y,w,h)Copies a (x, y, w, h) rectangle from self and return new surface|Surface object.
Raises SDL::Error on failure
NOTES
This method call SDL::Surface.blit internally, therefore you must unlock surface before calling it.
SDL.auto_lock?SDL.autoLock?SDL.auto_lockSDL.autoLockThis method is obsolete. Please use SDL::Surface.auto_lock? instead.
You need SGE to use this method.
SDL::Surface.auto_lock?SDL::Surface.autoLock?Returns true if surface is automatically locked when necessary, otherwise returns false.
Default is ON(true).
You need SGE to use this method.
SDL.auto_lock_onSDL.autoLockONThis method is obsolete. Please use SDL::Surface.auto_lock_on instead.
You need SGE to use this method.
SDL::Surface.auto_lock_onSDL::Surface.autoLockONEnables auto surface locking.
You need SGE to use this method.
SDL.auto_lock_offSDL.autoLockOFFThis method is obsolete. Please use SDL::Surface.auto_lock_off instead.
You need SGE to use this method.
SDL::Surface.auto_lock_offSDL::Surface.autoLockOFFDisables auto surface locking.
You need SGE to use this method.
SDL.auto_lock=(locking)SDL.autoLock=(locking)This method is obsolete. Please use SDL::Surface.auto_lock_on instead.
Enables or disables auto surface locking. 'SDL.auto_lock = true' is same as SDL::Surface.auto_lock_on and 'SDL.auto_lock = false' is same as SDL::Surface.auto_lock_off.
You need SGE to use this method.
SDL.transform(src,dst,angle,xscale,yscale,px,py,qx,qy,flags)This method is obsolete. Please use SDL::Surface.transform_draw instead.
You need SGE to use this method.
SDL::Surface.transform_draw(src,dst,angle,xscale,yscale,px,py,qx,qy,flags)Draws a rotated and scaled version of src on dest. angle the rotation angle in degrees, xscale and yscale are x and y scaling factor, (px, py) is the pivot point to rotate around in the src, and (qx, qy) is the destination point on dst surface.
flags is OR'd combination of follwing values:
You need SGE to use this method.
NOTES
To get optimal performance PLEASE make sure that the two surfaces has the same pixel format (color depth) and doesn't use 24-bpp.
You can set source and destination clipping rectangles with SDL::Surface#set_clip_rect.
If you use the interpolated renderer the image will be clipped 1 pixel in hight and width (to optimize the performance).
If you want to transform a 32-bpp RGBA (alpha) surface with the interpolated renderer, please use the SDL::TRANSFORM_SAFE flag.
This function will not do any alpha blending, but it will try to preserve the alpha channel. If you want to rotate and alpha blend the result, please use SDL::Surface.transform_blit and then blit that surface to its destination.
See Also
SDL::Surface.transform_blit, SDL::Surface#transform_surface, SDL::Surface.new
SDL.transform_blit(src,dst,angle,xscale,yscale,px,py,qx,qy,flags)SDL.transformBlit(src,dst,angle,xscale,yscale,px,py,qx,qy,flags)This method is obsolete. Please use SDL::Surface.transform_blit instead.
You need SGE to use this method.
SDL::Surface.transform_blit(src,dst,angle,xscale,yscale,px,py,qx,qy,flags)SDL::Surface.transformBlit(src,dst,angle,xscale,yscale,px,py,qx,qy,flags)Draw a rotated and scaled image. This method is same as SDL::Surface.transform_draw except colorkey and blending are enabled.
You need SGE to use this method.
SDL::Surface#draw_line(x1,y1,x2,y2,color, aa=false, alpha=nil)SDL::Surface#drawLine(x1,y1,x2,y2,color, aa=false, alpha=nil)Draws a color line from (x1, y1) to (x2, y2). If aa is true, draws an antialiased line. If alpha is integer, draws blended line with alpha value is alpha. If alpha is nil, draws a normal line.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_aa_line(x1,y1,x2,y2,color)SDL::Surface#drawAALine(x1,y1,x2,y2,color)This method is obsolete. Please use SDL::Surface#draw_line instead.
Draws a color antialiased line from (x1, y1) to (x2, y2).
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_line_alpha(x1,y1,x2,y2,color,alpha)SDL::Surface#drawLineAlpha(x1,y1,x2,y2,color,alpha)This method is obsolete. Please use SDL::Surface#draw_line instead.
Draws a color line from (x1, y1) to (x2, y2) with blending.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_aa_line_alpha(x1,y1,x2,y2,color,alpha)SDL::Surface#drawAALineAlpha(x1,y1,x2,y2,color,alpha)This method is obsolete. Please use SDL::Surface#draw_line instead.
Draws a antialiased color line from (x1, y1) to (x2, y2) with blending.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_rect(x,y,w,h,color, fill=false, alpha=nil)SDL::Surface#drawRect(x,y,w,h,color, fill=false, alpha=nil)Draws a rectangle with color color. Draw a filled rectangle if fill is true, and a blended rectangle if alpha is integer.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_rect_alpha(x,y,w,h,color,alpha)SDL::Surface#drawRectAlpha(x,y,w,h,color,alpha)This method is obsolete. Please use SDL::Surface#draw_rect instead.
Draws a blended rectangle.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_filled_rect_alpha(x,y,w,h,color,alpha)SDL::Surface#drawFilledRectAlpha(x,y,w,h,color,alpha)This method is obsolete. Please use SDL::Surface#draw_rect instead.
Draws a filled blended rectangle.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_circle(x,y,r,color,fill=false,aa=false,alpha=0)SDL::Surface#drawCircle(x,y,r,color,fill=false,aa=false,alpha=0)Draws a circle. (x,y) is center, r is radius and color is drawing color. If fill is true, draws a filled circle. If aa is true, draws an antialiased circle. If alpha is integer, draws a blended circle.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
NOTES
You cannot draw a filled antialiased blended circle.
See Also
SDL::Surface#draw_filled_circle(x,y,r,color)SDL::Surface#drawFilledCircle(x,y,r,color)This method is obsolete. Please use SDL.draw_circle instead.
Draws a filled circle.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_aa_circle(x,y,r,color)SDL::Surface#drawAACircle(x,y,r,color)This method is obsolete. Please use SDL.draw_circle instead.
Draws an antialiased circle.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_aa_filled_circle(x,y,r,color)SDL::Surface#drawAAFilledCircle(x,y,r,color)This method is obsolete. Please use SDL.draw_circle instead.
Draws a filled antialiased circle.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_circle_alpha(x,y,r,color,alpha)SDL::Surface#drawCircleAlpha(x,y,r,color,alpha)This method is obsolete. Please use SDL.draw_circle instead.
Draws blended circle.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_filled_circle_alpha(x,y,r,color,alpha)SDL::Surface#drawFilledCircleAlpha(x,y,r,color,alpha)This method is obsolete. Please use SDL.draw_circle instead.
Draws a filled blended circle.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_aa_circle_alpha(x,y,r,color,alpha)SDL::Surface#drawAACircleAlpha(x,y,r,color,alpha)This method is obsolete. Please use SDL.draw_circle instead.
Draws an antialiased blended circle
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_ellipse(x,y,rx,ry,color, fill=false, aa=false, alpha=nil)SDL::Surface#drawEllipse(x,y,rx,ry,color, fill=false, aa=false, alpha=nil) )Draws an ellipse. (x,y) is center, rx is x-radius, ry is y-radius and color is drawing color. If fill is true, draws a filled ellipse. If aa is true, draws an antialiased ellipse. If alpha is integer, draws a blended ellipse.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
NOTES
You cannot draw a filled antialiased blended ellipse.
See Also
SDL::Surface#draw_filled_ellipse(x,y,rx,ry,color)SDL::Surface#drawFilledEllipse(x,y,rx,ry,color)This method is obsolete. Please use SDL::Surface#draw_ellipse instead.
Draws a filled ellipse.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_aa_ellipse(x,y,rx,ry,color)SDL::Surface#drawAAEllipse(x,y,rx,ry,color)This method is obsolete. Please use SDL::Surface#draw_ellipse instead.
Draws an antialiased ellipse.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_aa_filled_ellipse(x,y,rx,ry,color)SDL::Surface#drawAAFilledEllipse(x,y,rx,ry,color)This method is obsolete. Please use SDL::Surface#draw_ellipse instead.
Draws a filled antialiased ellipse.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_ellipse_alpha(x,y,rx,ry,color,alpha)SDL::Surface#drawEllipseAlpha(x,y,rx,ry,color,alpha)This method is obsolete. Please use SDL::Surface#draw_ellipse instead.
Draws a blended ellipse.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_filled_ellipse_alpha(x,y,rx,ry,color,alpha)SDL::Surface#drawFilledEllipseAlpha(x,y,rx,ry,color,alpha)This method is obsolete. Please use SDL::Surface#draw_ellipse instead.
Draws a filled blended ellipse
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_aa_ellipse_alpha(x,y,rx,ry,color,alpha)SDL::Surface#drawAAEllipseAlpha(x,y,rx,ry,color,alpha)This method is obsolete. Please use SDL::Surface#draw_ellipse instead.
Draws an antialiased blended ellipse.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_bezier(x1,y1,x2,y2,x3,y3,x4,y4,level,color,aa=false,alpha=nil)SDL::Surface#drawBezier(x1,y1,x2,y2,x3,y3,x4,y4,level,color,aa=false,alpha=nil)Draws a bezier curve from (x1, y1) to (x4, y4) with the control points (x2, y2) and (x3, y3). level indicates how good precision the function should use, 4-7 is normal. If aa is true, draws an antialiased curve. If alpha is integer, draws blended curve.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
SDL::Surface#draw_aa_bezier(x1,y1,x2,y2,x3,y3,x4,y4,level,color)SDL::Surface#drawAABezier(x1,y1,x2,y2,x3,y3,x4,y4,level,color)This method is obsolete. Please use SDL::Surface#draw_bezier instead.
Draws an antialiased bezier curve.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_bezier_alpha(x1,y1,x2,y2,x3,y3,x4,y4,level,color,alpha)SDL::Surface#drawBezierAlpha(x1,y1,x2,y2,x3,y3,x4,y4,level,color,alpha)This method is obsolete. Please use SDL::Surface#draw_bezier instead.
Draws a blended bezier curve.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#draw_aa_bezier_alpha(x1,y1,x2,y2,x3,y3,x4,y4,level,color,alpha)SDL::Surface#drawAABezierAlpha(x1,y1,x2,y2,x3,y3,x4,y4,level,color,alpha)This method is obsolete. Please use SDL::Surface#draw_bezier instead.
Draws an antialiased blended bezier curve.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface.
You need SGE to use this method.
See Also
SDL::Surface#transform_surface(bgcolor,angle,xscale,yscale,flags)SDL::Surface#transformSurface(bgcolor,angle,xscale,yscale,flags)Returns a rotated and scaled version of self. See Surface.transform_draw for more information. bgcolor is background color that new surface have.
The new surface object will have the same depth and pixel format as self.
This method needs Locking. If SDL.auto_lock? is true, Ruby/SDL automatically locks/unlocks the surface. Raises SDL::Error on failure
You need SGE to use this method.
Ruby/SDL has the ability to create and use OpenGL contexts on several platforms(Linux/ X11, Win32, Mac OS X, etc). This allows you to use SDL's audio, event handling and times in your OpenGL applications (a function often performed by GLUT).
Ruby/SDL has no OpenGL methods, please use ruby-opengl or riko with Ruby/SDL.
Initialising Ruby/SDL to use OpenGL is not very different to initialising Ruby/SDL normally. There are three differences; you must pass SDL::OPENGL to SDL::Screen.open, you must specify several GL attributes (depth buffer size, framebuffer sizes) using SDL::GL.set_attr and finally, if you wish to use double buffering you must specify it as a GL attribute, not by passing the SDL::DOUBLEBUF flag to SDL::DOUBLEBUF.
EXAMPLE
# First, initialize SDL's video subsystem. SDL.init(SDL::INIT_VIDEO) # Let's get some video information. info = SDL::Screen.info # Set our width/height to 640/480 (you would # of course let the user decide this in a normal # app). width = 640 height = 480 # We get the bpp we will request from the display. bpp = info.bpp # Now, we want to setup our requested # window attributes for our OpenGL window. # We want *at least* 5 bits of red, green # and blue. We also want at least a 16-bit # depth buffer. # # The last thing we do is request a double # buffered window. '1' turns on double # buffering, '0' turns it off. # # Note that we do not use SDL::DOUBLEBUF in # the flags to SDL::Screen.open. That does # not affect the GL attribute state, only # the standard 2D blitting setup. SDL::GL.set_attr(SDL::GL::RED_SIZE, 5) SDL::GL.set_attr(SDL::GL::GREEN_SIZE, 5) SDL::GL.set_attr(SDL::GL::BLUE_SIZE, 5) SDL::GL.set_attr(SDL::GL::DEPTH_SIZE, 16) SDL::GL.set_attr(SDL::GL::DOUBLEBUFFER, 1) # We want to request that SDL provide us # with an OpenGL window, in a fullscreen # video mode. flags = SDL:;OPENGL | SDL::FULLSCREEN # Set the video mode SDL::Screen.open(width, height, bpp, flags)
You can use SDL::GL.get_attr and SDL::GL.set_attr with following attributes:
Apart from initialisation, using OpenGL within Ruby/SDL is the same as using OpenGL with any other API, e.g. GLUT. You still use all the same function calls and data types. However if you are using a double-buffered display, then you must use SDL::GL.swap_buffers to swap the buffers and update the display. To request double-buffering with OpenGL, use SDL::GL.set_attr with SDL::GL::DOUBLEBUFFER, and use SDL::GL.get_attr to see if you actually got it.
SDL::GL.get_attr(attr)SDL::GL.getAttr(attr)Returns the value of the SDL/OpenGL attribute attr. This is useful after a call to SDL::Screen.open to check whether your attributes have been set as you expected.
Raises SDL::Error on failure
See Also
SDL::GL.set_attr(attr, val)SDL::GL.setAttr(attr, val)Sets the OpenGL attribute attr to value. The attributes you set don't take effect until after a call to SDL::Screen.open. You should use SDL::GL.get_attr to check the values after a SDL::Screen.open call.
Raises SDL::Error on failure
NOTES
The SDL::DOUBLEBUF flag is not required to enable double buffering when setting an OpenGL video mode. Double buffering is enabled or disabled using the SDL::GL::DOUBLEBUFFER attribute.
See Also
SDL::GL.swap_buffers()SDL::GL.swapBuffers()See Also
SDL provides a small set of window management functions which allow applications to change their title and toggle from windowed mode to fullscreen (if available)
SDL::WM.captionSee Also
SDL::WM.set_caption(title, icon)SDL::WM.setCaption(title, icon)NOTES
title and icon must be UTF8 or ASCII string.
If Ruby/SDL m17n support is enabled, title and icon are converted to UTF8 automatically.
See Also
SDL::WM.icon=(icon_image)Sets the icon for the display window. Win32 icons must be 32x32.
This function must be called before the first call to SDL::Screen.open. icon_image should be an instance of SDL::Surface
EXAMPLE
SDL::WM.icon = SDL::Surface.load_bmp("icon.bmp")
See Also
SDL::WM.iconifyIf the application is running in a window managed environment SDL attempts to iconify/minimise it. If this method is successful, the application will receive a SDL::Event::APPACTIVE loss event.
Raises SDL::Error on failure
SDL::WM.grab_input(mode)SDL::WM.grabInput(mode)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.
You can use following three constants as mode.
When mode is SDL::WM::GRAB_QUERY, the grab mode is not changed, but the current grab mode is returned.
Returns the current/new mode.
Event handling allows your application to receive input from the user. Event handling is initalised (along with video) with a call to:
SDL_Init(SDL_INIT_VIDEO);
Internally, SDL stores all the events waiting to be handled in an event queue. Using functions like SDL::Event.poll and SDL::Event.wait you can observe and handle waiting input events.
The key to event handling in SDL is the subclasses of SDL::Event. The event queue itself is composed of a series of instance of (subclasses of) SDL::Event, one for each waiting event. Those objects are read from queue with the SDL::Event.poll and it is then up to the application to process the information stored with them.
Subclasses of SDL::Event is following:
Those classes have two uses.
Reading events from the event queue is done with SDL::Event.poll. We'll use SDL::Event.poll and step through an example. SDL::Event.poll removes the next event from the event queue, if there are no events on the queue it returns nil otherwise it returns event object. We use a while loop to process each event in turn.
while event = SDL::Event.poll
We know that if SDL::Event.poll removes an event from the queue then the event information will be placed in returned object, but we also know that the class of that object will represent the type of event. So we handle each event type seperately we use a switch statement.
case event
We need to know what kind of events we're looking for and the event type's of those events. So lets assume we want to detect where the user is moving the mouse pointer within our application. We look through our event types and notice that SDL::Event::MouseMotion is, more than likely, the event we're looking for. A little more research tells use that mouse motion events are handled within the SDL::Event::MouseMotion. We can check for the mouse motion event type within our switch statement like so:
when SDL::Event::MouseMotion
All we need do now is read the information out of this object as instance of SDL::Event::MouseMotion.
puts "We got a motion event"
puts "Current mouse position is: (#{event.x}, #{event.y})"
else puts "Unhandled Event!" end end puts "Event queue is empty."
It is also possible to push events onto the event queue. [Event.push] allows you to place events onto the event queue. You can use it to post fake input events if you wished.
This class handle events. All objects returned by SDL::Event.poll are instances of subclasses of SDL::Event.
The class that used to be known as SDL::Event is remove. The class now called SDL::Event was called SDL::Event2 before. A constant SDL::Event2 remains as alias of SDL::Event because of compatiblity with older version.
Class for Application visibility event.
This event raises when the mouse leaves or enters the window area, the application loses or gains keyboard focus, or the application is either minimised/iconified or restored.
SDL::Event::Active#state returns which event occurs.
NOTES
This event does not occur when an application window is first created.
Class for keyboard down event.
Class for key up event.
Class for mouse motion event.
Simply put, a event of this type occurs when a user moves the mouse within the application window or when [Mouse.warp] is called. Both the absolute coordinate (SDL::Event::MouseMotion#x and SDL::Event::MouseMotion#y) and relative coordinate (SDL::Event::MouseMotion#xrel and SDL::Event::MouseMotion#yrel) are reported along with the current button states (SDL::Event::MouseMotion#state).
Class for mouse button press event.
This type of event occurs when a mouse button press is detected.
Class for mouse button release event.
This type of event occurs when a mouse button release is detected.
Class for joystick axis motion event.
This event occurs when ever a user moves an axis on the joystick.
Class for joystick ball motion event.
This type of event occurs when a user moves a trackball on the joystick.
SEEALSO
Class for joystick hat position change event.
SEEALSO
Class for joystick button press event.
This event occurs when a user presses a button on a joystick.
SEEALSO
Class for joystick button release event.
This event occurs when a user releases a button on a joystick.
SEEALSO
Class for quit reqested event.
This event is very important. If you filter out or ignore a quit event then it is impossible for the user to close the window. On the other hand, if you do accept a quit event then the application window will be closed, and screen updates will still report success event though the application will no longer be visible.
Class for platform-dependent window manager event.
Event of this type occurs when unknown window manager event happens. You can never know the detail of this event. Only you can to do is to ignore this event.
Class for window resize event.
When SDL::RESIZABLE is passed as a flag to SDL::Screen.open the user is allowed to resize the applications window. When the window is resized an event of this type is report, with the new window width and height values stored in SDL::Event::VideoResize#w and
((<SDL::Event::VideoResize#h>)) respectively.
When this event is recieved the window should be resized to the new dimensions using SDL::Screen.open.
Class for video expose event.
This event is triggered when the screen has been modified outside of the application, usually by the window manager and needs to be redrawn.
Module for keyboard input.
This module defines some keyboard-related constants and module functions.
Key symbol constants definitions.
Module for mouse input.
This module defines some mouse constants and module functions.
SDL::Event.pollPolls for currently pending events, and returns event object if there are any pending events, or nil if there are none available.
If event object is returned, the next event is removed from the queue and stored in that area.
EXAMPLE
while event = SDL::Event.poll # Loop until there are no events left on the queue
case event # Process the appropiate event type
when SDL::Event::KeyDown # Handle a KEYDOWN event
puts "Oh! Key press"
when SDL::Event::MouseMotion
.
.
.
else # Report an unhandled event
puts "I don't know what this event is!"
end
end
See Also
SDL::Event.waitWaits indefinitely for the next available event and return that event.
If event object is returned, the next event is removed from the queue and stored in that area.
Raise SDL::Error if there was an error while waiting for events.
NOTES
In Ruby 1.9 and above, this method releases the global VM lock (GVL) prior to calling the underlying SDL_WaitEvent function. This allows other Ruby threads to continue executing while waiting for an event.
In Ruby 1.8 and below, there is no way to release the GVL, so all Ruby threads suspend execution until this method finishes.
This method may return nil when Ruby/SDL encounters an unknown type of event. You should treat this case.
See Also
SDL::Event.push(event)Push event onto event queue.
Raises SDL::Error on failure
NOTES
Pushing device input events onto the queue doesn't modify the state of the device within SDL.
See Also
SDL::Event.app_stateSDL::Event.appStateSee Also
SDL::Event.enable_unicodeSDL::Event.enableUNICODENOTES
Note that only key press events will be translated, not release events.
See Also
SDL::Event.disable_unicodeSDL::Event.disableUNICODESDL::Event.enable_unicode?SDL::Event.enableUNICODE?SDL::Event::Active#gainSee Also
SDL::Event::Active#stateSDL::Event::APPMOUSEFOCUS
This event occurs when the mouse leaves or enters the window area.
SDL::Event::APPINPUTFOCUS
THis event occurs when the application loses or gains input focus.
SDL::Event::APPACTIVE
This event occurs when the application is either minimized/iconcified or restored.
See Also
SDL::Event::KeyDown#pressSee Also
SDL::Event::KeyDown#symSee Also
SDL::Event::KeyDown#modSee Also
SDL::Event::KeyDown#unicodeReturns the UNICODE character corresponding to the keypress if Unicode translation is enabled with SDL::Event.enable_unicode. If the high 9 bits of the character are 0, then this maps to the equivalent ASCII character:
Returns zero if unicode translation is disabled.
SDL::Event::KeyUp#pressSee Also
SDL::Event::KeyUp#symSDL::Event::KeyUp#modSee Also
SDL::Event::MouseMotion#stateSee Also
SDL::Event::MouseMotion#xSee Also
SDL::Event::MouseMotion#ySee Also
SDL::Event::MouseMotion#xrelSDL::Event::MouseMotion#yrelSDL::Event::MouseButtonDown#buttonSDL::Event::MouseButtonDown#pressSee Also
SDL::Event::MouseButtonDown#xSee Also
SDL::Event::MouseButtonDown#ySee Also
SDL::Event::MouseButtonUp#buttonSDL::Event::MouseButtonUp#pressSee Also
SDL::Event::MouseButtonUp#xSee Also
SDL::Event::MouseButtonUp#ySee Also
SDL::Event::JoyAxis#whichSee Also
SDL::Event::JoyAxis#axisSee Also
SDL::Event::JoyAxis#valueSee Also
SDL::Event::JoyBall#whichSee Also
SDL::Event::JoyBall#ballSee Also
SDL::Event::JoyBall#xrelSee Also
SDL::Event::JoyBall#yrelSee Also
SDL::Event::JoyHat#whichSee Also
SDL::Event::JoyHat#hatSee Also
SDL::Event::JoyHat#valueReturns the current position of the hat. It is a logically OR'd combination of the following values (whose meanings should be pretty obvious:) :
The following defines are also provided:
SDL::Event::JoyButtonDown#whichSee Also
SDL::Event::JoyButtonDown#buttonSee Also
SDL::Event::JoyButtonDown#pressSDL::Event::JoyButtonUp#whichSee Also
SDL::Event::JoyButtonUp#buttonSee Also
SDL::Event::JoyButtonUp#pressSDL::Event::VideoResize#wSDL::Event::VideoResize#hSDL::Key.scanGets a snapshot of the current keyboard state. You can check this state with SDL::Key.press?.
NOTE Call SDL::Event.poll or SDL::Event.wait to update the state.
SDL::Key.press?(key)See Also
SDL::Key.mod_stateSDL::Key.modStateReturns the current state of the modifier keys (CTRL, ALT, etc.). The return value can be an OR'd combination of:
SDL also defines the following symbols for convenience:
See Also
SDL::Key.get_key_name(key)SDL::Key.getKeyName(key)SDL::Key.enable_key_repeat(delay,interval)SDL::Key.enableKeyRepeat(delay,interval)Enables the keyboard repeat rate. delay specifies how long the key must be pressed before it begins repeating, it then repeats at the speed specified by interval. Both delay and interval are expressed in milliseconds.
Good default values are SDL::Key::DEFAULT_REPEAT_DELAY and SDL::Key::DEFAULT_REPEAT_INTERVAL.
Raises SDL::Error on failure
See Also
SDL::Key.disable_key_repeatSDL::Key.disableKeyRepeatDisables key repeat.
Raises SDL::Error on failure
See Also
SDL::Mouse.stateReturns an array of five element:
[ X coordinate, Y coordinate, left button is pressed?, middle button is pressed?, right button is pressed?]
EXAMPLE
x, y, lbutton, * = SDL::Mouse.state if lbutton print "Left Mouse Button is pressed \n" end
SDL::Mouse.warp(x,y)See Also
SDL::Mouse.showShows cursor.
The cursor starts off displayed, but can be turned off.
See Also
SDL::Mouse.hideSee Also
SDL::Mouse.show?See Also
SDL::Mouse.set_cursor(bitmap,white,black,transparent,inverted,hot_x=0,hot_y=0)SDL::Mouse.setCursor(bitmap,white,black,transparent,inverted,hot_x=0,hot_y=0)Sets the currently active cursor to the specified one. If the cursor is currently visible, the change will be immediately represented on the display.
bitmap is shape of cursor, given by the instance of SDL::Surface. white is white color pixel value in bitmap, black is black color pixel value in bitmap, transparent is transparent pixel value in bitmap, inverted is inverted pixel value in bitmap. The cursor width must be a multiple of 8 bits.
See Also
Joysticks, and other similar input devices, have a very strong role in game playing and SDL provides comprehensive support for them. Axes, Buttons, POV Hats and trackballs are all supported.
Joystick support is initialized by passed the SDL::INIT_JOYSTICK flag to SDL.init. Once initilized joysticks must be opened using SDL::Joystick.open.
While using the functions describe in this secton may seem like the best way to access and read from joysticks, in most cases they aren't. Ideally joysticks should be read using the SDL::Event system. To enable this, you must set the joystick event processing state with SDL::Joystick.poll=. Joysticks must be opened before they can be used of course.
NOTES
If you are not handling the joystick via the event queue then you must explicitly request a joystick update by calling SDL::Joystick.update_all.
Force Feedback is not yet support.
The class represents one joystick.
SDL::Joystick.numSee Also
SDL::Joystick.index_name(index)SDL::Joystick.indexName(index)Get the implementation dependent name of joystick. The index parameter refers to the N'th joystick on the system.
EXAMPLE
# Print the names of all attached joysticks
num_joy = SDL::Joystick.num
printf("%d joysticks found\n", num_joy)
num_joy.times do |i|
puts SDL::Joystick.index_name(i)
end
See Also
SDL::Joystick.open(index)Opens a joystick for use within SDL. The index refers to the N'th joystick in the system. A joystick must be opened before it can be used.
Returns a SDL::Joystick instance on success.
Raises SDL::Error on failure
EXAMPLE
# Check for joystick
if SDL::Joystick.num > 0
# Open joystick
joy = SDL::Joystick.open(0)
printf("Opened Joystick 0\n");
printf("Name: %s\n", SDL::Joystick.name(0))
printf("Number of Axes: %d\n", joy.num_axes)
printf("Number of Buttons: %d\n", joy.num_buttons)
printf("Number of Balls: %d\n", joy.num_balls)
end SDL::Joystick.open?(index)Determines whether a joystick has already been opened within the application. index refers to the N'th joystick on the system.
Returns true if the joystick has been opened, or false if it has not.
See Also
SDL::Joystick#indexSDL::Joystick#num_axesSDL::Joystick#numAxesNOTES
This method counts two dimensional axes as two axes.
See Also
SDL::Joystick#num_ballsSDL::Joystick#numBallsSee Also
SDL::Joystick#num_hatsSDL::Joystick#numHatsSee Also
SDL::Joystick#num_buttonsSDL::Joystick#numButtonsSee Also
SDL::Joystick.poll=(enable)This function is used to enable or disable joystick event processing. With joystick event processing disabled you will have to update joystick states with SDL::Joystick.update_all and read the joystick information manually.
Joystick event polling is enabled by default.
NOTE Joystick event handling is preferred.
Even if joystick event processing is enabled, individual joysticks must be opened before they generate events.
Calling this method may delete all events currently in SDL's event queue.
See Also
SDL::Joystick.update_all, SDL::Joystick.poll, SDL::Event2::JoyAxis, SDL::Event2::JoyBall, SDL::Event2::JoyButtonDown, SDL::Event2::JoyButtonUp, SDL::Event2::JoyHat
SDL::Joystick.pollSDL::Joystick.update_allSDL::Joystick.updateAllSDL::Joystick#axis(axis_index)Returns the current state of given axis_index on self.
On most modern joysticks the X axis is usually represented by axis 0 and the Y axis by axis 1. The value returned by this method is a signed integer (-32768 to 32767) representing the current position of the axis, it may be necessary to impose certain tolerances on these values to account for jitter.
EXAMPLE
joy = SDL::Joystick.open(0) . . x_move = joy.axis(0) y_move = joy.axis(1)
See Also
SDL::Joystick#hat(hat_index)Returns the current state of the given hat_index.
The current state is returned as a unsinged integer which is an OR'd combination of one or more of the following
See Also
SDL::Joystick#button(button_index)See Also
SDL::Joystick#ball(ball_index)Get the ball axis change. Trackballs can only return relative motion since the last call to this method, these motion deltas are returned as an array of two elements, [dx, dy].
Raises SDL::Error on failure
EXAMPLE
delta_x, delta_y = joy.ball(0)
printf("Trackball Delta- X:%d, Y:%d\n", delta_x, delta_y)SDL::Joystick#closeSee Also
SDL supports audio control of up to 32 local CD-ROM drives at once.
You use this API to perform all the basic functions of a CD player, including listing the tracks, playing, stopping, and ejecting the CD-ROM. (Currently, multi-changer CD drives are not supported.)
Before you call any of the SDL CD-ROM functions, you must first call SDL.init(SDL::INIT_CDROM), which scans the system for CD-ROM drives, and sets the program up for audio control.
After you have initialized the library, you can find out how many drives are available using the SDL::CD.num_drives. The first drive listed is the system default CD-ROM drive. After you have chosen a drive, and have opened it with SDL::CD.open, you can check the status and start playing if there's a CD in the drive.
A CD-ROM is organized into one or more tracks, each consisting of a certain number of "frames". Each frame is ~2K in size, and at normal playing speed, a CD plays 75(SDL::CD::FPS) frames per second. SDL works with the number of frames on a CD, but this can easily be converted to the more familiar minutes/seconds format by using SDL::CD.frames_to_msf.
This class represents opened CDROM device and stores information on the layout of the tracks on the disc.
SDL::CD.num_drivesSDL::CD.numDrivesSee Also
SDL::CD.index_name(drive)SDL::CD.indexName(drive)Returns a human-readable, system-dependent identifier for the CD-ROM. drive is the index of the drive. Drive indices start to 0 and end at SDL::CD.num_drives-1.
Examples of return strings.
See Also
SDL::CD.open(drive)Opens a CD-ROM drive for access. It returns SDL::CD object on success.
Drives are numbered starting with 0. Drive 0 is the system default CD-ROM.
Raise SDL::Error if the drive was invalid or busy.
EXAMPLE
SDL.init SDL::INIT_CDROM # Check for CD drives if SDL::CD.num_drives == 0 # None found STDERR.print "No CDROM devices available\n" exit 255 end begin # Open the default drive cdrom = SDL::CD.open(0) rescue SDL::Error STDERR.puts "Couldn't open drive" exit 255 end # Print volume info printf "Name: %s\n", SDL::CD.index_name(0) printf "Tracks: %d\n", cdrom.num_tracks num_tracks.times do |cur_track| min, sec, frame = SDL::CD.frames_to_msf(cdrom.track_length(cur_track)) printf "\tTrack %d: Length %d:%d\n", cur_track, min, sec end
SDL::CD#statusThis method returns the current status of the given drive. Status is described like so:
If the drive has a CD in it, SDL.current_track, SDL.current_frame, SDL.num_tracks, SDL.track_type, and SDL.track_length are updated.
EXAMPLE
def play_track(track) raise "not cd in drive" unless $cdrom.in_drive? # clamp to the actual number of tracks on the CD track = $cdrom.num_tracks-1 if track >= $cdrom.num_tracks $cdrom.play_tracks(track, 0, 1, 0) end
SDL::CD#play(start, length)Plays the given cdrom, starting a frame start for length frames.
Raises SDL::Error on failure
See Also
SDL::CD#play_tracks(start_track, start_frame, ntracks, nframes)This method plays the given CD starting at track start_track, for ntracks tracks.
start_frame is the frame offset, from the beginning of the start_track, at which to start. $nframes] is the frame offset, from the beginning of the last track (start_track+ntracks), at which to end playing.
THis methods should only be called after calling SDL::CD#status to get track information about the CD.
Raises SDL::Error on failure
EXAMPLE
# assuming cdrom is a previously opened device # Play the entire CD if cdrom.in_drive? cdrom.play_tracks 0, 0, 0, 0 end # Play the first track if cdrom.in_drive? cdrom.play_tracks 0, 0, 1, 0 end # 2 Play first 15 seconds of the 2nd track if cdrom.in_drive? cdrom.play_tracks 1, 0, 0, SDL::CD::FPS*15 end
NOTES
Data tracks are ignored.
See Also
SDL::CD#pausePauses play on the given cdrom.
Raises SDL::Error on failure
See Also
SDL::CD#resumeResumes play on the given cdrom.
Raises SDL::Error on failure
See Also
SDL::CD#stopStops play on the given cdrom.
Raises SDL::Error on failure
See Also
SDL::CD#ejectEjects the given cdrom.
Raises SDL::Error on failure
SDL::CD#num_tracksSDL::CD#numTracksSee Also
SDL::CD#current_trackSDL::CD#currentTrackSee Also
SDL::CD#current_frameSDL::CD#currentFrameSee Also
SDL::CD#track_type(track)SDL::CD#trackType(track)SDL::CD#track_length(track)SDL::CD#trackLength(track)SDL::CD#in_drive?See Also
SDL::CD.frames_to_msf(frames)SDL::CD.framesToMSF(frames)See Also
SDL::CD.msf_to_frames(min, sec, frames)SDL::CD.MSFToFrames(min, sec, frames)See Also
SDL::CD#closeSee Also
SDL::CD#closed?See Also
SDL has portable and low-level audio playback system. Because this system is too low-level to use from Ruby, you can use only SDL_mixer functions from Ruby. So you should install SDL_mixer before using audio playback.
Due to popular demand, here is a simple multi-channel audio mixer. It supports 8 channels of 16 bit stereo audio, plus a single channel of music, mixed by the popular MikMod MOD, Timidity MIDI and SMPEG MP3 libraries.
The process of mixing MIDI files to wave output is very CPU intensive, so if playing regular WAVE files sound great, but playing MIDI files sound choppy, try using 8-bit audio, mono audio, or lower frequencies.
To play MIDI files, you'll need to get a complete set of GUS patches from: Timidity GUS Patches and unpack them in /usr/local/lib under UNIX, and C:\ under Win32.
Ruby/SDL supports playing music and sound samples from the following formats: - WAVE/RIFF (.wav) - AIFF (.aiff) - VOC (.voc) - MOD (.mod .xm .s3m .669 .it .med and more) using included mikmod - MIDI (.mid) using timidity or native midi hardware - OggVorbis (.ogg) requiring ogg/vorbis libraries on system - MP3 (.mp3) requiring SMPEG library on system
Some reports from Windows users say that programs playing MP3 sometimes hung up, so please don't play MP3 on Ruby/SDL.
Module for audio playback subsystem.
Class for sound samples. Ruby/SDL can play those samples with multi-channel. Support formats are WAVE, AIFF, RIFF, OGG, VOC.
Class for audio data. Suppor formats are WAVE, MOD, MIDI, OGG, MP3.
SDL::Mixer.open(frequency=Mixer::DEFAULT_FREQUENCY,format=Mixer::DEFAULT_FORMAT,cannels=Mixer::DEFAULT_CHANNELS,chunksize=4096)Initialize the mixer API. This must be called before using other functions in this library. SDL must be initialized with SDL::INIT_AUDIO before this call. frequency
would be 44100 for 44.1KHz, which is CD audio rate. Most games use 22050,
because 44100 requires too much CPU power on older computers. chunksize is the size of each mixed sample. The smaller this is the more your hooks will be called. If make this too small on a slow system, sound may skip. If made to large, sound effects will lag behind the action more. You want a happy medium for your target computer. You also may make this 4096, or larger, if you are just playing music. SDL::Mixer::CHANNELS(8)
mixing channels will be allocated by default.
format are the values listed there:
SDL::DEFAULT_FORMAT is SDL::Mixer::FORMAT_S16SYS.
channels is number of sound channels in output. Set to 2 for stereo, 1 for mono. This has nothing to do with mixing channels. Mixer::DEFAULT_CHANNELS is 2.
Raises SDL::Error on failure
EXAMPLE
# start SDL with audio support SDL.init(SDL::INIT_AUDIO) # 44.1KHz, signed 16bit, system byte order, stereo audio # using 1024 byte chunksize SDL::Mixer.open(44100, SDL::Mixer::DEFAULT_FORMAT, 2, 1024)
NOTES
If you observe sound skipping and delaying, you may change some parameters to resolve such problems. Please try to change frequency, chunksize and format parameter.
See Also
SDL::Mixer.specReturns the actual audio format in use by the opened audio device. This may or may not match the parameters you passed to SDL::Mixer.open. Return value is array of three elements: [frequency, format, channels].
Raises SDL::Error on failure
EXAMPLE
frequency, format, channels = SDL::Mixer.spec format_str = case format when SDL::Mixer::AUDIO_U8 then "U8" when SDL::Mixer::AUDIO_S8 then "S8" when SDL::Mixer::AUDIO_U16LSB then "U16LSB" when SDL::Mixer::AUDIO_S16LSB then "S16LSB" when SDL::Mixer::AUDIO_U16MSB then "U16MSB" when SDL::Mixer::AUDIO_S16MSB then "S16MSB" end printf "frequency=%dHz format=%s channels=%d", frequency, format_str, channels
See Also
SDL::Mixer.driver_nameSDL::Mixer.driverNameReturns the opened audio device name as String.
Raises Error] if audio playback system is not @[opened yet.
See Also
SDL::Mixer::Wave.load(filename)Load file for use as a sample and returns the instance of SDL::Mixer::Wave. filename is name of wave file to use. This can load WAVE, AIFF, RIFF, OGG, and VOC files.
Raises SDL::Error on failure
NOTES
You must call SDL::Mixer.open before calling this method. It must know the output characteristics so it can convert the sample for playback, it does this conversion at load time. Therefore you should pay attention to memory consumption.
SDL::Mixer::Wave.load_from_io(io)SDL::Mixer::Wave.loadFromIO(io)Read from Ruby's IO object (IO, StringIO or other objects with read, tell, rewind) and returns the instance of SDL::Mixer::Wave. This can read WAVE, AIFF, RIFF, OGG, and VOC files.
Raises SDL::Error on failure
NOTES
You must call SDL::Mixer.open before calling this method. It must know the output characteristics so it can convert the sample for playback, it does this conversion at load time. Therefore you should pay attention to memory consumption.
SDL::Mixer::Wave#destroySee Also
SDL::Mixer::Wave#destroyed?See Also
SDL::Mixer::Music.load(filename)Load music file to use and returns a instance of SDL::Mixer::Music. filename is a name of music file to use. This can load WAVE, MOD, MIDI, OGG, MP3, and any file that you use a command to play with.
Raises SDL::Error on failure
NOTES
Need SMPEG library to load MP3.
SDL::Mixer::Music.load_from_string(str)SDL::Mixer::Music.loadFromString(str)Convert str string into music data and returns a instance of SDL::Mixer::Music. This can load WAVE, MOD and OGG.
Raises SDL::Error on failure
NOTES
In this method, copy str and store it in returned object. Therefore this method may cause the large memory consumption.
On Windows, it may be impossible to use this method.
SDL::Mixer::Music#destroySDL::Mixer::Music#destroyed?SDL::Mixer::Wave#set_volume(volume)SDL::Mixer::Wave#setVolume(volume)SDL::Mixer.allocate_channels(num_channels)SDL::Mixer.allocateChannels(num_channels)Set the number of channels being mixed. This can be called multiple times, even with sounds playing. If numchans is less than the current number of channels, then the higher channels will be stopped, freed, and therefore not mixed any longer. It's probably not a good idea to change the size 1000 times a second though.
Returns the number of channels allocated.
EXAMPLE
# allocate 16 mixing channels SDL::Mixer.allocate_channels(16)
NOTES
passing in zero will free all mixing channels, however music will still play.
SDL::Mixer.set_volume(channel, volume)SDL::Mixer.setVolume(channel, volume)Set the volume for any allocated channel. If channel is -1 then all channels at are set at once. The volume is applied during the final mix, along with the sample volume. So setting this volume to 64 will halve the output of all samples played on the specified channel. All channels default to a volume of 128, which is the max. Newly allocated channels will have the max volume set, so setting all channels volumes does not affect subsequent channel allocations.
Returns current volume of the channel. If channel is -1, the average volume is returned.
SDL::Mixer.play_channel(channel, wave, loops)SDL::Mixer.playChannel(channel, wave, loops)Play wave(instance of SDL::Mixer::Wave on channel, or if channel is -1, pick the first free unreserved channel. The sample will play for loops+1 number of times, unless stopped by halt, or fade out, or setting a new expiration time of less time than it would have originally taken to play the loops, or closing the mixer. if loops is -1, loops infinitely.
the channel the sample is played on.
EXAMPLE
# play sample on first free unreserved channel # play it exactly once through SDL::Mixer.play_channel(-1, sample, 0)
SDL::Mixer.play_channel_timed(channel, wave, loops, ticks)SDL::Mixer.playChannelTimed(channel, wave, loops, ticks)If the wave is long enough and has enough loops then the sample will stop after ticks milliseconds. Otherwise this function is the same as SDL::Mixer.play_channel.
EXAMPLE
# play sample on first free unreserved channel # play it for half a second SDL::Mixer.play_channel(-1, sample, -1, 500)
SDL::Mixer.fade_in_channel(channel, wave, loops, ms)SDL::Mixer.fadeInChannel(channel, wave, loops, ms)Play wave on channel with fade in. The channel volume starts at 0 and fades up to full volume over ms milliseconds of time. The sample may end before the fade-in is complete if it is too short or doesn't have enough loops.
Otherwise this function is the same as SDL::Mixer.play_channel.
EXAMPLE
# play sample on first free unreserved channel # play it exactly 3 times through # fade in over one second SDL::Mixer.fade_in_channel(-1, sample, 2, 1000)
SDL::Mixer.fade_in_channel_timed(channel, wave, loops, ms, ticks)SDL::Mixer.fadeInChannelTimed(channel, wave, loops, ms, ticks)SDL::Mixer.pause(channel)Pause channel, or all playing channels if -1 is passed in. You may still halt|Mixer.halt a paused channel.
EXAMPLE
# pause all sample playback SDL::Mixer.pause(-1)
See Also
SDL::Mixer.resume(channel)See Also
SDL::Mixer.halt(channel)See Also
SDL::Mixer.expire(channel, ticks)Halt channel playback, or all channels if -1 is passed in, after ticks milliseconds.
Returns the number of channels set to expire. Whether or not they are active.
EXAMPLE
# halt playback on all channels in 2 seconds SDL::Mixer.expire(-1, 2000)
See Also
SDL::Mixer.fade_out(channel, ms)SDL::Mixer.fadeOut(channel, ms)Gradually fade out which channel
over ((|ms|)) milliseconds starting
from now. The channel will be halted after the fade out is completed. Only channels that are playing are set to fade out, including paused channels.
Returns the number of channels set to fade out.
EXAMPLE
# fade out all channels to finish 3 seconds from now printf "starting fade out of %d channels", SDL::Mixer.fade_out(-1, 3000)
SDL::Mixer.play?(channel)SDL::Mixer.playing_channelsSDL::Mixer.playingChannelsSDL::Mixer.pause?(channel)See Also
SDL::Mixer.fading(which)See Also
SDL::Mixer.play?, SDL::Mixer.pause?, SDL::Mixer.fade_in_channel, SDL::Mixer.fade_in_channel_timed, SDL::Mixer.fade_out
SDL::Mixer.play_music(music, loops)SDL::Mixer.playMusic(music, loops)Play the loaded music loops times through from start to finish. The previous music will be halted, or if fading out it waits (blocking) for that to finish.
Raises SDL::Error on failure
See Also
SDL::Mixer.fade_in_music
SDL.fade_in_music(music, loops, ms)SDL.fadeInMusic(music, loops, ms)Fade in over ms milliseconds of time, the loaded music, playing it loops times through from start to finish. The fade in effect only applies to the first loop. Any previous music will be halted, or if it is fading out it will wait (blocking) for the fade to complete.
Raises SDL::Error on failure
See Also
SDL::Mixer.set_volume_music(volume)SDL::Mixer.setVolumeMusic(volume)See Also
SDL::Mixer.fade_in_music, SDL::Mixer.fade_out_music
SDL::Mixer.pause_musicSDL::Mixer.pauseMusicSDL::Mixer.resume_musicSDL::Mixer.resumeMusicSDL::Mixer.rewind_musicSDL::Mixer.rewindMusicRewind the music to the start. This is safe to use on halted, paused, and already playing music. It is not useful to rewind the music immediately after starting playback, because it starts at the beginning by default.
This function only works for these streams: MOD, OGG, MP3, Native MIDI.
SDL::Mixer.halt_musicSDL::Mixer.haltMusicSee Also
SDL::Mixer.fade_out_music(ms)SDL::Mixer.fadeOutMusic(ms)SDL::Mixer.play_music?SDL::Mixer.playMusic?SDL::Mixer.pause_music?SDL::Mixer.pauseMusic?SDL::Mixer.fading_musicSDL::Mixer.fadingMusicTells you if music is fading in, out, or not at all. Does not tell you if the channel is playing anything, or paused, so you'd need to test that separately.
return value is one of follwoing:
See Also
SDL::Mixer.fading, SDL::Mixer.pause_music?, SDL::Mixer.play_music?, SDL::Mixer.fade_out_music
SDL provides several cross-platform functions for dealing with time. It provides a way to get the current time and a way to wait a little while.
SDL.get_ticksSDL.getTicksSee Also
SDL.delay(ms)NOTES
Count on a delay granularity of at least 10 ms. Some platforms have shorter clock ticks but this is the most common.
Ruby's threads cannot preempt while waiting with this method. You should use Kernel#sleep instead.
Ruby/SDL has three different font drawing system. First is True Type Font drawing by SDL_ttf, second is original bitmap font/SFont drawing by SGE, and the last is bdf font drawing by SDL_kanji.
Each system has following features.
SDL::TTF
Extension name of Font file name is ttf and ttc. True type font has vector data, therefore you can use arbitrary font size.
SDL::BMFont
Font files are mere Windows BMP files or PNG image files. In original font file format, image data is regarded as 256 character images ordered by ASCII. Creating your own fonts is more easy than true type fonts.
You can use SFont with this class. This format is also bitmap font, but character width is variable.
You can't use kanji and other Unicode characters.
SDL::Kanji
Font files are BDF format. BDF is a kind of bitmap font. You can mix multiple font files (for example, alphabet and kanji).
This class represents true type font. SDL_ttf is needed to use this class. Backend of SDL_ttf is Freetype.
Note that you should pay attention to font license.
This class represets bitmap font. SGE is needed.
This class represets bdf font.
SDL::TTF.initInitialize the truetype font API. This must be called before using other methods of this class, excepting SDL::TTF.init?. SDL.init does not have to be called before this call.
You need SDL_ttf to use this method.
See Also
SDL::TTF.init?Returns true if TTF API is already initialize, otherwise returns false.
You need SDL_ttf to use this method.
See Also
SDL::TTF.open(filename, ptsize, index=0)Load filename, face index, for use as a font, at ptsize size.
Returns new SDL::TTF object.
Raises SDL::Error on failure
You need SDL_ttf to use this method.
EXAMPLE
SDL::TTF.init
font = SDL::TTF.open("font.ttf", 32, 0)SDL::TTF#closeCloses a font and free related resources.
You need SDL_ttf to use this method.
See Also
SDL::TTF#closed?Returns whether a font is closed by SDL::TTF#close
You need SDL_ttf to use this method.
See Also
SDL::TTF#styleReturns the rendering style as a bitmask composed of the follwing masks:
If no style is set then SDL::TTF::STYLE_NORMAL is returned.
You need SDL_ttf to use this method.
EXAMPLE
print "The font style is:" print " normal" if font.style == SDL::TTF::STYLE_NORMAL print " bold" if (font.style & SDL::TTF::STYLE_BOLD) != 0 print " italic" if (font.style & SDL::TTF::STYLE_ITALIC) != 0 print " italic" if (font.style & SDL::TTF::STYLE_UNDERLINE) != 0 print "\n"
See Also
SDL::TTF#style=(new_style)Set the rendering style as new_style. new_style should be a bitmask composed of the follwing masks:
or SDL::TTF::STYLE_NORMAL to reset style.
You need SDL_ttf to use this method.
EXAMPLE
# set the loaded font's style to fake bold italics font.style = SDL::TTF::STYLE_ITALIC | SDL::TTF::STYLE_BOLD # render some text in fake bold italics... # set the loaded font's style back to normal font.style = SDL::TTF::STYLE_NORMAL
NOTES
This will flush the internal cache of previously rendered glyphs, even if there is no change in style, so it may be best to check the current style using SDL::TTF.style first.
See Also
SDL::TTF#heightReturns the maximum pixel height of all glyphs of the font. You may use this height for rendering text as close together vertically as possible, though adding at least one pixel height to it will space it so they can't touch. Remember that Ruby/SDL and SDL_ttf doesn't handle multiline printing, so you are responsible for line spacing, see the SDL::TTF#line_skip as well.
You need SDL_ttf to use this method.
SDL::TTF#ascentGet the maximum pixel ascent (height above baseline) of all glyphs of the loaded font. This can also be interpreted as the distance from the top of the font to the baseline. It could be used when drawing an individual glyph relative to a top point, by combining it with the glyph's maxy metric to resolve the top of the rectangle used when blitting the glyph on the screen.
You need SDL_ttf to use this method.
See Also
SDL::TTF#descentGet the maximum pixel descent (height below baseline) of all glyphs of the loaded font. This can also be interpreted as the distance from the baseline to the bottom of the font. It could be used when drawing an individual glyph relative to a bottom point, by combining it with the glyph's maxy metric to resolve the top of the rectangle used when blitting the glyph on the screen.
You need SDL_ttf to use this method.
See Also
SDL::TTF#line_skipGet the reccomended pixel height of a rendered line of text of the loaded font. This is usually larger than the SDL::TTF#height of the font.
You need SDL_ttf to use this method.
See Also
SDL::TTF#facesReturns the number of faces(subfonts) in a font.
You need SDL_ttf to use this method.
SDL::TTF#fixed_width?Returns true if self font is monospaced, otherwise returns false. If font is monospaced, width of the rendered surface is (width)*(length of string).
You need SDL_ttf to use this method.
See Also
SDL::TTF#family_nameSDL::TTF#familyNameReturns current font face family name string. Returns nil if that font has no name information.
You need SDL_ttf to use this method.
SDL::TTF#style_nameSDL::TTF#styleNameReturns current font face style name string. Returns nil if the font has no name information.
You need SDL_ttf to use this method.
SDL::TTF#hintingNot doucmented
You need SDL_ttf to use this method.
See Also
SDL::TTF#hinting=Not doucmented
You need SDL_ttf to use this method.
See Also
SDL::TTF#text_size(text)SDL::TTF#textSize(text)Calculate the resulting surface size of the UTF8 encoded text rendered using font. No actual rendering is done, however correct kerning is done to get the actual width. The height returned in h is the same as you can get using SDL::TTF#height.
Returns a 2 element array as [w, h].
Raises SDL::Error on failure
You need SDL_ttf to use this method.
EXAMPLE
w, h = font.size_text("Hello World!")
puts "width=#{w} height=#{h}"
NOTES
If Ruby/SDL m17n support is enabled, text will be converted to suitable encoding.
See Also
SDL::TTF#render_solid_utf8, SDL::TTF#render_shaded_utf8, SDL::TTF#render_blended_utf8, SDL::TTF#draw_solid_utf8, SDL::TTF#draw_shaded_utf8, SDL::TTF#draw_blended_utf8
SDL::TTF#render_solid_utf8(text, r, g, b)SDL::TTF#renderSolidUTF8(text, r, g, b)This method will render the given text with the given font with (r, [g], b) color onto a new surface. The Solid mode is used and this is the fastest. This method returns new surface object.
This method create an 8-bit palettized surface and render the given text at fast quality with the given font and color. The 0 pixel value is the colorkey, giving a transparent background, and the 1 pixel value is set to the text color. The colormap is set to have the desired foreground color at index 1, this allows you to change the color without having to render the text again. Colormap index 0 is of course not drawn, since it is the colorkey, and thus transparent, though it's actual color is 255 minus each RGB component of the foreground. This is the fastest rendering speed of all the rendering modes. This results in no box around the text, but the text is not as smooth. The resulting surface should blit faster than the Blended|TTF#render_blended_utf8 one. Use this mode for FPS and other fast changing updating text displays.
You need SDL_ttf to use this method.
SDL::TTF#render_shaded_utf8(text,fg_r,fg_g,fg_b,bg_r,bg_g,bg_b)SDL::TTF#renderShadedUTF8(text,fg_r,fg_g,fg_b,bg_r,bg_g,bg_b)This method will render the given text with the given font with (fg_r, [fg_g], fg_b) color onto a new surface with background color (bg_r, [bg_g], bg_b). Returns new surface object.
This method create an 8-bit palettized surface and render the given text at high quality with the given font and colors. The 0 pixel value is background, while other pixels have varying degrees of the foreground color from the background color. This results in a box of the background color around the text in the foreground color. The text is antialiased. This will render slower than Solid, but in about the same time as SDL::TTF#render_blended_utf8. The resulting surface should blit as fast as Solid, once it is made. Use this when you need nice text, and can live with a box...
You need SDL_ttf to use this method.
SDL::TTF#render_blended_utf8(text, r, g, b)SDL::TTF#render_blended_utf8(text, r, g, b)This method will render the given text with the given font with (r, [g], b) color onto a new surface with transparent background. This is the slowest but most beautiful.
This method creates a 32-bit ARGB surface and render the given text at high quality, using alpha blending to dither the font with the given color. This results in a surface with alpha transparency, so you don't have a solid colored box around the text. The text is antialiased. This will render slower than SDL::TTF#render_solid_utf8, but in about the same time as SDL::TTF#render_shaded_utf8. The resulting surface will blit slower than if you had used SDL::TTF#render_solid_utf8 and SDL::TTF#render_shaded_utf8. Use this when you want high quality, and the text isn't changing too fast.
You need SDL_ttf to use this method.
SDL::TTF#draw_solid_utf8(dest, text, x, y, r, g, b)SDL::TTF#drawSolidUTF8(dest, text, x, y, r, g, b)This method will draw the given text with the given font with (r, [g], b) onto dest surface at (x, y) in solid mode.
You need SDL_ttf to use this method.
SDL::TTF#draw_shaded_utf8(dest, text, x, y, fg_r, fg_g, fg_b, bg_r, bg_g, bg_b)SDL::TTF#drawShadedUTF8(dest, text, x, y, fg_r, fg_g, fg_b, bg_r, bg_g, bg_b)This method will draw the given text with the given font with (fg_r, [fg_g], fg_b) color onto onto dest surface at (x, y) with background color (bg_r, [bg_g], bg_b) in shaded mode.
You need SDL_ttf to use this method.
SDL::TTF#draw_blended_utf8(dest, text, x, y, r, g, b)SDL::TTF#drawBlendedUTF8(dest, text, x, y, r, g, b)This method will draw the given text with the given font with (r, [g], b) onto dest surface at (x, y) in blended mode.
You need SDL_ttf to use this method.
SDL::BMFont.open(filename, flags)Load a bitmap font from filename file and returns new SDL::BMFont object.
flags is OR'd combination of following values:
You need SGE to use this method.
SDL::BMFont#closeCloses a font and release the resources.
You need SGE to use this method.
See Also
SDL::BMFont#closed?Returns whether a font is closed by SDL::BMFont#close.
You need SGE to use this method.
See Also
SDL::BMFont#set_color(r, g, b)SDL::BMFont#setColor(r, g, b)Changes the color of the font to (r, g, b). Doesn't work on 'color fonts' or SFonts. Use SDL::BMFont::PALETTE when opening the font if you're going to use this function often.
You need SGE to use this method.
SDL::BMFont#heightReturns height.
You need SGE to use this method.
See Also
SDL::BMFont#widthReturns the width of one character in self font. Doesn't work on SFonts.
You need SGE to use this method.
See Also
SDL::BMFont#text_size(string)SDL::BMFont#textSize(string)Returns the width and height of the string with self.
You need SGE to use this method.
See Also
SDL::BMFont#textout(surface, string, x, y)Renders the given string on surface with the given font. (x, y) is the position of the left top corner.
You need SGE to use this method.
See Also
SDL::Kanji.open(filename, size)See Also
SDL::Kanji#closeSee Also
SDL::Kanji#closed?See Also
SDL::Kanji#add(filename)See Also
SDL::Kanji#set_coding_system(sys)SDL::Kanji#setCodingSystem(sys)Set encoding. sys is one of following:
Default is SDL::Kanji::JIS.
See Also
SDL::Kanji#get_coding_systemSDL::Kanji#getCodingSystemGet encoding. A return value is one of following:
Default is SDL::Kanji::JIS.
See Also
SDL::Kanji#heightSDL::Kanji#textwidth(text)See Also
SDL::Kanji#widthSee Also
SDL::Kanji#put(surface, text, x, y, r, g, b)NOTES
If Ruby/SDL m17n support is enabled, text will be converted to suitable encoding.
See Also
SDL::Kanji#put_tate(surface, x, y, r, g, b)SDL::Kanji#putTate(surface, x, y, r, g, b)Renders text as tagetaki at (x, y) in surface with (r, g, b) color.
`Half-width' character is not rendered.
NOTES
If Ruby/SDL m17n support is enabled, text will be converted to suitable encoding.
See Also
Ruby/SDL has collision detection system derived from SGE. This enables you to pixel-pixel checking after creating binary image by SDL::Surface#make_collision_map.
Please see sample/collision.rb too.
This class represents binary image used by collision detections. You can create this instance only by SDL::Surface#make_collision_map.
SDL::Surface#make_collision_mapSDL::Surface#makeCollisionMapCreates a new collision map from SDL::Surface object. Use SDL::Surface#set_color_key before calling this method. Every non-transparent pixel is set to solid in the collision map.
Returns a new SDL::CollisionMap object.
Raises SDL::Error on failure
You need SGE to use this method.
SDL::CollisionMap#collision_check(x1, y1, cmap, x2, y2)Does pixel perfect collision detection with self and cmap. The (x1,y1) and (x2,y2) coords are the positions of the upper left corners of the images. Returns true if any solid pixels of the two images overlap or else false.
This method calls SDL::CollisionMap#bounding_box_check internally.
You need SGE to use this method.
See Also
SDL::CollisionMap.bounding_box_check(x1,y1,w1,h1,x2,y2,w2,h2)SDL::CollisionMap.boundingBoxCheck(x1,y1,w1,h1,x2,y2,w2,h2)Checks if two rectangles (x1, $y1, w1, h1) and (x2, $y2, w2, h2) overlap.
Returns true if two rectangles overlap, otherwise returns false.
You need SGE to use this method.
See Also
SDL::CollisionMap#bounding_box_check(x1, y1, cmap, x2, y2)SDL::CollisionMap#boundingBoxCheck(x1, y1, cmap, x2, y2)Checks if two rectangles (the bounding boxes, self and cmap) overlap. The (x1,y1) and (x2,y2) coords are the positions of the upper left corners of the images.
Returns true if two rectangles overlap, otherwise returns false.
You need SGE to use this method.
SDL::CollisionMap#clear(x, y, w, h)Clears an area in the collision map from anything solid.
You need SGE to use this method.
See Also
SDL::CollisionMap#set(x, y, w, h)Makes an area in the collision map solid.
You need SGE to use this method.
See Also
SDL::CollisionMap#wReturns width of collision map.
You need SGE to use this method.
See Also
SDL::CollisionMap#hReturns height of collision map.
You need SGE to use this method.
See Also
Ruby/SDL has SKK-like Japanese input system by SDLSKK.
This system enables you not only to input Japanse but also to handle line input including cut and paste.
Please see sample/sdlskk.rb.
This module has some SDLSKK-related module functions and classes.
This class represents input state.
This class represents a Kana-Kanji dictionary. Load SKK dictionary from files.
This class represents keybind.
This class represents the translation table from Romaji(Alphabet) to Kana. Load text data from a file and create new table object.
SDL::SKK.encoding=(encoding)Sets SDLSKKK internal encoding to encoding. Following constants are allowed:
Default is SDL::SKK::EUCJP.
This encoding determines the encoding of dictionary files, a romaji-kana translation table file and private dictionary.
You need SDLSKK to use this method.
NOTES
This function should call once before calling other SDLSKK methods.
See Also
SDL::SKK.encoding, SDL::SKK::Dictionary#load, SDL::SKK::Dictionary#save, SDL::SKK::RomKanaRuleTable.new
SDL::SKK.encodingReturns the SDLSKK internal encoding. Please see SDL::SKK.encoding= for more detail.
You need SDLSKK to use this method.
See Also
SDL::SKK::RomKanaRuleTable.new(filename)Load a Romaji-Kana trasnlation table from filename. File format is:
You need SDLSKK to use this method.
NOTES
Encoding of this file is set by SDL::SKK.encoding= before loading it.
See Also
SDL::SKK::Dictionary.newCreates empty dictionary object and returns it.
You need SDLSKK to use this method.
See Also
SDL::SKK::Dictionary#load(filename, user)Read a dictionary data from filename. Format of dictionary is same as of SKK (Ruby/SDL cannot read data with annotations). If user is true, loaded data is treated as user dictionary data. If user is false, loaded data is treated as system dictionary data.
Raises SDL::Error on failure
You need SDLSKK to use this method.
NOTES
Encoding of this file is set by SDL::SKK.encoding= before loading it.
See Also
SDL::SKK::Dictionary.new, SDL::SKK::Dictionary#save, SDL::SKK::Context.new
SDL::SKK::Dictionary#save(filename)Save user dictionary data into filename.
You need SDLSKK to use this method.
SDL::SKK::Keybind.newCreates empty keybind object and returns it. Add keybind to this object using SDL::SKK::Keybind#set_key and SDL::SKK::Keybind#set_default_key.
You need SDLSKK to use this method.
SDL::SKK::Keybind#set_key(key_str, cmd_str)Sets keybind. key_str is a key-symbol string. cmd_str is command string.
Following strings are allowed as key_str:
Following strings is allowed as cmd_str:
You shouldn't change the keybind of only one ascii character key like "a" and "/".
SDL::SKK::Keybind#set_default_key is useful.
You need SDLSKK to use this method.
SDL::SKK::Keybind#set_default_keyLoad default Emacs-like keybinds.
You need SDLSKK to use this method.
See Also
SDL::SKK::Keybind#unset_key(key_str)Unset keybind of key_str.
You need SDLSKK to use this method.
See Also
SDL::SKK::Context.new(dict, romkama_table, bind, use_minibuffer)Creates input context and returns new SDL::SKK::Context object. dict is a dictionary, romkama_table is a Ronaji-Kana translation table and bind is keybind. If use_minibuffer is true, SKK-like minibuffer is enabled.
You need SDLSKK to use this method.
EXAMPLE
# Create dictionary object and read data from 'jisyo' dict = SDL::SKK::Dictionary.new dict.load( 'jisyo', false ) # Read Romaji-Kana translation table from 'rule_table' table = SDL::SKK::RomKanaRuleTable.new( 'rule_table' ) # Set keybind bind = SDL::SKK::Keybind.new bind.set_default_key # Create context context = SDL::SKK::Context.new( dict, table, bind, use_minibuffer )
See Also
SDL::SKK::Context#input(event)Handles keyboard event. event should be SDL::Event object. This method handles only keydown events and ignore other events.
You need SDLSKK to use this method.
EXAMPLE
while event = SDL::Event.poll do
case event
when SDL::Event::Quit
exit
when SDL::Event::KeyDown
if event.sym == SDL::Key::ESCAPE then
exit
end
if event.sym == SDL::Key::F1
dict.save("test_user_dict")
end
context.input( event )
end
endSDL::SKK::Context#strReturns input string.
You need SDLSKK to use this method.
NOTES
If Ruby/SDL m17n support is enabled, the string with proper encoding will be returned.
See Also
SDL::SKK::Context#render_str, SDL::SKK::Context#clear, SDL::SKK::Context#clear_text, SDL::SKK.encoding
SDL::SKK::Context#render_str(font, r, g, b)Renders input string and returns SDL::Surface object.
You need SDLSKK to use this method.
SDL::SKK::Context#render_minibuffer_str(font, r, g, b)Renders minibuffer string and returns SDL::Surface object.
You need SDLSKK to use this method.
SDL::SKK::Context#clearClears input context.
You need SDLSKK to use this method.
See Also
SDL::SKK::Context#clear_textClears input text, but input mode is held.
If you want multi-line input, this method is better than SDL::SKK::Context#clear
You need SDLSKK to use this method.
See Also
SDL::SKK::Context#get_basic_modeReturns true if self's input mode is kakutei-mode, latin-mode or jisx0208-latim-mode, otherwise returns false.
You need SDLSKK to use this method.
NOTES
Please see SKK.
See Also
Ruby/SDL enables you to play MPEG movie with SMPEG.
Before calling MPEG methods, SDL.init should be called with SDL::INIT_AUDIO|SDL::INIT_VIDEO and SDL::Mixer.open should be called.
MPEG playback system runs in sub thread(native thread). Therefore you cannot read and write movie SDL::Surface while playing. In addition you cannot use SDL::Mixer routines while playing if audio is enabled. Ruby/SDL doesn't control such an invalid access.
This class represents MPEG stream and playing state.
This class represents SDL::MPEG information. You can get instance by SDL::MPEG#info.
SDL::MPEG.new(filename)SDL::MPEG.load(filename)Loads a filename and returns new SDL::MPEG object.
Raises SDL::Error on failure
You need SMPEG to use this method.
See Also
SDL::MPEG#infoGets information about self as SDL::MPEG::Info object.
You need SMPEG to use this method.
See Also
SDL::MPEG#enable_audio(enable)SDL::MPEG#enableAudio(enable)Enables or disables audio. If enable is true, audio data is played, but if enable is false, audio data is not played.
You need SMPEG to use this method.
NOTES
Audio enable/disable setting is reflected after playing starts.
See Also
SDL::MPEG#enable_video(enable)SDL::MPEG#enableVideo(enable)Enables or disables audio. If enable is true, movie data is played, but if enable is false, movie data is not played.
You need SMPEG to use this method.
See Also
SDL::MPEG#statusReturns current status of self as follows:
You need SMPEG to use this method.
See Also
SDL::MPEG#set_volume(volume)SDL::MPEG#setVolume(volume)Set volume MPEG stream from 0 to 100.
You need SMPEG to use this method.
NOTES
You cannot get current volume.
See Also
SDL::MPEG#set_display(surface)SDL::MPEG#setDisplay(surface)Sets the surface that the playing movie displays on. Normally, the surface object returned by SDL.set_video_mode is used as surface.
You need SMPEG to use this method.
NOTES
MPEG playback system call SDL::Screen#update_rect from a (native) sub thread.
See Also
SDL::MPEG#set_loop(repeat)SDL::MPEG#setLoop(repeat)Set or clear looping play on self.
You need SMPEG to use this method.
See Also
SDL::MPEG#scale_xy(width, height)SDL::MPEG#scaleXY(width, height)Set scale pixel display on self. The Unit of width and height is pixel.
You need SMPEG to use this method.
See Also
SDL::MPEG#scale(scale)Set scale display on self.
You need SMPEG to use this method.
See Also
SDL::MPEG#move(x, y)Moves the video display to (x, y) within the destination surface set by SDL::MPEG#set_display.
You need SMPEG to use this method.
SDL::MPEG#set_display_region(x, y, w, h)Set the region of the video to be shown at the rectangle of x, y, w, h
You need SMPEG to use this method.
See Also
SDL::MPEG#playPlays an MPEG object.
You need SMPEG to use this method.
NOTES
You don't have to access surface set by SDL::MPEG#set_display. x
See Also
SDL::MPEG#pause, SDL::MPEG#stop, SDL::MPEG#rewind, SDL::MPEG#seek, SDL::MPEG#skip, SDL::MPEG#render_frame
SDL::MPEG#stopStop play back of self.
You need SMPEG to use this method.
See Also
SDL::MPEG#pausePauses/Resumes playback of self. Pauses playback if self is playing, and Resume playback if paused.
You need SMPEG to use this method.
SDL::MPEG#rewindRewinds the play position of self to the beginning of the MPEG.
You need SMPEG to use this method.
SDL::MPEG#seek(bytes)Seeks bytes bytes the play position of self.
You need SMPEG to use this method.
See Also
SDL::MPEG#skip(seconds)Skips seconds seconds in self MPEG stream. seconds can be Float or Integer.
You need SMPEG to use this method.
See Also
SDL::MPEG#render_frame(framenum)Render the framenum-th frame in the surface set by SDL::MEPG#set_display.
You need SMPEG to use this method.
See Also
SDL::MPEG#render_final(dst, x, y)Render the last frame of self video at (x, y) in the dst surface.
You need SMPEG to use this method.
SDL::MPEG#set_filer(filter)Selects video filter from one of following:
You need SMPEG to use this method.
SDL::MPEG::Info#has_audioReturns true if self MPEG stream has audio data, otherwise returns false.
You need SMPEG to use this method.
SDL::MPEG::Info#has_videoReturns true if self MPEG stream has video data, otherwise returns false.
You need SMPEG to use this method.
SDL::MPEG::Info#widthReturns the width of video as pixels.
You need SMPEG to use this method.
SDL::MPEG::Info#heightReturns the width of video as pixels.
You need SMPEG to use this method.
SDL::MPEG::Info#current_framenot documented yet
You need SMPEG to use this method.
SDL::MPEG::Info#current_fpsnot documented yet
You need SMPEG to use this method.
SDL::MPEG::Info#audio_stringnot documented yet
You need SMPEG to use this method.
SDL::MPEG::Info#audio_current_framenot documented yet
You need SMPEG to use this method.
SDL::MPEG::Info#current_offsetnot documented yet
You need SMPEG to use this method.
SDL::MPEG::Info#total_sizenot documented yet
You need SMPEG to use this method.
SDL::MPEG::Info#current_timenot documented yet
You need SMPEG to use this method.
SDL::MPEG#total_timenot documented yet
You need SMPEG to use this method.
SDL::MPEG#deletenot documented yet
You need SMPEG to use this method.
SDL::MPEG#deleted?not documented yet
You need SMPEG to use this method.