mkLibsdl 1.0 Manual

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted. The author makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. By use of this software the user agrees to indemnify and hold harmless the author from any claims or liability for loss arising out of such use.

mkLibsdl 1.0 - A package for joystick and CD-ROM control, based on the SDL library.

Introduction
Commands
Notes
Examples
Installation
Changes
Author

INTRODUCTION

mkLibsdl wraps a certain part of the SDL library for the Tcl world: the joystick module and the CD-Rom module.

What is SDL? Here's a quote from their web site: 'Simple DirectMedia Layer is a cross-platform multimedia library designed to provide low level access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL, and 2D video framebuffer. It is used by MPEG playback software, emulators, and many popular games,[...]'

From this all, mkLibsdl wraps the joystick and the CD-ROM module. Most of the other parts of SDL are already covered by Tcl/Tk or by other packages. Note that the term 'joystick' should read 'game controller', since SDL is not limited to the stick part but also handles balls, hats and buttons usually found on game controllers.

COMMANDS

joystick ?args ...?

This command lets you query your connected joysticks and their control elements: buttons, balls, axis and hats. It also comes with a new event handler type for joysticks, whose handling is much like that of the fileevent command.

joystick count

This command returns the number of connected joysticks. If you connect or disconnect joysticks while your Tcl program is running, then this is not detected by the SDL library. You need to call joystick rescan instead, see below.

joystick names

This returns a regular Tcl list with the names of all connected joysticks. It's the name, with which you identify a joystick, not the position in the list. joystick count and llength [joystick names] are equivalent.

joystick index pattern

Convenience function to help identify a joystick. The command returns the numeric index of the joystick whose name matches the given glob-style and case-insensitve pattern. This index is used in all subsequent commands and must range between 0 and [joystick count]-1. If no joystick matches the pattern, or if more than one joystick matches the pattern, an error is returned.

joystick name index

Convenience function to return the name of the joystick with a given index. The equivalent to it is lindex [joystick names] index, but this one has some error handling.

joystick rescan

Closes and re-opens all joysticks in the underlying SDL library, so that joysticks that have been disconnected or connected in the meantime are detected. Note that your indexes that were valid prior to calling joystick rescan may now be invalid! Use e.g. joystick index to identify the joysticks again, since the numerical index may have changed.

joystick info index option

This command returns information about the joystick specified by index. The option argument may be one of:

axes: Returns the number of axes of the joystick (usually 2 for each analog joystick).
balls: Returns the number of trackballs in the joystick.
hats: Returns the number of hats on the joystick (the four-way cross-shaped elements).
buttons: Returns the number of buttons on the joystick.

joystick configure index option ?value option value ...?

Configures or returns the settings for the maximum value and the dead zone of a joystick's axes. You can either pass option-value pairs to set these values, or you can pass exactly one option without a value to return the current value of the option. If you pass empty strings {} as option values, SDL's default values are set (see below). The option argument may be one of:

-maxvalue
The maximum value is the value that is returned when the stick is at its dead stop on either end. With this option you can specify or return this value. If you specify an integer, only integers are returned with joystick get and joystick event peek. If you secify a floating point value, then floating point values are returned likewise. Example: -maxvalue 1000 sets the range to -1000..1000 in integer numbers, whereas -maxvalue 1.0 sets the range to -1...1 in floating point numbers. The default value range of SDL is -32768..32767 (non symmetric!).

-deadzone
The dead zone value is the threshold, below which the stick position is always returned as 0 (zero). If the joystick is only tipped a little, you may want to supress any movement in your application. This can be achieved by setting a dead zone value. The dead zone value is always relative to the -maxvalue setting: E.g. if you configure -maxvalue 1.0 -deadzone 0.1, any value in the range of -0.1..0.1 is returned as 0. The default values of SDL is 0 (i.e., no dead zone).

joystick get index option control

This command returns the state of an element of the joystick specified by index. With the option argument you specify the control type (e.g. buttons) and with the control argument you specify which control exactly it should be (e.g. button no. 5). The option argument may be one of:

