LISPBUILDER-SDL - Use SDL from Common Lisp


 

Abstract

LISPBUILDER-SDL comprises several of packages that allow game development using Common Lisp. LISPBUILDER-SDL provides a set of bindings and Lispy abstractions for SDL and other graphics, sound, physics, character animation and 3D libraries. LISPBUILDER-SDL core functionality includes window and event management, 2D graphics, 3D graphics using OpenGL and sound support. The goal for the LISPBUILDER-SDL project is to become a useful resource for the development of games in Lisp.

SDL provides the low-level 2D rendering support. LISPBUILDER-SDL adds 2D graphical effects such as rotation, rendering circles, polygons, squares, Bezier and Cuttmull-Rom curves as well as bitmap font support. Additional packages provide native C drawing functions, True Type font rendering, loading of multiple image formats, a sound mixer and networking support. The lispbuilder packages are meant to work together with each package providing a specific core set of functionality. For example, an image that is loaded by lispbuilder-sdl-image may be rotated using lispbuilder-sdl-gfx. Text may be rendered to a surface using lispbuilder-sdl-ttf and finally blitted to the display using lispbuilder-sdl.

The code comes with a MIT-style license so you can basically do with it whatever you want.

Download shortcut: http://www.balooga.com/lispbuilder/lispbuilder-sdl.tgz.


 

Simple Example

	Alien Technology
(sdl:with-init ()
  (sdl:window 320 240)
  (sdl:draw-surface (load-image "lisp.bmp"))
  (sdl:update-display)
    (sdl:with-events ()
      (:quit-event () t)
      (:video-expose-event (sdl:update-display))))

 

