ECE597 Project 3D Chess

This project will simulate a hand-held chess game, and the game will allow two player games using two BeagleBoards over a network connection. The graphics will use the beagle's PowerVR SGX for hardware accelerated graphics by using OpenGL. If time permits, a third portion of the project will be to optimize the boot time because a chess computer should start up quickly.

Team Members
Paul Morrison

Steven Stark

Timeline
Below is an estimated timetable of tasks to be completed. Some adjustments may be necessary.

About priorities: High Priority items need to be completed for a successful project. Medium Priority items should be completed for an effective project, but the project can still be successful without the item's completion. Low Priority items should be completed if time allows.

Developing with OpenGL ES
This section will explain how to set up and use the graphics SDK to compile using the cross compiler previously set up during ECE597. The 2010.3 Angstrom demo image was used to run the programs.

Obtaining the Software
The Graphics SDK is available from TI's website. Download OMAP35x_Graphics_SDK_setuplinux_3_01_00_06.bin (you will need to create an account).

Make sure the file is executable $ chmod +x OMAP35x_Graphics_SDK_setuplinux_3_01_00_06.bin Extract the files to your desired location ./OMAP35x_Graphics_SDK_setuplinux_3_01_00_06.bin Everything necessary for 3D Chess is contained in /GFX_Linux_SDK/OGLES2/SDKPackage/. This will simply be referred to as SDKPackage/ in the future.

Compiling a Training Course Program
The general instructions on compiling the programs are provided in SDKPackage/OpenGL ES 2.x SDK.User Guide.1.20f.External.pdf. The following instructions are specific to the cross compiler used with OpenEmbedded:

Create a new source-me.txt similar to what was done for the u-boot exercise. Note the addition of PLATFORM and X11ROOT variables. X11ROOT specifies the directory of the X11 freedesktop binaries which is necessary if you want the programs to run inside a window using X11.

export OETREE="${HOME}/oe" export ARCH=arm export CROSS_COMPILE=arm-angstrom-linux-gnueabi-

export PLATFORM=LinuxOMAP3 export X11ROOT=${OETREE}/angstrom-dev/staging/armv7a-angstrom-linux-gnueabi/usr/lib/X11/

PATH=${OETREE}/angstrom-dev/staging/i686-linux/usr/bin/:${PATH} PATH=${OETREE}/angstrom-dev/cross/armv7a/bin/:${PATH}

Now to compile an interesting first program: 02_HelloTriangle. The source can be found in SDKPackage/TrainingCourse/02_HelloTriangle/OGLES2. There are two files, one for using X11 and one without. We need to set the flag, X11BUILD, to 1 if we want to build the X11 version.

cd SDKPackage/TrainingCourse/02_HelloTriangle/OGLES2/Build/LinuxOMAP3 make X11BUILD=1

It may be necessary to modify SDKPackage/Builds/OGLES2/LinuxOMAP3/make_platform.mak if the build fails. Modify the compiler lines to append the prefix arm-angstrom-linux-gnueabi-

ifdef TOOLCHAIN PLAT_CC = $(TOOLCHAIN)/bin/arm-angstrom-linux-gnueabi-gcc PLAT_CPP = $(TOOLCHAIN)/bin/arm-angstrom-linux-gnueabi-g++ PLAT_AR = $(TOOLCHAIN)/bin/arm-angstrom-linux-gnueabi-ar else PLAT_CC = arm-angstrom-linux-gnueabi-gcc PLAT_CPP = arm-angstrom-linux-gnueabi-g++ PLAT_AR = arm-angstrom-linux-gnueabi-ar endif

After the program is built, it will be in SDKPackage/TrainingCourse/02_HelloTriangle/OGLES2/Build/LinuxOMAP3/ReleaseRaw/OGLES2HelloTriangle.

To move this file to a running Beagleboard without setting up NFS, secure copy can be used: $ scp ../LinuxOMAP3/ReleaseX11/OGLES2HelloTriangle user@beagleoard:/home/ /Documents/HelloTriangle/

Finally, on the Beagleboard, run the program: $ cd /home/ /Documents/HelloTriangle $ ./OGLES2HelloTriangle

All of the other training course programs and the demo programs should compile similarly.

Understanding the Tools
Originally, Paul had intended to use Simple Direct Media Layer for mouse input, texture loading and creation of an OpenGL context because it was used in the project to be ported. However, SDL 1.2 does not support OpenGL ES at all, SDL 1.3 is still in development, and the development version would not compile easily. It is also unknown how much additional work would be necessary to get SDL 1.3 to work well with OpenGL ES on the Beagleboard. Rather than sinking more days into trying, it was decided that the port would move to using PVRShell for the OpenGL ES context creation, and PVRTools for the texture loading.

PVRShell
This is a very basic class that is used to wrap the EGL and X11 calls that are necessary for creating a window with an OpenGL ES context. Training course programs 01 and 02 do not use PVRShell, so their source is a good place to see some code which would be necessary without PVRShell.

PVRShell is documented in SDKPackage/Shell/Documentation/html/index.html

PVRTools (OGLES2Tools)
This library contains many tools that are used to perform common graphics related tasks. Some of the tools that will be used directly by the 3D chess game include:


 * PVRTMat4
 * This class implements the necessary matrix operations for translation, rotation, perspective, and other transformations. Much of this functionality was available in OpenGL 1.0 and 2.0 and for the chess game will need to be ported from OpenGL calls to PVRTMat4.


 * PVRTPrint3D
 * This is used to draw text to the OpenGL window.


 * PVRTTexture
 * This is used to perform texture loading from the application's binary to an OpenGL ES texture.


 * PVRTShader
 * All OpenGL ES 2.0 programs must have shader programs to specify how the hardware will perform rendering. This tool will load the shader program.