axis: Returns the position of the axis specified by control in the range set by joystick configure.
ball: Returns the relative movement of the ball specified by control as a two-element list for x and y direction.
hat: Returns the state of the hat specified by control as an ORed combination of bits: 1 for up, 2 for right, 4 for down and 8 for left.
button: Returns the state of the button specified by control: 1 for pressed, 0 for not pressed.

joystick event option ?arg ...?

This command provides an event mechanism for joysticks. You can set up a callback procedure that is evaluated every time any control on any joystick has changed its value. In the callback procedure you pick up the event data and process it. The syntax of the sub-commands is:

joystick event eval ?script?
Defines a Tcl script which is evaluated each time a joystick event occurs, and is usually a procedure. No arguments are appended to that script. If you specify an empty string, the event handler is removed. If you ommit this argument, the current script is returned.

joystick event peek
Returns the data of the joystick event, and is usually called in the event handler script. The return value is a Tcl list with keywoards and values, which is suitable for array set. The list elements are...
...for axis events: joystick index axis axis value value
...for ball events: joystick index ball ball xrel value yrel value
...for hat events: joystick index hat hat value value
...for button events: joystick index button button value value
The values of the various control types are those returned with joystick get.

joystick event poll
Almost identical to joystick event peek, except that, in addition, all joysticks are queried by SDL for new events first. This is necessary, if you do not use joystick event eval but have your own polling mechanism (e.g. because you are polling anyway already, and need to stay in a defined clock cycle). With a callback script, the underlying event handler does the joystick query internally, so you don't need to do it again and can use joystick event peek. Conversely, doing a joystick event poll instead of a joystick event peek in a callback script is of no harm.

cdrom ?args ...?

This command wraps the CD-ROM module of the SDL libary. It allows you to control and play CDs by track and even single frames.

cdrom count

This command returns the number of connected CD-ROM drives. If you connect or unplug CD-ROM drives while your Tcl program is running, then this is not detected by the SDL library. You need to call cdrom rescan instead, see below.

cdrom names

This returns a regular Tcl list with the names of all connected CD-ROM drives. It's the name, with which you identify a joystick, not the position in the list. cdrom count and llength [cdrom names] are equivalent.

cdrom index pattern

Convenience function to help identify a joystick. The command returns the numeric index of the drive whose name matches the given glob-style and case-insensitve pattern. This index is used in all subsequent commands and must range between 0 and [cdrom count]-1. If no drive matches the pattern, or if more than one drive matches the pattern, an error is returned.

cdrom name index

Convenience function to return the name of the CD-ROM drives with a given index. The equivalent to it is lindex [cdrom names] index, but this one has some error handling.

cdrom rescan

Closes and re-opens all CD-ROM drives in the underlying SDL library, so that drives that have been added or unplugged in the meantime are detected. Note that your indexes that were valid prior to calling cdrom rescan may now be invalid! Use e.g. cdrom index to identify the drives again, since the numerical index may have changed.

cdrom info index option

This command returns information about the CD-ROM drive specified by index. The option argument may be one of:

status: Returns one of trayempty, stopped, playing, paused or error. Self-explaining.
loaded: Returns 1 or 0, depending if a CD is in the drive or not.
tracks: Returns the number of data and audio tracks on the CD, if its loaded, or 0 (zero).
fps: Returns the number of frames per second. Calls to cdrom play take a frame number to play parts of a track.
current: When playing, the current track and frame is returned as a two-element list, or {0 0} when stopped.

cdrom trackinfo index trackno option

This command returns information about a particular track on a CD. The option argument may be one of:

type: Returns either audio or data for the given track. Self-explaining.
length: Returns the number of frames of the given track.
offset: Returns the starting frame of the given track, relative to the entire CD.

cdrom play index ?-track value? ?-frame value? ?-numtracks value? ?-numframes value?

Plays the CD starting at the track specified by -track (or the first track), for -numtracks tracks (or all tracks). Option -frame specifies the frame offset, from the beginning of the start track, at which to start. -numframes is the frame offset, from the beginning of the last track (track+numtracks), at which to end playing. With no arguments given, the entire CD is played from the beginning. All options default to 0 (zero). Data tracks are ignored.

