avolkov
919d4ffb4c
git-svn-id: svn://svn.code.sf.net/p/sc2/code/trunk@1893 8092fc87-c524-0410-9efc-e669fe64eaf9
130 lines
4.9 KiB
Plaintext
130 lines
4.9 KiB
Plaintext
UQM Code DataPlate modules
|
|
=====================================================================
|
|
Terminology:
|
|
------------
|
|
cdp Code DataPlate
|
|
refers to either a module or the architecture
|
|
itself;
|
|
|
|
module cdp module (ditto ^)
|
|
|
|
interface a set of functions defined by either the core
|
|
engine or a module aimed at performing various
|
|
tasks on a specific part of the game
|
|
|
|
itf interface; short form
|
|
|
|
host the game itself or core engine; also a top-level
|
|
interface for use by modules
|
|
|
|
interface kind a unique identifier of a particular defined
|
|
interface (not of the interface instance);
|
|
there can be several interfaces of the same
|
|
kind registered, but they all have to cover
|
|
different API versions (version ranges may
|
|
overlap though)
|
|
|
|
standard interface interface *defined* by the core engine
|
|
all host, sound, video, gfx, threads, time,
|
|
input, io (uio), memory, resource interfaces
|
|
are standard, including all subdivisions like
|
|
'sound mixer' and 'sound decoder';
|
|
a module can implement standard behavior of
|
|
the game or extend the game by implementing and
|
|
registering a corresponding interface
|
|
|
|
built-in interface interface *provided* by the core engine
|
|
e.g. host, sound, video, gfx, etc. lib wrappers
|
|
anything except 'host' can theoretically be
|
|
implemented as a 'standard' interface rather
|
|
than built-in; sound and video interfaces,
|
|
for example, would not make sense to rip out
|
|
from the core, but parts of 'gfx' might be good
|
|
candidates (gfx should probably be more than
|
|
1 interface); do not confuse 'sound' interface
|
|
with 'sound decoder' and 'sound mixer', mixers
|
|
(MixSDL and OpenAL) are also prime candidates
|
|
|
|
custom interface interface *defined and provided* by a module,
|
|
other than a standard interface
|
|
a module may decide to provide (expose) some
|
|
interfaces so that other modules can utilize
|
|
them; a module will register such interface
|
|
the same way it would register a standard
|
|
interface it implements
|
|
|
|
vtbl virtual table; a table of interface functions;
|
|
pointer to vtbl is semantically equivalent to
|
|
an interface pointer
|
|
|
|
event a bindable point in code of the engine or any
|
|
module; event observer recieves event
|
|
notifications via event handlers it installs
|
|
|
|
h_foo handle to 'foo'
|
|
|
|
plate cdp module
|
|
fork interface; something to poke a plate with
|
|
spoon event;
|
|
"hit the plate with a spoon" == "notify via
|
|
event handler"
|
|
|
|
|
|
Typical calling sequence:
|
|
-------------------------
|
|
1) something calls adlm_LoadModule(the_mod) ('the_mod' is used here
|
|
to identify the module and to *logically* group module properties
|
|
and operations performed on the module for the sake of this
|
|
document); the_mod gets dlopen()ed;
|
|
|
|
2) adlm_LoadModule() looks up the only exported symbol 'adlminfo'.
|
|
This symbol is the adlm_ModuleInfo struct;
|
|
|
|
3) adlm_LoadModule() verifies that the_mod is compatible with current
|
|
engine and API versions and calls
|
|
adlm_GetInterface(HOST,the_mod.api_ver) to lookup the host interface
|
|
with the correct API version for the module;
|
|
|
|
4) adlm_LoadModule() either increments module ref-count (if the module
|
|
has already been loaded previously) or calls
|
|
the_mod.module_init(host_itf)
|
|
|
|
5) the_mod.module_init() stores off the host_itf pointer and performs
|
|
internal initialization;
|
|
|
|
6) [Optional; but not useful w/o] the_mod.module_init() calls
|
|
host_itf->GetInterface(kind) to get access to whatever standard or
|
|
custom interfaces it requires (for example, it requests a sound
|
|
interface to register an audio decoder);
|
|
|
|
7) [Optional] the_mod.module_init() calls
|
|
host_itf->RegisterItf(kind,...,itf_vtbl,...) to register the custom
|
|
or standard (do not confuse with built-in) interfaces it wishes to
|
|
expose to the core engine or other modules;
|
|
|
|
8) [Continuous normal operation] module calls members of the interfaces
|
|
it acquired to perform various game-related tasks; core engine
|
|
and/or other modules call members of the interfaces that module
|
|
exposed (if it did so);
|
|
|
|
9) something calls adlm_FreeModule(h_the_mod) either when the game
|
|
quits or when the module is dynamically unloaded for whatever
|
|
reason: possibly when user decides to dump the game-mod and use
|
|
something else in its place or nothing at all, but for now there
|
|
is no mechanism to ensure safe mid-game unloading of modules --
|
|
interfaces are not ref-counted and anything can hold a pointer to
|
|
an interface at any given time (creating a safe system to do this
|
|
is probably not cost-effective);
|
|
|
|
10) adlm_FreeModule() decrements module ref-count and, when ref-count
|
|
reaches 0, calls the_mod.module_term();
|
|
|
|
11) the_mod.module_term() calls host_itf->UnregisterItf(h_itf) to
|
|
unregister the interfaces it had exposed previously; then it
|
|
unregisters any other objects it registered, releases all objects
|
|
it acquired through interfaces and destroys any objects it is
|
|
responsible for;
|
|
|
|
12) the_mod.module_term() performs internal cleanup;
|
|
|