Contents

  1. LISPBUILDER-SDL
    1. Abstract
    2. Compatibility
    3. Dependencies
    4. Download
    5. Installation
    6. Usage
    7. Included Examples
    8. Support
    9. License
    10. Package Overview
      1. Package Exports
      2. Package Structure
    11. Introduction
      1. Initialisation
      2. Creation of the SDL Window
      3. Events and the Game Loop
      4. Primitives
        1. Rectangle
        2. Color
      5. Drawing
      6. Fonts
        1. Initialisation
        2. Rendering Text
      7. Surfaces
        1. Overview
        2. Creation
        3. Loading Images
        4. Positioning
        5. Drawing & Blitting
      8. The SDL Display
      9. The Cursor
      10. Simple Example
      11. Garbage Collection
    12. The LISPBUILDER-SDL dictionary
    13. Acknowledgements

     

    Compatibility

    The following table describes the status of LISPBUILDER-SDL on the major Common Lisp implementations:

    Lisp Implementation LISPBUILDER-SDL Status Comments
    Win32 Linux MacOS
    CLISP v2.38 Working Working Working
    Lispworks v4.4.6 Personal Working Working Working
    Allegro Express 8.0 Unknown Working Unknown
    OpenMCL NA NA Unknown
    SBCL Working Working Unknown
    CMUCL Not Working Not Working Not Working

     

    Dependencies


     

    Download

    Current Version: The latest stable version of LISPBUILDER-SDL, together with this documentation can be downloaded from http://www.balooga.com/lispbuilder/lispbuilder-sdl.tgz. The current version is 0.9.5.


     

    Installation

    See the LISPBUILDER documentation for installation instructions for Windows, Mac OS-X and Linux.
     

    Using LISPBUILDER-SDL

    Enter the following at the REPL to compile and load the LISPBUILDER-SDL package: 

    (asdf:operate 'asdf:load-op :lispbuilder-sdl)
    ASDF will take care of loading the CFFI and :LISPBUILDER-SDL dependencies. The SDL.dll library will also be loaded into the Lisp image at this time.


     

    Running the Included Examples

    Enter the following at the REPL to compile and load the examples included in the LISPBUILDER-SDL-EXAMPLES package:

    	      (asdf:operate 'asdf:load-op :lispbuilder-sdl-examples)

    Run the examples by entering any of the following at the REPL: 

    	  (SDL-EXAMPLES:BEZIER)
	  (SDL-EXAMPLES:BMP-SAMPLE)
	  (SDL-EXAMPLES:CIRCLE-1)
	  (SDL-EXAMPLES:CIRCLE-2)
	  (SDL-EXAMPLES:CIRCLE-3)
	  (SDL-EXAMPLES:CIRCLE-4)
	  (SDL-EXAMPLES:CIRCLE-5)
	  (SDL-EXAMPLES:DISTANCE-2D)
	  (SDL-EXAMPLES:FLOOD-FILL)
	  (SDL-EXAMPLES:INBUILT-FONTS)
	  (SDL-EXAMPLES:LINE-DRAWING)
	  (SDL-EXAMPLES:MANDELBROT)
	  (SDL-EXAMPLES:METABALLS)
	  (SDL-EXAMPLES:MOUSE-2D)
	  (SDL-EXAMPLES:MOUSE-PAINTER)
	  (SDL-EXAMPLES:PIXELS-1)
	  (SDL-EXAMPLES:PIXELS-2)
	  (SDL-EXAMPLES:PIXELS-3)
	  (SDL-EXAMPLES:PIXELS-4)
	  (SDL-EXAMPLES:POINTS-AND-LINES)
	  (SDL-EXAMPLES:RANDOM-RECTS)
	  (SDL-EXAMPLES:RANDOM-BOX-1)
	  (SDL-EXAMPLES:RANDOM-BOX-2)
	  (SDL-EXAMPLES:RANDOM-BOX-3)
	  (SDL-EXAMPLES:RANDOM-BOX-4)
	  (SDL-EXAMPLES:RECURSIVE-RECTS)
	  (SDL-EXAMPLES:SETUP-AND-DRAW)
	  (SDL-EXAMPLES:SIMPLE-FONT-DEMO)
	  (SDL-EXAMPLES:STROKE)
	  (SDL-EXAMPLES:VERTICES)
	  (SDL-EXAMPLES:WIDTH-HEIGHT)

     

    Documentation, Support & Mailing Lists

    Questions answered and help given on the lispbuilder discussion list. Documentation for LISPBUILDER-SDL and related packages is available on the LISPBUILDER project page on Sourceforge. For additional information, look at the Lisp Gardeners page, and Application Builder page on the ALU's (Association of Lisp Users) wiki.
     

    License

    LISPBUILDER-SDL is distributed under the MIT-style license.


     

    Package Overview

    Package Exports

    Functions and symbols exported from the LISPBUILDER-SDL package are accessible from the LISPBUILDER-SDL: prefix or the shorter form SDL: nickname.

    Package Structure

    The cffi/ directory contains the raw CFFI bindings. These bindings may be automatically generated by SWIG or created by hand. CFFI translation functions perform simple low-level conversions for example, converting Lisp strings to C strings and back (see cffi-translate.lisp). All functions in cffi/ accept and return foreign objects only.

    The base/ directory defines wrappers over the functions in cffi/ . The functions in base/ accept keyword arguments and accept NIL instead of CFFI:NULL-POINTER where appropriate. Generally functions in base/ accept and return foreign objects. base/ may perform some type checks (IS-VALID-PTR SURFACE) but this layer is meant to be lean. Someone who implements a graphics engine might use this layer instead of sdl/ if speed is a concern. There are no fancy drawing primitives in this layer.

    The sdl/ directory defines the abstractions over cffi/ and base/. Foreign objects are passed around sdl/ neatly wrapped in CLOS objects, using TRIVIAL-GARBAGE for automatic garbage collection (minimize foreign objects being left on the heap). There are no functions in sdl/ that accept or return foreign objects (with the exception of the functions that create the CLOS wrapper objects) Functions in sdl/ call down into cffi/ and base/ as appropriate. All LISPBUILDER-SDL symbols available in SDL: are exported from sdl/, with symbols imported into sdl/ from cffi/ and base/ as appropriate (e.g. WITH-EVENTS). All drawing primitives are defined in this layer; circles, rectangles, lines, triangles, with-bezier etc. Functions in sdl/ implement a lot of type checking.

    An example of the difference between base/ and sdl/ is WITH-RECTANGLE. The WITH-RECTANGLE macro in base/ creates and destroys a foreign SDL_Rect. The WITH-RECTANGLE macro in sdl/ will create and destroy a RECTANGLE object.


     

    Introduction

    Initialisation of SDL

    The SDL library and SDL subsystems must be initialized prior to use. This is handled automatically when using the macro WITH-INIT. WITH-INIT also uninitialises the SDL library upon exit. More detailed information on the LISPBUILDER-SDL initialisation process can be found in the documentation for WITH-INIT. 

    (WITH-INIT (SDL-INIT-VIDEO)
  ...)

    Creation of the SDL Window

    A window must be created to display any kind of output. A window of a specific pixel width and height is created using the function WINDOW. WINDOW takes additional keyword parameters to set the requested video mode, color bit depth, the window title and the icon title. More detailed information can be found in in the documentation for WINDOW. 

    (WITH-INIT (SDL-INIT-VIDEO)
  (WINDOW 320 240))

    Handling Events and the Game Loop

    LISPBUILDER-SDL provides the WITH-EVENTS macro that simplifies the game loop and handling SDL events. Event handlers are defined by specifying the event type a well as an optional list of fields specific to that event.

    More detailed information on all SDL events (Keyboard events, Joystick events, User events etc.) can be found in in the documentation for WITH-EVENTS.

    For example, to process the current x and y mouse position when the mouse is moved: 

    (:MOUSE-MOTION-EVENT (:X X-POS :Y Y-POS)
  ...)

    Or to process the x and y relative mouse positions when the mouse is moved: 

    (:MOUSE-MOTION-EVENT (:X-REL relative-x :Y-REL relative-y)
  ...)

    The only event that must be handled with WITH-EVENTS is the :QUIT-EVENT. If :QUIT-EVENT is ignored then it is impossible for the user to close the SDL Window or exit the game loop. 

    (WITH-EVENTS ()
  (:QUIT-EVENT () T)
  (:MOUSE-MOTION-EVENT (:X mouse-x :Y mouse-y)
    ...))

    In addition to handling events, WITH-EVENTS also manages the game loop. Introducing the :IDLE event. :IDLE, although not technically an actual event, is executed once per game loop after all events have been processed in the SDL event queue. :IDLE is where the user can place code that needs to be executed once per game loop and that is not 'event' driven. This code may involve updating world physics, updating the state of game objects and rendering sprites to the display. 

    (WITH-EVENTS ()
  (:QUIT-EVENT () T)
  (:MOUSE-MOTION-EVENT (:X mouse-x :Y mouse-y)
    ...)
  (:IDLE ()
    (UPDATE-DISPLAY)))

    WITH-EVENTS can also limit execution of the the game loop to a specific number of iterations a second using FRAME-RATE. This effectively limits the number of frames displayed per second. To set the frame rate to 60 frames per second, (SETF (SDL:FRAME-RATE) 60). To unlock the frame rate effectively running the game loop as fast as the CPU will allow set the FRAME-RATE to NIL, (SETF (SDL:FRAME-RATE) NIL)

    The SDL display surface needs to be updated once per game loop, as described in the section SDL Display. 

    (SETF (FRAME-RATE) 30)
(WITH-EVENTS ()
  ...)

    Primitives

    LISPBUILDER-SDL supports the SDL RECTANGLE and COLOR primitives. These are described below.

    Rectangle

    A new rectangle is created by the function RECTANGLE. The function RECTANGLE-FROM-EDGES will create a new rectangle from the specified top left and bottom right coordinates. The function RECTANGLE-FROM-MIDPOINT-* will create a new rectangle from midpoint.

    The macros WITH-RECTANGLE and WITH-RECTANGLEs will create a new rectangle and free this rectangle when it goes out of scope.

    The rectangle position and width and height can be inspected and modified using the following functions: X, Y, WIDTH and HEIGHT. X2 and Y2 will return the (+ x width) and (+ y height) of the rectangle respectively.

    Additional functions that operate on rectangles are as follows:

    The section Drawing describes how to render a rectangle to a surface.

    Color

    A new SDL color is created by COLOR, returning either a new RGB or RGBA color.

    RGB/A color componets can be manipulated using the functions R, G, B, A, SET-COLOR and SET-COLOR-*. Two colors may be compared using COLOR=.

    Functions that accept a color parameter will most likely bind color to *DEFAULT-COLOR* when unspecified. The macro WITH-COLOR will bind a color to *DEFAULT-COLOR* within the scope of this macro. When *DEFAULT-COLOR* is bound to a color, all subsequent drawing functions will use this implied color while it remains in scope.

    Additional functions that operate on colors are as follows:

    LISPBULDER-SDL contains several predefined colors; *BLACK*, *WHITE*, *RED*, *GREEN*, *BLUE*, *YELLOW*, *CYAN*, *MAGENTA*.

    Drawing

    LISPBUILDER-SDL provides low-level drawing support for several primitives. Most primitives can be drawn with or without alpha transparency. In addition, the filled primitives can be drawn with a single pixel outline (or stroke) that is a different color to the fill color.

    Drawing functions require a target surface and color. LISPBUILDER-SDL uses defaults for both target surface (*DEFAULT-SURFACE*) and color (*DEFAULT-COLOR*) unless these are otherwise specified by the user. The macros with-surface, and with-surfaces will bind a surface to *DEFAULT-SURFACE* within the scope these macros. For example, instead of specifying a target surface for each draw-* function a user may bind *DEFAULT-SURFACE* to a surface once and subsequent draw-* functions will use this implied surface while it remains in scope. 

    (DRAW-POINT (sdl:point :x x1 :y y1) :surface a-surface :color *white*)
(DRAW-POINT (sdl:point :x x2 :y y2) :surface a-surface :color *white*)	    
(DRAW-POINT (sdl:point :x x3 :y y3) :surface a-surface :color *white*)
(DRAW-POINT (sdl:point :x x4 :y y4) :surface a-surface :color *white*)

    Now, we use WITH-SURFACE to bind a surface to *DEFAULT-SURFACE*.

    (WITH-SURFACE (a-surface)
  (DRAW-POINT (sdl:point :x x1 :y y1) :color *white*)
  (DRAW-POINT (sdl:point :x x2 :y y2) :color *white*)
  (DRAW-POINT (sdl:point :x x3 :y y3) :color *white*)
  (DRAW-POINT (sdl:point :x x4 :y y4) :color *white*))

    We can use WITH-COLOR to bind *DEFAULT-COLOR* to *WHITE*: 

    (WITH-SURFACE (a-surface)
  (WITH-COLOR (*white*)
    (DRAW-POINT (sdl:point :x x1 :y y1))
    (DRAW-POINT (sdl:point :x x2 :y y2))
    (DRAW-POINT (sdl:point :x x3 :y y3))
    (DRAW-POINT (sdl:point :x x4 :y y4)))

    Finally, if the target surface is the display then *WITH-SURFACE* is not required as :SURFACE when NIL will be bound to *DEFAULT-DISPLAY* as a default. So the above code can be shortened as follows: 

    (WITH-COLOR (*white*)
  (DRAW-POINT (sdl:point :x x1 :y y1))
  (DRAW-POINT (sdl:point :x x2 :y y2))
  (DRAW-POINT (sdl:point :x x3 :y y3))
  (DRAW-POINT (sdl:point :x x4 :y y4)))

    Fonts

    LISPBUILDER-SDL contains several bitmap fonts of different sizes and faces (italics/bolded). See INITIALISE-FONT for the complete list of built-in fonts.

    Initialisation

    Fonts are initialised using INITIALISE-DEFAULT-FONT, or INITIALISE-FONT. The resouces allocated to a font are freed by FREE-FONT. A font must be initialised prior to use.

    LISPBUILDER-SDL provides the macros WITH-DEFAULT-FONT and WITH-FONT for the above functions that bind *DEFAULT-FONT* to font within the scope of the macro.

    Rendering Text

    LISPBUILDER-SDL supports the rendering of colored text over a transparent background (Solid rendering), and the rendering of colored text over a solid colored background (Shaded rendering). Text may be left, right or center justified. Text can be drawn directly to a target surface using DRAW-STRING-SOLID and DRAW-STRING-SHADED. Text can be rendered to a new surface of character height and string width using RENDER-STRING-SOLID and RENDER-STRING-SHADED. This new surface may be optionally cached in the font object. A cached surface font can be accessed using CACHED-SURFACE) and can be blitted to a target surface using DRAW-FONT.

    The font rendering functions accept a font object. This font parameter is bound to *DEFAULT-FONT* when unspecified. The function INITIALISE-DEFAULT-FONT and the macros WITH-FONT and WITH-DEFAULT-FONT will bind a font to *DEFAULT-FONT* within the scope of these macros. When *DEFAULT-FONT* is bound to a font, all subsequent font drawing or font rendering functions will use this implied font while it remains in scope. 

    (WITH-COLOR (*WHITE*)
  (WITH-FONT (*FONT-8x8*)
    (DRAW-STRING-SOLID-* "Font is 8x8." 10 10)

    (WITH-FONT (*FONT-10x20*)
      (DRAW-STRING-SOLID-* "Font is 10x20." 10 20))

    (DRAW-STRING-SOLID-* "Font is 8x8 again." 10 40)))

    Surfaces

    Overview of Surfaces

    An SDL surface, SURFACE, represents an area of graphical memory that can be drawn or rendered to, for example the video framebuffer or an image that is loaded from disk.

    Creating Surfaces

    A surface is created:

    Functions that accept a surface parameter will most likely bind surface to *DEFAULT-SURFACE* when unspecified. The macros WITH-SURFACE and WITH-SURFACES will bind a surface to *DEFAULT-SURFACE* within the scope of these macro. When *DEFAULT-SURFACE* is bound to a surface, all subsequent drawing functions will use this implied surface while it remains in scope.

    A surface can be explicitely freed by calling FREE-SURFACE.

    Images

    BMP images are loaded from disk using LOAD-IMAGE. Support for additional image formats is provided in the LISPBUILDER-SDL-IMAGE package. A surface is saved to disk as a BMP image using SAVE-IMAGE. 

    (DRAW-SURFACE (LOAD-IMAGE "sdl.bmp") 
              :surface *default-display*)

    Positioning Surfaces

    A SURFACE stores its own position X/Y coordinates. These coordinates can be inspected and modified using the following functions: X, Y, WIDTH and HEIGHT.

    Additional functions and macros that manage surface coordinates are as follows:

    Drawing & Blitting Surfaces

    The functions BLIT-SURFACE and DRAW-SURFACE will blit or draw a source surface onto a destination surface using the position coordinates stored in the source surface. DRAW-SURFACE-AT will draw the source surface at a specified position.

    The composition rules that determine how the source surface is composed over the destination surface are described in the description of BLIT-SURFACE. FILL-SURFACE fill will the target surface with a single color. Drawing Primitives describes how *DEFAULT-SURFACE* is used when calling blitting operations.

    Use SET-COLOR-KEY, CLEAR-COLOR-KEY and SET-ALPHA to modify the key color and alpha transparency properties of a surface after the surface has been created.

    Set a clipping rectangle to limit the draw area on a destination surface. The clipping rectangle for a surface is manipulated using GET-CLIP-RECT and SET-CLIP-RECT. When this surface is the destination of a blit, only the area within the clip rectangle will be drawn into.

    Set a cell rectangle to limit the surface area on the source surface. The cell rectangle for a surface is manipulated using CLEAR-CELL and SET-CELL. When this surface is the source of a blit, only the areas within the cell rectangle will be used. The cell is useful when only a small area of the source surface needs to be blitted to the destination surface. For example a sequence of images composed into a single sprite sheet and only the current frame of animation is to be drawn to the display at any one time.

    Sprite Sheet

    Updating SDL Surfaces and the SDL Display

    The functions UPDATE-DISPLAY and UPDATE-SURFACE update the SDL display surface (or OpenGL context) and general SDL surfaces respectively.

    The SDL Display

    The SDL display surface must be updated at least once each game loop using the function UPDATE-DISPLAY. This function will call SDL-GL-SWAP-BUFFERS to update the OpenGL display, or SDL-FLIP to update the SDL surface depending on the current *OPENGL-CONTEXT*. The display can be filled with a background color using CLEAR-DISPLAY.

    The properties of an SDL surface can be queried using SURFACE-INFO. The properties of the SDL display and video hardware can be queried using VIDEO-INFO. The screen resolutions supported by a particular set of video flags can be retrieved using LIST-MODES. A pointer to the native SDL window can be retrieved using GET-NATIVE-WINDOW. The name of the video driver can be retrieved as a STRING using VIDEO-DRIVER-NAME.

    The Cursor

    The the current state of the cursor is returned using QUERY-CURSOR, and is set using SHOW-CURSOR.

    Simple Example

    Putting this all together, we can write short example showing a white rectangle that follows the users mouse movements within an SDL Window. Exit the example by closing the window or pressing the Esc key on the keyboard. 

    ;; Initialise SDL and the Video subsystem
(WITH-INIT (SDL-INIT-VIDEO) 
  (WINDOW 320 240)          ; Open a window, 320 x 240

  (SETF (FRAME-RATE) 30)    ; Lock the frame rate to 30 fps
  (WITH-EVENTS ()
    (:QUIT-EVENT () T)      ; Absolutely have to handle the :QUIT-EVENT

    (:KEY-DOWN-EVENT (:KEY key) (WHEN (KEY= key :SDL-KEY-ESCAPE) (PUSH-QUIT-EVENT)))

    (:MOUSE-MOTION-EVENT (:X mouse-x :Y mouse-y)
      (CLEAR-DISPLAY *black*)
      ;; Draw the box with center at the mouse x/y coordinates.
      (DRAW-BOX-* (- mouse-x (/ 50 2)) (- mouse-y (/ 50 2)) 50 50 :color *white*))

    (:IDLE ()
      (UPDATE-DISPLAY))))

    Object Lifecycles and Garbage Collection

    ...


     

    The LISPBUILDER-SDL dictionary


    [Special variable]
    *black*


    The COLOR black.


    [Special variable]
    *blue*


    The COLOR blue.


    [Special variable]
    *cyan*


    The COLOR cyan.


    [Special variable]
    *default-color*


    Functions that accept the KEYword parameter COLOR will most likely bind to the symbol *DEFAULT-COLOR* if COLOR is not specified, automatically using whatever color is referenced by *DEFAULT-COLOR*.

    A color is bound to *DEFAULT-COLOR* by the following macro: WITH-COLOR.

    Example 
    (DRAW-BOX A-BOX :SURFACE SDL:DEFAULT-DISPLAY* :COLOR SDL:*BLACK*)
(DRAW-BOX B-BOX :SURFACE SDL:DEFAULT-DISPLAY* :COLOR SDL:*BLACK*)
(DRAW-BOX C-BOX :SURFACE SDL:DEFAULT-DISPLAY* :COLOR SDL:*BLACK*)

    The above can be shortened by setting *DEFAULT-COLOR* to *BLACK*. 

    (WITH-SURFACE (DISP SDL:*DEFAULT-DISPLAY*)
  (WITH-COLOR (COL SDL:*BLACK*)
    (DRAW-BOX A-BOX)
    (DRAW-BOX B-BOX)
    (DRAW-BOX C-BOX)))


    [Special variable]
    *default-display*


    The symbol *DEFAULT-DISPLAY* is bound to the current display surface DISPLAY-SURFACE) by the function WINDOW).


    [Special variable]
    *default-font*



    [Special variable]
    *default-font-path*



    [Special variable]
    *default-position*



    [Special variable]
    *default-rectangle*



    [Special variable]
    *default-surface*


    Functions that accept the KEYword parameter SURFACE will most likely bind to the symbol *DEFAULT-SURFACE* if SURFACE is not specified, automatically using whatever surface is referenced by *DEFAULT-SURFACE*.

    A surface is bound to *DEFAULT-SURFACE* by the following macros: WITH-SURFACE, and WITH-SURFACES.

    Example 
    (DRAW-SURFACE SURF-1 :SURFACE SDL:*DEFAULT-DISPLAY*)
