JGE++: A hardware accelerated 2D game engine for PSP/Windows

dr_watson · Post by **dr_watson** » Tue Mar 28, 2006 8:31 pm

Introduction

JGE++ (Jas Game Engine++) is a hardware accelerated 2D game engine for PSP (using GU) and Windows. It's inspired by the popular game engine HGE on MS Windows. In fact the Windows' counterpart is basically a wrapper of HGE.

For more information about HGE, please visit its web site at:

http://hge.relishgames.com.

With JGE++, you can build a project as a Windows executable or a PSP EBOOT image with the same source code without any modification. This means the game development process, including coding, debugging and testing, can be done mainly in Windows. However, since JGE++ is still under development and not heavily tested, it is recommended that the PSP EBOOT image should be built and put onto a PSP for testing from time to time just to make sure everything is working properly.

Of course you may also put in platform specific codes with #if/#else/#endif.

SkyAnimator is introduced with JGE++ v0.2b. It is a visual tool written by
HuangYZ for creating sprite animations. HuangYZ has ported the runtime library to JGE++ and this gives JGE++ a very powerful animation system to play with.

Contents of the JGE++ package

- JGE++ v0.2b (source + lib)
- SkyAnimator lib
- JGE++ demo (source + assets)
- SkyAnimator demo (source + assets)
- StarBugz (source + assets)
- Mario Demo (source + assets)

Prerequisites

libpng
libz
mikmodlib

Directory Structure

Code: Select all

____JGE
|    |___HGE &#40;Windows backend&#41;
|    |___include &#40;JGE++ header files&#41;
|    |___lib
|    |    |___psp &#40;lib files for PSP&#41;
|    |    |    |
|    |    |    |___libjgesky.a &#40;SkyAnimator lib&#41;
|    |    |    |___libjge.a &#40;JGE++ lib&#41;
|    |    |
|    |    |___win &#40;lib files for Windows&#41;
|    |         |
|    |         |___JgeSky60.lib &#40;SkyAnimator lib for VC6.0&#41;
|    |         |___JgeSky71.lib &#40;SkyAnimator lib for VC2003&#41;
|    |         |___jge.lib &#40;JGE++ lib Release version&#41;
|    |         |___jge_debug.lib &#40;JGE++ lib debug version&#41;
|    |
|    |___src &#40;JGE++ source files&#41;
|
|___Demo
|    |___bin
|    |___Debug
|    |___JGEFramework
|    |___Release
|    |___src
|        |___GameApp.cpp
|        |___GameApp.h
|            
|___Mario &#40;same structure as Demo&#41;
|
|___SkyDemo &#40;same structure as Demo&#41;
|
|___StarBugz &#40;same structure as Demo&#41;

To build the JGE++ lib for Windows

Open "JGE.dsw" in JGE directory with Visual Studio 6.0. With the BATCH BUILD option, select "REBUILD ALL".

To build the JGE++ lib for PSP

Change to JGE directory, then

make clean
make install

or just run the batch file "mk.bat"

To build a project for Windows

Open "xxx.dsw" in the project directory with Visual Studio 6.0 and build for either "Release" or "Debug".

To build a project for PSP

Change to the project directory, then

make clean
make

or just run the batch file "mk.bat"

To run on Windows

You need DirectX 8.0+ installed.

Key mapping:

Code: Select all


PSP                     WINDOWS
------------------      -------------
UP/DOWN/LEFT/RIGHT      W/S/A/D
ANALOG CONTROL          UP/DOWN/LEFT/RIGHT
TRIANGLE                8 on NumPad &#40;with NUMLOCK&#41;
SQUARE                  4 on NumPad &#40;with NUMLOCK&#41;
CIRCLE                  6 on NumPad &#40;with NUMLOCK&#41;
CROSS                   2 on NumPad &#40;with NUMLOCK&#41;
SELECT                  CTRL
START                   ENTER
HOME                    F1
HOLD                    F2
NOTE                    F3
L                       Q
R                       E

To run on PSP

With firmware 1.50 PSP, use KXploit Tool to transfer the proper EBOOT.PBP onto your memory stick. Then you need to copy the entire "Res" folder in "bin" into the appropriate folder on your PSP too!

