______   ___    ___
    /\  _  \ /\_ \  /\_ \
    \ \ \L\ \\//\ \ \//\ \      __     __   _ __   ___ 
     \ \  __ \ \ \ \  \ \ \   /'__`\ /'_ `\/\`'__\/ __`\
      \ \ \/\ \ \_\ \_ \_\ \_/\  __//\ \L\ \ \ \//\ \L\ \
       \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
        \/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
                                       /\____/
                                       \_/__/


                PlayStation Portable-specific information.

                Written by diedel.

         See readme.txt for a more general overview.


PlayStation Portable notes

This is a near complete PSP port. It's very young so all feedback is welcome!


Required software

To build Allegro under PSP, you need:


Installing Allegro

Allegro ships in source code form; this means you need to compile it before you can use it. The first step is to generate the makefile so that Allegro can be built for PSP, by running:

      chmod +x fix.sh
      ./fix.sh psp
If you have checked out a development version from Allegro's SVN repository, run the following command. Otherwise, skip this step:
      make depend
Now Allegro is ready to be compiled. Start building it:
      make lib
And finally you install it:
      make install
Allegro has now been installed in your PSP development directories as a static library, typically in /usr/local/pspdev/psp/lib. And the headers in /usr/local/pspdev/psp/include. For a static debug version of the library:
      make DEBUGMODE=1 lib install
And for a static profile version:
      make PROFILEMODE=1 lib install


Building your own programs

To avoid you having to work out the right compiler and linker options for yourself, the installation creates a script, psp-allegro-config. It fills out include and library paths, and links the right libraries for you. For build the Allegro programs use the standard Makefile as supplied with any PSPSDK sample program. Example: the Makefile for building the Allegro "Hello, world! example program

      TARGET = exhello
      OBJS = exhello.o

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

      LIBDIR =
      LDFLAGS =
      LIBS =

      EXTRA_TARGETS = EBOOT.PBP
      PSP_EBOOT_TITLE = Allegro Hello World

      PSPSDK=$(shell psp-config --pspsdk-path)
      PSP_PREFIX = $(shell psp-config --psp-prefix)
      PSPBIN = $(PSP_PREFIX)/bin
      CFLAGS += $(shell $(PSPBIN)/psp-allegro-config --cflags)
      LIBS += $(shell $(PSPBIN)/psp-allegro-config --libs release)
      include $(PSPSDK)/lib/build.mak
Or if you want to build a debug version of your program, assuming that you have installed the debug version of Allegro, change these lines:
      ...
      CFLAGS = -G0 -Wall -O2 -g
      ...
      LIBS += $(shell $(PSPBIN)/psp-allegro-config --libs debug)
      ...


The Allegro magic main

When writing an Allegro program, the typical use for portability is to don't worry with the PSP init stuff (setup callbacks, etc.) and add the Allegro END_OF_MAIN() macro at the end of your main() function (see allegro.txt). The default linked -lalleg-main library provides the real main() with the necessary PSP init code:

For write the real main() and the PSP init code yourself define the ALLEGRO_NO_MAGIC_MAIN prior to include the Allegro headers:

      ...
      #define ALLEGRO_NO_MAGIC_MAIN
      #include <allegro.h>

      int main(void)
      {
      ...
And, following the above Makefile example, change the corresponding line by this one:
      ...
      LIBS += $(shell $(PSPBIN)/psp-allegro-config --libs release | sed -r s/-l\(alleg\|alld\|allp\)-main//)
      ...


Notes on drivers

This section contains PSP-specific notes on the drivers available.

Graphics:
The 15, 16 and 32 bpp modes are supported with accelerated blitting and triple buffering.

Support for screen resolutions not bigger than 480x272 and always centered at the PSP display. Typical resolutions like 320x200 or 360x272 (4:3 aspect ratio) can be used.

Support for virtual screens bigger than the 480x272 physical screen (with some restrictions in the truecolor modes) and scroll. Due to PSP hardware restrictions the scrolling routine handle horizontal scrolling in eight pixel increments under 15, 16 bpp modes and four pixel increments under 32 bpp mode.

The 8 bpp mode is also supported but via emulation because the PSP don't support a 8 bpp direct display framebuffer: in some cases the direct screen access in this mode don't work as expected and no accelerated blitting neither triple buffering is supported. But this mode has advantages like less memory consumption, ability to use palette effects, it supports any virtual screen resolution and is the only mode which can scroll horizontally pixel by pixel.

Each video bitmap created has his own memory surface rather than being a screen sub-bitmap.

Sound:
The sound output is 44100 Hz, 16 bits, stereo and the multivoice is supported via the Allegro mixer.

Keyboard:
The keyboard must be polled to get the key presses unlike most of the platforms which update the keyboard state from interrupts.

This is the PSP controller button to key mapping:

          SELECT          Esc
          START           Enter
          UP              Cursor Up
          RIGHT           Cursor Right
          DOWN            Cursor Down
          LEFT            Cursor Left 
          TRIANGLE        Left Control
          CIRCLE          Alt
          CROSS           Space
          SQUARE          Tab
          LEFT TRIGGER    Left Shift
          RIGHT TRIGGER   Right Shift
This is useful for common functions like Allegro GUI dialog navigation, etc.

Joystick:
Only a digital joystick with two axes and 8 no directional buttons has been implemented.

The button mapping is:

          0 TRIANGLE
          1 CIRCLE
          2 CROSS
          3 SQUARE
          4 LEFT TRIGGER
          5 RIGHT TRIGGER
          6 SELECT
          7 START
And the PSP digital pad for the directional control.

Mouse:
The driver is not implemented yet.