SDL_oglblit v. 0.5

1. About
 1.1 License
 1.2 Authors
 1.3 Limitations
 1.4 Implementation and structure

2 Compiling and linking
 2.1 Building the library
 2.2 Linking with the library

3. Function Reference
 3.1 Types
 3.2 Library functions

4. Examples

1. About

SDL_oglblit is a library for doing fast, hardware accelerated 2D operations with
SDL surfaces using OpenGL. It supports hardware rotation and scaling while
blitting with no cost in regards to performance.

For the latest version of SDL_oglblit check its website at
http://nurd.se/~noname/sdl_oglblit/

1.1 License

Gnu Public License v. 3, see license.txt for more details.

1.2 Authors

Fredrik Hultin
email: noname() the same domain as the website

1.3 Limitations


The library does not do any inter-surface blitting operations, all such
operations will have to be done using normal SDL blits before converting the
surfaces to OpenGL textures and should be avoided.

1.4 Implementation and structure

The project uses a fairly standard directory structure. The source goes in src/
and the headers in include/. An example on how to use the library can be found
under example/.

2. Compiling and linking

To build the project you could either build it as a library using the provided
cmake project file, or embed SDL_oglblit into your project. SDL_oglblit has no
external dependencies part from SDL and OpenGL.

2.1 Building the library

To compile the library using the provided cmake project file, create a directory
anywhere on your system where you want to build SDL_oglblit, eg. /tmp/build. 

 mkdir /tmp/build
 cd /tmp/build

Run cmake with the path you downloaded and extracted SDL_oglblit to.

 cmake ~/downloads/sdl_oglblit-XX

Then run make while still in the temporary build directory you created. 

 make

Once the compilation finishes (which it will in about 2 seconds if your system
isn't painfully slow), run make install as root to install the library.

 sudo make install


I did add some initial support for building distribution packages, like Debian
.deb-files, in the cmake project file but at the time of writing this is a new
and experimental feature of cmake. Consult the cmake documentation if you want
to try this out.

2.2 Linking with the library

To link SDL_oglblit with your project you can use the pkg-config files cmake
should have installed on your system. To get the needed cflags and ldflags use

 pkg-config --cflags SDL_oglblit
 pkg-config --libs SDL_oglblit

As an example, if you have a file called myproject.c, you can compile and link
that with gcc and SDL_oglblit using the command

 gcc `pkg-config --cflags SDL_oglblit` `pkg-config --libs SDL_oglblit`
myproject.c -o myproject


3. Function Reference

3.1 Types

typedef struct
{
 GLuint name;  /* OpenGL texture name (texture id) */
 GLenum format;  /* The color format of the texture */
 int w, h;  /* The width and height of the original surface */
 int wTex, hTex;  /* The actual size of the OpenGL texture (it might differ,
power of two etc.) */
} OGL_Texture;

All members are to be considered read only.

3.2 Library functions

---------------------------------------------------
int OGL_Init(int w, int h, int bpp, Uint32 flags);
---------------------------------------------------
Initializes SDL with OpenGL with the given width, height, color depth and flags.
Note that OGL_Init does not return a pointer to the screen surface. You can't do
much with the screen surface in OpenGL mode, but if you need it you could use
the SDL-function SDL_GetVideoSurface() to get a pointer to it.

w  Desired width of the screen
h  Desired height of the screen
bpp  Desired bit depth of the screen
flags  SDL_Surface flags, passed along to SDL_SetVideoMode. SDL_OPENGL is
automatically added. Passing 0 is ok.
Returns  0 if it is successful and -1 if it encounters an error.

---------------------------------------------------
void OGL_FreeTexture(OGL_Texture* texture);
---------------------------------------------------
Frees a OGL_Texture structure created with OGL_FromSurface.

texture  A pointer to a texture you wish to free.

---------------------------------------------------
void OGL_Flip();
---------------------------------------------------
Flips the OpenGL buffers, updates the screen.

---------------------------------------------------
void OGL_Clear();
---------------------------------------------------
Clears the screen.

---------------------------------------------------
void OGL_Blit(OGL_Texture* texture, SDL_Rect* clipping, int x, int y, GLfloat
vZoom, GLfloat hZoom, GLfloat rotation);
---------------------------------------------------
Blits an OGL_Texture to the screen. Note that blits are texture centered. So a
blit of a 32 x 32 sized texture on position 64, 64 would result in a destination
rectangle of x = 48, y = 48, w = 32, h = 32. This to make positioning more
logical when zooming and rotating the texture.

texture  A pointer to the OGL_Texture you wish to blit to the screen.
clipping The area of the source texture you wish to blit. If NULL is passed the
whole texture will be used.
x  Horizontal target position of the blit.
y  Vertical target position of the blit.
vZoom  Vertical zoom of the resulting blit (0.5 = half the size, 2.0 = double
the size).
hZoom  Horizontal zoom of the resulting blit.
rotation Rotation of the resulting blit in radians.

---------------------------------------------------
OGL_Texture* OGL_FromSurface(SDL_Surface* surface);
---------------------------------------------------
Creates an OGL_Texture from an SDL_Surface. Should work on any surface in terms
of color bit depth, color space and size as long as SDL can handle it. To avoid
intermediary blits during conversion it is however most efficient to use RGB or
RGBA surfaces with power of two width and height.

surface  An SDL_Surface to convert to an OGL_Texture.
Returns  A pointer to the new OGL_Texture, or NULL if it fails. Use
SDL_GetError() to fetch any error messages.

4. Examples

See the examples-directory in the SDL_oglblit project root.