The intended public for this document is OSDL developers, i.e. working on the library itself : OSDL users ought to refer to the OSDL User Guide.
This developer's guide is still to be written, however here are a few hints about OSDL's inner working.
See also : Ceylan developer's guide for common informations.
|
Note : this documentation is quite deprecated, it would need some serious update and rewriting.
|
For some transverse subjects, such as the anti-aliasing mode (wanted or not), at least two ways of managing these informations were possible, having them static or not :
OSDL::VideoModule::GetAntialiasingState), a specific instance of a module would have to be used and, therefore, passed in some way to its caller. It would imply adding arguments to most methods or, preferably, use a kind of state machine where, unless specified otherwise, there would be a current instance of module to which operations would be applied.The first solution was preferred, since the 'singleton to many instances' transition could be performed with a state machine indeed, but the call to static methods could handle that internally without needing to perform tremendous changes in the code that uses these features : that change could be transparent for user code.
The endianness of the system is detected at compile-time (#if SDL_BYTEORDER == SDL_BIG_ENDIAN...#else ... #endif), not at "run-time" ( if (SDL_BYTEORDER == SDL_BIG_ENDIAN) {... } else { ... }). This does not change much, since even the second form, which should evaluate to a comparison between constants, should be translated by the compiler similarly to the first one.
First of all, the Ceylan release guide should be applied in the OSDL context as well. Additional actions are :
ceylan.m4 in trunk/src/conf/build/m4.As for SVN, it leads to a tag command like :
|
Here is an example template for the osdl-announces@lists.sourceforge.net list :
|
The corresponding news item could be :
|
Then update both LOANI archives in Sourceforge file release system.
Follow again the Ceylan release guide.
To use another version of gcc than the one OSDL selected (use make checktools to check which would be used by default), redefine GCC_ROOT make variable so that it points to the compiler you want to use. Ex : if one wants to use the gcc compiler installed under /usr/local (i.e. /usr/local/bin for gcc executables and /usr/local/lib for its libraries), one would use : make all GCC_ROOT=/usr/local. If GCC_ROOT is not redefined, and if with its default value (GCC_ROOT being the directory where OSDL and Ceylan were extracted, i.e. GCC_ROOT = OSDL/OSDL-x.y/src/../../..) no compiler can be found, then it will be searched through the PATH. If gcc is to be found in the PATH, its corresponding libraries are supposed to be found in the LD_LIBRARY_PATH environment variable.
| Make variable | Meaning | Used in build phase |
|---|---|---|
| INC | include flags | compilation |
| DFLAGS | debug flags | compilation and link |
| CFLAGS | compile flags | compilation |
| LDFLAGS | link flags | link |
| OPT | option flags | compilation and link |
With many projects, fine tuning of installation settings is difficult since usual make variables, such as INC or LDFLAGS, are set and used directly by the project.
For example, often the configure step determines which series of library names and locations should be used. Too often, there is no way for the user to define his settings and to add directly what lacks.
For example, users need to be able to add to LDFLAGS the following : -L<a path> -l<a library>. Unfortunately, they cannot use make LDFLAGS="-L<a path> -l<a library>" since LDFLAGS is used by most project, and it would erase any previous information hardcoded in LDFLAGS.
An unsatisfying solution would be to take LDFLAGS's hardcoded value, to add the settings the user wants to add, and to define a full new LDFLAGS value, which would contain both informations, from the command line. This solution is a bad idea, since the hardcoded value, often set by the configure step, depends on the platform, therefore the user fix would break portability.
To overcome this issue, we chose deliberatly not to use in OSDL internals the following variables :
INCDFLAGSCFLAGSLDFLAGSOPTLDFLAGS=) and
to make us of variables with the same names, but suffixed with _PRIV, which stands for "private to the project" (ex : LDFLAGS_PRIV).
That way, everywhere where library informations were needed, we used $(LDFLAGS) $(LD_FLAGS_PRIV), in that order, letting the possibility to customize the build thanks to a LD_FLAGS which would not interfere with our LD_FLAGS_PRIV. So the user just has to specify make LDFLAGS="-L<a path> -l<a library>" to add, not replace library informations and such.
Of course, if ever one wanted actually to replace these values, he just would have to specify
make LDFLAGS_PRIV="-L<a path> -l<a library>".
This procedure applies for the Ceylan library as well.
One should not be afraid of those libtool warnings for various libraries :
|
libtool: link: warning: library `<your path>/LOANI-installations/SDL_image-1.2.3/lib/libSDL_image.la' was moved.
|
For the moment, we did not manage to get rid of these messages, but they do not really matter since they do not denote any real problem.
The library itself, whether downloaded as binary or rebuilt from sources, is named :
libOSDL.so.0 and
libOSDL.so pointing directly towards
libOSDL.so.0.0.4.libOSDL.a, and with libOSDL.la, which
does respect GNU libtool's conventions (no links for them, .a
and .la are different files)Please keep in mind that OSDL is a multimedia-oriented library built on top of pre requesites, so you should install them priorly to have OSDL-0.4 working.
One interesting file to source is OSDL-environment.sh, which is to be found under the prefix used by LOANI, LOANI-installations by default.
By sourcing this script, you set your shell environment so that all LOANI installed tools are selected, thanks to the PATH and LD_LIBRARY_PATH environment variable.
When developing code that performs rendering, it is often difficult to know what is exactly drawn in each step, or what might be the culprit of an unintended behaviour : the graphic system (OSDL) or the user program performing the actual rendering ? One very easy way to tell it is to use the screenshot generating capabilities of the Surface class. For example, using Surface::savePNG allows to freeze graphics being generated at runtime, in order to understand what happens actually.
The build of tests is split from library's build, since we designed these tests to behave exactly as any other user application which would make use of Ceylan or OSDL.
If you have informations more detailed or more recent than those presented in this document, if you noticed errors, neglects or points insufficiently discussed, drop us a line!