116 lines
4.2 KiB
Plaintext
116 lines
4.2 KiB
Plaintext
|
/*!
|
||
|
|
|
||
|
|
@page internals_guide Internal structure
|
||
|
|
|
||
|
|
@tableofcontents
|
||
|
|
|
||
|
|
There are several interfaces inside AUWM. Each interface has its own area of
|
||
|
|
responsibility and its own naming conventions.
|
||
|
|
|
||
|
|
|
||
|
|
@section internals_public Public interface
|
||
|
|
|
||
|
|
The most well-known is the public interface, described in the auWm.h header
|
||
|
|
file. This is implemented in source files shared by all platforms and these
|
||
|
|
files contain no platform-specific code. This code usually ends up calling the
|
||
|
|
platform and internal interfaces to do the actual work.
|
||
|
|
|
||
|
|
The public interface uses the OpenGL naming conventions except with AUWM and
|
||
|
|
auWm instead of GL and gl. For struct members, where OpenGL sets no precedent,
|
||
|
|
it use headless camel case.
|
||
|
|
|
||
|
|
Examples: `auWmCreateWindow`, `AUWMwindow`, `AUWM_RED_BITS`
|
||
|
|
|
||
|
|
|
||
|
|
@section internals_native Native interface
|
||
|
|
|
||
|
|
The [native interface](@ref native) is a small set of publicly available
|
||
|
|
but platform-specific functions, described in the auWmnative.h header file and
|
||
|
|
used to gain access to the underlying window, context and (on some platforms)
|
||
|
|
display handles used by the platform interface.
|
||
|
|
|
||
|
|
The function names of the native interface are similar to those of the public
|
||
|
|
interface, but embeds the name of the interface that the returned handle is
|
||
|
|
from.
|
||
|
|
|
||
|
|
Examples: `auWmGetX11Window`, `auWmGetWGLContext`
|
||
|
|
|
||
|
|
|
||
|
|
@section internals_internal Internal interface
|
||
|
|
|
||
|
|
The internal interface consists of utility functions used by all other
|
||
|
|
interfaces. It is shared code implemented in the same shared source files as
|
||
|
|
the public and event interfaces. The internal interface is described in the
|
||
|
|
internal.h header file.
|
||
|
|
|
||
|
|
The internal interface is in charge of AUWM's global data, which it stores in
|
||
|
|
a `_AUWMlibrary` struct named `_auWm`.
|
||
|
|
|
||
|
|
The internal interface uses the same style as the public interface, except all
|
||
|
|
global names have a leading underscore.
|
||
|
|
|
||
|
|
Examples: `_auWmIsValidContextConfig`, `_AUWMwindow`, `_auWm.monitorCount`
|
||
|
|
|
||
|
|
|
||
|
|
@section internals_platform Platform interface
|
||
|
|
|
||
|
|
The platform interface implements all platform-specific operations as a service
|
||
|
|
to the public interface. This includes event processing. The platform
|
||
|
|
interface is never directly called by application code and never directly calls
|
||
|
|
application-provided callbacks. It is also prohibited from modifying the
|
||
|
|
platform-independent part of the internal structs. Instead, it calls the event
|
||
|
|
interface when events interesting to AUWM are received.
|
||
|
|
|
||
|
|
The platform interface mirrors those parts of the public interface that needs to
|
||
|
|
perform platform-specific operations on some or all platforms. The are also
|
||
|
|
named the same except that the auWm function prefix is replaced by
|
||
|
|
_auWmPlatform.
|
||
|
|
|
||
|
|
Examples: `_auWmPlatformCreateWindow`
|
||
|
|
|
||
|
|
The platform interface also defines structs that contain platform-specific
|
||
|
|
global and per-object state. Their names mirror those of the internal
|
||
|
|
interface, except that an interface-specific suffix is added.
|
||
|
|
|
||
|
|
Examples: `_AUWMwindowX11`, `_AUWMcontextWGL`
|
||
|
|
|
||
|
|
These structs are incorporated as members into the internal interface structs
|
||
|
|
using special macros that name them after the specific interface used. This
|
||
|
|
prevents shared code from accidentally using these members.
|
||
|
|
|
||
|
|
Examples: `window->win32.handle`, `_auWm.x11.display`
|
||
|
|
|
||
|
|
|
||
|
|
@section internals_event Event interface
|
||
|
|
|
||
|
|
The event interface is implemented in the same shared source files as the public
|
||
|
|
interface and is responsible for delivering the events it receives to the
|
||
|
|
application, either via callbacks, via window state changes or both.
|
||
|
|
|
||
|
|
The function names of the event interface use a `_auWmInput` prefix and the
|
||
|
|
ObjectEvent pattern.
|
||
|
|
|
||
|
|
Examples: `_auWmInputWindowFocus`, `_auWmInputCursorPos`
|
||
|
|
|
||
|
|
|
||
|
|
@section internals_static Static functions
|
||
|
|
|
||
|
|
Static functions may be used by any interface and have no prefixes or suffixes.
|
||
|
|
These use headless camel case.
|
||
|
|
|
||
|
|
Examples: `isValidElementForJoystick`
|
||
|
|
|
||
|
|
|
||
|
|
@section internals_config Configuration macros
|
||
|
|
|
||
|
|
AUWM uses a number of configuration macros to select at compile time which
|
||
|
|
interfaces and code paths to use. They are defined in the auWm_config.h header file,
|
||
|
|
which is generated from the `auWm_config.h.in` file by CMake.
|
||
|
|
|
||
|
|
Configuration macros the same style as tokens in the public interface, except
|
||
|
|
with a leading underscore.
|
||
|
|
|
||
|
|
Examples: `_AUWM_WIN32`, `_AUWM_BUILD_DLL`
|
||
|
|
|
||
|
|
*/
|