Java for SDL is a binding for SDL written in java.


Table Of Contents

  1. Java for SDL

    1. About JSDL - what is it?
    2. About SDL
    3. Core Features - what can it do?
    4. Extensions

  2. Javadoc structure

    1. (J)SDL Architecture and API
    2. Package Examples
    3. Test Examples

  3. Developing in JSDL

    1. JSDL Basics
    2. Environment

  4. API Overview

    1. Initilializing SDL - sdl.core.Main
    2. Video - sdl.video.SDLSurface
    3. Video - sdl.video.SDLPixelFormat
    4. Events - sdl.event
    5. Audio - sdl.audio




Java for SDL



About JSDL
Java for SDL is a binding for SDL written in java. Now you can use SDL and still program with Java.  For more information, refer to the project website at http://jsdl.sourceforge.net    

Java's bindings are written in C to support JNI and Linux. This C part should be easily portable to other platforms. SDL itself (not JSDL) currently supports Linux, Win32, BeOS, MaxOS, Solaris, IRIX and FreeBSD.

About SDL ( copied from SDL toc)
The project homepage of SDL is located at  http://www.libsdl.org/.


JSDL  Core Features

 Like core SDL, JSDL provides a set of interfaces to do the following
JSDL Extensions

A number of multimedia extensions have been added to the SDL API.  Currently the following SDL extensions have been wrapped by JSDL bindings.

Javadoc Structure - where to look for API and samples



(J)SDL Architecture

SDL is composed of eight subsystems
Each subsytem has a corresponding API and must be initialized before use.

* Subsystem is handled by Java + JSDL runtime, developer need not interact with SDL API's directly.

Package Examples

Each subsystem correponds to a java package.  The naming convention is sdl.subsystem or sdl.extension.  Typically, each package overview will describe the SDL subsystem and provide some sample code on how to use the subsystem.  For example, the Package overview for sdl.audio describes how to work with the SDL Audio subsystem.

Test Examples

The unit tests and demos are located in the sdl.test package. The have been added to the JSDL java docs to provide further examples on how to code with JSDL.





Developing in JSDL




JSDL Development Basics

JSDL development mirrors standard SDL coding.  The SDL official web site has API documentation and tutorials that are esstential in understanding how to develop using the Java SDL bindings.  

Because of the similarity in syntax and implementation, the SDL "C" APIs / tutorials can be easily translated into JSDL java code.

JSDL Environment

JSDL requires Java and SDL to run.  JSDL is comprised of
libSDL4Java.so must be added to the java.library.path.  The easiest way to do this is to run java with the following arguments.
java  -Djava.library.path=$JSDL_BASE
where $JSDL_BASE is the directory containing this library.
jsdl.jar must be added to the classpath when compiling and testing your JSDL application.

A typical set of build / test commands would look something like

JSDL_BASE=/home/sstraw/build/jsdl
cd sdl/test
javac  -classpath .:$JSDL_BASE TestVideo.java
cd ../..
java  -Djava.library.path=$JSDL_BASE:/usr/lib -classpath .:$JSDL_BASE/build sdl.test.TestVideo.java


API Overview



JSDL Runtime Interface - sdl.core.Main
The core of any JSDL app starts with an instance of the sdl.core.Main class to initialize the JSDL runtime environment.

Main sdl = new Main();
int result = sdl.SDLInit(Main.SDL_INIT_VIDEO);
Next, we need to initialize the video buffer through the java.video.Video class, and retreive a reference to the "SDLSurface" object. The "surface" object is our interface to the framebuffer itself. (We will discuss surfaces later)
Video video = new Video();
SDLSurface surface = video.setVideoMode(640,480,16);
When are finished with our SDL routines, we (should) free whatever resources we've consumed,  unlock the framebufffer, etc.  This is done through the following method in the "Main" object.
sdl.SDLQuit()

Surfaces
Surfaces represent the buffer you will read and write "raw" pixels to.  A surface may refer to the acutal graphics device,
SDLSurface surface = video.setVideoMode(640,480,16);
or may refer to an offscreen image buffer.  
SDLSurface image = SDLImage.createFromFile("/tmp/icon23.jpg");
Since surfaces in JSDL have built in buffering, it is necessary to "update" the surface so the changes are pushed to the actual graphics device.
surface.updateRawPixels();
surface.updateRect(0,0,0,0);

Pixels and PixelFormat
Low level drawing to the surface is done by defining pixels.  Each Pixel is an integer (int,  long or short) that represents a RGB color value.  The number of bits used by this long is determined by the color depth.  Attributes like color depth and bitmasks used to extract color component information are stored in the SDLPixelFormat class.  It is very helpful to review the JSDL test examples and the SDL documentation.

The following code creates a pixel with a pixel depth greater than 8 bits.  (8 bit color is a special case)
public static short createHiColor(SDLPixelFormat fmt, byte red, byte green, byte blue)
    {
        short value =  (short) (((red >> fmt.m_RLoss) << fmt.m_RShift) + ((green >> fmt.m_GLoss) << fmt.m_GShift) + ((blue >> fmt.m_BLoss) << fmt.m_BShift));
        return value;
    }


An alternative convenience routine creates a pixel value based on the color depth of an arbitrary surface.
int colorkey = surface.mapRGB((byte)0,(byte)0,(byte)0) ;

Events
JSDL presents SDL events as standard Java events. However the JSDL Event mechanism is based on the SDL Event subsystem.   Thus JSDL Event development incorporates aspects of both Standard Java Events and SDL Events.

JSDL supports the following types of events.
Classes that will listen to JSDL events must implement the sdl.event.SDLEventListener interface and create this single method,
public boolean incomingEvents(SDLCustomEvent event) throws SDLEventException;

Audio
JSDL provides a set of classes to control the audio device and to load/play audio streams.  Refer to the javadocs on use of the following classes

jsdl4scott 09/22/02