How to create Games and Apps on your PSP using OSlib

[PSdonkey]

Alright, so you downloaded and installed your PSP Dev environment that I posted in the other sticky here and you have also checked out and compiled some of the samples in your PSP SDK sample folder. Now you are ready to move onto making your own homebrew.

There is an unofficial library for the PSP called OSlib.
(You won't find it at the PSP repository via Subversion or included in any library installer. What this library does is make 2D game making very easy for everyone.)
This is an easily extensible library for doing nice 2D games, apps & demos. It brings you the power of the PSP GPU without having to learn its subtilities.

I have uploaded it for everyone to install in their current PSP Win32 environment setup. I have already precompiled all the OSlib's objects and files and have included all the header files in the link as well. I have also modified the install.bat batch file so that it will install under your new PSP Win32 environment. It was previously only installable under cygwin.
All you have to do is download the file, place the folder in your C:\pspdev folder, go into the install folder and double click the install.bat and you are done.
All the precompiled files will automatically install in the right places including all the header files. I have also included 3 samples in the samples folder with all of the sources for you all to use and check out.

Don't have windows and want to install this OSlib library under Ubuntu Linux? Not a problem. The user _prototype_ has found a nice way to install this library for Ubuntu. Check out his thread and download link here:

http://www.psp-hacks.com/forums/f141...buntu-t189682/

So what is the big deal about this library? What is so special about it?
Well for starters, it is a complete 2D game engine already programmed for you. You really don't need to know how to program in any language to create your very own 2D homebrew game with this. (Knowing C or C++ would help). A lot of the coding that a 2D game would take has already been done for you in simple one line functions for you to implement.

Like I said, I have included 3 samples for you to all take a look at.
The first sample, called logo, shows you how to flip and rotate a full background picture with simple animation.
The second sample, called sprite, shows you how to load a background image and a sprite image to the screen. It then also shows you how to move the sprite (Mickey Mouse) on the screen, stretch the sprite, rotate the sprite, enlarge the sprite and flip the sprite.
The third sample, called maps, shows you how to load over 8 maps on top of each other to give a great 3D view and atmosphere to your game. It also shows how when you move the D-Pad left or right, the maps move along with you. It also loads background music and sound effects for your game.


Here's the download link:
http://www.mediafire.com/?63q5y0tdwsj

More Info
Explanation of Predefined functions
Screenshot of 3rd sample (maps)
Lesson #1 on using OSLib to make homebrew
Lesson #2 on using the PSP's controller inputs
Lesson #3 on Image loading and Sprite movement
Lesson #4 on Sprite Animations
Lesson #5 on creating music and sound effects for your program
Lesson #6 on creating Maps and basic border collision for your game
How to create SND0.AT3 music file for your homebrew in the GAME folder
How to create full screen size images together to make large animations
Here is a good detailed collision function in OSlib you can use to detect collisions between 2 or more images in your program.
How to install OSlib under Ubuntu Linux.

[Chernobyl]

Do you have any screenies of this game running ?

[PSdonkey]

Sure. Here is a screenshot of the second example code that I posted:

[p0Wer]

Lmao, cool!

[A_Z]

I read PSdonkey's tut, practiced with other things, downloaded this file, installed the files and tried the samples...

its damn cool stretching and moving mickey..:P

but I have no idea whats in there or how to really make it... :/

[PSdonkey]

Start off simple by just drawing lines or creating sound effects. It really is easy to do. Go into the Doc folder in the OSlib folder that you downloaded and read all the things that you can do with this library. To draw a color filled rectangle, all you would have to do is use this one function in their library:

void oslDrawFillRect(int x0, int y0, int x1, int y1, OSL_COLOR color);

And that would be it. The x0,y0,x1,y1 are your coordinates for your box, and color is the color you want your box to be filled as. It's that simple. In fact, take a look at all the predefined functions that are made for your use:

_______________________________________________________________________________________________ _______________________________________________________________________________________________
oslib.h

void oslInit(int useOwnCallbacks);
Initializes the library. This function should be called at the beginning of every program. If you put TRUE to useOwnCallbacks, you can manage the standard callbacks by yourself (update_thread, Exit Callback and Power Callback, that must call osl_powerCallback if it's not NULL!).

void oslQuit();
Quits the game immediately. You'll go back to the PSP game menu.

void oslInitGfx(int pixelFormat, int bDoubleBuffer);
Initializes the graphic part. You have to specify pixelFormat, which is in fact the size of a pixel on the screen, as well as if you wish to use double buffering or not.


void oslStartDrawing();
You have to call this function before drawing anything. The number of operations the GPU can do at the same time is limited, and the fact of restart the drawing permits you to start again.

void oslSyncDrawing();
Waits until all pending drawing operations are terminated. This operation can be very slow, because at normal time the GPU works in parallel to our program, and makes its tasks at its pace. This function waits that the GPU finished everything before continue. It is useful if you want to show an image which is going to change afterward (the GPU does not draw it immediately when you ask it to do it, but only when it has finish with the rest of pending operations, and thus meanwhile, the image could have changed and the display will be erroneous).

void oslEndDrawing();
End of the drawing code. It makes sure that everything was correctly drawn too. To be called before synchronizing the screen or swapping buffers.

void oslWaitVSync();
Waits the VSync (60 Hz).

void oslSwapBuffers();
In double buffering mode, swaps the visible and drawing buffer.

void oslEndGfx();
Ends the graphic part of the library. Then you can reset it with other parameters.

void oslFlushDataCache();
Flushes the data cache. Do not use.

int oslSyncFrame();
Synchronizes the screen, use it when you have finish all the drawings. This function will take charge itself swapping buffers or waiting for the VSync.

int oslSyncFrameEx();
Indicates the supplementary parameters for the synchronization.

Frameskip:
0: no frameskip (normal)
1: normal frameskip
>1: depends from vsync, skips 1 frame out of X

Max frameskip:
>=1: Maximum authorized frameskip

VSync:
0: no VSync
1: VSync enabled
+4: if you add 4, fixes the minimum frameskip (ex. with 2, the game will run at 60 fps, but 30 images per second)
+0: else, with frameskip > 1, synchronizes to the wanted framerate, ex. 2 -> 30 fps
Examples:

	//30 fps (no frameskip)
	oslSyncFrameEx(2,0,0);

	//30 fps, game at 60, max frameskip is 2, this means no more than one frame skipped per one displayed
	oslSyncFrameEx(2,2,4);

	//synchronizes to 60 fps
	oslSyncFrameEx(0,0,0);

void void oslSetTransparentColor(OSL_COLOR color);
Defines the color the transparent color. If a pixel of the image you want to draw is of this colour, it will not be drawn. It extends to anything (text, rectangles, etc.), that's why you should rather desactivate it once your image is drawn. During the loading of an image, pixels which have this color will take the alpha value 0, indicating that they are transparent, so you can activate the transparent color only when loading images and deactivate it when finished, it's simplier.

void oslDisableTransparentColor();
Deactivates the transparent color (all the pixels will be drawn, except those whose alpha is null).

float oslSin(int angle, int dist);
Computes the sinus from the specified angle, multiplying it by the specified ray.

float oslCos(int angle, int dist);
Idem for cosinus.

int oslGetNextPower2(int val);
Returns the next power of two for the passed number.

OSL_IMAGE *oslCreateImage(int larg, int haut, short location, short pixelFormat);
Creates a new image with the supplied parameters. Location can be OSL_IN_RAM (in RAM, 20 MB, slow) or OSL_IN_VRAM (in VRAM, 2 MB, fast). The VRAM is very limited, so use it only for the very often used images.

void oslDeleteImage(OSL_IMAGE *img);
Deletes the specified image. There is no VRAM manager by now, so if the image is in VRAM, you must have to erase the last created one, then the one which before it, in this order.

OSL_IMAGE *oslLoadImageFile(char *filename, int location, int pixelFormat);
Loads an image file (only the PNG is supported for the moment). You can choose where to put it as well as its pixelformat.

OSL_IMAGE *oslCreateImageTile(OSL_IMAGE *img, int offsetX0, int offsetY0, int offsetX1, int offsetY1);
Creates an image referencing a piece of another. You can use it to indicate a zone between (offsetX0, offsetY0) and (offsetX1, offsetY1) into img. The image contents is not copied, just referenced, but you have to call oslDeleteImage anyways when you finished with it.

OSL_IMAGE *oslCreateImageTileSize(OSL_IMAGE *img, int offsetX0, int offsetY0, int width, int height);
Idem, except that you specify the upper-left positions and the width/height of the zone.

void oslCopyImage(OSL_IMAGE *imgDst, OSL_IMAGE *imgSrc);
Copies an image to another. The format of both images must be the same.

void oslSwizzleImage(OSL_IMAGE *imgDst, OSL_IMAGE *imgSrc);
Creates an optimized copy of imgSrc to imgDst. imgSrc must be different than imgDst. The optimized version is faster to display with the GPU, but you cannot modify it after.

void oslClearImage(OSL_IMAGE *img, int color);
Erases the image entirely using the specified color.
Note: If the image is in RAM, the operation is made by the main processor. It is slower, and the color calculation is not the same as the one from the GPU. Furthermore, in 8 or 4 bits mode, the color specifies the palette index to fill the buffer, and not the real color to be looked for in the palette.

vvoid oslUncacheImage(OSL_IMAGE *img);[/i]
Flushes the specified image from the CPU cache. You have to call this function before displaying an image from which you modified the data.

OSL_IMAGE *oslCreateImageCopy(OSL_IMAGE *src, int newLocation);
Creates a copy of the specified image.

OSL_IMAGE *oslCreateSwizzledImage(OSL_IMAGE *src, int newLocation);
Idem, but the copy will be swizzled (optimized).

OSL_PALETTE *oslCreatePalette(int size, short pixelFormat);
Creates a new palette containing size colors of pixelFormat type.

OSL_PALETTE *oslLoadPalette(void *data, int size, short pixelFormat);
Creates a new palette from an array defined in your code.

void oslDrawImage(OSL_IMAGE *img);
Draws the specified image, using parameters contained in it.

void oslDrawImageSimple(OSL_IMAGE *img);
Draws the specified image. It's a faster version, but it doesn't support rotation.

void oslDrawLine(int x0, int y0, int x1, int y1, OSL_COLOR color);
Draws a line using a specified color between the points (x0, y0) and (x1, y1).

void oslDrawRect(int x0, int y0, int x1, int y1, OSL_COLOR color);
Draws a frame (empty rectangle).

void oslDrawFillRect(int x0, int y0, int x1, int y1, OSL_COLOR color);
Draws a filled rectangle.

void oslDrawGradientRect(int x0, int y0, int x1, int y1, OSL_COLOR c1, OSL_COLOR c2, OSL_COLOR c3, OSL_COLOR c4);
Draws a four-point gradient (c1: upper-left, c2: upper-right, c3: bottom-left, c4: bottom-right).

OSL_MAP *oslCreateMap(OSL_IMAGE *img, void *map_data, int tileX, int tileY, int mapSizeX, int mapSizeY, int map_format);
Create a new map. map_format must be OSL_MF_U16 (each element of the map is an unsigned short). img is the tileset (the width has to be a power of two), tileX and tileY the size of each tile, mapSizeX and mapSizeY the total size of the map.

void oslDrawMap(OSL_MAP *m);
Draws the specified map.

void oslDrawMapSimple(OSL_MAP *m);
Faster version, tileX, tileY and the tileset width must be powers of two.

void oslClearScreen(int backColor);
Clears the screen with the specified color.

void oslSetScreenClipping(int x0, int y0, int x1, int y1);
Sets the screen region on which you can draw. Anything outside this rectangle will not be drawn. It is useful for windowing for example.

void oslSetDrawBuffer(OSL_IMAGE *img);
Defines the image on which you want to draw. Pass OSL_DEFAULT_BUFFER to reset to the default screen and OSL_SECONDARY_BUFFER for the currently displayed buffer in double-buffering mode.

void oslSetAlpha(int effect, int coeff);
Defines the alpha parameters (transparency). The alpha type can be one of the following:

OSL_FX_NONE: no effect.
Formula: dst = src; (alpha is also copied to the destination, not computed)
[color=orangeOSL_FX_FLAT: Identical to OSL_FX_NONE, except that if alpha is null, the pixel will not be drawn.
Formula: dst = (src & 0xff000000) ? src : dst;
OSL_FX_RGBA: Takes the alpha channel in account for color computation. By calling this, you can for example draw a transparent blue box like this:
oslDrawFillRect(0,0,100,100,RGBA(0,0,255,128));
For the alpha channel, zero means transparent, and 255 opaque. Those values can also be used for each pixel of an image or each color of a
palette, allowing to render parts of your image transparent very easily. It's the default mode.
Formula: dst = src * asrc + dst * (1 - asrc);
OSL_FX_ALPHA: Alpha blend (normal transparency). The coefficient is multiplicated by the source color to define if your plane is
more or less transparent
Formula: dst = src * coeff + dst * (1 - coeff);
OSL_FX_ADD: Adds the source and destination, useful for "ghost" planes. You can also specify the coefficient, which is multiplicated
by the source value before the addition. If you want simple addition, pass 0xff as coefficient.
Formula: dst = src * coeff + dst;
OSL_FX_SUB: Substracts the source and destination. Useful for "mask" planes.
Formula: dst = src * coeff - dst;
OSL_FX_COLOR: Add (with an OR) to other effects so that you can define the transparency for each RGBA component. For example,
if you want to tint an image to red, you can do:
oslSetAlpha(OSL_FX_ALPHA|OSL_FX_COLOR, RGBA(0xff,0,0,0xff));


void oslSystemMessage(const char *message);
Displays the Sony system message. It is strange, but it doesn't work very well.

unsigned int oslMessageBox(const char *text, const char *title, unsigned int flags);
Displays a small dialog box.

int oslBenchmarkTestEx(int startend, int slot);
Makes an operation on the specified benchmark slot.

OSL_CONTROLLER *oslReadKeys();
Reads the current joypad state and stores it into the global variable named osl_keys. It also returns a pointer to those data.

int oslWaitKey();
Waits a key pressed and returns its code.

int oslKbhit();
Returns the last pressed key code, and if this code is not null, you can call oslWaitKey to get it (none of the keys pressed after will be stored until you called oslWaitKey).

void oslFlushKey();
Empty the key buffer, so that next pressed keys are taken in account.


_______________________________________________________________________________________________ _______________________________________________________________________________________________
audio.h

int oslInitAudio();
Initializes the audio part of the library. This function must be necessarily called if you want to play any sound from your program.

void oslDeinitAudio();
Destroyes the audio part of the library. After having called this function, it will not be possible to play sound anymore. Call it to free audio resources and make sure that any sound is stopped.

void oslPlaySound(OSL_SOUND *s, int voice);
Plays a sound on the specified audio channel. The channel number can be between 0 and 7, and if you play the sound on an already used channel, the new sound will replace the one which is currently being played.

int oslGetSoundChannel(OSL_SOUND *s);
Allows to know on which hardware audio channel a sound is currently played. The result is -1 if the sound is not played at the moment.

void oslStopSound(OSL_SOUND *s);
Stops a sound being played, and does nothing in the opposing case. To resume the sound, call oslPlaySound, the sound will be played since the beginning.

void oslPauseSound(OSL_SOUND *s, int pause);
Pauses a currently played sound. If the pause argument is 1, the sound is paused, if it's 0 the sound is resumed (from where it had been paused), if it's -1 the current state is inverted (play/pause).

void oslAudioVSync();
Call it in your main loop if you stream some sounds. Why? When you put your PSP in stand-by mode, the kernel closes all opened files! Then, obviously the audio system was crashing. Now OSLib manages that, but it is necessary to reopen files later to continue, and it's not possible directly when the PSP wakes up because the MS is not initialized yet. This function will verify that the MS is ready, and reload files and continue where they stopped if they were. If you do not call this function, any sound currently played in streaming will be stopped when the PSP wakes up. However, it will be reloaded automatically (but restart at the beginning) when you call oslPlaySound. Exactly the same for sounds which were opened in streaming but which were not playing at this moment.

OSL_SOUND *oslLoadSoundFile(const char *filename, int stream);
Loads a .wav or .bgm file. You just need to indicate the file name as well as if you wish to stream it from the Memory Stick. If you are streaming a sound, it will not be loaded in memory, that makes you spare loading time but especially many RAM space, because the PSP as "only" 20 MB, so imagine that if you load sound effects of 1 MB each, it will be quickly saturated (memory is also shared for your code, variables, images and sound). However, streaming affects performance, especially for a high sample rate. For better performances, I advise you to use small .wav loaded for the sound effects and streamed .bgm for musics. You can also stream sound effects, but only those which are very rarely played at normal time.

int oslDeleteSound();
Deletes a sound.

void oslSetSoundLoop(OSL_SOUND *s, int loop);
Sets up looping for a sound. If the sound is looped (loop = TRUE), the sound will be repeated when finished.

[PSdonkey]

Here is a scree nshot of the third sample using the maps. This game has 8 different maps layered on top of each other to give it a realistic 3D environment. It also has music and sound effects.

[Chernobyl]

Thats pretty sweet, just like Mario but widescreen mode :D

[PSdonkey]

OK, so it seems like most people here want a simple and basic tutorial on how to create their own homebrew. I will now start giving out lessons here using OSlib on how to begin creating homebrew. I will start with just the basics on displaying "hello World" on your PSP and then move up to more advanced homebrew. All of these lessons will use the library OSlib so make sure you have that library installed (check my first post in this thread). Using this library will make creating homebrew a LOT more simplier then using just the standard PSPSDK.



Lesson 1: Displaying HelloWorld on your PSP.

First of all, create a new directory. It will contain the files of your project. In this directory, we will create a makefile (it's a text file describing our project, in order to know which compiler to use, which files to compile, which libraries to use, and which file to produce in the end).

The Makefile is a file named Makefile (without extension). Here is the Makefile we will use for our first lesson:

TARGET = Donkey_Lesson1
OBJS = main.o  

INCDIR = 
CFLAGS = -G4 -Wall -O2 
CXXFLAGS = $(CFLAGS) -fno-exceptions -fno-rtti
ASFLAGS = $(CFLAGS)

LIBDIR =
LDFLAGS =
STDLIBS= -losl -lpng -lz \
  -lpspsdk -lpspctrl -lpspumd -lpsprtc -lpsppower -lpspgu -lpspaudiolib -lpspaudio -lm
LIBS=$(STDLIBS)$(YOURLIBS)


EXTRA_TARGETS = EBOOT.PBP
PSP_EBOOT_TITLE = Donkey_Lesson1


PSPSDK=$(shell psp-config --pspsdk-path)
include $(PSPSDK)/lib/build.mak

Ok, lets talk about the Makefile.
Look at the first line TARGET = Donkey_Lesson1. That is the name of our project. You can change it to whatever you would like.
Then, there is OBJS = main.o. That tells what object files are to be created, that mean files to be compiled. Files that will be created have the extension .o (it is the result of the compilation of .c or .cpp files), that's why I wrote main.o and not main.c.
The line YOURLIBS = defines your own libraries to be added to the project.
PSP_EBOOT_TITLE is the name which will appear to the PSP game selection menu.
For the other lines in the makefile, you do not need to worry or change them, except when you want to use another library.

If you simply want to add OSLib to an already existing project, you just have to add -losl to your libraries list. However you have to make sure that all the system libraries on which OSLib depends are included, and placed in this order (otherwise you will get errors at linking stage):

-losl -lpng -lz -lpspsdk -lpspctrl -lpspumd -lpsprtc -lpsppower -lpspgu -lpspaudiolib -lpspaudio -lm

Now, here is the source file for our first lesson:

//OSlib header file
#include <oslib/oslib.h>

//callbacks
PSP_MODULE_INFO("OSLib Sample", 0, 1, 1);
PSP_MAIN_THREAD_ATTR(THREAD_ATTR_USER | THREAD_ATTR_VFPU);

int main()
{
    //Initialization of the Oslib library
    oslInit(0);

    //Initialization of the graphics mode
    oslInitGfx(OSL_PF_8888, 0);

    //Initialization of the text console
    oslInitConsole();

    //Print on the screen this text
    oslPrintf("Hello World");

    //Wait for a button to be pressed
    oslWaitKey();
    
    //terminate the program
    oslEndGfx();
    oslQuit();
    return 0;
}

Source code Explanation:

1) #include <oslib/oslib.h>
You must include this in all of your programs that use OSlib.

2) PSP_MODULE_INFO (“OSLib Sample”, 0, 1, 1);
PSP_MAIN_THREAD_ATTR (THREAD_ATTR_USER | THREAD_ATTR_VFPU);
This code is necessary for the PSPSDK to run the EBOOT that will be made by our program.

3) oslInit (0);
void oslInit(int useOwnCallbacks);
This line of code takes care of all your PSP callbacks. Normally, without this library, you would have to setup and initialize your callbacks with every single PSP program. With this line of code, you don't need to worry about the callback initialization, as long as the value 0 is between the parenthesis (). If you want to use your own callbacks (if you do not know what that is, do not change it, of course), type 1 in the parenthesis.

4) oslInitGfx (OSL_PF_8888, 0);
void oslInitGfx(int pixelFormat, int bDoubleBuffer);
This is used to initialize the graphic part, by specifying which pixelformat you want to use on the screen, as well as if you want to use double buffering. Default 0 is used for single buffereing and 1 for double buffereing. We will talk about later what are pixelFormats, for the time being simply use OSL_PF_8888 for a 32-bit screen (2^32 = 16,777,216 colors) or OSL_PF_5650 for a 16-bit screen (2^16 = 65,536 colors) as an argument for pixelFormat.

