Welcome to the first tutorial on using the Lightweight Java Game Library created by these Java wizards.
A lot of work has gone into the library to effectively create an environment within the Java runtime capable of supporting high speed access to the display and input devices that games rely on.

As you may or may not know, Java runs in a self-contained virtual machine on a variety of operating systems and platforms.
If your goal is to maximize platform support for your game, while at the same time minimizing the headaches due to
crafting cross-platform code, then you would need some solid arguments for not choosing Java.

The reference section at the end of this tutorial has some other links which go into further details aimed at
easing your fears about using Java for games.

The LWJGL Code

Before diving into working with OpenGL to draw objects using your hardware, there is some groundwork when dealing
with LWJGL. For those not too familiar with the Lightweight Java Game Library, at a very loose level
it can be thought of as a library for the Java Runtime, in the same vein as DirectX is a game library for Windows.

The whole point of LWJGL is to tuck away the unneccessary lower level display and input code, in order to provide
you with the fastest possible access to these devices which games rely on.

Browsing through the project source code will provide a working example of what we are trying to accomplish
with our tiny LWJGL framework, but I’ll try to explain the basic principles here.

The main workhorse of the sample, is the GameWindow object which is the kernel in our application
and provides our Java entry point. In a lot of ways, the main use of LWJGL to get a basic game loop up and running
is not really any different from our DirectX or SDL tutorials in C++.

try {
  // find out what the current bits per pixel of the desktop is
  int currentBpp = Display.getDisplayMode().getBitsPerPixel();

  // find a display mode at 800x600
  DisplayMode mode = findDisplayMode(800, 600, currentBpp);

  // if can't find a mode, then bail!
  if (mode == null) {
    Sys.alert("Error", "800x600x" + currentBpp +
      " display mode unavailable");
    return;
  }

  // configure and create the LWJGL display
  Display.setTitle("LWJGL-getting-started");
  Display.setDisplayMode(mode);
  Display.setFullscreen(false);

  Display.create();

  init();
} catch (LWJGLException e) {

  e.printStackTrace();
  Sys.alert("Error", "Failed: "+e.getMessage());

}

Upon starting up the main object, we first use LWJGL to query the current bits per
pixel our main desktop. Once we obtain this value, we use it to attempt to create
a valid OpenGL context of 800×600 by enumerating the display modes available to LWJGL and then
selecting the one that fits our requirements.

private DisplayMode findDisplayMode(int width, int height, int bpp)
  throws LWJGLException {

  DisplayMode[] modes = Display.getAvailableDisplayModes();
  DisplayMode mode = null;

  for (int i=0;i < modes.length; i++) {

    if ((modes[i].getBitsPerPixel() == bpp) || (mode == null)) {

      if ((modes[i].getWidth() == width) &&
        (modes[i].getHeight() == height)) {

        mode = modes[i];

      }
    }
  }

  return mode;
}

After setting a few other LWJGL window parameters, we finally create it.

Next, we need to go through a bit of work to prepare our OpenGL context for
rendering.

Finally, we’re ready to put the application into its main workhorse game loop. With
every pass through the loop, we’re first clearing the OpenGL backbuffer to prepare
it for drawing. Normally we would also pass in all of our desired objects we want
to render, with a call to flip the OpenGL backbuffer to the front. However, since
there’s nothing to draw in this tutorial, we go right ahead
to the end of our main loop. LWJGL checks to see if we have requested to close
the application, by closing the window for example. If no such signal has been
detected, we will loop around to the beginning of the loop.

public void gameLoop() {
  boolean gameRunning = true;

  while (gameRunning) {

    GL11.glClear(GL11.GL_COLOR_BUFFER_BIT | GL11.GL_DEPTH_BUFFER_BIT);

    Display.update();

    // if the user has requested that the window be closed, either
    // pressing ALT-F4 on windows, or clicking the close button
    // on the window - then we want to stop the game
    if (Display.isCloseRequested()) {
      gameRunning = false;
      System.exit(0);
    }
  }
}

Running the Sample (on Windows)

Simply unzip the included project zip folder and launch the run-win32.bat batch file from the command prompt. Note that an existing Java runtime will need to be already in the system path.

Resources

lwjgl-EmptyProject