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 (under construction)
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:

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.

Annotated Bibliography
Under development
 * 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.