5) oslInitConsole ();
This initialize the text part of the PSP, to be able to draw some text (the standard Sony font is loaded at this moment).

6) oslPrintf (“Hello World”);
This prints on the screen like the good old code printf, with the same use (oslPrintf (“%i”, variable) to post the contents of an integer variable for example)
You can decide where you would like your text to be placed on the screen with a oslPrintf_xy (X, y, “text”) with X and Y as the coordinates in pixels.

7) void oslEndGfx();
This ends the graphics part of the library. You can also reset it with other parameters.

8) oslQuit ();
Quits the game immediately. You'll go back to the PSP game menu.

9) return 0;
Always used at the end of main()



So that is the basics of creating your first homebrew displaying helloworld. I tried to keep it as simple and basic as possible. Try changing the text and try placing your text in different areas of your screen to learn more about this lesson.

In the next lesson, "lesson 2" (awesome name, eh? :P), I will talk about controller inputs and how to use the PSP buttons.

[ZiNgABuRgA]

Wow, nice guide (lol, how long does it take you to type up all that stuff?).
Goes quite deep into the graphics/sound libraries... (I hope everyone understands all of that - if not, just skip it for now :P).

Oh, and PSdonkey, you may wanna put the links for:
unsigned int oslMessageBox(const char *text, const char *title, unsigned int flags);

and
int oslBenchmarkTestEx(int startend, int slot);

Again, nice guide :P