Final Platform Layer 0.9.8-beta
Loading...
Searching...
No Matches
Initialization & Release

Include the Library

In one of your C/C++ translation units include this:

#define FPL_IMPLEMENTATION
Final Platform Layer (FPL) - A C99 Single-Header-File Platform Abstraction Library.

You can then include this file in any other C/C++ source or header file as you would with any other header file.

Entry Point

Simply provide the typical main entry point:

int main(int argc, char **argv) {
// code goes here
}

Initialization with default settings

Call fplPlatformInit() (inside the main Entry Point) and provide the desired fplInitFlags and fpl_null as arguments, to initialize FPL with default settings.

int main(int argc, char **argv) {
// With defaults (Window, Video, Audio)
// Only audio
// Only window and audio
return 0;
}
#define fpl_null
Null.
fpl_common_api bool fplPlatformInit(const fplInitFlags initFlags, const fplSettings *initSettings)
Initializes the platform layer.
@ fplInitFlags_Audio
Use asynchronous audio playback.
@ fplInitFlags_All
All init flags.
@ fplInitFlags_Window
Create a single window.

It is recommended to always pass a pointer to a fplSettings structure, but you can leave it as fpl_null as well.
Call fplSetDefaultSettings() with a pointer to your local settings container to initialize the settings container with default values.

Initialization with custom settings

Call fplPlatformInit() (inside the main Entry Point) and provide the desired fplInitFlags and a pointer to fplSettings argument to initialize FPL with custom settings.

// Overwrite settings
fplSettings settings;
// or
// change the settings here
fpl_common_api fplSettings fplMakeDefaultSettings()
Creates a full settings structure containing default values.
fpl_common_api void fplSetDefaultSettings(fplSettings *settings)
Resets the given settings container to default values for window, video, audio, etc.
A structure containing settings, such as window, video, etc.

Releasing the Platform

Call fplPlatformRelease() when you are done. This will release all internal resources.

fpl_common_api void fplPlatformRelease()
Releases the resources allocated by the platform layer.

Result/Error checking

There is no guarantee that fplPlatformInit() will always work with the fplSettings you specified, maybe the audio device does not support a sample rate of 1337 kHz or your video card does not support OpenGL version 3.7 - who knows.

Therefore, you should always check the result using fplGetPlatformResult() !
This returns a fplPlatformResultType enum which is fplPlatformResultType_Success when initialization succeeded.

Also, you should release the platform when the initialization was successful only!
If something goes wrong the remaining resources are already cleaned up by FPL automatically.

Also, you should use fplGetLastError() to print out the actual error when the initialization fails!

Very bad: (But will work)

Bad: (But will work)

Good:

Better:

// your code here
} else {
const char *errStr = fplGetLastError();
fplConsoleFormatError("FPL-ERROR: %s\n", errStr);
}
fpl_common_api void fplConsoleFormatError(const char *format,...)
Writes the given formatted text to the standard error console buffer.
fpl_common_api const char * fplGetLastError()
Gets the last internal error string.

Much better:

// your code here
} else {
const char *initResultStr = fplPlatformGetResultName(initResult);
const char *errStr = fplGetLastError();
fplConsoleFormatError("FPL-ERROR[%s]: %s\n", initResultStr, errStr);
}
fpl_common_api fplPlatformResultType fplGetPlatformResult()
Gets the result type of the platform initialization.
fplPlatformResultType
An enumeration of platform result types.
fpl_common_api const char * fplPlatformGetResultName(const fplPlatformResultType type)
Gets the string representation of a platform result type.

See the Error handling page for more details about error handling.

Tips

After releasing FPL you can call fplPlatformInit() again if needed - for example: Finding the proper audio device, Testing for OpenGL compatibility, etc. may require you to call fplPlatformInit() and fplPlatformRelease() multiple times.
For more details see Getting started

Optionally you can use fplMakeDefaultSettings to create a default filled fplSettings structure, which can be directly used for fplPlatformInit()

If needed you can get the currently used fplSettings configuration by calling fplGetCurrentSettings()