c o r e   a p i

tl tr
introduction
The core api is my suggestion for a way to produce fast performing graphics using Java.
But why you may ask? Well I was tired of always implementing the same methods, creating the same animation loop and other trivial routines each time I wanted to make a new applet
- something I found quite tedious. I also wanted to do my own graphical routines (drawing a straight line is not that simple a task as one may think) and not use SUN's awt and 2D/3D api's.

To sum it up, this is what the core api gives you:

- An easy way of creating new applets
- Fast access to the screen through an array
- An easy and safe way of fetching graphics
- Flicker free animation loop
- Fps calculations (optional)
- A 32-bit direct color model with optional alpha blending
- A way of putting one pixel on the screen..... (I'm not kidding)


overview
The core api consists of three classes:
1/ AppletCore which gives you the animation loop
2/ ScreenCore which gives you fast direct access to the screen
3/ ImageLibCore which takes care of loading graphics for you if needed by your application.

core_api.jpg

applet core
This is the class you must extend to create your own applet. It only has 2 protected methods (which you must implement) and 3 mandatory instance variables. The rest has default values, so there is not much for you to remember!
In the following I will describe the use and function of variables and methods.

Mandatory fields:
screen: This is an association (reference) to the ScreenCore class. The ScreenCore class' function is to create the graphics, which is displayed in the applet. So basically you use this variable to get access to setting pixels.

width/height: The size of the applet

Optional fields:
refreshRate: How long is the delay between each frame, i.e. for how long shall the Thread (animation loop) sleep between each update? The higher the number the longer the Thread will sleep.

calcFps: Set this to true if you want to know how many fps you applet is running with.

fps: The actual fps value can be read in this variable. If calcFps is set to false then the value is 0

tripleBuffering: If set to true the applet will call the updateBackBuffer method after the screen-array has been painted. This will give you access to the awt methods of the Graphics class, e.g. drawString.
The entire screen will be painted flicker free. Using this method will cost you a few fps.
It is properly easier to understand this if you look at template code....

offscreen: If tripleBuffering is set to true then this is the Graphics on which you paint your additional things (do it in the updateBackBuffer method)


Methods:
init: This is the place where you set-up the environment needed for your applet and other initializing code. You are required to assign values to refreshRate, width and height. You must also create screen on which you set your pixels.

refreshRate = 20;
width = 640;
height = 480;

// The false parameter indicates if alpha blending is needed or not
screen = new ScreenCore(width, height, false);


render: This is the place to put your rendering code. The following coool code sets a blue pixel at position (100,100). -- You would properly want to do a little more than this, but hey its a start....

screen.setPixel(100,100,0x0000ff)


updateBackbuffer: In this method you can use Java's awt classes e.g. to draw tekst on top of your applet. Note that the method is called AFTER the screenArray is painted!
The screen will remain flicker free unlike if the Applets update method is overwritten (look at the template for examples). The instance variable calcFps must be set to true (do it in the init method) otherwise this method will not be called. Example:

offscreen.drawString("Hello World", 0, 10);


screen core
This is the class that gives you fast access to the screen. This is done through an array representing pixels on the screen.

Fields:
width/height: The size of the applet. These values are set when the class is instantiated (done in the init method from "YourCoolApplet")

screenArray: This is the int array representing pixels on the screen. You can set pixel values through here or by using the setPixel method.

Methods:
ScreenCore: The constructor takes three arguments: width, height and if alpha-blending is used or not.

setPixel: Use this method to set a single pixel at a x,y position. The pixel is only set if it is inside the defined screen dimensions.

clearScreen: Clears the screen using the defined value.

getUpdatedImage: This method is called from the AppletCore right before the new pixels are painted. You do not need (to think about) this one.

getHeight: Returns the height of the picture

getWidth: Returns the width of the picture



imagelib core
This class is used to safely load a picture (using MediaTracker) from either a local store or from the web. The picture is stored as pixels in an int array.

Methods:
ImageLibCore: The constructor takes a String argument with the placement of the picture to load.
This code shown how to fetch a picture first locally and then from the web:

imLib = new ImageLibCore("gfx/C64logo.gif");

imLib = new ImageLibCore("http://www.devnull.dk/graphics/C64logo.gif");


getImageHeight: Returns the height of the picture

getImageWidth: Returns the width of the picture

getpixels: Returns an int array containing the pixel representation of the picture. To use the picture you must copy the pixels to your screenArray, this can be done like this (done from within "yourCoolApplet"):

imLib = new ImageLibCore("http://www.devnull.dk/graphics/C64logo.gif");
int i = 0;
for (int y = 0; y < imLib.getImageHeight(); y++) {
  for (int x = 0; x < imLib.getImageWidth(); x++) {
     int px = pixels[x + y * imLib.getImageWidth()];
     backbuffer[i++] = px;
  }
}




Files

bl br