License

SkyAnimator(libjgesky/JgeSky60.lib/JgeSky71.lib) is free software. You can use it anyway you like at your own risk. Copyright (C) 2006 HuangYZ.

JGE++/JGE++ Demo/SkyAnimator Demo/StarBugz/Mario Demo are released under GPL and below is the license agreement:

"This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA"

Special thanks to

- PSPSDK team
- devkitPSP team
- friends at pspchina.net
- Jasmine (James' lovely wife ^^)

Credits

JGE++:
Programmer - James Hui (a.k.a. Dr.Watson)

SkyAnimator and SkyAnimator Demo:
Programmer - HuangYZ

JGE++ Demo:
Programmer - James Hui
Artist - Zhen (TMD Games)

StarBugz:
Programmer - James Hui
Artist - Fung Lap Tong

Mario Demo:
Programmer - James Hui
Artist - Zhen (TMD Games)

Screenshots

SkyAnimator:

SkyAnimator Demo:

JGE++ Demo:

StarBugz:

Mario Demo:

Downloads
JGE++ v0.2b
SkyAnimator v1.6b R2 (English version)
SkyAnimator v1.6b R2 (Chinese version)

Prebuilt binaries:

JGE++ Demo for PSP firmware 1.50
JGE++ Demo for Windows
SkyAnimator Demo for PSP firmware 1.50
SkyAnimator Demo for Windows
Mario Demo for PSP firmware 1.50
Mario Demo for Windows
StarBugz Prototype for PSP firmware 1.50
StarBugz Prototype for Windows

Known issues
- Wav files must be 8 bit mono.
- There is an extra "." in front of hge.lib in VC6 project settings of Demo's Debug build for Windows. Please remove it in order to build.

dr_watson · Post by **dr_watson** » Tue Mar 28, 2006 8:32 pm

An introduction to rendering 2D images with GU

JGE++ uses the GU functions for rendering and this is an introduction on how the 2D rendering is done with this 3D library.

PSP has 2MB video RAM. Apart from using as frame buffers, user textures can also be stored here for faster GPU process. The pixel format that is chosen for the game will have a big impact on how many textures can be stored in the video RAM.

There are four different pixel formats available on PSP:

PSP_DISPLAY_PIXEL_FORMAT_565 //16-bit RGB 5:6:5
PSP_DISPLAY_PIXEL_FORMAT_5551 //16-bit RGBA 5:5:5:1
PSP_DISPLAY_PIXEL_FORMAT_4444 //16-bit RGBA 4:4:4:4
PSP_DISPLAY_PIXEL_FORMAT_8888 //32-bit RGBA 8:8:8:8

Since transparent colour is pretty much needed for all game applications, the 565 format is basically out. The 5551 and 4444 format both take 2 bytes for a single pixel. If effects such as alpha blending is required, then the 4444 format will be the choice to use.

Of course, the optimal option will be the 8888 format, which produce the maximum number of colours on screen. However this format uses 4 bytes for each pixel. A primary frame buffer plus a back buffer will take up 512x272x4x2 = 1,088KB. There will be only 960KB left for user textures. In that case, most of the textures will need to be stored in system RAM and thus will slow down all the rendering.

Here is the code segment on GU intialization:

sceGuInit();

sceGuStart(GU_DIRECT,list);
mVideoBufferStart = 0;

// setup frame buffer for rendering
sceGuDrawBuffer(BUFFER_FORMAT, (void *)mVideoBufferStart, FRAME_BUFFER_WIDTH);
mVideoBufferStart += FRAME_BUFFER_SIZE;

// setup frame buffer for displaying
sceGuDispBuffer(SCREEN_WIDTH, SCREEN_HEIGHT, (void *)mVideoBufferStart, FRAME_BUFFER_WIDTH);

// setup starting address of video RAM for user textures
mVideoBufferStart += FRAME_BUFFER_SIZE;
mCurrentPointer = mVideoBufferStart;

sceGuOffset(2048 - (SCREEN_WIDTH/2), 2048 - (SCREEN_HEIGHT/2));
sceGuViewport(2048, 2048, SCREEN_WIDTH, SCREEN_HEIGHT);

sceGuScissor(0, 0, SCREEN_WIDTH, SCREEN_HEIGHT);
sceGuEnable(GU_SCISSOR_TEST);
sceGuFrontFace(GU_CW);
sceGuEnable(GU_TEXTURE_2D);
sceGuShadeModel(GU_SMOOTH);

// enable alpha blending
sceGuEnable(GU_BLEND);
sceGuBlendFunc(GU_ADD, GU_SRC_ALPHA, GU_ONE_MINUS_SRC_ALPHA, 0, 0);

sceGuClear(GU_COLOR_BUFFER_BIT);
sceGuFinish();
sceGuSync(0,0);

sceDisplayWaitVblankStart();
sceGuDisplay(1);

To render a 2D image onto screen, a texture containing such image is loaded and a quad structure is defined to specify the area of the texture to render. Basically 2D images rendering with GU is done by rendering textured quads.

A quad consists of four vertices. The order of the vertices is shown below:

Code: Select all

v0---v1
 |  /|
 | / |
 |/  |
v2---v3

Here is the structure of Vertex:

Code: Select all

struct Vertex
&#123;
       float u, v;
       PIXEL_TYPE color;
       float x, y, z;
&#125;;

(x,y) is the screen coordinates and (u,v) is the texture coordinates.

As an example, the first frame of the following animation will be shown at screen location (100,100). The size of each frame is 100x100:

Here is the settings of the four vertices:

Code: Select all

vertices&#91;0&#93;.u = 0.0f; 
vertices&#91;0&#93;.v = 0.0f;
vertices&#91;0&#93;.color = color;
vertices&#91;0&#93;.x = 100.0f; 
vertices&#91;0&#93;.y = 100.0f; 
vertices&#91;0&#93;.z = 0.0f;

vertices&#91;1&#93;.u = 100.0f; 
vertices&#91;1&#93;.v = 0.0f;
vertices&#91;1&#93;.color = color;
vertices&#91;1&#93;.x = 200.0f; 
vertices&#91;1&#93;.y = 100.0f; 
vertices&#91;1&#93;.z = 0.0f;

vertices&#91;2&#93;.u = 0.0f; 
vertices&#91;2&#93;.v = 100.0f;
vertices&#91;2&#93;.color = color;
vertices&#91;2&#93;.x = 100.0f; 
vertices&#91;2&#93;.y = 200.0f; 
vertices&#91;2&#93;.z = 0.0f;

vertices&#91;3&#93;.u = 100.0f 
vertices&#91;3&#93;.v = 100.0f;
vertices&#91;3&#93;.color = color;
vertices&#91;3&#93;.x = 200.0f; 
vertices&#91;3&#93;.y = 200.0f; 
vertices&#91;3&#93;.z = 0.0f;

After setting up the vertices, GU function sceGuDrawArray will be used to render the quad:

Code: Select all

sceGuDrawArray&#40;GU_TRIANGLE_STRIP,GU_TEXTURE_32BITF|TEXTURE_COLOR_FORMAT|GU_VERTEX_32BITF|GU_TRANSFORM_2D, 4, 0, vertices&#41;;

Parameters of sceGuDrawArray:

GU_TRIANGLE_STRIP
- rendering triangles

GU_TEXTURE_32BITF|TEXTURE_COLOR_FORMAT|GU_VERTEX_32BITF|GU_TRANSFORM_2D:
- vertex structure is texture coordinates(floats), followed by colour, followed by screen coordinates(floats) with 2D transform.

4
- 4 vertices.

0
- starting index of vertices

vertices
- vertices

dr_watson · Post by **dr_watson** » Tue Mar 28, 2006 8:32 pm

Hello World for JGE++

The JGE++ package comes with a demo application called Demo. This is basically a Hello World program for JGE++.

When programming 2D games, in order to show an image on screen, the image is loaded and then a "DrawImage" function is used to do the job. Sometimes a few images are packed into a single one and portions of it are used for rendering in order to save file space, for easy management or for whatever reasons.

With hardware accelerated 2D game engines, this "packed" image approach has become a necessary because the width/height of the texture that is fed to the graphics hardware need to be in the power of 2. And also, switching from one texture to another may take some extra GPU cycles. Obviously the best way to do is to have a relative large texture, say 512x512, and putting all images in it and render portions of it for different sprites. In practice of course it is not required to have just one single texture for a whole game. But keeping the number of textures to a minimal is a good habit anyway!

Here is a sample texture (128x128) with a cartoon character and the text "HELLO WORLD":

A quad structure is used to specify which area of the large texture is to be rendered. Here is an example on how to load a texture and render an image to screen in JGE++:

Code: Select all


// load texture
mTexture = mEngine->LoadTexture&#40;"Res/mario.png", true&#41;;	
// setup quad structure
mMario = new JQuad&#40;mTexture, 0.0f, 0.0f, 62.0f, 72.0f&#41;;
// set center of quad
mMario->SetHotSpot&#40;31.0f, 36.0f&#41;;

.
.
.
// render to screen
mEngine->RenderQuad&#40;mMario, 80.0f, 80.0f&#41;;

It may seem tedious to concatenate images together and define quads just to render a few images on screen, but the good thing about using hardware accelerated functions is that apart from plain rendering, it is possible to do scaling, rotation and alpha/colour blending at the same time and cost nothing to the main CPU. All these mean fast speed, hence, the term hardware accleration!

Here are some examples of how to do scaling, rotation and colour blending:

Code: Select all


// render with rotation
mEngine->RenderQuad&#40;mMario, 80.0f, 200.0f, mAngle, 1.0f, 1.0f&#41;;

// set blending colour
mMario->SetColor&#40;ARGB&#40;128,255,255,0&#41;&#41;;
// render with colour blending and scaling
mEngine->RenderQuad&#40;mMario, 380.0f, 150.0f, 0.0f, mScale, mScale&#41;;	
mMario->SetColor&#40;ARGB&#40;255,255,255,255&#41;&#41;;

Easy! Time to make some cool games!

Brunni · Post by **Brunni** » Tue Mar 28, 2006 9:37 pm

Cool ^^
Was it originally designed for Windows or PSP (or both at once)?

dr_watson · Post by **dr_watson** » Tue Mar 28, 2006 10:29 pm

It was written for PSP while I was making StarBugz. Since I borrowed lots of ideas from HGE, I knew I would make a kind of HGE wrapper to make JGE++ games run on Windows as well. It's really painful to debug programs on PSP directly. I made the Mario Demo almost entirely in M$ Windows. Occasionally I would put it on my PSP for some "real" testing ;)

dot_blank · Post by **dot_blank** » Wed Mar 29, 2006 8:06 pm

nice work :)

