LISPBUILDER-SDL -


 

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.

Current Version: The version of LISPBUILDER-SDL to use is the latest version in SVN.


 

Simple Example

This example was created with the following code:

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))))
      
  1. LISPBUILDER-SDL
    1. Abstract
    2. Simple Example
    3. Compatibility
    4. Downloads
    5. Installation
    6. Usage
    7. Included Examples
    8. Dependencies
    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. LISPBUILDER-SDL dictionary
      1. INDEX
    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

 

Downloads

See the LISPBUILDER documentation for downloads.


 

Installation

See the LISPBUILDER documentation for installation instructions.


 

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)
	

 

Dependencies

None.


 

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 Index

  1. *black*
  2. *blue*
  3. *cyan*
  4. *default-color*
  5. *default-display*
  6. *default-font*
  7. *default-font-path*
  8. *default-position*
  9. *default-rectangle*
  10. *default-surface*
  11. *external-init-on-startup*
  12. *external-quit-on-exit*
  13. *font-10x20*
  14. *font-5x7*
  15. *font-5x8*
  16. *font-6x10*
  17. *font-6x12*
  18. *font-6x13*
  19. *font-6x13b*
  20. *font-6x13o*
  21. *font-6x9*
  22. *font-7x13*
  23. *font-7x13b*
  24. *font-7x13o*
  25. *font-7x14*
  26. *font-7x14b*
  27. *font-8x13*
  28. *font-8x13b*
  29. *font-8x13o*
  30. *font-8x8*
  31. *font-9x15*
  32. *font-9x15b*
  33. *font-9x18*
  34. *font-9x18b*
  35. *green*
  36. *magenta*
  37. *opengl-context*
  38. *red*
  39. *sdl-initialized*
  40. *white*
  41. *yellow*
  42. a
  43. all-integers?
  44. any-color-but-this
  45. b
  46. bit-depth
  47. blit-surface
  48. cached-surface
  49. calculate-curve
  50. cast
  51. cast-all-to-int
  52. cast-to-int
  53. catmull-rom-spline
  54. char-height
  55. char-width
  56. check-types
  57. clear-cell
  58. clear-color-key
  59. clear-display
  60. color
  61. color
  62. color-*
  63. color-a
  64. color=
  65. convert-surface
  66. copy-point
  67. copy-surface
  68. create-list-if-not
  69. create-path
  70. create-rwops-from-file
  71. create-surface
  72. distance
  73. distance-*
  74. draw-bezier
  75. draw-box
  76. draw-box-*
  77. draw-circle
  78. draw-circle-*
  79. draw-curve
  80. draw-filled-circle
  81. draw-filled-circle-*
  82. draw-font
  83. draw-font
  84. draw-font-at
  85. draw-font-at-*
  86. draw-hline
  87. draw-line
  88. draw-line-*
  89. draw-point
  90. draw-point-*
  91. draw-polygon
  92. draw-rectangle
  93. draw-rectangle-*
  94. draw-shape
  95. draw-string-shaded
  96. draw-string-shaded-*
  97. draw-string-solid
  98. draw-string-solid-*
  99. draw-surface
  100. draw-surface-at
  101. draw-surface-at-*
  102. draw-trigon
  103. draw-vline
  104. fill-surface
  105. fill-surface-*
  106. flood-fill
  107. flood-fill-*
  108. flood-fill-stack
  109. flood-fill-stack-*
  110. fp
  111. fp-cell
  112. fp-position
  113. frame-rate
  114. free-cached-surface
  115. free-color
  116. free-font
  117. free-rectangle
  118. free-rwops
  119. free-surface
  120. g
  121. get-clip-rect
  122. get-native-window
  123. get-point
  124. get-position
  125. get-rectangle
  126. get-surface-rect
  127. height
  128. init-sdl
  129. init-sub-systems
  130. initialise-default-font
  131. initialise-font
  132. initialize-on-startup
  133. initialized-sub-systems-p
  134. is-valid-ptr
  135. key=
  136. list-modes
  137. list-sub-systems
  138. load-image
  139. map-color
  140. pack-color
  141. point
  142. point-*
  143. position-*
  144. push-quit-event
  145. push-user-event
  146. query-cursor
  147. quit-on-exit
  148. quit-sdl
  149. quit-sub-systems
  150. r
  151. random+1
  152. random-rectangle
  153. read-point
  154. rectangle
  155. rectangle
  156. rectangle-*
  157. rectangle-from-edges
  158. rectangle-from-edges-*
  159. rectangle-from-midpoint-*
  160. render-string-shaded
  161. render-string-solid
  162. return-sub-systems-of-status
  163. rotate-surface
  164. rwops
  165. save-image
  166. sdl-any-format
  167. sdl-async-blit
  168. sdl-color
  169. sdl-doublebuf
  170. sdl-fullscreen
  171. sdl-get-ticks
  172. sdl-hw-accel
  173. sdl-hw-palette
  174. sdl-hw-surface
  175. sdl-init-audio
  176. sdl-init-cdrom
  177. sdl-init-eventthread
  178. sdl-init-everything
  179. sdl-init-joystick
  180. sdl-init-noparachute
  181. sdl-init-on-startup
  182. sdl-init-timer
  183. sdl-init-video
  184. sdl-iyuv-overlay
  185. sdl-no-frame
  186. sdl-opengl
  187. sdl-pre-alloc
  188. sdl-quit-on-exit
  189. sdl-resizable
  190. sdl-rle-accel
  191. sdl-rle-accel-ok
  192. sdl-src-alpha
  193. sdl-src-color-key
  194. sdl-surface
  195. sdl-sw-surface
  196. sdl-uyvy-overlay
  197. sdl-yuy2-overlay
  198. sdl-yv12-overlay
  199. sdl-yvyu-overlay
  200. set-alpha
  201. set-cell
  202. set-cell-*
  203. set-clip-rect
  204. set-color
  205. set-color-*
  206. set-color-key
  207. set-frame-rate
  208. set-point
  209. set-point-*
  210. set-position
  211. set-position-*
  212. set-rectangle
  213. set-rectangle-*
  214. set-surface
  215. set-surface-*
  216. show-cursor
  217. surface
  218. surface
  219. surface-info
  220. to-degree
  221. to-radian
  222. update-display
  223. update-surface
  224. update-surface-*
  225. video-driver-name
  226. video-info
  227. width
  228. window
  229. with-bezier
  230. with-color
  231. with-curve
  232. with-default-font
  233. with-events
  234. with-font
  235. with-init
  236. with-locked-surface
  237. with-locked-surfaces
  238. with-point
  239. with-rectangle
  240. with-rectangles
  241. with-shape
  242. with-surface
  243. with-surface-slots
  244. with-surfaces
  245. within-range
  246. within-range-*
  247. x
  248. x2
  249. y
  250. y2

 

The NIL 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.


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



[Function]
calculate-curve p1 p2 p3 p4 segments => result



