[Java-game-lib-cvs] CVS: LWJGL/doc/tutorial index.html,NONE,1.1

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/java-game-lib/LWJGL/doc/tutorial
In directory usw-pr-cvs1:/tmp/cvs-serv28445/doc/tutorial

Added Files:
	index.html 
Log Message:
Rough incomplete draft

--- NEW FILE: index.html ---
CVS Browser:
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/java-game-lib/LWJGL/doc/tutorial/index.html
<html>

<head>
<meta http-equiv="Content-Language" content="en-gb">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Lightweight Java Game Library Tutorial Index</title>
<style>
<!--
.document_title { text-align: Center; font-size: 24pt; letter-spacing: 4 }
.code_snippet { font-family: Courier New }
-->
</style>
</head>

<body>

Lightweight Java Game Library
Tutorial
Written by Caspian Rychlik-Prince
Please direct comments, errata, and flames to the author at <a href="mailto:ci...@us...">ci...@us...</a>
Last modified 23 August 2002

&nbsp;
<a name="Introduction">1.0 Introduction</a>
The Lightweight Java Game Library (LWJGL) is a solution aimed directly at
professional and amateur Java programmers alike to enable commercial quality
games to be written in Java. This tutorial is nonetheless aimed at experienced
programmers and won't be explaining some obvious techniques. Currently the
LWJGL supports only the Win32 platform, and JDK1.4.&nbsp;
LWJGL is not meant to make writing games particularly easy; it is
primarily an enabling technology which allows developers to get at
resources that are simply otherwise unavailable or poorly implemented on the
existing Java platform. We anticipate that the LWJGL will, through evolution and
extension, become the foundation for more complete game libraries and &quot;game
engines&quot; as they have popularly become known, and hide some of the new
evils we have had to expose in the APIs.
2.0 Contents
&nbsp;
3.0 Aims &amp; Design
Because the LWJGL API is not meant to be a fully featured game engine it has
been ruthlessly pruned of all non-essential code. Its ultimate philosophy is
that it provides the bare minimum of API functionality which will let a
game programmer produce games in Java without having to write native code in
order to get performance or access some hardware feature not exposed
by Java 2. We settled on using two other open technologies as our major
foundations, namely OpenGL and OpenAL for graphics and sound respectively.
A sub-requirement of the LWJGL is that it be freed Java programmers from the
requirement to ship a whole JRE with their games. Currently the Sun licensing
terms dictate that J2SE be shipped in its entirety, even for the tiniest of
demos. As this could easily triple the size of a demo and discourage end users
with configuration issues we have made it a primary concern that games written
using LWJGL can be compiled into completely standalone native binary executables
by compilers such as GNU's GCJ and Excelsior's JET. We have done this by
implementing the library in such a way that no dependencies on Sun's
proprietry JRE binaries are present in the library.
The final aim of LWJGL is to make the library available for Win32 systems
above all others, for that is what most commercial programmers need.
Linuxians and Macophiles do not despair! There's nothing inherently
non-portable about the LWJGL - we just don't have the time and expertise to do
it yet. But it will happen.
3.1 General API
The general API gives us the foundations of game programming: we have a
Display class, for initialising the display and querying its available modes; we
have a Math class to provide us with some floating point maths functions (rather
than the double-precision ones provided by Java), and matrix batch operations;
and a Sys class, which gives us our most useful gaming functions: the
ability to get the address of a direct byte buffer so we can cache it on the
Java side of the JNI barrier, and hence access all those lovely hardware calls
we need for performance; and the ability to use the system's hires timer,
which is so critical for animation timing. In addition we can also create a
direct byte buffer at any address in memory.
The Evil Of Pointers And What It Means For Security
Yes, we have exposed pointers to Java programmers. Yes, you can write
to just about any bit of memory you so please, and cause untold havoc. You can
break things. You can bypass security constraints and exploit the dreaded buffer
vuln.
But why? Because without pointers, all those nice easy native API
calls would suddenly become complex and behave slightly differently to their C
counterparts, and require us to pass direct ByteBuffers to JNI for every call.
This requires that every single call which takes a pointer calls the JNI method
GetDirectBufferAddress every time, which is an unnecessary overhead.
The implications for security are simple and final: your game can no
longer be considered secure and part of the Java security model. This puts
it in exactly the same boat as any other application on the user's system. This
also means you will not be able to use it in applets or with Webstart without
getting your code signed and trusted. LWJGL itself will not be signed nor
trusted; you are expected to deliver it bundled in with every application you
ship and verify that your entire distribution is safe.
We feel that our target developer, the commercial game developer, should not
be concerned with this issue as the status quo is merely maintained from the old
ways of programming with any other language; and used wisely, your exposure to
pointers is unlikely to cause you any problems.
If you are concerned about security, or wish to write games which will run as
applets or from Webstart, or would rather have a full game library which takes
care of things for you, you don't want to use LWJGL at all - it's that simple!
What you need is Sun's Java Gaming Profile, or Java3D. If you feel a need to
argue, you're using LWJGL for the wrong reasons.
3.2 Graphics
Graphics is based on the latest OpenGL1.4, and all the extensions we could
implement that might be vaguely useful for games programmers. These include all
of Nvidia's and ATI's proprietry extensions, and all the ARB extensions,
and most of the EXT extensions, as well as numerous other miscellaneous ones.
For Windows programmers, our primary target, the WGL extensions are present.
All OpenGL functions that take pointers are passed ints. These pointers can
be obtained from direct ByteBuffers using the Sys.getDirectBufferAddress()
method. There are a very few native methods that return pointers as ints as
well. Be sure to read the caveat about using pointers in Java!
3.3 Sounds
Sound is based on the latest OpenAL1.0 specification, which comes with but
one extension, EAX, for interesting environmental effects. The LWJGL binary
distribution includes the OpenAL .dlls for Win32.
3.4 Input
Input can be a complicated topic. A user can have all sorts of strange fancy
force-feedback hardware installed on their systems, with scrolly knobs and
twistgrips and bristling with many buttons. However, the vast majority of gamers
have just a keyboard and a mouse; some of them have analogue joysticks too, and
some of them have a gamepad attached from some console or other. For our first
cut of the input library we've just kept it all rather simple, and decided that
there is but one of each of these devices, and that force feedback and multiple
potentiometers is a feature we may add another time.
So in the interests of keeping things simple, the four input classes -
Keyboard, Mouse, Gamepad and Joystick - are all static, and can all be polled
once per game loop iteration to determine where they've moved since you last
looked and what buttons are down at the time. The Gamepad and Keyboard may
additionally support buffering which is a more reliable way of detecting
rapid changes of state which may occur rather more quickly than your framerate.
3.5 Maths
Java's maths performance leaves much to be desired, particularly with respect
to bulk operations for 3D rendering engines. The main problem is that the
existing maths libraries use double precision when single precision is entirely
adequate for most realtime games programming; and that no clever
processor-specific optimisations can be done because the Hotspot compiler is
simply not supplied enough semantic context to understand that it could use some
special SIMD instruction to achieve the effect you desire in a fraction of the
cycles. Furthermore, all maths in Java is done in Java - and once you've
computed the results you usually have to subsequently copy them into a buffer to
pass to a native rendering method in OpenGL anyway.
The Math class provides two totally generic vector operators for unary
and binary vector operations performed on direct ByteBuffers containing packed
floating point vectors. The idea is to set up the source(s) of the operations
and then perform a single call to JNI to perform a highly optimised operation
on the whole lot in one go. The JNI code is specially optimised for the common
cases in 3d games programming to use processor-specific instructions and take
advantage, where feasible, of memory caching architecture. And the end result is
placed directly back in memory, ready to simply send as a pointer direct to
OpenGL or some other API.
In addition we provide implementations of common Vector and Matrix sizes
similar to those provided by the javax.vecmath package, but ours are open
source and available without downloading the whole of Java3D.
&nbsp;

</body>

</html>