dr_watson · Post by **dr_watson** » Wed Mar 29, 2006 9:09 pm

SkyAnimator English version is available now:

SkyAnimator (English version)

Shapyi · Post by **Shapyi** » Thu Mar 30, 2006 3:42 am

Great work. I like the fact you included the source code so we can learn from it. I'm gonna check out the samples.

alain91 · Post by **alain91** » Thu Mar 30, 2006 6:18 am

Hello dr_watson,

It seems great but when I try to launch demo project, it hangs with a blue screen :) and registers dump ?

dr_watson · Post by **dr_watson** » Thu Mar 30, 2006 8:36 am

Is it Windows build or PSP build?

For PSP, there's a "res" folder in the "bin" folder of each project. Did you put that on PSP together with your EBOOT?

ipsp · Post by **ipsp** » Thu Mar 30, 2006 9:26 am

Nice work.

I've had a quick look whilst I was at work yesterday, and I must say the examples gave some insight into it abilities, hence making it standout for other libraries.

I'll investigate this more once I finish my current project. Again nice work good to see more libararies added to the PSP community.

dr_watson · Post by **dr_watson** » Thu Mar 30, 2006 9:18 pm

Thank you for all the good words!

Here are some prebuilt binaries of the included demos for people to check out the features of JGE++:

