WesnothGL
From Wesnoth
Contents |
Wesnoth Open GL Framework
Wesnoth has a simple framework for using OpenGL to render 2D graphics.
Developers are discouraged from calling OpenGL directly from general code. Rather, code that calls OpenGL should be placed in the namespace gl, and should provide a simple interface that hides the underlying implementation well.
Overview
OpenGL redraws the entire screen for every frame. It can do this quite fast on most systems, but it does mean that the application code needs to be designed to be able to render a frame efficiently, if necessary using some kind of caching.
The function gl::prepare_frame() should be called at the start of every frame, and gl::flip() should be called when ready to update the screen.
Drawing SDL Surfaces with OpenGL
To allow easy use with SDL, the gl framework provides a function to draw SDL_Surface objects. The function is declared in gl_draw.hpp, and is called gl::draw_surface.
gl::draw_surface() is very easy to use -- simply pass it the surface, the x,y co-ordinates to draw at, and some other optional parameters, and it will draw the surface.
gl::draw_surface() is not the most efficient way to draw surfaces though. It has to convert the SDL_Surface to an OpenGL texture, and this is not a fast process. However, it keeps a one-way-associative cache of the OpenGL textures for past surfaces, and so drawing the same SDL_Surface over and over for subsequent frames is *usually* quite fast. (Since the cache is only one-way-associative though, it is possible for things to thrash in and out of the cache).
More Efficient Drawing
Drawing can be performed more efficiently by using the gl::image class. The gl::image class is constructed with an SDL_Surface. The SDL_Surface is not referenced by the gl::image after construction, and so may be discarded if its only purpose is to construct the gl::image.
gl::image provides a number of drawing functions, similar to gl::draw_surface. If an image is going to be drawn over and over, it is recommended to keep it in a gl::image.
To allow gl::image objects to easily be acquired, there is a global cache of them. To get a gl::image, one can simply call gl::get_image(), with a filename or ::image::locator. The gl::image cache is currently never cleared or items removed from it. Thus, it is recommended that only images that are small and will be frequently used are placed in this cache (e.g. terrain/tiles, units, and so forth).
It is recommended that larger, less often used images (e.g. storyline images), be obtained from the normal SDL_Surface image cace, and drawn with gl::draw_surface().