[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-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 bpp surface key-color alpha-value type rle-accel => result



[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))
               :LINE-STRIP)


[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))
    :LINE-STRIP
    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 => 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-point point &key clipping-p surface color => result


See DRAW-POINT-*.

Parameters


[Function]
draw-point-* 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))
    :LINE-STRIP)


[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 => result


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

Parameters


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


fill the entire surface with the specified R G B A 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-* color x y w h &key surface update-p clipping-p => result



[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 object => result
(setf (fp rwops) value)


Returns the default foreign object for OBJECT.


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


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


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



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



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



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



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



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



[Specialized accessor]
fp (object 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 object => result


Returns the default foreign SDL_Rect object for OBJECT.


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


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


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



[Function]
frame-rate => result


Returns the specified frame rate, not the actual frame rate.


[Generic function]
free-cached-surface font => result


Frees resources allocated to the cached surface SURFACE in FONT, if any. Sets the FONTs CACHED-SURFACE slot to NIL.


[Method]
free-cached-surface (font sdl-font) => result


Frees resources allocated to the cached surface SURFACE in FONT, if any. Sets the FONTs CACHED-SURFACE slot to NIL.


[Generic function]
free-color color => result


Free's resources allocated to COLOR. Meant specifically for the SDL_Color foreign object. COLOR and COLOR-A are ignored.


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



[Method]
free-color (color sdl-color) => result



[Generic function]
free-font font => result


Free's the resources allocated to the FONT.


[Method]
free-font (font bitmap-font) => result


Free resources associated with the bitmap font FONT.


[Method]
free-font (font sdl-font) => result


Free's the resources allocated to the FONT.


[Generic function]
free-rectangle rectangle => result


Free's the resources allocated to RECTANGLE. Specifically free's the wrapped SDL_Rect foreign object.


[Method]
free-rectangle (rectangle rectangle) => result


Frees the resources allocated to the rectangle RECTANGLE.


[Method]
free-rectangle (rectangle null-rectangle) => result


Does nothing. A NULL-RECTANGLE cannot be freed.


[Generic function]
free-rwops rwops => result


Free's the resources allocated to RWOPS. Specifically free's the wrapped SDL_rwops foreign object.


[Method]
free-rwops (rwops rwops) => result


Free's the wrapped foreign SDL_rwops object.


[Generic function]
free-surface surface => result


Free's the resources allocated to SURFACE. Specifically free's the wrapped SDL_Surface foreign object.


[Method]
free-surface (surface surface) => result


Free the foreign SDLSurface and the SDLRect used for position. Also free the SDL_Rect used as the cell mask.


[Method]
free-surface (surface sdl-surface) => result



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


Returns the green component of color COLOR as an INTEGER.


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


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


[Function]
get-clip-rect &key surface rectangle => result



[Function]
get-native-window => result


Returns a foreign pointer to the native SDL display window.


[Generic function]
get-point object => result


Returns the X and Y coordinates of object OBJ as a POINT.


[Method]
get-point (object sdl-surface) => result


Returns the X and Y position coordinates of the surface SURFACE as a POINT.


[Method]
get-point (object rectangle) => result


Returns the X and Y coordinates of rectangle RECTANGLE as a POINT.


[Method]
get-point (object vector) => result


Returns the point POINT.


[Generic function]
get-position object => result


See GET-POINT


[Method]
get-position (object sdl-surface) => result


See GET-POINT.


[Method]
get-position (object rectangle) => result


See GET-POINT


[Generic function]
get-rectangle rectangle => result



[Method]
get-rectangle (rectangle rectangle) => result


Returns the rectangle RECTANGLE.


[Function]
get-surface-rect &key surface rectangle => result



[Generic accessor]
height obj => result
(setf (height obj) value)


Returns the height of the object.


[Specialized accessor]
height (obj sdl-font) => result
(setf (height (obj sdl-font)) value)


Returns the INTEGER height of the cached surface SURFACE in FONT.


[Specialized accessor]
height (obj sdl-surface) => result
(setf (height (obj sdl-surface)) value)


Returns the height of the surface SURFACE as an INTEGER.


[Specialized accessor]
height (obj rectangle) => result
(setf (height (obj rectangle)) value)


Returns the INTEGER height of the rectangle RECTANGLE.


[Function]
init-sdl &optional init => result


Initalizes the SDL library when the OPTIONAL parameter INIT is T, or the value returned by SDL-INIT-ON-STARTUP is T.


[Function]
init-sub-systems &optional flags => result


Initializes the SDL subsystems specified in FLAGS. FLAGS is an INTEGER bitmask containing the logior of zero or more of: SDL-INIT-EVERYTHING, SDL-INIT-VIDEO, SDL-INIT-CDROM, SDL-INIT-AUDIO, SDL-INIT-TIMER, SDL-INIT-JOYSTICK, SDL-INIT-EVENTTHREAD and SDL-INIT-NOPARACHUTE.

INIT-SUB-SYSTEMS can be called only after SDL is succesfully initialized by INIT-SDL.


[Function]
initialise-default-font &optional font-definition => result


Calls INITIALISE-FONT to create a new BITMAP-FONT from FONT-DEFINITION. FONT-DEFINITION is set to *font-8x8* if unspecified. Binds the symbol *DEFAULT-FONT* to the new font. Reutns the new font, or NIL if the font cannot be created.


[Function]
initialise-font font-definition => result


Creates a new BITMAP-FONT object from the font data in FONT-DEFINITION. Returns the new bitmap font, or NIL if the font cannot be created. FONT-DEFINITION must be one of the following built-in fonts: *FONT-10X20*, *FONT-5X7*, *FONT-5X8*, *FONT-6X10*, *FONT-6X12*, *FONT-6X13*, *FONT-6X13B*, *FONT-6X13O*, *FONT-6X9*, *FONT-7X13*, *FONT-7X13B*, *FONT-7X13O*, *FONT-7X14*, *FONT-7X14B*, *FONT-8X13*, *FONT-8X13B*, *FONT-8X13O*, *FONT-8X8*, *FONT-9X15*, *FONT-9X15B*, *FONT-9X18* OR *FONT-9X18B*.


[Function]
initialize-on-startup &rest flags => result


Sets the SDL subsystems that must be initialized in subsequent calls to INIT-SUB-SYSTEMS.

Parameters
Returns
Example
(INITIALIZE-ON-STARTUP SDL:SDL-INIT-VIDEO SDL:SDL-INIT-CDROM)


[Function]
initialized-sub-systems-p => result


Returns a list of the initialized SDL subsystems.


[Function]
is-valid-ptr pointer => result


Returns T if pointer is not NULL and is a valid CFFI pointer to a foreign object.


[Function]
key= key1 key2 => result



[Function]
list-modes flags &optional surface => result


Returns a LIST of vectors sorted largest to smallest that contains the width and height dimensions of the screen that will support the pixel format of the specified surface SURFACE and video flags FLAGS. LIST-MODES must be called after SDL is initialised using INIT-SDL or WITH-INIT.

Parameters
Returns
Example
(LIST-MODES '(SDL-HW-SURFACE SDL-FULLSCREEN))


[Function]
list-sub-systems flag => result


Returns a list of SDL subsystems that are specified in FLAGS.

FLAGS is an INTEGER bitmask containing the logior of zero or more of: SDL-INIT-EVERYTHING, SDL-INIT-VIDEO, SDL-INIT-CDROM, SDL-INIT-AUDIO, SDL-INIT-TIMER, SDL-INIT-JOYSTICK, SDL-INIT-EVENTTHREAD and SDL-INIT-NOPARACHUTE.


[Generic function]
load-image source &key key-color alpha-value image-type force free => result


Creates and returns a new surface from the source SOURCE.

Parameters
Returns


[Method]
load-image (source string) &key key-color alpha-value image-type force free => result


Load a BMP image from a file at location FILENAME.

Parameters


[Generic function]
map-color color &optional surface => result


Maps the color COLOR to the pixel format of the surface SURFACE and returns the pixel value that best approximates the color value of the surface SURFACE. If the surface has a palette (8-bit) the index of the closest matching color in the palette will be returned. If the surface has an alpha component it will be returned as all 1 bits (fully opaque). If the surface color depth is less than 32-bpp then the unused upper bits of the return value can safely be ignored (e.g., with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).


[Method]
map-color (color color-a) &optional surface => result


Maps the RBGA color COLOR to the pixel format of the surface SURFACE and returns the pixel value that best approximates the color value of the surface SURFACE. If the surface has a palette (8-bit) the index of the closest matching color in the palette will be returned. If thesurface has no alpha component the alpha value will be ignored (as it will be in formats with a palette). If the surface color depth is less than 32-bpp then the unused upper bits of the return value can safely be ignored (e.g., with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).


[Method]
map-color (color color) &optional surface => result


Maps the RBG color COLOR to the pixel format of the surface SURFACE and returns the pixel value that best approximates the color value of the surface SURFACE. If the surface has a palette (8-bit) the index of the closest matching color in the palette will be returned. If the surface has an alpha component it will be returned as all 1 bits (fully opaque). If the surface color depth is less than 32-bpp then the unused upper bits of the return value can safely be ignored (e.g., with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).


[Generic function]
pack-color color => result


Packs the color components in COLOR into a four byte INTEGER.


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


Packs the RGBA color components in color into a four byte INTEGER.


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


Packs the RGB color components in color into a four byte INTEGER.


[Function]
point &key x y => result


Creates a new POINT set to the specified horizontal X and vertical Y coordinate.


[Generic function]
point-* point => result


Returns the X and Y coordinates of the object as a spread. The RESULT is (VALUES X Y)


[Method]
point-* (point sdl-surface) => result


Returns the X and Y position coordinates of the surface SURFACE as a spread.


[Method]
point-* (point rectangle) => result


Returns the X and Y coordinates of the rectangle RECTANGLE as a spread. The RESULT is (VALUES X Y)


[Method]
point-* (point vector) => result


Returns the X and Y coordinates of the point POINT as a spread.


[Generic function]
position-* obj => result


See POINT-*


[Method]
position-* (obj sdl-surface) => result


See POSITION.


[Method]
position-* (obj rectangle) => result


See POINT-*


[Method]
position-* (obj vector) => result


See POINT-*.


[Function]
push-quit-event => result


Pushes a new SDL_Event of type :SDL-QUIT-EVENT onto the event queue.


[Function]
push-user-event &key code data1 data2 => result


Pushes a new SDL_Event of type :SDL-USER-EVENT onto the event queue.


[Function]
query-cursor => result


Queries the current state of the cursor. Returns T if the cursor is enabled and shown on the display. Returns NIL if the cursor is disabled and hidden.


[Function]
quit-on-exit &rest flags => result


Sets one or more SDL subsystems that must be uninitialized in subsequent calls to QUIT-SUB-SYSTEMS.

Parameters
Returns
Example
(QUIT-ON-EXIT SDL:SDL-INIT-VIDEO SDL:SDL-INIT-CDROM)


[Function]
quit-sdl &optional quit => result


Uninitalizes the SDL library when the OPTIONAL parameter QUIT is T, or the value returned by SDL-QUIT-ON-EXIT is T.


[Function]
quit-sub-systems &optional flags => result


Uninitializes the SDL subsystems specified in the INTEGER bitmask FLAGS. FLAGS contains the logior of zero or more of: SDL-INIT-EVERYTHING, SDL-INIT-VIDEO, SDL-INIT-CDROM, SDL-INIT-AUDIO, SDL-INIT-TIMER, SDL-INIT-JOYSTICK, SDL-INIT-EVENTTHREAD, SDL-INIT-NOPARACHUTE.

QUIT-SUB-SYSTEMS can be called only after SDL is successfully intialized using INIT-SDL.


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


Returns the red component of color COLOR as an INTEGER.


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


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


[Function]
random+1 rnd => result


Returns a random number in the range 0 > num <= rnd.


[Function]
random-rectangle bound-w bound-h &optional rectangle => result


Creates and return s a new RECTANGLE of random x, y width and height within the specified bounds of width BOUND-W and height BOUND-H. RECTANGLE if unset will force the creation of a new RECTANGLE object. RECTANGLE if set will be modified with the coordinates.


[Function]
read-point point &key clipping-p surface => result



[Standard class]
rectangle


A RECTANGLE object manages the foreign SDL_Rect object.


[Function]
rectangle &key x y w h fp null => result


Creates a new RECTANGLE from the specified X, Y, width W and height H. If FP&#039; is NIL then a foreign SDL_Rect is created. If FP is a pointer to a foreign SDL_Rect object then FP is used. If NULL is NIL, then a new RECTANGLE is returned. If NULL not NIL` then a NULL-RECTANGLE` is created.


[Generic function]
rectangle-* obj => result


Returns the X, Y, WIDTH and HEIGHT coordinates of the object as a spread. The RESULT is (VALUES X Y WIDTH HEIGHT)


[Method]
rectangle-* (obj sdl-surface) => result


Returns the X, Y, WIDTH and HEIGHT values of the surface SURFACE as a spread. The RESULT is (VALUES X Y WIDTH HEIGHT)


[Method]
rectangle-* (obj rectangle) => result


Returns the X, Y, WIDTH and HEIGHT coordinates of the rectangle RECTANGLE as a spread. The RESULT is (VALUES X Y WIDTH HEIGHT)


[Function]
rectangle-from-edges p1 p2 &optional rectangle => result


See RECTANGLE-FROM-EDGES-*.


[Function]
rectangle-from-edges-* x1 y1 x2 y2 &optional rectangle => result


Returns a new RECTANGLE using the bounds specified by the INTEGERSX1, X2, Y1 and Y2. The coordinates of the rectangle are X = X1, Y = Y1, WIDTH = (- X2 X1), HEIGHT = (- Y2 Y1)

Parameters


[Function]
rectangle-from-midpoint-* x y w h &optional rectangle => result


Returns a RECTANGLE of width W and height H with the rectangle mid-point at coordinates X and Y. RECTANGLE if unset will force the creation of a new RECTANGLE object. RECTANGLE if set will be modified with the coordinates.


[Function]
render-string-shaded string fg-color bg-color &key font free cache => result


Render the string STRING using font FONT with text color FG-COLOR and background color BG-COLOR to a new SURFACE. The dimensions of the new surface are height == FONT height, and width == FONT width * STRING length. The surface background is filled with BG-COLOR so the surface cannot be keyed over other surfaces. Use :CACHE T to cache the new surface in the FONT object. When :FREE T any exisiting cached surface in FONT is automatically freed. When :FREE NIL the caller is responsible for freeing any existing cached surface in FONT.

Parameters
Returns
Example
(RENDER-STRING-SHADED &quot;Hello World!&quot; F-COLOR B-COLOR)


[Function]
render-string-solid string &key font color free cache => result


Render the string STRING using font FONT with text color COLOR to a new SURFACE. The dimensions of the new surface are height == FONT height, and width == FONT width * STRING length. The surface background is transparent and therefore can be keyed over other surfaces. Use :CACHE T to cache the new surface in the FONT object. When :FREE T any exisiting cached surface in FONT is automatically freed. When :FREE NIL the caller is responsible for freeing any existing cached surface in FONT.

Parameters
Returns
Example
(DRAW-STRING-SOLID &quot;Hello World!&quot; :COLOR A-COLOR)


[Function]
return-sub-systems-of-status flags status => result


Returns the status STATUS of the the specified SDL subsystems in FLAGS as an INTEGER bitmask.

Parameters
Returns


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


Returns a new SURFACE rotated 0, 90, 180, or 270 degrees.

Parameters


[Standard class]
rwops


A wrapper around a foreign SDL_RWops object.


[Function]
save-image surface filename => result


Saves the surface SURFACE as a BMP image to a file at location FILENAME.


[Constant]
sdl-any-format


Applies to DISPLAY-SURFACE.

Normally, if a DISPLAY-SURFACE of the requested bits-per-pixel (bpp) is not available, SDL will emulate one with a shadow surface. Passing SDL-ANY-FORMAT prevents this and causes SDL to use the DISPLAY-SURFACE surface, regardless of its pixel depth.


[Constant]
sdl-async-blit


Applies to DISPLAY-SURFACE.

Asynchronous blits usually slows down blitting on single CPU machines, but may provide a speed increase on SMP systems.


[Standard class]
sdl-color


Root class defining an SDL color. All colors in SDL must inherit from this class.


[Constant]
sdl-doublebuf


Applies to DISPLAY-SURFACE.

Calling SDL-FLIP will flip the buffers and update the screen. All drawing will take place on the surface that is not displayed at the moment. If double buffering could not be enabled then SDL-FLIP will just perform a SDL-UPDATE-RECT on the entire screen.


[Constant]
sdl-fullscreen


Applies to DISPLAY-SURFACE.


[Function]
sdl-get-ticks => result



[Constant]
sdl-hw-accel


Applies to SURFACE and DISPLAY-SURFACE.


[Constant]
sdl-hw-palette


Applies to SURFACE and DISPLAY-SURFACE.

Without this flag you may not always get the the colors you request with SDL-SET-COLORS or SDL-SET-PALETTE.


[Constant]
sdl-hw-surface


Applies to SURFACE and DISPLAY-SURFACE.

This will allow SDL to take advantage of Video->Video blits (which are often accelerated).


[Constant]
sdl-init-audio



[Constant]
sdl-init-cdrom



[Constant]
sdl-init-eventthread



[Constant]
sdl-init-everything



[Constant]
sdl-init-joystick



[Constant]
sdl-init-noparachute



[Function]
sdl-init-on-startup => result


Returns T if the SDL library must be initialised in INIT-SDL, or WITH-INIT. Returns NIL otherwise.


[Constant]
sdl-init-timer



[Constant]
sdl-init-video



[Constant]
sdl-iyuv-overlay



[Constant]
sdl-no-frame


Applies to DISPLAY-SURFACE.

Fullscreen modes automatically have this flag set.


[Constant]
sdl-opengl


Applies to DISPLAY-SURFACE.


[Constant]
sdl-pre-alloc


Applies to SURFACE.


[Function]
sdl-quit-on-exit => result


Returns T if the SDL library must be uninitialised in QUIT-SDL, or WITH-INIT. Returns NIL otherwise.


[Constant]
sdl-resizable


Applies to DISPLAY-SURFACE.

When the window is resized by the user a :VIDEO-RESIZE-EVENT event is generated and WINDOW can be called again with the new size.


[Constant]
sdl-rle-accel


Applies to SURFACE

RLE acceleration can substantially speed up blitting of images with large horizontal runs of transparent pixels (i.e., pixels that match the key color). The key must be of the same pixel format as the surface, MAP-COLOR is often useful for obtaining an acceptable value.


[Constant]
sdl-rle-accel-ok


Applies to SURFACE.


[Constant]
sdl-src-alpha


Applies to SURFACE.


[Constant]
sdl-src-color-key


Applies to SURFACE.


[Standard class]
sdl-surface


A wrapper for a foreign object of type SDL_Surface. A SDL-SURFACE object contains:


[Constant]
sdl-sw-surface


Applies to SURFACE and DISPLAY-SURFACE.

This improves the performance of pixel level access, however you may not be able to take advantage of some types of hardware blitting.


[Constant]
sdl-uyvy-overlay



[Constant]
sdl-yuy2-overlay



[Constant]
sdl-yv12-overlay



[Constant]
sdl-yvyu-overlay



[Function]
set-alpha alpha &key surface rle-accel => result


Adjust the alpha ALPHA properties of a surface SURFACE. Also enables or disables alpha blending.

Parameters
Alpha effects

Alpha has the following effect on surface blitting:

Note: When blitting, the presence or absence of SDL-SRC-ALPHA is relevant only on the source surface, not the destination.

Note: Note that RGBA to RGBA blits (with SDL-SRC-ALPHA 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.

Note: Also note that per-pixel and per-surface alpha cannot be combined; the per-pixel alpha is always used if available.


[Function]
set-cell rectangle &key surface => result



[Function]
set-cell-* x y w h &key surface => result



[Function]
set-clip-rect rectangle &key surface => result



[Generic function]
set-color dst src => result


Copies the RGB/A color components to teh destination color DST from the source color SRC.


[Method]
set-color (dst sdl-color) (src sdl-color) => result


Copies the color components from the source color SRC to the destination color DST.


[Generic function]
set-color-* color &key r g b a => result


Sets the red R, green G, blue B and alpha A components of the color COLOR. R, G, B and A are KEYword parameters having default values of 0 if unspecified.


[Method]
set-color-* (color sdl-color) &key r g b a => result


Sets the components of the color COLOR to the red R, green G, blue BLUE or alpha A color components.


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


Sets the color key (transparent pixel) COLOR in a blittable surface SURFACE.

Paremeters


[Function]
set-frame-rate rate => result



[Generic function]
set-point dst src => result


Copies the X and Y coordinates to the destination DST from the source SRC.


[Method]
set-point (dst sdl-surface) (src vector) => result


Sets the X and Y position coordinates of the surface SURFACE. POSITION is a POINT.


[Method]
set-point (dst rectangle) (src vector) => result


Copies the X and Y coordinates to the destination rectangle RECTANGLE from the source point POSITION.


[Method]
set-point (dst vector) (src vector) => result


Sets the X and Y coordinates of the destination point DST to the coordinates in the source point SRC. Returns the destination point DST.


[Generic function]
set-point-* obj &key x y => result


Sets the X and Y coordinates of the object OBJ. X and Y are KEYword parameters.


[Method]
set-point-* (obj sdl-surface) &key x y => result


Sets the X and Y position coordinates of the surface SURFACE. X and Y are INTEGERS.


[Method]
set-point-* (obj rectangle) &key x y => result


Sets the X and Y coordinates of the rectangle RECTANGLE. X and Y are KEYword parameters.


[Method]
set-point-* (obj vector) &key x y => result


Sets the X and Y coordinates of the point POINT to X and Y.


[Generic function]
set-position dst src => result


See SET-POINT


[Method]
set-position (dst sdl-surface) (src vector) => result


See SET-POINT.


[Method]
set-position (dst rectangle) (src vector) => result


Sets the X and Y coordinates of the rectangle RECTANGLE from the point POSITION.


[Method]
set-position (dst vector) (src vector) => result


See SET-POINT.


[Generic function]
set-position-* obj &key x y => result


See SET-POINT-*


[Method]
set-position-* (obj sdl-surface) &key x y => result


See SET-POINT-*.


[Method]
set-position-* (obj rectangle) &key x y => result


Sets the X and Y coordinates of the rectangle RECTANGLE. X and Y are KEYword parameters.


[Method]
set-position-* (obj vector) &key x y => result


See SET-POINT-*.


[Generic function]
set-rectangle dst src => result


Copies the X, Y, WIDTH and HEIGHT coordinates to the destination rectangle DST from the source rectangle SRC.


[Method]
set-rectangle (dst rectangle) (src rectangle) => result


Copies the X, Y, WIDTH and HEIGHT coordinates to the destination rectangle DST from the source rectangle SRC.


[Generic function]
set-rectangle-* rectangle &key x y w h => result


Sets the X, Y, WIDTH and HEIGHT coordinates of the rectangle RECTANGLE. X, Y, WIDTH and HEIGHT are KEYword parameters having default values of 0 if unspecified.


[Method]
set-rectangle-* (rectangle rectangle) &key x y w h => result


Sets the coordinates of the rectangle RECTANGLE to the specified X, Y , width W and height HEIGHT coordinates. X, Y, W and H are KEYword parameters of type INTEGER. Returns the rectangle RECTANGLE as RESULT.


[Generic function]
set-surface surface position => result


Sets the coordinates of the surface SURFACE to POSITION, where position is of type POINT.


[Method]
set-surface (surface sdl-surface) (position vector) => result


Sets the coordinates of the surface SURFACE to POSITION, where position is of type POINT.


[Generic function]
set-surface-* surface &key x y => result


Sets the coordinates of the surface SURFACE. X and Y are KEYword parameters having default values of 0 if unspecified.


[Method]
set-surface-* (surface sdl-surface) &key x y => result


Sets the coordinates of the surface SURFACE to the spead X and YINTEGER coordinates. X and Y are KEYword parameters having default values of 0 if unspecified.


[Function]
show-cursor state => result


Disables the cursor when state is NIL, otherwise enables the cursor.


[Standard class]
surface


A subclass of 'SDL-SURFACE' that holds a standard SDL_Surface object. This object will be garbage collected and the surface freed when out of scope.


[Function]
surface surface-fp &optional display => result


Creates a new SURFACE or a new DISPLAY-SURFACE when DISPLAY is T. SURFACE-FP must be a pointer to a valid SDL_Surface foreign object.


[Function]
surface-info surface &optional info => result


Returns information about the SDL surface SURFACE.

Parameters
Returns

INFO when NIL will return a list of all enabled surface flags. Otherwise will return the status of INFO as T or NIL if supported by the surface.

Example
(SURFACE-INFO A-SURFACE &#039;(SDL-HW-SURFACE SDL-HW-PALETTE SDL-HW-ACCELL))


[Function]
to-degree radian => result


Converts radians to degrees.


[Function]
to-radian degree => result


Converts degrees to radians.


[Function]
update-display &optional surface => result


When OPENGL-CONTEXT is NIL; UPDATE-DISPLAY will flip the SDL video buffers and update the screen SURFACE if SDL-HW-SURFACE is set in WINDOW. If double buffering is not enabled then SDL will perform an SDL-UPDATE-RECT on the entire screen.

When OPENGL-CONTEXT is T; UPDATE-DISPLAY will call SDL-GL-SWAP-BUFFERS to update the OpenGL display context.

SURFACE is bound to *DEFAULT-DISPLAY* if unspecified.


[Function]
update-surface surface &optional template => result



[Function]
update-surface-* surface x y w h => result



[Function]
video-driver-name => result


Returns the driver name of the initialised video driver. The driver name is a STRING containing a one-word identifier like "x11" or "windib". Returns 'NIL' if the video driver is not already initialised with INIT-SDL or WITH-INIT.

Example
(sdl:with-init ()
  (sdl:video-driver-name))
&gt;&gt; &quot;windib&quot;


[Function]
video-info info => result


Returns information about the video hardware. GET-VIDEO-INFO must be called after SDL is initialised using INIT-SDL or WITH-INIT. If GET-VIDEO-INFO is called before WINDOW, the information returned is of the best video mode. If GET-VIDEO-INFO is called after WINDOW, the information returned is of the current video mode.

Parameters
Example
(video-info :video-mem)


[Generic accessor]
width obj => result
(setf (width obj) value)


Returns the width of the object.


[Specialized accessor]
width (obj sdl-font) => result
(setf (width (obj sdl-font)) value)


Returns the INTEGER width of the cached surface SURFACE in FONT.


[Specialized accessor]
width (obj sdl-surface) => result
(setf (width (obj sdl-surface)) value)


Returns the width of the surface SURFACE as an INTEGER.


[Specialized accessor]
width (obj rectangle) => result
(setf (width (obj rectangle)) value)


Returns the INTEGER width of the rectangle RECTANGLE.


[Function]
window width height &key bpp flags title-caption icon-caption => result


Creates a new SDL window of pixel width WIDTH and height HEIGHT using SDL_SetVideoMode.

Use SDL-SW-SURFACE if you plan on doing per-pixel manipulations, or blit surfaces with alpha channels, and require a high framerate. When you use hardware surfaces like SDL-HW-SURFACE, SDL copies the surfaces from video memory to system memory when you lock them, and back when you unlock them. This can cause a major performance hit. (Be aware that you may request a hardware surface, but receive a software surface. Many platforms can only provide a hardware surface when using SDL-FULL-SCREEN.) SDL-HW-SURFACE` is best used when the surfaces you'll be blitting can also be stored in video memory.

Note: To control the position on the screen when creating a windowed surface, set the environment variables SDL_VIDEO_CENTERED=center or SDL_VIDEO_WINDOW_POS=x,y. These may be set using SDL-PUT-ENV.

Parameters
Returns
Example
(WINDOW 320 240 :TITLE-CAPTION &quot;Random-Rects&quot; :ICON-CAPTION &quot;Random-Rects&quot;
                 :FLAGS &#039;(SDL-DOUBLEBUF SDL-FULLSCREEN))


[Macro]
with-bezier (shape-type &optional segments) declaration* statement* => result


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

The number of segments SEGENTS used to draw the Bezier curve defaults to 10. The greater the number of segments, the smoother the Bezier curve.

Local Methods

A vertex may be added using:

ADD-VERTEX and ADD-VERTEX-* are valid only within the scop of WITH-BEZIER.

Parameters
Example
(SDL:WITH-COLOR (COL (SDL:COLOR))
   (WITH-BEZIER (30)
     (ADD-VERTEX-* 60  40)
     (ADD-VERTEX-* 160 10)
     (ADD-VERTEX-* 170 150)
     (ADD-VERTEX-* 60  150)))


[Macro]
with-color (var &optional color free-p) declaration* statement* => result


A convience macro that binds *DEFAULT-COLOR* to VAR within the scope of WITH-COLOR. VAR is set to COLOR when COLOR is not NIL.VAR must be of type SDL-COLOR. VAR is freed using FREE-COLOR when FREE-P is not NIL.


[Macro]
with-curve (shape-type &optional segments) declaration* statement* => result


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

Local Methods

A vertex may be added using:

ADD-VERTEX and ADD-VERTEX-* are valid only within the scope of WITH-CURVE.

Parameters
Example
(SDL:WITH-COLOR (COL (SDL:COLOR))
   (WITH-CURVE (:LINE-STRIP 30)
     (ADD-VERTEX-* 60  40)
     (ADD-VERTEX-* 160 10)
     (ADD-VERTEX-* 170 150)
     (ADD-VERTEX-* 60  150)))


[Macro]
with-default-font (font) declaration* statement* => result


Sets *DEFAULT-FONT* to the bitmap font in FONT within the scope of WITH-DEFAULT-FONT.

Example
(WITH-DEFAULT-FONT (new-font)
    (DRAW-CHARACTER-SHADED-* &quot;Hello World!&quot; 0 0 F-COLOR B-COLOR))


[Macro]
with-events (&optional type) declaration* statement* => result


WITH-EVENTS is a convenience macro for managing the main game loop. It processes incoming SDL events and limits the game loop to the specified number of frames per second.

Both the SDL-POLL-EVENT and SDL-WAIT-EVENT event mechanisms are supported by specifying the TYPE as :POLL or :WAIT respectively.

NOTE:WITH-EVENTS must be called in the same thread used to set the video mode.

Example
(SDL:WITH-EVENTS (:POLL)
  (:QUIT-EVENT () T)
  (:KEY-DOWN-EVENT (:KEY KEY)
      (WHEN (SDL:KEY= KEY :SDL-KEY-ESCAPE)
        (SDL:PUSH-QUIT-EVENT)))
  (:VIDEO-EXPOSE-EVENT () (SDL:UPDATE-DISPLAY))))))
Frame Rate Limiting

The frame rate is specified using FRAME-RATE. For example to set the frame rate to 60 frames per second:

(SETF (SDL:FRAME-RATE) 60)
Event Syntax

Events are specified using the format (:EVENT-TYPE (&amp;KEYS KEYS))

NOTE::QUIT-EVENT must return T to exit the WITH-EVENT macro.

NOTE::IDLE is ignored when TYPE is :WAIT.

Polling for Events

When TYPE is :POLL, WITH-EVENTS will continually poll for currently pending events. If no events are available then the game loop is run and the forms in :IDLE are executed.

Waiting for Events

When TYPE is :WAIT, WITH-EVENTS will sleep indefinitely for the next available event. If no events are available then the game loop is paused.

The :IDLE Event
 (:IDLE ()
    &amp;BODY BODY)

The :IDLE event is special in that it is not generated by SDL. Rather the forms in :IDLE are executed once each game loop after event queue is emptied. :IDLE is ignored when the event mechanism specified by TYPE is :WAIT.

Active Event
(:ACTIVE-EVENT (:GAIN GAIN :STATE STATE) 
   &amp;BODY BODY)

When the mouse leaves or enters the window area an SDL-APP-MOUSE-FOCUS type activation event is generated. If the mouse has entered the window then GAIN will be 1, otherwise GAIN will be 0. An SDL-APP-INPUT-FOCUS type activation event occurs when the application loses or gains keyboard focus, usually when a different application is made active. Finally, an SDL-APP-ACTIVE type event occurs when the application is either minimised/iconified, GAIN is 0, or restored. A single event can have multiple values set in STATE. Note: This event does not occur when an application window is first created.

Keyboard Events
(:KEY-DOWN-EVENT (:STATE STATE :SCANCODE SCANCODE :KEY KEY :MOD MOD :UNICODE UNICODE)
   &amp;BODY BODY)
(:KEY-UP-EVENT (:STATE STATE :SCANCODE SCANCODE :KEY KEY :MOD MOD :UNICODE UNICODE)
   &amp;BODY BODY)

A keyboard event generally occurs when a key is released or when a key is pressed. The information on the key that generated the event is stored in KEY and MOD.

The SDL-CAPS-LOCK and SDL-NUM-LOCK keys are special cases and report an SDL-KEY-DOWN when first pressed, then an SDL-RELEASED when released and pressed again. These keys KEYUP and KEYDOWN events are therefore analogous to the state of the caps lock and num lock LEDs rather than the keys themselves. These special cases are required for compatibility with Sun workstations.

Note: Repeating SDL-KEY-DOWN events will occur if key repeat is enabled using SDL-ENABLE-KEY-REPEAT.

Mouse Motion Event
(:MOUSE-MOTION-EVENT (:STATE STATE :X X :Y Y :X-REL X-REL :Y-REL Y-REL)
   &amp;BODY BODY)

A MOUSE-MOTION-EVENT event occurs when the mouse moves within the application window or when SDL-WARP-MOUSE is called. Both the absolute X and Y and relative X-REL and Y-REL coordinates are reported along with the current button state STATE. The button state can be interpreted using SDL-BUTTON, see SDL-GET-MOUSE-STATE.

If the cursor is hidden using SDL-SHOW-CURSOR and the input is grabbed using SDL-WM-GRAB-INPUT, then the mouse will give relative motion events even when the cursor reaches the edge of the screen. This is currently only implemented on Windows and Linux/Unix-alikes.

Mouse Button Events
 (:MOUSE-BUTTON-DOWN-EVENT (:BUTTON BUTTON :STATE STATE :X X :Y Y)
   &amp;BODY BODY)
 (:MOUSE-BUTTON-UP-EVENT (:BUTTON BUTTON :STATE STATE :X X :Y Y)
   &amp;BODY BODY)

When a mouse button press or release is detected the number of the button pressed (from 1 to 255, with 1 usually being the left button and 2 the right) is placed into BUTTON, the position of the mouse when this event occured is stored in the X and the Y fields.

Mouse wheel events are reported as buttons 4 (up) and 5 (down). Two events are generated i.e. a SDL-MOUSE-BUTTON-DOWN followed by a SDL-MOUSE-BUTTON-UP event.

Joystick Motion Event
(:JOY-AXIS-MOTION-EVENT (:WHICH WHICH :AXIS AXIS :VALUE VALUE)
   &amp;BODY BODY)

A JOY-AXIS-MOTION-EVENT event occurs whenever a user moves an axis on the joystick.

Joystick Button Events
(:JOY-BUTTON-DOWN-EVENT (:WHICH WHICH :BUTTON BUTTON :STATE STATE)
   &amp;BODY BODY)
(:JOY-BUTTON-UP-EVENT (:WHICH WHICH :BUTTON BUTTON :STATE STATE)
   &amp;BODY BODY)

A JOY-BUTTON-DOWN-EVENT or JOY-BUTTON-DOWN-EVENT event occurs whenever a user presses or releases a button on a joystick.

Joystick Hat Motion Event
   (:JOY-HAT-MOTION-EVENT (:WHICH WHICH :HAT HAT :VALUE VALUE)
     &amp;BODY BODY)

A JOY-HAT-MOTION-EVENT event occurs when ever a user moves a hat on the joystick.

Joystick Ball Motion Event
(:JOY-BALL-MOTION-EVENT (:WHICH WHICH :BALL BALL :X-REL X-REL :Y-REL Y-REL)
  &amp;BODY BODY)

A JOY-BALL-MOTION-EVENT event occurs when a user moves a trackball on the joystick. Trackballs only return relative motion.

Quit Event
(:QUIT-EVENT () 
   &amp;BODY BODY)

If QUIT-EVENT is filtered or ignored then it is impossible for the user to close the window. If QUIT-EVENT is accepted and returns T then the application window will be closed. Note: Screen updates will continue to report success even though the application is no longer visible. If QUIT-EVENT is accepted and returns NIL then the application window will not be closed. SDL_QUIT-REQUESTED will return non-zero if a QUIT-EVENT event is pending.

SDL Window Resize Event
(:VIDEO-RESIZE-EVENT (:W W :H H)
   ...)

When SDL-RESIZABLE is passed as a flag to WINDOW, the user is allowed to resize the application window. When the window is resized a VIDEO-RESIZE-EVENT event is reported, with the new window width and height values stored in W and H respectively. When an VIDEO-RESIZE-EVENT event is recieved the window should be resized to the new dimensions using WINDOW.

SDL Window Expose Event
(:VIDEO-EXPOSE-EVENT ()
   ...)

VIDEO-EXPOSE-EVENT is triggered when the screen has been modified outside of the application, usually by the window manager, and needs to be redrawn.

System Window Events
(:SYS-WM-EVENT () 
   ...)

The system window manager event contains a pointer to system-specific information about unknown window manager events. If this event is enabled using SDL-EVENT-STATE, it will be generated whenever unhandled events are received from the window manager. This can be used, for example, to implement cut-and-paste in your application. If you want to obtain system-specific information about the window manager, you can fill in the version member of a SDL-SYS-WM-INFO structure using SDL-VERSION, and pass it to the function: SDL-GET-WM-INFO

User
(:USER-EVENT (:TYPE TYPE :CODE CODE :DATA1 DATA1 :DATA2 DATA2)
   ...)

USER-EVENT is unique in that it is created by the user not SDL. USER-EVENT can be pushed onto the event queue using PUSH-USER-EVENT. The contents of the event are completely up to the programmer.

Syntax
(WITH-EVENTS (TYPE)
 (:ACTIVE-EVENT (:GAIN GAIN :STATE STATE) 
    ... )
 (:KEY-DOWN-EVENT (:STATE STATE :SCANCODE SCANCODE :KEY KEY :MOD MOD :UNICODE UNICODE)
    ... )
 (:KEY-UP-EVENT (:STATE STATE :SCANCODE SCANCODE :KEY KEY :MOD MOD :UNICODE UNICODE)
    ...)
 (:MOUSE-MOTION-EVENT (:STATE STATE :X X :Y Y :X-REL X-REL :Y-REL Y-REL)
    ...)
 (:MOUSE-BUTTON-DOWN-EVENT (:BUTTON BUTTON :STATE STATE :X X :Y Y)
    ...)
 (:MOUSE-BUTTON-UP-EVENT (:BUTTON BUTTON :STATE STATE :X X :Y Y)
    ...)
 (:JOY-AXIS-MOTION-EVENT (:WHICH WHICH :AXIS AXIS :VALUE VALUE)
    ...)
 (:JOY-BUTTON-DOWN-EVENT (:WHICH WHICH :BUTTON BUTTON :STATE STATE)
    ...)
 (:JOY-BUTTON-UP-EVENT (:WHICH WHICH :BUTTON BUTTON :STATE STATE)
    ...)
 (:JOY-HAT-MOTION-EVENT (:WHICH WHICH :HAT HAT :VALUE VALUE)
    ...)
 (:JOY-BALL-MOTION-EVENT (:WHICH WHICH :BALL BALL :X-REL X-REL :Y-REL Y-REL)
    ...)
 (:VIDEO-RESIZE-EVENT (:W W :H H)
    ...)
 (:VIDEO-EXPOSE-EVENT ()
    ...)
 (:SYS-WM-EVENT () 
    ...)
 (:USER-EVENT (:TYPE TYPE :CODE CODE :DATA1 DATA1 :DATA2 DATA2)
    ...)
 (:QUIT-EVENT () 
    ... 
    T)
 (:IDLE ()
    ... ))


[Macro]
with-font (font font-definition) declaration* statement* => result


Creates a new bitmap font BITMAP-FONT and sets *DEFAULT-FONT* to the bitmap font in FONT within the scope of WITH-FONT. Frees the bitmap font when WITH-FONT goes out of scope.

Example
(WITH-FONT (new-font *font-8x8*)
    (DRAW-CHARACTER-SHADED-* &quot;Hello World!&quot; 0 0 F-COLOR B-COLOR))


[Macro]
with-init flags declaration* statement* => result


WITH-INIT is a convenience macro that will attempt to initialise the SDL library and SDL subsystems prior to executing the forms in BODY. Upon exit WITH-INIT will uninitialize the SDL library and SDL subsystems.

The lispbuilder-sdl initialization routines are somewhat complicated by the fact that a Lisp development environment will load a foreign library once but then initialise and uninitialise the library multiple times. A C/C++ development environment will open and then close a library after each execution, freeing all resources left hanging by incomplete or buggy uninitialise functions. C libraries may therefore frequently core dump in a Lisp environment when resources are not feed properly prior to the library being reinitialized.

LISPBUILDER-SDL provides functionality affording the programmer a finer granularity of control of the initialisation/uninitialisation of foreign libraries. The fuctions that provide these capabilities are as follows:

Defaults
Initialisation/Uninitialisation of the SDL library

The SDL library is initialised only:

The SDL library is uninitialised only:

Initialisation/Uninitialisation of external libraries

Hooks are provided to allow external libraries to be initialized or uninitialised automatically following the initialisation or uninitialisation of the SDL library.

To initialise an external library, push a function that initialises the external library onto *EXTERNAL-INIT-ON-STARTUP*. The function must take no arguments. For example:

(defun init-ttf ()
   (if (is-init)
     t
     (sdl-ttf-cffi::ttf-init)))
(pushnew &#039;init-ttf sdl:*external-init-on-startup*) 

To uninitialise an external library, push a function that uninitialises the external library onto *EXTERNAL-QUIT-ON-EXIT*. The function must take no arguments. For example:

(defun quit-ttf ()
   (if (is-init)
     (sdl-ttf-cffi::ttf-quit)))
(pushnew &#039;quit-ttf sdl:*external-quit-on-exit*)
Parameters
Example
(with-init (SDL-INIT-VIDEO SDL-INIT-CDROM SDL-INIT-AUDIO)
  ....)
(with-init ()
  (INITIALIZE-ON-STARTUP SDL-INIT-VIDEO SDL-INIT-CDROM SDL-INIT-AUDIO)
  (QUIT-ON-EXIT SDL-INIT-VIDEO SDL-INIT-CDROM SDL-INIT-AUDIO)
  ....)


[Macro]
with-locked-surface (var &optional surface) declaration* statement* => result



[Macro]
with-locked-surfaces bindings &rest body => result



[Macro]
with-point (var &optional point) declaration* statement* => result


A convenience macro that binds *DEFAULT-POINT* to VAR within the scope of WITH-POINT. VAR must be of type POINT. If POINT is not NIL, then VAR is set to POINT`.


[Macro]
with-rectangle (var &optional rectangle free-p) declaration* statement* => result


A convenience macro that binds *DEFAULT-RECTANGLE* to VAR within the scope of WITH-RECTANGLE. VAR must be of type RECTANGLE. VAR is set to RECTANGLE when RECTANGLE is not NIL. VAR is freed when FREE-P is T.

Example
(WITH-RECTANGLE (a-rect (RECTANGLE :x 0 :y 0 :w 100 :h 100))
    ...)


[Macro]
with-rectangles bindings declaration* statement* => result


A convenience macro that binds multiple rectangles as per WITH-RECTANGLE.

Example
(WITH-RECTANGLES ((a-rect (RECTANGLE :x 0 :y 0 :w 100 :h 100))
                  ((b-rect (RECTANGLE :x 0 :y 100 :w 100 :h 100))
                  ((c-rect (RECTANGLE :x 0 :y 200 :w 100 :h 100)))
    ...)


[Macro]
with-shape (shape-type) declaration* statement* => result


Draw a polygon of color *DEFAULT-COLOR* to the surface *DEFAULT-SURFACE*.

Local Methods

A vertex may be added using:

ADD-VERTEX and ADD-VERTEX-* are valid only within the scop of WITH-SHAPE.

Parameters
Example
(SDL:WITH-COLOR (COL (SDL:COLOR))
   (WITH-SHAPE (:POINTS)
     (ADD-VERTEX-* 60  40)
     (ADD-VERTEX-* 160 10)
     (ADD-VERTEX-* 170 150)
     (ADD-VERTEX-* 60  150)))


[Macro]
with-surface (var &optional surface free-p) declaration* statement* => result



[Macro]
with-surface-slots (var &optional surface) declaration* statement* => result



[Macro]
with-surfaces bindings &rest body => result



[Function]
within-range p1 p2 distance => result


Returns true T, if the distance between the POINTs P1P2 is <= the distance DISTANCE.


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


Returns true T, if the distance between the coordinates X1, Y1 and X2, Y2 is <= the distance DISTANCE.


[Generic accessor]
x obj => result
(setf (x obj) value)


Returns the x coordinate of the object.


[Specialized accessor]
x (obj sdl-font) => result
(setf (x (obj sdl-font)) value)


Returns the X position of the cached surface SURFACE in FONT.


[Specialized accessor]
x (obj sdl-surface) => result
(setf (x (obj sdl-surface)) value)


Returns the x position coordinate of the surface SURFACE as an INTEGER.


[Specialized accessor]
x (obj rectangle) => result
(setf (x (obj rectangle)) value)


Returns the X position coordinate of the rectangle RECTANGLE as an INTEGER.


[Specialized accessor]
x (obj vector) => result
(setf (x (obj vector)) value)


Returns the X coordindate of the point POINT as an INTEGER.


[Generic accessor]
x2 obj => result
(setf (x2 obj) value)


Returns (+ X WIDTH) of the object.


[Specialized accessor]
x2 (obj rectangle) => result
(setf (x2 (obj rectangle)) value)


Sets the WIDTH of the rectangle RECTANGLE to (- X2 X)


[Generic accessor]
y obj => result
(setf (y obj) value)


Returns the y coordinate of the object.


[Specialized accessor]
y (obj sdl-font) => result
(setf (y (obj sdl-font)) value)


Returns the Y position of the cached surface SURFACE in FONT.


[Specialized accessor]
y (obj sdl-surface) => result
(setf (y (obj sdl-surface)) value)


Returns the y position coordinate of the surface SURFACE as an INTEGER.


[Specialized accessor]
y (obj rectangle) => result
(setf (y (obj rectangle)) value)


Returns the Y position coordinate of the rectangle RECTANGLE as an INTEGER.


[Specialized accessor]
y (obj vector) => result
(setf (y (obj vector)) value)


Returns the Y coordindate of the point POINT as an INTEGER.


[Generic accessor]
y2 obj => result
(setf (y2 obj) value)


Returns (+ Y HEIGHT) of the object.


[Specialized accessor]
y2 (obj rectangle) => result
(setf (y2 (obj rectangle)) value)


Returns (+ Y HEIGHT) of the rectangle RECTANGLE.


 

Acknowledgements

BACK