JGE++ Demo for PSP firmware 1.50
JGE++ Demo for Windows
SkyAnimator Demo for PSP firmware 1.50
SkyAnimator Demo for Windows
Mario Demo for PSP firmware 1.50
Mario Demo for Windows
StarBugz Prototype for PSP firmware 1.50
StarBugz Prototype for Windows

alain91 · Post by **alain91** » Fri Mar 31, 2006 2:35 am

Hello dr_watson,

The problem was only on demo program. Mario & others work well.

subbie · Post by **subbie** » Fri Mar 31, 2006 6:37 am

Yo, just simple question. Why use GU_TRIANGLE_STRIP to render sprites? You can just use GU_SPRITES insted. You just need to suply the upper left & lower right verticies to form a quad.

dr_watson · Post by **dr_watson** » Fri Mar 31, 2006 8:45 am

subbie wrote:Yo, just simple question. Why use GU_TRIANGLE_STRIP to render sprites? You can just use GU_SPRITES insted. You just need to suply the upper left & lower right verticies to form a quad.

yes, you can use GU_SPRITES... but you can't rotate with it ;)

alain91 wrote:The problem was only on demo program

Can you try the prebuilt Demo and see if that works?

alain91 · Post by **alain91** » Fri Mar 31, 2006 6:08 pm