(DRAW-SURFACE SURF-2 :SURFACE SDL:*DEFAULT-DISPLAY*)
(DRAW-SURFACE SURF-2 :SURFACE SDL:*DEFAULT-DISPLAY*)

    The above can be shortened using by setting the *DEFAULT-SURFACE* to the display surface. 

    (WITH-SURFACE (DISP SDL:*DEFAULT-DISPLAY*)
  (DRAW-SURFACE SURF-1)
  (DRAW-SURFACE SURF-2)
  (DRAW-SURFACE SURF-2))


    [Special variable]
    *external-init-on-startup*


    The list of functions that are called from INIT-SDL.


    [Special variable]
    *external-quit-on-exit*


    The list of functions that are called from QUIT-SDL.


    [Special variable]
    *font-10x20*


    Contains the font data for an 10x20 bitmap font.


    [Special variable]
    *font-5x7*


    Contains the font data for an 5x7 bitmap font.


    [Special variable]
    *font-5x8*


    Contains the font data for an 5x8 bitmap font.


    [Special variable]
    *font-6x10*


    Contains the font data for an 6x10 bitmap font.


    [Special variable]
    *font-6x12*


    Contains the font data for an 6x12 bitmap font.


    [Special variable]
    *font-6x13*


    Contains the font data for an 6x13 bitmap font.


    [Special variable]
    *font-6x13b*


    Contains the font data for an 6x13 bitmap font.


    [Special variable]
    *font-6x13o*


    Contains the font data for an 6x13 bitmap font.


    [Special variable]
    *font-6x9*


    Contains the font data for an 6x9 bitmap font.


    [Special variable]
    *font-7x13*


    Contains the font data for an 7x13 bitmap font.


    [Special variable]
    *font-7x13b*


    Contains the font data for an 7x13 bitmap font.


    [Special variable]
    *font-7x13o*


    Contains the font data for an 7x13 bitmap font.


    [Special variable]
    *font-7x14*


    Contains the font data for an 7x14 bitmap font.


    [Special variable]
    *font-7x14b*


    Contains the font data for an 7x14 bitmap font.


    [Special variable]
    *font-8x13*


    Contains the font data for an 8x13 bitmap font.


    [Special variable]
    *font-8x13b*


    Contains the font data for an 8x13 bitmap font.


    [Special variable]
    *font-8x13o*


    Contains the font data for an 8x13 bitmap font.


    [Special variable]
    *font-8x8*


    Contains the font data for an 8x8 bitmap font.


    [Special variable]
    *font-9x15*


    Contains the font data for an 9x15 bitmap font.


    [Special variable]
    *font-9x15b*


    Contains the font data for an 9x15 bitmap font.


    [Special variable]
    *font-9x18*


    Contains the font data for an 9x18 bitmap font.


    [Special variable]
    *font-9x18b*


    Contains the font data for an 9x18 bitmap font.


    [Special variable]
    *green*


    The COLOR green.


    [Special variable]
    *magenta*


    The COLOR magenta.


    [Special variable]
    *opengl-context*


    The symbol *OPENGL-CONTEXT* is T when an OpenGL display context is created, and NIL otherwise. UPDATE-SURFACE will call SDL-GL-SWAP-BUFFERS when *OPENGL-CONTEXT* is T, and SDL-FLIP otherwise.


    [Special variable]
    *red*


    The COLOR red.


    [Special variable]
    *sdl-initialized*



    [Special variable]
    *white*


    The COLOR white.


    [Special variable]
    *yellow*


    The COLOR yellow.


    [Generic accessor]
    a color => result
    (setf (a color) value)


    Returns the alpha component of color COLOR as an INTEGER.


    [Specialized accessor]
    a (color color-a) => result
    (setf (a (color color-a)) value)


    Returns the alpha color component of the color COLOR as an INTEGER.


    [Method]
    a (color color) => result


    Returns NIL as COLOR has no alpha component.


    [Macro]
    all-integers? &rest values => result


    Returns T if all values are INTEGERS.


    [Generic function]
    any-color-but-this color => result


    Returns a new color that is different to the color COLOR.


    [Method]
    any-color-but-this color => result


    Returns a new color that is different to the color COLOR.


    [Function]
    average-fps => result



    [Generic accessor]
    b color => result
    (setf (b color) value)


    Returns the blue component of color COLOR as an INTEGER.


    [Specialized accessor]
    b (color color) => result
    (setf (b (color color)) value)


    Returns the blue color component of the color COLOR as an INTEGER.


    [Function]
    bit-depth surface => result


    Returns the bit depth (the number of bytes per pixel, or bpp) of the surface SURFACE as an INTEGER.


    [Function]
    blit-surface src &optional surface => result



    [Generic accessor]
    cached-surface sdl-font => result
    (setf (cached-surface sdl-font) value)



    [Specialized accessor]
    cached-surface (sdl-font sdl-font) => result
    (setf (cached-surface (sdl-font sdl-font)) value)



    [Macro]
    cast type value => result


    Coerces the value VALUE to the type TYPE.


    [Macro]
    cast-all-to-int &rest values => result


    Casts the values in REST to FIXNUMs.


    [Macro]
    cast-to-int value => result


    Casts the value VALUE to a FIXNUM.


    [Function]
    catmull-rom-spline val v0 v1 v2 v3 => result



    [Generic function]
    char-height bitmap-font => result



    [Method]
    char-height (bitmap-font bitmap-font) => result



    [Generic function]
    char-width bitmap-font => result



    [Method]
    char-width (bitmap-font bitmap-font) => result



    [Macro]
    check-types type &rest rest => result


    Performs CHECK-TYPE on items in rest.


    [Function]
    clear-cell &key surface => result



    [Function]
    clear-color-key &key surface rle-accel => result



    [Function]
    clear-display color &key surface update-p => result


    Fills the display SURFACE using color COLOR. SURFACE is bound to *DEFAULT-DISPLAY* if unspecified. The display is updated when UPDATE-P is T.


    [Standard class]
    color


    An SDL color containing INTEGER Red, Green and Blue color components.


    [Function]
    color &key r g b a => result


    Creates and returns a new COLOR from the soecified red R, green G, and blue B color components. When A is an INTEGER, will return a new COLOR-A with the alpha transparency.


    [Generic function]
    color-* color => result


    Returns the RGB/A components of color as a spread. If COLOR contains an alpha component then RESULT is (VALUES R G B A) If COLOR contains no alpha component then RESULT is (VALUES R G B)


    [Method]
    color-* (color foreign-color) => result


    Not implemented yet. Returns NIL


    [Method]
    color-* (color color-a) => result


    Returns the read, green, blue and alpha components of the color COLOR as a spread.


    [Method]
    color-* (color color) => result


    Returns the read, green and blue components of the color COLOR as a spread.


    [Standard class]
    color-a


    An SDL color containing INTEGER Red, Green, Blue and Alpha color components.


    [Generic function]
    color= color1 color2 => result


    Returns T if colors match, returns NIL otherwise.


    [Method]
    color= (color1 color-a) (color2 color-a) => result


    Returns T if the RGBA colors match, returns NIL otherwise.


    [Method]
    color= (color1 color) (color2 color) => result


    Returns T if the RGB colors match, returns NIL otherwise.


    [Method]
    color= color1 color2 => result


    Returns NIL. This is a catch all when an RGB color is compared with an RGBA color.


    [Function]
    convert-surface &key surface key-color alpha-value free-p => result



    [Function]
    copy-channel-to-alpha destination source &key channel => result



    [Function]
    copy-point point => result


    Returns a copy of the point POINT.


    [Function]
    copy-surface &key surface key-color alpha-value type rle-accel => result



    [Function]
    create-list-if-not var => result


    If VAR is not already a list, then returns (LIST VAR).


    [Function]
    create-path filename &optional path => result


    Creates a new path from FILENAME and PATH.


    [Function]
    create-rwops-from-file filename => result


    Creates and returns a new RWOPS object from the file at location FILENAME.


    [Function]
    create-surface width height &key surface bpp key-color alpha-value type rle-accel => result



    [Function]
    disable-key-repeat => result


    Disables keyboard repeat.


    [Function]
    distance p1 p2 => result


    Returns the distance between the POINTs P1 and P2.


    [Function]
    distance-* x1 y1 x2 y2 => result


    Returns the distance between the coordinates X1, Y1 and X2, Y2.


    [Function]
    draw-bezier points type &key clipping-p surface color segments => result


    Draw a bezier curve of color COLOR to the surface SURFACE. The shape of the Bezier curve is defined by several control points. A control point is a vertex containing an X and Y coordinate pair.

    Parameters
    Example 
    (DRAW-BEZIER (LIST (SDL:POINT :X 60  :Y 40)
                     (SDL:POINT :X 160 :Y 10)
                     (SDL:POINT :X 170 :Y 150)
                     (SDL:POINT :X 60 :Y 150))
               :SOLID)


    [Function]
    draw-box rect &key clipping-p surface color stroke-color alpha => result


    See DRAW-BOX-*.

    Parameters


    [Function]
    draw-box-* x y w h &key clipping-p surface color stroke-color alpha => result


    Draws a filled rectangle of color COLOR to surface SURFACE.

    Parameters


    [Function]
    draw-circle p1 r &key surface color alpha => result


    See DRAW-CIRCLE-*.

    Parameters


    [Function]
    draw-circle-* x0 y0 r &key surface color alpha => result


    Draws a circle circumference of color COLOR to the surface SURFACE. Use DRAW-FILLED-CIRCLE-* to draw a filled circle.

    Parameters


    [Function]
    draw-curve points type &key clipping-p surface color segments => result


    Draw a Cattmul-Rom spline using color COLOR to the surface SURFACE. The shape of the curve is defined by waypoints. A waypoint is a vertex containing an X and Y coordinate pair.

    Parameters
    Example 
    (DRAW-CURVE (LIST (SDL:POINT :X 60  :Y 40)
    	  (SDL:POINT :X 160 :Y 10)
	  (SDL:POINT :X 170 :Y 150)
	  (SDL:POINT :X 60  :Y 150))
    :SOLID
    10)


    [Function]
    draw-filled-circle p1 r &key surface color stroke-color alpha => result


    See DRAW-FILLED-CIRCLE-*.

    Parameters


    [Function]
    draw-filled-circle-* x0 y0 r &key surface color stroke-color alpha => result


    Draws a filled circle of color COLOR to the surface SURFACE.

    Parameters


    [Generic function]
    draw-font &key font surface => result


    Blit the cached surface in the font FONT to the destination surface SURFACE. The cached surface is created during a previous call to any of the DRAW-STRING* functions. Uses the POSITION of the cached surface to render at X/Y coordinates on the destination SURFACE. This function can provide a speed increase upon redraws when the text in FONT remains unchanged between screen updates.


    [Function]
    draw-font &key font surface => result


    Blit the cached surface in the font FONT to the destination surface SURFACE. The cached surface is created during a previous call to any of the DRAW-STRING* functions. Uses the POSITION of the cached surface to render at X/Y coordinates on the destination SURFACE. This function can provide a speed increase upon redraws when the text in FONT remains unchanged between screen updates.


    [Generic function]
    draw-font-at position &key font surface => result


    See DRAW-FONT.

    Parameters


    [Method]
    draw-font-at position &key font surface => result


    See DRAW-FONT.


    [Generic function]
    draw-font-at-* x y &key font surface => result


    See DRAW-FONT

    Parameters


    [Method]
    draw-font-at-* x y &key font surface => result


    See DRAW-FONT.

    Parameters


    [Function]
    draw-hline x0 x1 y &key surface color clipping-p template => result


    Draw a horizontal line of color COLOR from X0 to X1 through Y onto the surface SURFACE.

    Parameters


    [Function]
    draw-line p1 p2 &key surface color clipping-p => result


    See DRAW-LINE-*.

    Parameters


    [Function]
    draw-line-* x0 y0 x1 y1 &key surface color clipping-p => result


    Draws a line of color COLOR to the surface SURFACE.

    Parameters


    [Function]
    draw-pixel point &key clipping-p surface color => result


    See DRAW-PIXEL-*.

    Parameters


    [Function]
    draw-pixel-* x y &key clipping-p surface color => result


    Draw a single pixel of color COLOR to the surface SURFACE at the specified X and Y coordiates.

    Parameters


    [Function]
    draw-polygon vertices &key surface color clipping-p => result


    Draw the circumference of a polygon of color COLOR to surface SURFACE using the vertices in POINTS. Use DRAW-FILLED-POLYGON-* to draw a filled polygon.

    Parameters


    [Function]
    draw-rectangle rect &key clipping-p surface color alpha => result


    See DRAW-RECTANGLE-*.

    Parameters


    [Function]
    draw-rectangle-* x y w h &key clipping-p surface color alpha => result


    Draw a rectangle outline of color COLOR to the surface SURFACE.

    Parameters


    [Function]
    draw-shape points type &key clipping-p surface color => result


    Draw a polygon of color COLOR to the surface SURFACE using the vertices in POINTS.

    Parameters
    Example 
    (DRAW-SHAPE (LIST (SDL:POINT :X 60  :Y 40)
	    (SDL:POINT :X 160 :Y 10)
	    (SDL:POINT :X 170 :Y 150)
	    (SDL:POINT :X 60  :Y 150))
    :SOLID)


    [Function]
    draw-string-centered-* str x y fg-color bg-color &key surface font => result


    Draw the text in the string STRwith midpoint centered at location X and Y using font FONT with foreground and background colors FG-COLOR and BG-COLOR onto surface SURFACE.

    Parameters
    Returns


    [Function]
    draw-string-shaded string p1 fg-color bg-color &key justify surface font => result


    See DRAW-STRING-SHADED-*.

    Parameters


    [Function]
    draw-string-shaded-* string x y fg-color bg-color &key justify surface font => result


    Draw text STRING at location XY using font FONT with text color FG-COLOR and background color BG-COLOR onto surface SURFACE. The surface background is filled with BG-COLOR so the surface cannot be keyed over other surfaces.

    Returns
    Example 
    (DRAW-STRING-SHADED-* "Hello World!" 0 0 F-COLOR B-COLOR :SURFACE A-SURFACE)


    [Function]
    draw-string-solid string p1 &key justify surface font color => result


    See DRAW-STRING-SOLID-*.

    Parameters


    [Function]
    draw-string-solid-* string x y &key justify surface font color => result


    Draw text STRING at location XY using font FONT with color COLOR onto surface SURFACE. The text is keyed onto SURFACE.

    Parameters
    Returns
    Example 
    (DRAW-STRING-SOLID-* "Hello World!" 0 0 :SURFACE A-SURFACE :COLOR A-COLOR)


    [Function]
    draw-surface src &key surface => result



    [Function]
    draw-surface-at src point &key surface => result



    [Function]
    draw-surface-at-* src x y &key surface => result



    [Function]
    draw-trigon p1 p2 p3 &key surface color clipping-p => result


    Draw the outline of a trigon or triangle, of color COLOR to surface SURFACE. Use DRAW-FILLED-TRIGON-* to draw a filled trigon.

    Parameters


    [Function]
    draw-vline x y0 y1 &key surface color clipping-p template => result


    Draw a vertical line of color COLOR from Y0 to Y1 through X onto the surface SURFACE.

    Parameters


    [Function]
    enable-key-repeat delay interval => result


    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. Setting DELAY or INTERVAL to NIL will set the default values of SDL-DEFAULT-REPEAT-DELAY and SDL-DEFAULT-REPEAT-INTERVAL respectively.


    [Function]
    enable-key-repeat-p => result


    Returns the current keyboard DELAY and INTERVAL repeat rate in milliseconds as (VALUES DELAY INTERVAL).


    [Function]
    enable-unicode state => result


    Unicode translation is enabled with STATE is T, and disabled when STATE is NIL. To obtain the character codes corresponding to received keyboard events, Unicode translation must first be turned on using this function. The translation incurs a slight overhead for each keyboard event and is therefore disabled by default. For each subsequently received key down event, the unicode member of the SDL_keysym structure will then contain the corresponding character code, or zero for keysyms that do not correspond to any character code. Note that only key press events will be translated, not release events. Returns the previous unicode translation state.


    [Function]
    enable-unicode-p => result


    Queries the current state of Unicode keyboard translation. Returns T if enabled, NIL if disabled.


    [Function]
    fill-surface color &key template surface update-p clipping-p => result


    Fill the surface with the specified color COLOR. Use :template to specify the SDLRect to be used as the fill template. Use :update-p to call SDLUpdateRect, using :template if provided. This allows for a 'dirty recs' screen update.


    [Function]
    fill-surface-* r g b &key a template surface update-p clipping-p => result


    Fill the surface with the specified color R G B :A A. Use :TEMPLATE to specify the SDLRectangle to be used as the fill template. Use :UPDATE-P to call SDLUpdateRect, using :TEMPLATE if provided. This allows for a 'dirty recs' screen update.


    [Function]
    flood-fill point &key surface color => result


    See FLOOD-FILL-*.

    Parameters


    [Function]
    flood-fill-* x y &key surface color => result


    Performs a flood fill of surface SURFACE with color COLOR. The fill starts at the position specified by the X and Y coordinates. Uses a stack based flood fill that does a lot of consing because it uses PUSH/POP as the stack. This function is fast.

    Parameters


    [Function]
    flood-fill-stack point &key surface color => result


    See FLOOD-FILL-STACK-*.

    Parameters


    [Function]
    flood-fill-stack-* x y &key surface color => result


    See FLOOD-FILL-*.

    FLOOD-FILL-STACK-* is maintains an internal array-based stack.

    Note: More of an experiment to see if an array would be faster than a bunch of consing. The timing of both functions indicates they run at the same speed. With compiler declarations it may have better results. Another disadvantage to this is it preallocates the stack, chewing up quite a bit of ram.


    [Generic accessor]
    fp rwops => result
    (setf (fp rwops) value)


    Returns the default foreign object for OBJECT.


    [Method]
    fp (rwops sdl-font) => result


    Returns the cached surface SURFACE in FONT, or NIL if the font does not contain a cached surface.


    [Specialized accessor]
    fp (rwops rwops) => result
    (setf (fp (rwops rwops)) value)



    [Specialized accessor]
    fp (rwops rectangle-array) => result
    (setf (fp (rwops rectangle-array)) value)



    [Method]
    fp (rwops sdl-surface) => result



    [Specialized accessor]
    fp (rwops rectangle) => result
    (setf (fp (rwops rectangle)) value)



    [Specialized accessor]
    fp (rwops foreign-color) => result
    (setf (fp (rwops foreign-color)) value)



    [Specialized accessor]
    fp (rwops color-a) => result
    (setf (fp (rwops color-a)) value)



    [Specialized accessor]
    fp (rwops color) => result
    (setf (fp (rwops color)) value)



    [Generic accessor]
    fp-cell sdl-surface => result
    (setf (fp-cell sdl-surface) value)



    [Specialized accessor]
    fp-cell (sdl-surface sdl-surface) => result
    (setf (fp-cell (sdl-surface sdl-surface)) value)



    [Generic function]
    fp-position sdl-surface => result


    Returns the default foreign SDL_Rect object for OBJECT.


    [Method]
    fp-position (sdl-surface sdl-font) => result


    Returns the X and Y coordinates of the cached surface SURFACE in FONT, as POINT.


    [Method]