cdrom stop index

Stops playing of the CD. Does nothing if the CD is not currently playing anyways.

cdrom pause index

Pauses the CD. Does nothing special if the CD is not currently playing.

cdrom resume index

Resumes playing a previously paused CD. Does nothing if the CD is not currently paused.

cdrom ejectindex

Ejects the CD.

NOTES

Credits

This extension is based on the great work that was put into SDL. Please check out the site for newest releases, ready-to-use binary downloads and documentation.

General

Since the SDL library is a cross-platform software, mkLibsdl is supposed to work on all platforms where Tcl/Tk and SDL is available.
The wrappers are rather straight, while attempting to provide a Tcl-style syntax instead of an SDL-style syntax.
I made the observation that a game controller with one hat but no analog stick lets the hat appear as a stick with two axes.
Also, I couldn't test the ball functions, because my joystick don't got balls...
I couldn't make function SDL_CDPlay() work on my computer, but SDL_CDPlayTracks() is wrapped with cdrom play

Internal

The event handler joystick event eval cannot set up callbacks for a particular joystick, because it's not supported by SDL.
The values of the joystick controls retrieved by joystick get are identical to those of SDL.
The event handler is based on polling, since the SDL function SDL_WaitEvent() does internally the same.
mkLibsdl opens and closes the joysticks and CD-ROMs (necessary in SDL) automatically.
mkLibsdl always calls SDL_CDStatus() prior to all functions where this is recommended by the SDL docs.

EXAMPLES

Identify my RumblePad game controller

    % package require mkLibsdl
    1.0
    % joystick count
    2
    % joystick names
    {Logitech Cordless RumblePad 2 USB} {Logitech(R) Precision(TM) Gamepad}
    % joystick index *logitech*
    ambiguous pattern '*logitech*'
    % joystick index *rumble*
    0
    % joystick name 0
    Logitech Cordless RumblePad 2 USB
    %

See what it's got. 4 axes means two analog joysticks.

    % joystick info 0 axes
    4
    % joystick info 0 balls
    0
    % joystick info 0 hats
    1
    % joystick info 0 buttons
    12
    %

Moving the x axis of a stick from left to right

    % joystick get 0 axis 0
    0
    % joystick get 0 axis 0
    -32768
    % joystick get 0 axis 0
    32767

Set up an event handler and test it for 10 seconds

    % joystick event eval { puts [joystick event peek] }
    % after 10000 set x 0; vwait x
    joystick 0 hat 0 value 1
    joystick 0 hat 0 value 0
    joystick 0 hat 0 value 2
    joystick 0 hat 0 value 0
    joystick 0 button 0 value 1
    joystick 0 button 0 value 0
    joystick 0 button 1 value 1
    joystick 0 button 1 value 0
    joystick 0 axis 0 value 520
    joystick 0 axis 0 value 11962
    joystick 0 axis 0 value 18203
    joystick 0 axis 1 value -513
    joystick 0 axis 0 value 27305
    joystick 0 axis 1 value -1537
    joystick 0 axis 0 value 32767
    joystick 0 axis 1 value -2049
    joystick 0 axis 1 value -2561
    joystick 0 axis 1 value -5377
    joystick 0 axis 0 value 30166
    joystick 0 axis 1 value -6145
    joystick 0 axis 0 value 26525
    joystick 0 axis 1 value -6657
    joystick 0 axis 0 value 22104
    joystick 0 axis 0 value 19244
    joystick 0 axis 0 value -1
    joystick 0 axis 1 value -1
    %

Identify my first CD-ROM drive (drive D: on Windows)

    % package require mkLibsdl
    1.0
    % cdrom count
    2
    % cdrom names
    D:\\ E:\\
    % cdrom index D:*
    0
    % cdrom name 0
    D:\
    %

Check status and the disk's content.

    % cdrom info 0 fps
    75
    % cdrom info 0 status
    stopped
    % cdrom info 0 loaded
    1
    % cdrom info 0 tracks
    25
    % cdrom trackinfo 0 23 type
    audio
    % cdrom trackinfo 0 23 length
    9378            <-- 9378 frames / fps = 130.44 seconds
    % cdrom trackinfo 0 23 offset
    245973