dr_watson : The prebuit demo work well :)

dr_watson · Post by **dr_watson** » Fri Mar 31, 2006 9:23 pm

A new bug-fixed version of SkyAnimator is available for download and the URL is at the original post.

alain91 · Post by **alain91** » Mon Apr 03, 2006 7:30 pm

hello dr_watson,

I wondered how you would code a scrolling map with jge ?

- a big sprite where you put tiles in it ?
- a direct memory access ?
- ..?

Thanks a lot,
Alain

Brunni · Post by **Brunni** » Mon Apr 03, 2006 10:03 pm

You draw multiple sprites, each one corresponding to one tile.

alain91 · Post by **alain91** » Mon Apr 03, 2006 11:28 pm

Thanks Brunni ;)

Just wondering if your lib is better than this...

dr_watson · Post by **dr_watson** » Tue Apr 04, 2006 8:35 pm

hi alain91, you can have a look of the Mario demo. It features parallax scrolling. The very front layer is a tile map while the other layers are just big images.

I reckon OSLib has more features but JGE++ offers M$ Windows' support, which makes it easier for the development ;)

However, from Brunni's posts I think he's aiming at Windows support too :)

alain91 · Post by **alain91** » Wed Apr 05, 2006 7:18 am

Hello dr_watson,

Windows support for testing is a sure 'plus' :)

So you use sprites to build a map.. wouldn't it be faster and less ressources consuming to have a 'blit' functions (direct draw from tiles to memory) ?

Sorry if it is a stupid question, Brunni oslib seems to use the same system as you ..

Regards,
Alain

dr_watson · Post by **dr_watson** » Wed Apr 05, 2006 12:07 pm

Hi Alain,

By "draw from tiles to memory", do you mean you have a large image in memory for the background, you blit all tiles to that image to construct the background and then render that large image to screen?

If you are to use GU functions to render that large image, the size of it need to be within 512x512, which is the largest texture size GU supports. Anything larger than that will require you to play some tricks to render them properly.

Since GU functions are hardware accelerated, there's no problem to render few dozens of tile images at each frame for the tile map. For example, with that Mario Demo, you got 300-400 FPS. Not fast enough? ^^

Brunni · Post by **Brunni** » Wed Apr 05, 2006 4:11 pm

alain91> I don't think you can compare both libraries, it's up to you to test them to find the most adapted to you ;)
And to answer your question, direct memory blitting is not better than using "sprites", as they are hardware accelerated.
The advantage of using sprites lets you mix pixelformats (for example draw a 16-bit tilemap on a 32-bit drawbuffer) and is more flexible. You can for example enable transparency and then display your map => it will be transparent, and so on.

Panajev2001a · Post by **Panajev2001a** » Wed Apr 05, 2006 8:02 pm

