Compiling
---------

To compile CPAL you need SDL, SDL_image and SDL_mixer development files. Get
them from libsdl.org or from your operating systems package repository.


To compile with MSVC use (replace the SDL/ parts with the path to your SDL
development files):

cl cpal.c /O2 /LD /ISDL SDL/lib/SDL.lib SDL/lib/SDL_image.lib SDL/lib/SDL_mixer.lib opengl32.lib


with GCC:

gcc cpal.c -O2 -fpic -L/usr/lib -lGL -lSDL -lSDL_mixer -lSDL_image $(sdl-config --cflags) -shared -o libcpal.so


To compile the example use:

cl cpal.c example.c /O2 /ISDL SDL/lib/SDL.lib SDL/lib/SDL_image.lib SDL/lib/SDL_mixer.lib opengl32.lib

or

gcc cpal.c example.c -O2 -L/usr/lib -lGL -lSDL -lSDL_mixer -lSDL_image $(sdl-config --cflags)



Documentation
-------------

General:

CPAL is a thin wrapper around SDL and OpenGL that aims to provide easy to use
API for basic functionality needed in 2d games. While it can be easily used from
C/C++ it is specially designed to be easily binded to higher level languages
which makes the API a bit cumbersome at some points.
Note: You should be able to mix regular OpenGL functionality with CPAL when
necessary, just note that it does some of its own state management which means
that before calling any GL functions you should call CPAL's palFlushState() function.


Types: 

enum PAL_Resource_Type {INVALID, IMAGE, SAMPLE, MUSIC, FONT, BUFFER}
enum PAL_Blend_Mode {NONE, BLEND, ADDITIVE}
#define BOOL int
#define FALSE 0
#define TRUE 1

Keycodes are standard SDLKey enumerations (SDLK_a, SDLK_b etc.). In addition
keycodes 500 and up are used for mousebuttons, 500 is left mousebutton, 501 is middle
mousebutton etc.
	


Functions:

- BOOL palOpen(char* title, int width, int height, int max_fps, BOOL fullscreenp)

Open CPAL screen/window. If screen is already opened calls palClose() first.
Maximum framerate is capped to max_fps. To disable capping set it to some
insanely high value.


- void palClose()

Closes CPAL and frees all allocated resources.


- BOOL palIsRunning()

Return TRUE if screen is already opened.


- int palUpdate()

Update screen, nothing is shown until this is called. Return an OpenGL error
code if anything goes wrong (if this happens it is likely a bug in CPAL).


- void palClear(int r, int b, int g)

Clears screen with given RGB color.


- int palScreenWidth()
- int palScreenHeight()
- int palMaxImageSize()
- int palGetFps()

Returns screens size, maximum image size (depends on the graphics hardware and driver) and current frames per second.


- void palSetCursor(PAL_Resource* cursor, BOOL showp, float xhs, float yhs)

When PAL_Resource* cursor is an image uses that as mousecursor, with offsets xhs and
yhs. If showp is FALSE hides hardware cursor.


- void palSetMousePos(float x, float y)

Moves mouse pointer to given coordinates.


- void palSetBlendMode(PAL_Blend_Mode mode)
- void palSetBlendColor(int r, int g, int b, int a)

Sets current blend mode and blend color. The default values are BLEND and
255,255,255,255 (white), respectively.
Blend color changes the color of _everything_ drawn on the screen while blend mode
changes the way drawn pixels are combined. It is best to experiment with different
values to see how this works in practice.



- void palRotate(float angle)

Rotates the view angle degrees.


- void palScale(float sx, float sy)

Scales the view horizantally and/or vertically.


- void palTranslate(float x, float y)

Translates (moves) the view by x/y amount.


- void palPushTransformation()
- void palPopTransformation()

Pushes and pops current view transformations to stack.


- PAL_Resource_Type palResourceType(PAL_Resource* r)

Return the type of given resource.


- void palFreeResource(PAL_Resource* r)

Frees given resource. 


- void palFreeAllResources()

Frees all allocated resources (images, fonts etc.).



- PAL_Resource* palLoadImage(char* file, BOOL smoothp)

Loads image. If smoothp is TRUE sets image to use linear interpolation which
looks better if image gets scaled or rotated but is likely to be slower.
If image is bigger than the allowed maximum size (see palGetMaxImageSize()) it
gets clipped.
Non power-of-two sized images get rounded up to nearest power of two. Normally
this is transparent to the user.
Note that all resources are loaded only once, so calling loadImage("foo.png")
repeatedly will give you the same resource each time.



- void palDrawImage(PAL_Resource* resource, float x, float y, BOOL hmirror, BOOL vmirror)
- void palDrawImagePart(PAL_Resource* resource, float fromx, float fromy, float tox, float toy, int width, int height, BOOL hmirror, BOOL vmirror)
- void palDrawPoint(float x, float y, float size, BOOL smoothp)
- void palDrawLine(float x1, float y1, float x2, float y2, float size, BOOL smoothp)
- void palDrawRectangle(float x, float y, int width, int height, PAL_Resource* image, BOOL fill, float size, BOOL absolutep, BOOL smoothp)
- void palDrawCircle(float x, float y, float r, int segments, PAL_Resource* image, BOOL fill, float size, BOOL absolutep, BOOL smoothp)
- int palImageWidth(PAL_Resource* image)
- int palImageHeight(PAL_Resource* image)

- PAL_Resource* palStartBuffer(PAL_Resource* image, int size);
- void palAddToBuffer(PAL_Resource* resource, float fromx, float fromy, float tox, float toy, int width, int height);
- void palDrawBuffer(PAL_Resource* resource);

- PAL_Resource* palLoadFont(char* file)
- void palDrawText(char* string, PAL_Resource* resource, float x, float y, PAL_Text_Alignment alignment);
- int palFontHeight(PAL_Resource* font)
- int palTextWidth(char* string, PAL_Resource* font)

- PAL_Resource* palLoadMusic(char* file)
- void palPlayMusic(PAL_Resource* resource, int volume, int loops, int fade_ms)
- void palStopMusic(int fade_ms)
- PAL_Resource* palLoadSample(char* file)
- void palPlaySample(PAL_Resource* resource, int volume, int direction)


- BOOL palIsKeyDown(int key)

Checks if given key is held down.

- BOOL palIsKeyPressed(int key)

Checks if given key was just pressed down.


- int palMouseX()
- int palMouseY()

Returns mouse position.


- int palHandleEvent()

Handles pending events. If a key was pressed or released its code is returned,
otherwise returns 0. To check the state of the returned key use palIsKeyDown().
At least on Windows you should call this function regularly, preferably once per
each frame.