Play parts of the CD

    % # play entire CD
    % cdrom play 0
    % cdrom info 0 status
    playing
    % cdrom info 0 current
    0 448
    % cdrom info 0 current
    0 560
    % cdrom info 0 current
    0 672
    % cdrom stop 0  
    %
    % # play only the second track
    % cdrom play 0 -track 1 -numtracks 1
    %
    % # play the first 2 seconds of track 20
    % cdrom play 0 -track 20 -numframes 150

INSTALLATION

General

You need the SDL 1.2 runtime library to run mkLibsdl. The SDL website offers this library for a number of operating systems. For the Windows platform this library (SDL.dll) is included in the mkLibsdl distribution.

mkLibsdl is written in C and comes with a DLL for Windows. On Unix, the package needs to be compiled into a shared library first (see below). mkLibsdl works with Tcl/Tk version 8.3 and higher and is stubs-enabled.

To install, simply place the directory "mkLibsdl1.0" into one of the directories contained in the global Tcl variable "auto_path". For a standard Tcl/Tk installation, this is commonly "C:/tcl/lib" (Windows) and "/usr/local/lib" (Unix). Also make sure that the SDL runtime library is in an accessible path. For Windows the supplied DLL in the mkLibsdl directory is used automatically.

Compiling

Besides from the only mkLibdsl source file (mkLibsdl10.c) you need the development libraries and the header files. Again, you can download them from the SDL website for several platforms, or build them yourself. Check the SDL documentation on how to do that, but there seems to be a makefile for nearly every platform.

To compile mkLibsdl, just provide the correct path to "tcl.h", to "SDL.h", and link against "tcl84.lib", "SDL.lib" and "SDLmain.lib" (Windows) or "libtcl84.a", "libsdl.a" and "libsdlmain.a" (Unix) respectively. If you use stubs, define USE_TCL_STUBS and link against "tclstub84.lib" (Windows) or "libtclstub84.a" (Unix) instead.

Windows: For Visual C++, the following command should work:

    cl /MD /D USE_TCL_STUBS /I C:/Tcl/include /I C:/SDL/include /c mkLibsdl10.c
    link /subsystem:console /dll C:/Tcl/lib/tclstub84.lib C:/SDL/lib/SDL.lib C:/SDL/lib/SDLmain.lib mkLibsdl10.obj

Unix: At the moment I do not have a system on hand, so I trust that the following would work at least on Linux:

    gcc -shared -DUSE_TCL_STUBS -ltclstub8.4 -lz -o mkLibsdl10.so mkLibsdl10.c

Test

Test the installation by opening a tclsh or wish and entering "package require mkLibsdl". The string "1.0" should appear. If it fails, "cd" into the directory "mkLibsdl1.0" and load it directly with "load ./mkLibsdl10.dll" (Windows) or "load ./mkLibsdl10.so" (Unix). If no error occured, it succeeded and something must be wrong with the location of "mkLibsdl1.0".

CHANGES

No changes - Initial version.

AUTHOR

Michael Kraus
mailto:michael@kraus5.de
http://mkextensions.sourceforge.net

mkLibsdl 1.0 Manual

CONTENTS

joystick count

joystick names

joystick index pattern

joystick name index

joystick rescan

joystick info index option

joystick configure index option ?value option value ...?

joystick get index option control

joystick event option ?arg ...?

cdrom count

cdrom names

cdrom index pattern

cdrom name index

cdrom rescan

cdrom info index option

cdrom trackinfo index trackno option

cdrom play index ?-track value? ?-frame value? ?-numtracks value? ?-numframes value?

cdrom stop index

cdrom pause index

cdrom resume index

cdrom ejectindex

Credits

General

Internal

Identify my RumblePad game controller

See what it's got. 4 axes means two analog joysticks.

Moving the x axis of a stick from left to right

Set up an event handler and test it for 10 seconds

Identify my first CD-ROM drive (drive D: on Windows)

Check status and the disk's content.

Play parts of the CD

General

Compiling

Test