Brunni wrote:alain91> I don't think you can compare both libraries, it's up to you to test them to find the most adapted to you ;)
And to answer your question, direct memory blitting is not better than using "sprites", as they are hardware accelerated.
The advantage of using sprites lets you mix pixelformats (for example draw a 16-bit tilemap on a 32-bit drawbuffer) and is more flexible. You can for example enable transparency and then display your map => it will be transparent, and so on.

Brunni, does OSlib "emulates" also the GBA's BG Tile Modes map and amount of unique tiles limitations making it similar to how you would do things on the GBA or you only have a limitation on map size (1024x1024 maybe or 512x512 ?) ?

Brunni · Post by **Brunni** » Wed Apr 05, 2006 8:51 pm

Yes. The map size is not limited (unlike the GBA), but all tiles must fit in a single image (and its maximum size is 512x512, it's a limitation of the PSP GPU).

Panajev2001a · Post by **Panajev2001a** » Wed Apr 05, 2006 9:03 pm

Brunni wrote:Yes. The map size is not limited (unlike the GBA), but all tiles must fit in a single image (and its maximum size is 512x512, it's a limitation of the PSP GPU).

So basically you have an unlimited map size, but effectively the map can only have 4096 unique tiles (which is (512*512) / (8*8)), am I correct (assuming tile size is 8*8 of course) ?

At least it simplifies the work a bit... there's only the need to find out how to dynamically update the tile set for the BG map and it should work out quite well.

subbie · Post by **subbie** » Thu Apr 06, 2006 12:19 am

dr_watson wrote:
subbie wrote:Yo, just simple question. Why use GU_TRIANGLE_STRIP to render sprites? You can just use GU_SPRITES insted. You just need to suply the upper left & lower right verticies to form a quad.
yes, you can use GU_SPRITES... but you can't rotate with it ;)

In which sense. sceGumRotateX/Y/Z ?

Could also just manualy rotate your verticies (only 2) yourself. The benifit is you're only sending 2 verts though the pipeline vs 4.

dr_watson · Post by **dr_watson** » Thu Apr 06, 2006 1:02 pm

subbie wrote:
In which sense. sceGumRotateX/Y/Z ?

Could also just manualy rotate your verticies (only 2) yourself. The benifit is you're only sending 2 verts though the pipeline vs 4.

I've tried rotating vertices manually with GU_SPRITES but it didn't work. It makes sense if you think about it as by manually rotating 2 vertices, you are basically changing the locations of these 2 vertices only. These 2 vertices are the 2 corners of a GU_SPRITE so this "rotation" only changes the SIZE of the SPRITE rather than rotates it.

With 2D images, we are using GU_TRANSFORM_2D rather than GU_TRANSFORM_3D. I think sceGumRotateX/Y/Z may not work. I'm not a GU expert so I guess someone else may have a better answer for this question.

subbie · Post by **subbie** » Fri Apr 07, 2006 1:19 am

dr_watson wrote:
subbie wrote:
In which sense. sceGumRotateX/Y/Z ?

Could also just manualy rotate your verticies (only 2) yourself. The benifit is you're only sending 2 verts though the pipeline vs 4.
I've tried rotating vertices manually with GU_SPRITES but it didn't work. It makes sense if you think about it as by manually rotating 2 vertices, you are basically changing the locations of these 2 vertices only. These 2 vertices are the 2 corners of a GU_SPRITE so this "rotation" only changes the SIZE of the SPRITE rather than rotates it.

With 2D images, we are using GU_TRANSFORM_2D rather than GU_TRANSFORM_3D. I think sceGumRotateX/Y/Z may not work. I'm not a GU expert so I guess someone else may have a better answer for this question.

Ah I see. That might be why.
Could always just do an Ortho projection and transform in 3D. It could lead to many advantages. Since Transform_2d just passes evertything to the rasterizer vs transforming then passing along.

forums.ps2dev.org

JGE++: A hardware accelerated 2D game engine for PSP/Windows

JGE++: A hardware accelerated 2D game engine for PSP/Windows

An introduction to rendering 2D images with GU

Hello World for JGE++

hang

blue screen

prebuilt demo

scrolling & hge

merci