The sdl2kit Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The sdl2kit Reference Manual

This is the sdl2kit Reference Manual, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:33:47 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

sdl2.kit

This is a utility kit for cl-sdl2 that provides something similar to GLUT. However, it's also geared at being useful for "real" applications or games.

At the moment, this includes the following functionality:

For an example, see examples/sdl2kit.lisp.

Windows

To make a new window, you simply create a subclass of WINDOW or GL-WINDOW, and implement the WINDOW protocol. You should primarily specialize on WINDOW:

NOTE: INITIALIZE-INSTANCE requires you CALL-NEXT-METHOD first, or simply define your method as :AFTER. (This is due to method ordering being most-specific-first.)

Of these, you should only call RENDER or CLOSE-WINDOW from user code. However, these can be called from any thread safely.

By default, windows do not render continuously, but only when RENDER is called, or when an expose event is received. You may do the following to enable idle rendering:

(setf (idle-render WINDOW) t)

You may do this at any time, and also set it to NIL to disable idle rendering.

Render Disable

When an unhandled error happens in RENDER, this could lead to unpleasant effects: often a long string of errors until the window is close, or the error is fixed, especially if IDLE-RENDER is enabled.

However, sdl2kit will automatically disable window rendering if such an error occurs. This will prevent further errors from occurring. To re-enable or check the status of rendering, use the following:

Note that this only prevents rendering; events and other callbacks will still be active. This makes it easy to close a window if desired before fixing the issue.

Startup Functions and Making Binaries

While you can call (kit.sdl2:start) and (make-instance 'my-window) manually, you should define a startup function. This will ease a number of things:

(define-start-function run-my-game (&key (w 1280) (h 720))
  (sdl2:gl-set-attr :context-major-version 3)
  (sdl2:gl-set-attr :context-minor-version 3)
  (sdl2:gl-set-attr :context-profile-mask 1)
  (sdl2:gl-set-attr :stencil-size 8)
  (make-instance 'game-window :w w :h h))

This wraps the function in SDL2:IN-MAIN-THREAD, as well as pre- and post-initialization.

This is convenient, but it's even more important for making binaries. When you dump a lisp image, this makes sure the initialization and startup of cl-sdl2 and sdl2kit are in the right order.

Typically when you dump a binary, you define a "toplevel function" to be called. It should look something like this:

(save-my-lisp
 :toplevel-function
 (lambda () (sdl2:make-this-thread-main 'run-my-game)))

This will prevent additional threads from being created (unless your game makes them itself), and everything should run and exit seamlessly (but see below). (RUN-MY-GAME) should also work normally in Sly or SLIME.

Implementation specifics

It's worth noting that in some lisp implementations, all SDL and OpenGL calls must be made from the main thread. The examples/rotating-cube.lisp can be run as follows:

(ql:quickload :sdl2kit-examples)

(sdl2.kit:define-start-function cube-test (&key (w 800) (h 500))
  (sdl2:gl-set-attr :stencil-size 8)
  (sdl2:gl-set-attr :context-profile-mask 1)
  (sdl2:gl-set-attr :context-major-version 3)
  (sdl2:gl-set-attr :context-minor-version 3)
  (make-instance 'kit.sdl2.test:cube-window :w w :h h))

(sdl2:make-this-thread-main #'cube-test)

Exiting

Quitting sdl2kit can by done with (kit.sdl2:quit). This also quits cl-sdl2, calling (sdl2:quit). Normally, you should not need to do this during development, or if you're running things in Sly or SLIME. However, if you're making a binary, you probably want your game to exit! In this case, calling (kit.sdl2:quit) during CLOSE-WINDOW or some other event should be sufficient to exit, if you're using a startup function as above.

Build integration is coming soon, so it's easy to tell whether you're running "as a binary" or not. Currently to do this, you will need to set some flag yourself during the build process, which is also available during normal runs.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 sdl2kit

Author

Chip Collier <photex@lofidelitygames.com>

License

MIT

Description

A utility kit for SDL2

Dependencies
Source

sdl2kit.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 sdl2kit.asd

Location

/home/quickbuilder/quicklisp/dists/quicklisp/software/sdl2kit-20171130-git/sdl2kit.asd

Systems

sdl2kit (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 sdl2kit/package.lisp

Parent

sdl2kit (system)

Location

package.lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 sdl2kit/window.lisp

Dependency

package.lisp (file)

Parent

sdl2kit (system)

Location

window.lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 sdl2kit/keyboard.lisp

Dependency

window.lisp (file)

Parent

sdl2kit (system)

Location

keyboard.lisp


Previous: , Up: Lisp files   [Contents][Index]

3.1.5 sdl2kit/main.lisp

Dependency

keyboard.lisp (file)

Parent

sdl2kit (system)

Location

main.lisp


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   S  
Index Entry  Section

F
File, Lisp, sdl2kit.asd: The sdl2kit<dot>asd file
File, Lisp, sdl2kit/keyboard.lisp: The sdl2kit/keyboard<dot>lisp file
File, Lisp, sdl2kit/main.lisp: The sdl2kit/main<dot>lisp file
File, Lisp, sdl2kit/package.lisp: The sdl2kit/package<dot>lisp file
File, Lisp, sdl2kit/window.lisp: The sdl2kit/window<dot>lisp file

L
Lisp File, sdl2kit.asd: The sdl2kit<dot>asd file
Lisp File, sdl2kit/keyboard.lisp: The sdl2kit/keyboard<dot>lisp file
Lisp File, sdl2kit/main.lisp: The sdl2kit/main<dot>lisp file
Lisp File, sdl2kit/package.lisp: The sdl2kit/package<dot>lisp file
Lisp File, sdl2kit/window.lisp: The sdl2kit/window<dot>lisp file

S
sdl2kit.asd: The sdl2kit<dot>asd file
sdl2kit/keyboard.lisp: The sdl2kit/keyboard<dot>lisp file
sdl2kit/main.lisp: The sdl2kit/main<dot>lisp file
sdl2kit/package.lisp: The sdl2kit/package<dot>lisp file
sdl2kit/window.lisp: The sdl2kit/window<dot>lisp file

Jump to:   F   L   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions


Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables


Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   S  
Index Entry  Section

S
sdl2kit: The sdl2kit system
System, sdl2kit: The sdl2kit system

Jump to:   S