All of the PVRTools are documented in SDKPackage/Tools/Documentation/html/index.html

Makefiles
If you look in a makefile for a training course program (try 06_IntroducingPVRTools) you will see that it includes another file, make_demo.mak, which then includes make_platform.mak. Additionally, make_demo.mak's build_textures_and_shaders uses two more makefiles: maketex.mak and content.mak. This initially confusing arrangement is allows one make command to compile all the necessary PVR libraries and to package application specific data into the binary which will be loaded at runtime.

content.mak is of particular interest because it specifies what textures, shaders, and 3D models should be wrapped inside the binary. This file is specific to each program and can be found in SDKPackage/TrainingCourse/06_IntroducingPVRTools/OGLES2/.

For example, in the 3D chess graphics port, a texture is used to make the board look like marble. In order to use this texture with PVRTTexture (one of the PVRTools used to load textures for use with OpenGL ES), the texture must be converted to a format usable by PVRTTexture and linked into the actual binary of the program. This can be accomplished by placing the texture (marble.bmp) into the Media folder and making a few modifications to content.mak and Makefile.


 * Modifying content.mak:

TEXTURES = \ Marble.pvr

BIN_SHADERS = \ FragShader.fsc \ VertShader.vsc

RESOURCES = \ $(CONTENTDIR)/Marble.cpp \ $(CONTENTDIR)/FragShader.cpp \ $(CONTENTDIR)/VertShader.cpp

TEXTURES, BIN_SHADERS and RESOURCES indicate what files need to be created during the building process. Lines for the actual building are below:

Marble.pvr: $(MEDIAPATH)/marble.bmp $(PVRTEXTOOL) -m -fOGLPVRTC4 -i$(MEDIAPATH)/marble.bmp -o$@

$(CONTENTDIR)/Marble.cpp: Marble.pvr $(FILEWRAP) -o $@ Marble.pvr

What does all this do? A couple more tools are used to convert the bitmap texture into a usable form. These utilities are located in SDKPackage/Utilities/.

The Marble.pvr: command converts the bitmap texture to a compressed pvr form using the PVRTexTool utililty. The next command is then used to take the compressed data and wrap it .cpp file with the Filewrap utility. Finally, the .cpp files can be compiled and linked into the binary.

Two changes need to be made to Makefile before we can use the marble texture in the program.
 * Modifying Makefile:

Add Marble.o to OBJECTS: OBJECTS += Marble.o FragShader.o VertShader.o

Add Marble.cpp to build_textures_and_shaders: ../../Content/Marble.cpp ../../Content/MarbleRookTexture.cpp ../../Content/FragShader.cpp ../../Content/VertShader.cpp: build_textures_and_shaders

Now we can load the texture in our program with a call to PVRTTextureLoadFromPVR.

Chess Logic
The chess logic includes several features. One feature is that the board is represented by a 12 x 12 grid of pieces. A chess board only has 8 x 8 spaces, but including extra spaces around the outside eliminates edge cases. For example, consider the computation of a rook's possible moves. Four loops are used to determine what spaces in each of the four directions are legal. When a space is occupied by another piece the loop breaks, and a movement to that space is possible only if the space is occupied by the opponent's color, which allows for a piece to attack the opponent's piece. The spaces that are beyond the 8 x 8 grid are occupied by pieces that say the space is occupied, but is not on either team's side so a movement to those spaces is never legal. One may wonder why a 12 x 12 grid is necessary, since a 10 x 10 grid would work properly for computing the rook's possible moves. The reason for the extra pieces is because knight's can jump over pieces, so the outside must have two rows of dummy spaces.

The discussion above only determines the set of possible moves for a piece. However, not all moves that are generated by this process are legal because a player cannot leave the king in check or make a movement that causes the king to become in check. Thus, additional code is needed to examine each of the possible moves and ensure that the king is not in check at after making the possible move. This functionality automatically ends the game when a checkmate occurs because there no legal moves would remain.

Chess Graphics
All chess graphics were implemented using the OpenGL ES API. This API is well documented, and there are many tutorials available, so the details of how to use OpenGL will not be covered here.

Piece Meshes
The piece mesh class consists of a file parser to load the data, arrays to hold the data, and OpenGL code to perform the actual drawing. The meshes were created by Paul using the open 3D modeling tool Blender before this project began. They were exported to a simple format, Wavefront OBJ. The file parser is capable of reading in the vertices, normals, texture coordinates, and the texture itself.

Piece Selection
Piece picking is performed by rendering each distinct object in a unique color when the mouse is clicked. The color of the pixel that was clicked on is then returned by a call to glReadPixels and the specific object that was clicked on can then be determined from the unique color returned. The drawing is done directly to the framebuffer, but the buffers are not swapped before the scene is drawn again with proper colors. This prevents the user from seeing the unique colors for each piece. In the future, this could be accomplished using framebuffer objects and a modified shader program to render this picking texture offscreen at the same time the correctly colored image is rendered on screen. This should be able help performance after a mouse click slightly, but at the cost of more memory usage. However, the performance penalty is likely not significant.

Annotated Bibliography

 * 1) New beagleboard demo image available This thread describes how to obtain the latest image for the Angstrom distribution on the beagleboard which includes the SGX 3D demos.
 * 2) OMAP Graphics SDK This is the download page for the OMAP35x graphics SDK required to build your own image.  It also links to a wiki containing the getting started guide.
 * 3) OpenGL ES Overview This is the official website for OpenGL ES.  Of particular use is the OpenGL ES quick reference card that has a list of all OpenGL ES function prototypes and some information of the GLSL shading language.