Tank Java2D Tutorial

This is just a trivial example of how to do java2d programming. It's basically a really crude demonstration of basic java2D concepts.

Don't let the "Tank" name fool you, this isn't anything neat. I cobbled this together as a first, really rough attempt at making a typical tank game, but I never got past the rudimentary stage. If it took over the entire screen when it ran, it'd be a bouncing ball screen-saver.

The things missing include:

• some ability for the user to control their tank
• some sort of intelligence to control the non-player tanks
• cannons
• tank-to-tank collision detection
• better tank icons

Maybe one of these days. Meanwhile, it's simple enough that I thought it'd be useful as (very) basic intro into java2d topics.

Classes

There are two class files:

• TankSimulator.java runs the show.
• Tank.java represents a tank object.

Specifically, the TankSimulator class:

• sets up a JFrame
• creates six Tank objects and adds them to the Jframe, so that when the JFrame repaints itself, it'll also repaint the tanks.
• sets the starting conditions of each tank, the location, rotation, scale, and also the shape of each tank (aka the GeneralPath)
• starts a "heartbeat" loop that:
  • calls each tank's increment method to move their location, rotation, etc, one step further
  • sleeps 10 milliseconds
  • repaints the jframe

Meanwhile, the Tank class:

• keeps track of the state of the tank in the world
• figures out how to "increment" the tank object with each call of the TankSimulator heartbeat loop.
• keeps track of the drawing details of the tank
• figures out how to draw the tank onto the Graphics2D object

The Graphics2D Stuff

TankSimulator extends JComponent. Because TankSimulator extends JComponent, I can add it to a JFrame's content pane. Fortunately, that's just what I do in TankSimulator's main() method:

• instantiate a JFrame
• instantiate a TankSimulator
• add the TankSimulator to the JFrame
• display the JFrame by calling its .setVisible() method

  At that point I call TankSimulator's heartbeat() method, which just loops forever. Each loop, it updates the state of the tank objects, sleeps 10 milliseconds, and then calls frame.repaint().

  See Painting in AWT and Swing, but basically repaint() schedules the JFrame to be re-rendered as soon as possible, which in our application is almost immediately.

  When the JFrame is repainted, it in turn calls the TankSimulator's paint() method, which in turn iterates through the TankSimulator's Vector of Tank objects, and calls each tank's .draw() method.

  Note: The "draw()" method is not at all standard, I just chose that name. I guess if I wanted to be more standard, I'd think about having each Tank object extend JComponent, or something, and have a paint() method.

  One curiosity to note here is that while JFrame passes TankSimulator.paint() a Graphics object, it is in fact passing a Graphics2D object. Graphics2D came along after most of the Swing stuff was already defined and in use. Instead of just changing all the Swing classes so they passed around a Graphics2D object instead, they pass the Graphics2D as a Graphics object, and trust that anybody who needs to use the Graphics2D stuff will cast the object to Graphics2D. Which is what we're doing here.

  TankSimulator.paint(Graphics) casts the Graphics to Graphics2D, and then calls each tank's draw(Graphics2D) method. Like I said, draw() is not a standard method, so I'm free to do anything I like there.

  Head Twisting

  One twist that I had to wrap my head around is the general model of how java2d works. When I started trying to learn java2D, I was thinking in terms of manipulating a canvas, creating graphical shapes/objects and placing them on the canvas.

  However, java2d turns that sort of inside-out. Don't think about manipulating the objects and the canvas. Instead, think of the canvas as something you're never allowed to directly touch. Instead, you get to manipulate a this nifty gadget that's a cross between a slide projector, a spotlight, and a paint sprayer.

  • The way it's like a slide projector is that you put an image slide into it and project it onto the canvas.
  • The way it's like a spotlight is that you only get to project it on one spot of your canvas at a time. You have to go around your canvas projecting at each spot where you need to draw something, in turn.
  • Also like a spotlight, youo get to use various fun lenses, called AffineTransforms, to rotate, enlarge, shrink, etc, the image you're projecting.
  • And of course, the way it's like a paint sprayer is that you project, then the image stays there while you move to another spot and project something else.

  Once I got into the habit of thinking of it this way, it all made a lot more sense.

  The Tank

  Tank represents a tank object, with instance variables for location and motion:

  • X and Y coordinates
  • Current rotation
  • X and Y vectors of motion
  • Vector of rotation

  Note, here I'm using vector more in the geometric sense of motion, rather than the java sense. I'm probably using it imprecisely, I think a Vector actually should contain both the current coordinates and the change in coordinates, and I'll bet that using the term to describe the rate of change in rotation will have various mathematicians climbing the walls... but you get the general idea.

  The Tank also has a number of instance variables reflecting the appearance of the tank icon. If I ever do anything more with this code, I'll probably refactor this stuff out to some sort of icon class.

  • Scale, which is a concept I'm using to dictate the size at which the finished tank object is rendered.
  • Path, a java2d GeneralPath that defines the line (a series of x/y points) to draw the tank shape. Note that this is generally set on the Tank from the outside (though I don't know why I bothered to get fussy about this when the rest of this demo is so crude and messy).
  • Stroke, a java2d concept of the way to render the line defined by the GeneralPath.
  • Fill, another java2d concept of what Color to fill the shape with when rendering.

  Animating The Model

  I also have two simple methods for controlling the animation of the object. Now note, these are really crude by any standard:

  • increment() - move the Tank along its X and Y vectors and spin it according to its Rotation Vector.
  • bounce() - check if the Tank's X and Y coordinates are past the boundary (passed in as xSize and ySize parameters), and if so invert the Tank's X and Y Vectors.

  As just two little examples of how crude this is:

  First, increment() should really take some sort of duration parameter, and increment the object according to that parameter. The way it's done now, it assumes that you have everything locked to the same frame rate, and you call increment() on every object once per frame.

  Second, bounce() is basically a quick kludge to check for colliding with the map boundaries. Strictly speaking, this should live somewhere else.

  It gets even thornier when you think about combining these two problems, because right now, the same outside code is calling increment() and then calling bounce(). If you have increment() going over a larger duration, you have to figure out how and when you're going to check for collisions.

  The Java2D Stuff

  Finally we come to the actual java2D work methods... well, not quite, first we're going to need some helper methods:

  • getWidth() - get the tank icon's width based on the GeneralPath bounds.
  • getHeight() - get the tank icon's height based on the GeneralPath's bounds.
  • getRotationRadians() - convert the Rotation Vector to radians (using java.lang.Math)

  Now that we have the stage all set, let's talk about doing the java2d dirty work. The last two methods on the Tank class are:

  • getTransform() - generate an object, an AffineTransform, that represents how this tank's image will have to be rotated, translated and scaled before it can be painted onto the Graphics2D object.
  • draw() - will be called when it's time to paint this Tank object onto the Graphisc2D object that's passed in as a parameter.

  The getTransform() method creates a java2d AffineTransform object that you'll use to render the Tank. It uses the other methods on Tank, like getScale(), getX(), getY(), getRotationRadians(), getWidth() and getHeight(), to create an appropriate AffineTransform. Then you'll set this AffineTransform on the Graphics2D object when it's time to render this Tank.

  The draw() method gets invoked with a Graphics2D reference as a parameter. draw() sets the Stroke, Fill and AffineTransform, then passes the GeneralPath object to the Graphics2D object's draw() and fill() methods.

  Wtf is an AffineTransform?

  AffineTransform is named after a mathematical operation you use to manipulate the sort of data structure that java2d uses to keep track of what pixels go where. I'm not going to get any deeper into it than this because, well, I don't understand it :-). At least, not well enough to explain it properly.

  I will say that the AffineTransform is the "lens" I mentioned above, in the section titled "Head Twisting". If you look at the Tank.draw() method, you'll see that it calls Tank.getTransform() and sets the AffineTransform on the Graphics2D object (g2.setTransform(this.getTransform())) right before it actually draws the tank's path (g2.draw(this.getPath()). Anything that you pipe through the graphics2D object after you call setTransform() gets, well, transformed by the AffineTransform.

  I wrote a little more about affine transforms, specifically some of the gotchas when using them for rotating, translating and scaling.