Home

Configuration Options

Command line options and tools

Running core.exe from command line

core.exe can be invoked either via the GamesManager or directly via the command line. For ease of debugging command line parameters can also be placed in a params.txt file in the MGDF root directory (the contents of this file will have preference over anything specified on the command line)

-logLevel
[Optional] Allows you to specify the logging verbosity, possible values in descending order of verbosity log_low|log_medium|log_high|log_error
-userdiroverride
[Optional] If specified, the directory from which to load and save user specific data to (save games/preferences etc.) will be either the gamesdir override (if specified) or application directory. If this parameter is omitted, the data directory will be the users appData\Local\MGDF\uid folder
-gamediroverride
[Optional] Allows you to specify a directory from which to load games from (by default this is the core.exe's application /game subdirectory)
-usedefaultadapter
[Optional] Skips Direct3D adapter enumeration, which can cause issues when running via the Visual Studio graphics debugger
-metricsport
[Optional] If specified, exposes a Prometheus metrics server on the given port that can record performance metrics
-logendpoint
[Optional] If specified, streams logs to a Loki server
-statisticsenabled
[Optional] If specified, enables sending statistics to a remote endpoint (see here for more info on setting up a statistics endpoint)
-statisticsendpointoverride
[Optional] If specified, overrides the statisticsService property in game.json

Running GamesManager.exe from command line

GamesManager.exe run without any arguments will check for updates and launch the game in its /game folder. However it also has a couple of arguments which can be useful to run as part of a games installer such as NSIS

-register
[Optional] In order to make installing/uninstalling your game easier. When invoked will install any framework dependencies (for example the Visual C++ runtime), as well as any installed program registry entries, desktop shortcuts, start menu shortcuts and windows games explorer integration required.
-deregister
[Optional] Removes anything added via the register argument (with the exception of framework dependancies)
-userdiroverride
[Optional] If specified, the directory from which to load and save user specific data to (save games/preferences etc.) will be either the gamesdir override (if specified) or application directory. If this parameter is omitted, the data directory will be the users appData\Local\MGDF\uid folder
-gamediroverride
[Optional] Allows you to specify a directory from which to load games from (by default this is the core.exe's application /game subdirectory)
-noupdatecheck
[Optional] Disables any checking for updates before launching

PackageGen.exe

PackageGen.exe is a tool supplied in the SDK (Found in the Bin folder of the SDK) and allows you to create MGDF game packages or create a game update package based upon the difference between two existing game packages. Packages created by this tool can then be posted for download by the GamesManager as updates. Full game packages are simply a zip file containing the contents of the /game folder. Game update packages are similar, though they include an extra update.json file which specifies which old files should be removed before installing, and only includes files which have changed since the last full package was installed - as such they typically result in smaller download sizes.

Usage

PackageGen "framework /game folder" -o "game package file"

Creates a new installer package from a directory.

PackageGen -u "older game package file" "newer game package file" -o "game update package file"

Creates a new update installer package that contains the differences between the old version to the new one.

Example output
Creating installer package
Creating install package c:\users\glenn\desktop\game.zip ...........
Validating installer package c:\users\glenn\desktop\game.zip
Installer package created
    Version: 0.1
    MD5: bd226dd32804d683348e2708b7288087

Game.json configuration

The game.json file is where all configuration and default preferences for a game is stored. The full schema for a game.json file is as follows

{
    "gameUid":"a unique id",
    "gameName":"A human readable name",
    "version":"0.1",
    "interfaceVersion":"1",
    "developerName":"Human readable developer name",
    "homepage":"https://www.example.com",
    "supportType":"S3",
    "supportUrl":"https://www.example.com/api/crashes",
    "updateService":"https://www.example.com/api/updates",
    "statisticsService":"https://www.example.com/api/statistics",
    "statisticsPrivacyPolicy":"https://www.example.com/privacy",
    "preferences":{
        "key":"value",
    }
}

Game.json schema

gameUid
[Required] A unique identifier used to partition away game data from other MGDF games. It is important that this value is unique, so we recommend a GUID or similar string which is unlikely to collide with other MGDF games installed on a users system
gameName
[Required] A human readable name of the game. This will be used for any user visible display of the game in the GamesManager user interface
version
[Required] A version string in the format major.minor.revision.build.
interfaceVersion
[Required] The host interface version supported by the module. Currently, this should always be "1"
developerName
[Required] A human readable description of the games developer. This will be displayed when the GamesManager requires the users permission to do something, for example to collect game statistics.
homepage
[Optional] A url to the game's homepage, this will be added to the entry for the game in the Windows installed programs list if provided
supportType
[Optional] one of either "email", "github", or "s3", which determines how the framework should handle crash reporting.
supportUrl
[Optional] Depending on the support type, controls where error reports are submitted.
  • email: An email address shown to users when crashes and other errors occur so that they can submit error reports.
  • github: A github repo URL (e.g. https://github.com/user/repo) shown to users when crashes and other errors occur so that they can create a Github issue.
  • s3: A url which returns a presigned link to an S3 Bucket which MGDF can automatically upload crash reports to (see Crash reporting service configuration for more information)
updateService
[Optional] A url used to check for updates (see Update manifest configuration for more information)
statisticsService
[Optional] A url used to post game statistics information to (see Statistics service configuration for more information)
statisticsPrivacyPolicy
[Required if statisticsservice is set] A url containing the privacy policy information for a developer who wishes to collect game statistics. This url is shown to the user when the GamesManager asks thier permission to gather statistics. If it is not specified, then no statistics can be collected
preferences
[Optional] A dictionary of strings specifying any preferences used by the game. These can be accessed via the IMGDFGame Get/Set/HasPreference methods. A number of built in preferences are also used by the MGDF host and are always prefixed with host. The full list of built in preferences is shown below. These built in preferences can be overridden by specifying them in the game.json file.

Built in host preferences

host.musicVolume
A string value between 0 and 1 that sets the volume for all music played using IMGDFSoundStreams. Defaults to "1.0"
host.soundVolume
A string value between 0 and 1 that sets the volume for all sounds played using IMGDFSounds. defaults to "1.0"
host.simFps
The target framerate of the sim thread. If the sim thread is able to run faster than this, the host will add in sleeps between timesteps to ensure that the sim is limited to this framerate (note the render thread framerate is unaffected by this setting). Defaults to "60"
host.renderFps
The target framerate of the render thread. If vsync is disabled or the refresh rate of the monitor is faster, the host will add in sleeps between renders to ensure that the rendering is limited to this framerate (note the sim thread framerate is unaffected by this setting). Not set by default
host.screenX
The desired horizontal resolution to display the game at when running in fullscreen. If this resolution is not possible on the current display, then the native resolution will be used instead. Defaults to "1024"
host.screenY
The desired vertical resolution to display the game at when running in fullscreen. If this resolution is not possible on the current display, then the native resolution will be used instead. Defaults to "768"
host.fullScreen
Whether to start the game in fullscreen ("1") or in windowed mode ("0"). Defaults to "0"
host.fullScreenExclusive
Should fullscreen use exclusive mode ("1") or windowed mode ("0"). Defaults to "0"
host.multiSampleLevel
The desired multisample level to use for the backbuffer, if this is not supported on the current display device, then the next highest level that is supported will be used instead. Defaults to "1"
host.RTMultiSampleLevel
The desired multisample level to use for render target buffers. Modules don't have to use this setting, though it is recommended. Defaults to "1"
host.vsync
Whether or not to use vsync on the render thread ("1"), or whether to render frames fast as possible ("0"). Defaults to "1"
host.windowResize
Whether to allow resizing of the game window in windowed mode ("1") or to have a fixed size window ("0"). This setting is provided as resizing the window may cause a D3D device reset. Because of this, having a resizable window means your game will have to be able to handle this. If you don't want to worry about this, leave it at the default of "0"
host.windowSizeX
The desired horizontal size of the window when in windowed mode. Defaults to "1024"
host.windowSizeY
The desired vertical size of the window when in windowed mode. Defaults to "768"
host.windowPositionX
The desired horizontal position of the window when in windowed mode. Defaults to null (position determined by the OS)
host.windowPositionY
The desired vertical position of the window when in windowed mode. Defaults to null (position determined by the OS)

Game update manifest

The game update manifest file is a json file whose url is specified in the updateservice property of the game.json file. This file is used to determine if updates to a game are available. The framework will request the manifest using the updateservice url (and append the gameUid as a querystring parameter). the The full schema for an update manifest file is shown below.

NOTE The GamesManager supports downloading game updates from urls that use http authentication (either basic or digest) if you want to restrict download access to paid users. The GamesManager will pop up a username/password prompt in this case before the update will proceed.

{
  "framework": {
    "version": "0.11.22",
    "url": "https://s3.matchstickframework.org/MGDF_0.11.22_x64.zip",
    "md5": "be4573e2058fa6106093443e6c7857d1"
  },
  "latest": {
    "version": "0.2.4",
    "url": "https://www.example.com/game_0.2.4.zip",
    "md5": "8059891b6663315a72a954c282a963c8"
  },
  "updateOlderVersions": [
    {
      "url": "https://www.example.com/game_0.2.4_update.zip",
      "md5": "eac5db79ad1fa8f61d20283fef37ad33",
      "fromVersion": "0.2.2",
      "toVersion": "0.2.3"
    }
  ]
}

Game update manifest schema

framework
[Optional] Used to specify which version of the MGDF framework the game should use. This is useful as it gives you control over which framework version you want your game to run on and can update the framework as you require. The framework .zip file should be a framework distributable which can be found in the MGDF SDK download
latest
[Required] Specifies the latest version of your game which is available. This zip file must be a game package built by the MGDF SDK PackageGen tool
updateOlderVersions
[Optional] Specifies a list of partial upgrade packages which can upgrade a version fromVersion - toVersion up to the latest version. The partial update zip file should be an update package built by the MGDF SDK PackageGen tool

Statistics service

The MGDF statistics service works by having the GamesManager upload lists of statistics (created by calls to the IStatisticsManager inside a running game) to a restful json web service endpoint specified in a games game.json file. In order to use this feature you will need to implement a compatible web service that implements the methods shown below.

Request fields

gameUid
A string value.
sessionId
A string value. All statistic key/values should be associated with this session id.
statistics
An array of statistic objects containing the fields below.
  • timestamp An unsigned integer value marking the time the statistic was recorded. The time interval is measured in seconds since the beginning of the current session.
  • name A string value.
  • value A string value.

Sample HTTP request to https://example.com/statistics (Note the statisticsservice url in game.json would be https://example.com/statistics in this case)

POST https://example.com/statistics HTTP/1.1
Content-Type: application/json; charset=utf-8
Host: example.com
Content-Length: 146
{"gameUid":"blah","sessionId":"xxxx","statistics":[{"timestamp":0,"name":"key1","value":"value1"},{"timestamp":1,"name":"key2","value":"value2"}]}

Response fields

errors
An array of strings containing any errors caused in processing the request. If the request is successful, this array will be empty.
success
A boolean value that is true if the request was successfully processed, false otherwise.

Sample HTTP response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 29
{"errors":[], "success":true}

Crash reporting service

The MGDF S3 crash reporting service works in two steps, first by calling the supportUrl endpoing with crash metadata (see below). The service should then respond with a presigned S3 URL that the framework will then issue an HTTP Put for to upload a crash report zip file into. In order to use this feature you must have an AWS account with an S3 bucket set up & have supportType set to "S3" in your game.json file. You will also need to implement a compatible web service that implements the contract shown below.

Request fields

detail
A string value containing a brief description of the crash.
gameUid
A string value of the crashing game's uid.
gameVersion
A string value containing the version number of the game that crashed.
frameworkVersion
A string value containing the version number of the framework that the game was running on when it crashed.

Sample HTTP request to https://example.com/crashes (Note the supportUrl url in game.json would be https://example.com/crashes in this case)

POST https://example.com/crashes HTTP/1.1
Content-Type: application/json; charset=utf-8
Host: example.com
Content-Length: 146
{"detail": "Exception thrown", "gameUid":"blah", "gameVersion":"1.2.3.4", "frameworkVersion":"1.2.3.4"}

Response fields

errors
An array of strings containing any errors caused in processing the request. If the request is successful, this array will be empty.
success
A boolean value that is true if the request was successfully processed, false otherwise.
uploadUrl
A string value containing a presigned S3 URL that the framework will then issue an HTTP Put to upload a crash report zip file into.

Sample HTTP response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 29
{"errors":[], "success":true, "uploadUrl":"https://s3.amazonaws.com/yourbucket/crash.zip"}

Functions

There are a number of entrypoint functions which can be exported by a module which are used by the host to create the module instance and to query the requirements of the module.

GetCompatibleFeatureLevels Allows a module to tell the host what D3D11 feature level to try and use when creating the D3D device.

UINT64 GetCompatibleFeatureLevels ( D3D_FEATURE_LEVEL * levels , UINT64 * featureLevelSize )
Parameters
levels An array supplied to the module to fill with acceptable D3D feature levels
featureLevelSize The size of the levels array
Returns
Should return 0 if the supplied levels array is large enough, otherwise should return the size required

GetCustomArchiveHandlers Allows a module to tell the host if it is going to provide any custom virtual file system handlers.

HRESULT GetCustomArchiveHandlers ( IMGDFArchiveHandler ** list , UINT64 * length , IMGDFLogger * logger )
Parameters
list Pointer to a buffer to store the list of provided archive handlers
length The length of the provided buffer
logger An interface allowing the archive handler to write to the MGDF logs
Returns
Should return S_OK if the supplied list is large enough to contain all the items in the list, otherwise return E_FAIL and sets the required size in the length parameter

GetModule Factory function which returns an instance of the module to the host.

HRESULT GetModule ( IMGDFModule ** module )
Parameters
module An instance of the module interface
Returns
Should return S_OK if the module could be created, otherwise E_FAIL

Interfaces

Once the module has been created, it can access the MGDF host's functionality using the following interfaces. Most of these interfaces are not directly accessible to a module, but are instead properties of the ISimHost and IRenderHost interfaces.

IMGDFArchiveHandler Provides an interface for creating portions of the vfs tree from archive files

Inherits from: IUnknown

  • TestPathSegment Test if the logical path segment looks like it could be an archive file

    BOOL TestPathSegment ( const MGDFArchivePathSegment * segment )
    Parameters
    segment Part of the logical path to test
    Returns
    TRUE if the segment looks like it could be an archive file

  • MapArchive If the logicalPath points to a file that is an archive, this function will map the archive and return the file inside the archive at the logical path

    BOOL MapArchive ( const wchar_t * rootPath , const wchar_t * archivePath , const MGDFArchivePathSegment * logicalPathSegments , UINT64 logicalPathSegmentCount , IMGDFArchiveHandler ** handlers , UINT64 handlerCount , IMGDFReadOnlyFile * parent , IMGDFReadOnlyFile ** file )
    Parameters
    rootPath The physical path on disk to the vfs root
    archivePath The physical path on disk to the archive file
    logicalPathSegments The logical path to the file within the archive
    logicalPathSegmentCount The number of segments in the logical path
    handlers An array of all registered archive handlers
    handlerCount The number of registered archive handlers
    parent The parent file in the vfs tree
    file Pointer to the file in the mapped vfs subtree
    Returns
    TRUE if the fullPath could be mapped to an archive, otherwise FALSE

IMGDFCommonHost Provides an entrypoint for a module to interact with the MGDF host. Methods in this interface are safe to be used from any thread

Inherits from: IMGDFLogger

  • FatalError This method should be invoked when a fatal error is encountered

    void FatalError ( const small * sender , const small * message )
    Parameters
    sender The location or component the error occurred in
    message Details of the fatal error

  • GetRenderSettings Get the render settings manager

    void GetRenderSettings ( IMGDFRenderSettingsManager * * settings )
    Parameters
    settings The render settings manager

  • GetTimer Get the host timer

    void GetTimer ( IMGDFTimer * * timer )
    Parameters
    timer Pointer to the host timer

  • GetMGDFVersion Gets the current version of the framework

    const MGDFVersion * GetMGDFVersion ( )
    Returns
    The current version of the framework

  • GetVFS Get the readonly content filesystem

    void GetVFS ( IMGDFReadOnlyVirtualFileSystem * * vfs )
    Parameters
    vfs The readonly filesystem

  • GetWorkingVFS Get the read/write working folder

    void GetWorkingVFS ( IMGDFWriteableVirtualFileSystem * * vfs )
    Parameters
    vfs The writeable filesystem

  • GetD3DDevice Get the direct3d device object from the host

    void GetD3DDevice ( ID3D11Device * * device )
    Parameters
    device The direct3d device object from the host

  • GetD2DDevice Get the direct2d device object from the host

    void GetD2DDevice ( ID2D1Device * * device )
    Parameters
    device The direct2d device object from the host

  • GetDebug Get the onscreen debug overlay interface

    void GetDebug ( IMGDFDebug * * debug )
    Parameters
    debug Pointer to a debug overlay object

  • CreateCPUCounter Create a performance counter for profiling CPU time taken. When no longer used it should be released

    HRESULT CreateCPUCounter ( IMGDFMetric * metric , IMGDFPerformanceCounter * * counter )
    Parameters
    metric The metric the counter should update
    counter Points to the created counter
    Returns
    S_OK if the counter could be created, otherwise an error code is returned

  • CreateCounterMetric Create or get an existing metric for a monotonically increasing counter

    HRESULT CreateCounterMetric ( const small * name , const small * description , IMGDFMetric ** metric )
    Parameters
    name The name of the metric
    description A description of what the metric is measuring
    metric Points to the created metric
    Returns
    S_OK if the metric could be created, otherwise an error code is returned

  • CreateGaugeMetric Create or get an existing metric that can go up and down over time

    HRESULT CreateGaugeMetric ( const small * name , const small * description , IMGDFMetric ** metric )
    Parameters
    name The name of the metric
    description A description of what the metric is measuring
    metric Points to the created metric
    Returns
    S_OK if the metric could be created, otherwise an error code is returned

  • CreateHistogramMetric Create or get an existing metric that can go up and down over time

    HRESULT CreateHistogramMetric ( const small * name , const small * description , const double * buckets , const UINT64 bucketCount , IMGDFMetric ** metric )
    Parameters
    name The name of the metric
    description A description of what the metric is measuring
    buckets Pointer to an array of buckets used in the histogram
    bucketCount The length of the buckets array parameter
    metric Points to the created metric
    Returns
    S_OK if the metric could be created, otherwise an error code is returned

  • QueueDeviceReset After a module receives an RTOnBeforeDeviceReset callback, calling this tells the host that all references to the previous D3D device have been cleaned up and that the device can be safely reset

    void QueueDeviceReset ( )

IMGDFDebug Controls the data displayed in the MGDF debug overlay sheet (press ALT-F12 to see in game)

Inherits from: IUnknown

  • Set Set some data to display in the overlay

    void Set ( const small * section , const small * key , const small * value )
    Parameters
    section The section to display the key:value in
    key The key to display
    value The value to display

  • Clear Clear some data out of the overlay

    void Clear ( const small * section , const small * key )
    Parameters
    section To clear the key from
    key The key to clear (if null, clears all keys in the section)

  • IsShown Whether the debug overlay is currently visible

    BOOL IsShown ( )
    Returns
    Whether the debug overlay is currently visible

  • ToggleShown Toggle the visibility status of the overlay

    void ToggleShown ( )

IMGDFFile Provides a base interface for filesystem access that is common across the readonly virtual filesystem and writeable save and working directories.

Inherits from: IUnknown

  • GetChildCount Get how many children this file has

    UINT64 GetChildCount ( )
    Returns
    How many children this file has

  • IsFolder Determines if the file entity is a folder

    BOOL IsFolder ( )
    Returns
    True if the file is a folder

  • IsOpen Determines if the file has an open reader

    BOOL IsOpen ( )
    Returns
    True if the file has an open reader

  • Open Attempt to open the file for reading. Only one fileReader can be open for a file at any time. Because of this, you should ensure that any reader is closed after it is no longer needed.

    HRESULT Open ( IMGDFFileReader * * reader )
    Parameters
    reader Pointer to any reader that is created
    Returns
    S_OK if the reader was created, E_FAIL if the file could not be opened or E_ACCESSDENIED if it was already open

  • GetLastWriteTime Find the last write time of the file

    UINT64 GetLastWriteTime ( )
    Returns
    A timestamp indicating the last write time

  • GetPhysicalName Gets the physical name of this file on disk

    HRESULT GetPhysicalName ( wchar_t * name , UINT64 * length )
    Parameters
    name Buffer to store the file name
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length or was NULL, otherwise E_NOT_SUFFICIENT_BUFFER

  • GetPhysicalPath Gets the physical path to this file

    HRESULT GetPhysicalPath ( wchar_t * name , UINT64 * length )
    Parameters
    name Buffer to store the file path
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length or was NULL, otherwise E_NOT_SUFFICIENT_BUFFER

  • GetLogicalName Gets the logical name of this file

    HRESULT GetLogicalName ( wchar_t * name , UINT64 * length )
    Parameters
    name Buffer to store the file name
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length or was NULL, otherwise E_NOT_SUFFICIENT_BUFFER

  • GetLogicalPath Gets the logical path to this file

    HRESULT GetLogicalPath ( wchar_t * name , UINT64 * length )
    Parameters
    name Buffer to store the file name
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length or was NULL, otherwise E_NOT_SUFFICIENT_BUFFER

IMGDFFileReader Provides an interface for reading data from a file

Inherits from: IUnknown

  • Read Reads the specified number of bytes into the buffer

    UINT32 Read ( void * buffer , UINT32 length )
    Parameters
    buffer A buffer to store the read data
    length The max amount of data that can be read into the buffer
    Returns
    The amount of bytes actually read into the buffer

  • SetPosition Sets the read position of the file in bytes

    void SetPosition ( INT64 pos )
    Parameters
    pos The read position of the file in bytes

  • GetPosition Get the current read position of the file in bytes

    INT64 GetPosition ( )
    Returns
    The read position in the file

  • EndOfFile Determines whether the file read position has reached the end of the file

    BOOL EndOfFile ( )
    Returns
    True if the read position is past the end of the file

  • GetSize Get the size of the file in bytes

    INT64 GetSize ( )
    Returns
    The filesize in bytes (for compressed archives this value is the uncompressed size)

IMGDFFileWriter Provides an interface for writing data to a file

Inherits from: IUnknown

  • Write Writes the specified number of bytes into the buffer

    UINT32 Write ( void * buffer , UINT32 length )
    Parameters
    buffer A buffer to store the write data
    length The max amount of data to write to the file
    Returns
    The amount of bytes actually written to the file

  • SetPosition Sets the write position of the file in bytes

    void SetPosition ( INT64 pos )
    Parameters
    pos The write position of the file in bytes

  • GetPosition Get the current write position of the file in bytes

    INT64 GetPosition ( )
    Returns
    The write position in the file

IMGDFGame Provides information regarding the current game being run and the preferences associated with that game

Inherits from: IUnknown

  • GetName Get the name of the current game running

    const small * GetName ( )
    Returns
    The name of the current game running

  • GetUid Get the uid of the current game running

    const small * GetUid ( )
    Returns
    The name of the current game running

  • GetVersion Get the version of the current game running

    void GetVersion ( MGDFVersion * version )
    Parameters
    version The version of the current game running

  • HasPreference Determine if the game has a preference for the given key

    BOOL HasPreference ( const small * name )
    Parameters
    name The preference name
    Returns
    True if the key has an associated value

  • GetPreference Determine if the game has a preference for the given key and return its value. Preferences can be defined in a games game.json file, or new ones can be added/overwritten by calling SetPreference

    HRESULT GetPreference ( const small * name , small * value , UINT64 * length )
    Parameters
    name The preference name
    value Buffer to store the value associated with the key or nullptr if there is no such key
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the value was found and the buffer was the correct length or was NULL, otherwise E_NOT_SUFFICIENT_BUFFER

  • SetPreference Change the value of a preference

    void SetPreference ( const small * name , const small * value )
    Parameters
    name The preference name
    value The new preference value

  • SetPreferences Sets a number of preferences in one go. Used for applying system render & sound settings

    void SetPreferences ( IMGDFPreferenceSet * preferences )
    Parameters
    preferences A set of preferences

  • SavePreferences Save the current preferences list

    void SavePreferences ( )

  • ResetPreferences Reload all preferences to their user independent default values

    void ResetPreferences ( )

IMGDFGamepad Provides the ability to query the state of and control other properties of an XInput compatible gamepad connected to the PC

Inherits from: IUnknown

  • IsConnected Determines if a controller is connected

    BOOL IsConnected ( )
    Returns
    True if if a controller is connected

  • IsButtonDown Determines if a button is pressed

    BOOL IsButtonDown ( MGDFGamepadButton button )
    Parameters
    button The gamepad button code representing the desired button
    Returns
    True if the button is being held down

  • IsButtonUp Determines if a button is NOT pressed

    BOOL IsButtonUp ( MGDFGamepadButton button )
    Parameters
    button The gamepad button code representing the desired button
    Returns
    True if the button is not being pressed

  • IsButtonPress Determines if a button press has occured

    BOOL IsButtonPress ( MGDFGamepadButton button )
    Parameters
    button The gamepad button code representing the desired button
    Returns
    True if the button has been pressed (i.e pressed down then released)

  • GetLeftTrigger Returns the state of the controllers left trigger

    UINT8 GetLeftTrigger ( )
    Returns
    0 for idle to 255 for fully held

  • GetRightTrigger Returns the state of the controllers right trigger

    UINT8 GetRightTrigger ( )
    Returns
    0 for idle to 255 for fully held

  • GetLeftThumbX Returns the state of the left thumbstick on the X axis

    INT32 GetLeftThumbX ( )
    Returns
    -32768 for far left to +32767 for far right

  • GetLeftThumbY Returns the state of the left thumbstick on the Y axis

    INT32 GetLeftThumbY ( )
    Returns
    -32768 for top to +32767 for bottom

  • GetRightThumbX Returns the state of the right thumbstick on the X axis

    INT32 GetRightThumbX ( )
    Returns
    -32768 for far left to +32767 for far right

  • GetRightThumbY Returns the state of the right thumbstick on the Y axis

    INT32 GetRightThumbY ( )
    Returns
    -32768 for top to +32767 for bottom

  • SetVibrationSpeed Sets the vibration intensity in the left and right vibrator motors of the controller, valid values are 0-65535

    void SetVibrationSpeed ( UINT16 left , UINT16 right )
    Parameters
    left The intensity of the left vibrator motor
    right The intensity of the right vibrator motor

IMGDFGameState A saved game state and its associated metadata

Inherits from: IUnknown

  • GetMetadata Gets the value of a metadata key

    HRESULT GetMetadata ( const small * key , small * value , UINT64 * length )
    Parameters
    key The name of the metadata key
    value Buffer to store the value associated with the key or nullptr if there is no such key
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the value was found and the buffer was the correct length or was NULL, otherwise E_NOT_SUFFICIENT_BUFFER

  • SetMetadata Sets the value of a metadata key

    HRESULT SetMetadata ( const small * key , const small * value )
    Parameters
    key The name of the metadata key
    value The value associated with the key
    Returns
    S_OK if the value could be stored

  • IsNew Is this a new game state with no persisted data that has been created from a recent call to CreateGameState

    BOOL IsNew ( )
    Returns
    True if the game state is new with no persisted data

  • GetVersion Get the version of the Module that saved this game state

    void GetVersion ( MGDFVersion * version )
    Parameters
    version The version of the Module that saved this game state

  • GetVFS Get the readonly virtual filesystem for the game states previously persisted data.

    HRESULT GetVFS ( IMGDFReadOnlyVirtualFileSystem * * vfs )
    Parameters
    vfs The virtual filesystem for accessing the game states data
    Returns
    S_OK if the virtual filesystem could be mounted, will fail if the game state is new

  • BeginSave Begins the process of saving the gamestate data. Once finished saving all data to the VFS instance returned. Modules should release the VFS to commit the save

    HRESULT BeginSave ( IMGDFWriteableVirtualFileSystem * * pending )
    Parameters
    pending A VFS mounted in a temporary save directory, once released any data in this directory will be copied into the permanent game state data directory
    Returns
    S_OK if the VFS could be mounted

IMGDFHttpClientRequest An interface for sending an HTTP request

Inherits from: IUnknown

  • SetRequestHeader Set the value of an HTTP header on the request

    IMGDFHttpClientRequest * SetRequestHeader ( const small * name , const small * value )
    Parameters
    name The name of the header
    value The value of the header
    Returns
    This request object for chaining

  • SetRequestMethod Set the HTTP method to use for the request

    IMGDFHttpClientRequest * SetRequestMethod ( const small * method )
    Parameters
    method The HTTP method to use for the request, one of the standard HTTP verbs (GET, POST, PUT, DELETE, etc)
    Returns
    This request object for chaining

  • SetRequestBody Set the body of the request. This method copies the body data into the request

    IMGDFHttpClientRequest * SetRequestBody ( const small * body , UINT64 bodyLength )
    Parameters
    body The body of the request
    bodyLength The length of the body
    Returns
    This request object for chaining

  • CancelRequest Cancels a pending request. Causes any calls to GetResponse to return true with a response with a code of -1, and a 'Cancelled' error message

    void CancelRequest ( )

  • SendRequest Initiates the request. The request is not actually sent until this method is called

    void * SendRequest ( IMGDFHttpClientRequestGroup * group )
    Parameters
    group An optional group to send the request in
    Returns
    A unique pointer to the request in the group if the request was sent in a group, otherwise nullptr. This can be used to identify the request in the group when calling GetResponse later

  • GetResponse Check if the request has received a response and if so get the response

    BOOL GetResponse ( IMGDFHttpClientResponse * * response )
    Parameters
    response The response to the request
    Returns
    True if the request has received a response, been cancelled, or failed with an error. If the request is still pending, false is returned

IMGDFHttpClientRequestGroup An interface for grouping HTTP requests together. This allows multiple requests to be checked for completion at once.

Inherits from: IUnknown

  • GetResponse Call this repeatedly to check if any requests in a group have completed

    void * GetResponse ( IMGDFHttpClientResponse * * response )
    Parameters
    response The response to the request
    Returns
    The handle of any completed http request, nullptr otherwise

IMGDFHttpClientResponse An interface for an HTTP Response. The memory returned by all methods are owned by the response and are only valid for the lifetime of the response. If you want to persist these values you should create copies of them.

Inherits from: IUnknown

  • GetResponseCode Get the value of the HTTP response code

    INT32 GetResponseCode ( )
    Returns
    0 indicates an error making the request -1 indicates the request was cancelled any other value represents the HTTP status code returned from the server

  • GetResponseHeader Get the value of a header in the response

    HRESULT GetResponseHeader ( const small * name , small * value , UINT64 * length )
    Parameters
    name The name of the header
    value A buffer to store the header value in
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length or was NULL, E_NOT_SET if no header exists, otherwise E_NOT_SUFFICIENT_BUFFER if the buffer size was insufficient

  • GetResponseError If the request failed, get the error message

    HRESULT GetResponseError ( small * error , UINT64 * length )
    Parameters
    error A buffer to store the error message in
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length or was NULL, otherwise E_NOT_SUFFICIENT_BUFFER if the buffer size was insufficient

  • GetResponseBody Get he body of the response. NOTE: this is not necessarily a valid C string and may not be null terminated.

    HRESULT GetResponseBody ( small * body , UINT64 * length )
    Parameters
    body A buffer to store the response body in
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length or was NULL, otherwise E_NOT_SUFFICIENT_BUFFER if the buffer size was insufficient

IMGDFHttpServerRequest An interface for querying the contents of an incoming http request to a server and responding to that request. The memory returned by all methods are owned by the request and are only valid for the lifetime of the request. If you want to persist these values you should create copies of them.

Inherits from: IUnknown

  • GetRequestHeader Get the value of a header in the request

    HRESULT GetRequestHeader ( const small * name , small * value , UINT64 * length )
    Parameters
    name The name of the header
    value A buffer to store the header value in
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length or was NULL, E_NOT_SET if no header exists, otherwise E_NOT_SUFFICIENT_BUFFER if the buffer size was insufficient

  • GetRequestMethod Gets the HTTP method used in the request

    HRESULT GetRequestMethod ( small * method , UINT64 * length )
    Parameters
    method A buffer to store the method in
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length or was NULL, otherwise E_NOT_SUFFICIENT_BUFFER if the buffer size was insufficient

  • GetRequestPath Gets the path of the request

    HRESULT GetRequestPath ( small * path , UINT64 * length )
    Parameters
    path A buffer to store the path in
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length or was NULL, otherwise E_NOT_SUFFICIENT_BUFFER if the buffer size was insufficient

  • GetRequestBody Gets the body of the request. NOTE: this is not necessarily a valid C string and may not be null terminated

    HRESULT GetRequestBody ( small * body , UINT64 * length )
    Parameters
    body A buffer to store the request body in
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length or was NULL, otherwise E_NOT_SUFFICIENT_BUFFER if the buffer size was insufficient

  • SetResponseHeader Sets a header in the response

    IMGDFHttpServerRequest * SetResponseHeader ( const small * name , const small * value )
    Parameters
    name The name of the header to set
    value The value to set for the header
    Returns
    This request object for chaining

  • SetResponseBody Sets the body of the response

    IMGDFHttpServerRequest * SetResponseBody ( const small * body , UINT64 bodyLength )
    Parameters
    body The body content to set
    bodyLength The length of the body content
    Returns
    This request object for chaining

  • SetResponseCode Sets the HTTP status code for the response

    IMGDFHttpServerRequest * SetResponseCode ( INT32 code )
    Parameters
    code The HTTP status code to set
    Returns
    This request object for chaining

  • SendResponse Sends the response back to the client

    void SendResponse ( )

IMGDFInputManager Provides a means for modules to access information regarding user input from the mouse, keyboard, and xinput controllers

Inherits from: IUnknown

  • ShowCursor Determines whether the OS cursor is displayed or not

    void ShowCursor ( BOOL show )
    Parameters
    show Whether to show the cursor or not

  • IsKeyDown Determines if a key is presed

    BOOL IsKeyDown ( UINT16 key )
    Parameters
    key The Microsoft Virtual key code representing the desired key (see here for a list http://msdn.microsoft.com/en-us/library/windows/desktop/dd375731%28v=vs.85%29.aspx)
    Returns
    True if the key is being held down

  • IsKeyUp Determines if a key is NOT pressed

    BOOL IsKeyUp ( UINT16 key )
    Parameters
    key The Microsoft Virtual key code representing the desired key (see here for a list http://msdn.microsoft.com/en-us/library/windows/desktop/dd375731%28v=vs.85%29.aspx)
    Returns
    True if the key is not being pressed

  • IsKeyPress Determines if a keypress has occured

    BOOL IsKeyPress ( UINT16 key )
    Parameters
    key The Microsoft Virtual key code representing the desired key (see here for a list http://msdn.microsoft.com/en-us/library/windows/desktop/dd375731%28v=vs.85%29.aspx)
    Returns
    True if the key has been pressed (i.e pressed down then released)

  • GetMouseX Get the x position of the mouse

    INT32 GetMouseX ( )
    Returns
    The x position of the mouse relative to the left of the screen in pixels

  • GetMouseY Get the y position of the mouse

    INT32 GetMouseY ( )
    Returns
    The y position of the mouse relative to the top of the screen in pixels

  • GetMouseDX Get the x movement of the mouse in the current frame

    INT32 GetMouseDX ( )
    Returns
    The x movement of the mouse in the current frame

  • GetMouseDY Get the y movement of the mouse in the current frame

    INT32 GetMouseDY ( )
    Returns
    The y movement of the mouse in the current frame

  • GetMouseDZ Get the position of the scroll wheel

    short GetMouseDZ ( )
    Returns
    The change in position of the scroll wheel, this value will increment/decrement in divisions of 120 depending on direction

  • IsButtonDown Determine if a mouse button is down

    BOOL IsButtonDown ( MGDFMouse mouseButton )
    Parameters
    mouseButton The mousebutton code representing the desired button
    Returns
    True if the button is held down

  • IsButtonUp Determine if a mouse button is up

    BOOL IsButtonUp ( MGDFMouse mouseButton )
    Parameters
    mouseButton The mousebutton code representing the desired button
    Returns
    True if the button is NOT held down

  • IsButtonClicked Determine if a mouse button was clicked

    BOOL IsButtonClicked ( MGDFMouse mouseButton )
    Parameters
    mouseButton The mousebutton code representing the desired button
    Returns
    True if the button has been clicked, i.e held down then released

  • GetGamepadCount Get the maximum number of gamepads available (not all of them may be connected)

    UINT64 GetGamepadCount ( )
    Returns
    The maximum number of gamepads available (not all of them may be connected)

  • GetGamepads Gets a list of all compatible gamepads connected to the PC

    void GetGamepads ( IMGDFGamepad * * gamepads )
    Parameters
    gamepads Pointer to an array of gamepads (must be large enough to fit GetGamepadCount entries)

IMGDFLogger The MGDF logging system

Inherits from: IUnknown

  • SetLoggingLevel Set the current logging verbosity level

    void SetLoggingLevel ( MGDFLogLevel level )
    Parameters
    level The verbosity level

  • GetLoggingLevel Get the current logging verbosity level

    MGDFLogLevel GetLoggingLevel ( )
    Returns
    The current logging verbosity level

  • Log Write an entry to the log

    void Log ( const small * sender , const small * message , MGDFLogLevel level )
    Parameters
    sender The location or component writing the log message
    message The content of the log message
    level The verbosity filter for writing out the message. The message will be written if this is less than or equal to the current logging level

IMGDFMetric Allows recording of a metric value over time. These can then be exposed via the Prometheus metrics server endpoint when enabled

Inherits from: IUnknown

  • Record Records the latest value of the metric

    void Record ( double value , const MGDFTags * tags )
    Parameters
    value The latest value of the metric
    tags Any tags to identify with this recording of the metric, pass NULL if no tags are to be included

IMGDFModule The interface to be implemented by an MGDF game

Inherits from: IUnknown

  • STNew Called by the host after a module is first created and should be used to do perform any initialization required by the module

    BOOL STNew ( IMGDFSimHost * host )
    Parameters
    host The simulation thread host
    Returns
    False if the module experiences a fatal error on initialization

  • STUpdate Called once per simulation timestep by the host once the game is running and represents the main sim loop

    BOOL STUpdate ( IMGDFSimHost * host , double elapsedTime )
    Parameters
    host The simulation thread host
    elapsedTime The simulation timestep
    Returns
    False if the module experiences a fatal error updating the scene

  • STShutDown Called by the host to tell the module to cleanup and shutdown as soon as possible. This is invoked when external events such as clicking the windows close button try to close the application. After being invoked it is the modules responsibility to call the ->Shutdown() function as soon as possible in order to actually terminate the application. This function may be called multiple times.

    void STShutDown ( IMGDFSimHost * host )
    Parameters
    host The simulation thread host

  • RTBeforeFirstDraw Called by the host immediately before the first call to RTDrawScene

    BOOL RTBeforeFirstDraw ( IMGDFRenderHost * host )
    Parameters
    host The render thread host
    Returns
    False if the module experiences a fatal error

  • RTDraw Called by the host once per render frame. The module should do any rendering required for the current frame in here

    BOOL RTDraw ( IMGDFRenderHost * host , double alpha )
    Parameters
    host The render thread host
    alpha How far between the current and next simulation frame (0-1)
    Returns
    False if the module experiences a fatal error drawing the scene

  • RTBeforeBackBufferChange Called by the host if the swap chain options need to be changed, or the display window needs to be resized. The module should clear out all references to the previous back buffer so a new resized backbuffer can be set

    BOOL RTBeforeBackBufferChange ( IMGDFRenderHost * host )
    Parameters
    host The render thread host
    Returns
    False if the module experiences a fatal error

  • RTBackBufferChange Called by the host after the swap chain options has been changed, or the display window has been resized. The module should re-acquire references to the new backbuffer or resize any backbuffer size dependent resources u

    BOOL RTBackBufferChange ( IMGDFRenderHost * host )
    Parameters
    host The render thread host
    Returns
    False if the module experiences a fatal error

  • RTBeforeDeviceReset Called by the host if the dxgi device needs to be removed. The module should clean out all device dependent resources and references to the old d3d device, which will now be invalid.

    BOOL RTBeforeDeviceReset ( IMGDFRenderHost * host )
    Parameters
    host The render thread host
    Returns
    False if the module experiences a fatal error

  • RTDeviceReset Called by the host after the dxgi device has been reset, the module should recreate any device dependent resources that were removed in RTBeforeDeviceReset

    BOOL RTDeviceReset ( IMGDFRenderHost * host )
    Parameters
    host The render thread host
    Returns
    False if the module experiences a fatal error

  • RTShutDown Called by the host just before Direct3D gets cleaned up

    void RTShutDown ( IMGDFRenderHost * host )
    Parameters
    host The render thread host

  • Panic Called by the host when a fatalError event occurs. This method gives the module a chance to clean up any memory/open files etc. as best it can before the host aborts. Methods on the render and sim hosts should not be accessed from within this method

    void Panic ( )

IMGDFPendingRenderSettingsChange Provides an interface for changing various rendering settings. Once released the settings will be applied to the render system on the next frame

Inherits from: IUnknown

  • SetMaxFrameLatency Sets the number of frames that the swap chain is allowed to queue for rendering.

    void SetMaxFrameLatency ( UINT32 frames )
    Parameters
    frames The maximum number of frames that can be queued (1+)

  • SetVSync Sets the current vsync setting

    void SetVSync ( BOOL vsync )
    Parameters
    vsync True if vsync is to be enabled

  • SetFullscreen Sets the current fullscreen setting

    void SetFullscreen ( const MGDFFullScreenDesc * fullscreen )
    Parameters
    fullscreen A description of the desired fullscreen settings

  • SetBackBufferMultiSampleLevel Set the display devices current multisample level

    BOOL SetBackBufferMultiSampleLevel ( UINT32 multisampleLevel )
    Parameters
    multisampleLevel The desired multisample level for the backbuffer
    Returns
    Returns false if the desired multisample level cannot be set.

  • SetCurrentMultiSampleLevel Set the desired multisample level for off screen render targets. This setting is not used directly by the framework but any client code should query this property when creating render targets that may require multisampling (see also

    BOOL SetCurrentMultiSampleLevel ( UINT32 multisampleLevel )
    Parameters
    multisampleLevel The desired multisample level for off screen render targets
    Returns
    Returns false if the desired multisample level cannot be set.

  • SetCurrentPrimaryDisplayMode Sets the display mode of the primary display output when running in exclusive fullscreen mode

    BOOL SetCurrentPrimaryDisplayMode ( const MGDFDisplayMode * mode )
    Parameters
    mode The display mode to use
    Returns
    True if the display mode is supported and can be applied, false otherwise

  • SetWindowSize Sets the size of the window when running in windowed mode. While running in fullscreen, this function has no effect.

    void SetWindowSize ( UINT32 width , UINT32 height )
    Parameters
    width The width of the window
    height The height of the window

  • SetHDREnabled Sets whether HDR should be enabled when its supported by the current display output

    void SetHDREnabled ( BOOL enabled )
    Parameters
    enabled Whether HDR should be enabled

  • Cancel Cancels any pending changes

    void Cancel ( )

IMGDFPerformanceCounter A names performance counter that can be used to time the duration of events. The results of these counters are shown in the MGDF debug overlay (press ALT-F12 to see in game)

Inherits from: IUnknown

  • GetMetric Gets the metric the counter updates

    void GetMetric ( IMGDFMetric * * metric )
    Parameters
    metric The metric the counter updates

  • Begin Begin timing by creating a performance counter scope. The timing is recorded at the point the scope is released

    HRESULT Begin ( const MGDFTags * tags , IMGDFPerformanceCounterScope ** scope )
    Parameters
    tags Any tags to identify with this counter, pass NULL if no tags are to be included
    scope Points to the performance counter scope created
    Returns
    S_OK if the the performance counter scope was created, otherwise will return an error code

  • GetAverageValue Get the average value recorded by this timer

    double GetAverageValue ( )
    Returns
    The average value recorded by the timer

IMGDFPerformanceCounterScope Tracks an interval of time being recorded by a performance counter. When released the timing recorded will be the duration of time between the scopes creation and release

Inherits from: IUnknown

IMGDFPreferenceSet A set of preferences that can be persisted

Inherits from: IUnknown

IMGDFReadOnlyFile Provides an interface for navigating a readonly file/directory structure in the virtual filesystem. Directories have no data but can have subfiles Files have no subfiles (except for archives) but may have data. Archives that have been added to the vfs are mapped as files with the same name as the archive filename, but unlike normal files they also have a tree of subdirectories containing the uncompressed archive data

Inherits from: IMGDFFile

  • GetParent Gets the parent of this file. If this file is the root of the virtual filesystem, then this will be nullptr

    BOOL GetParent ( IMGDFReadOnlyFile * * parent )
    Parameters
    parent Pointer to the parent of this file.
    Returns
    If this file is the root of the filesystem, then return false

  • GetChild Gets a child of this file with the given name (if any)

    BOOL GetChild ( const wchar_t * name , IMGDFReadOnlyFile ** child )
    Parameters
    name The child name of this file
    child The child file of the current file. If no such file exists, nullptr is returned
    Returns
    True if the child could be found

  • GetAllChildren Get all the children of this file (non-recursive)

    HRESULT GetAllChildren ( IMGDFReadOnlyFile * * buffer , UINT64 * length )
    Parameters
    buffer An array to store the results
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if all the children could be stored in the provided buffer or the buffer was NULL, E_NOT_SUFFICIENT_BUFFER otherwise

  • IsArchive Determines if the file is a (or is a member of) an archive file

    BOOL IsArchive ( )
    Returns
    True if the file is a (or is a member of) an archive file

  • CopyTo Copies this file or folder to the desired writeable target location

    HRESULT CopyTo ( IMGDFWriteableFile * destination )
    Parameters
    destination The target location for this file/folder. If the destination exists it should be deleted first or else this call will fail.
    Returns
    S_OK if the file/folder could be copied, otherwise E_FAIL

IMGDFReadOnlyVirtualFileSystem Provides an interface for accessing the readonly filesystem, which is a fast read only interface to access game content files. The root MGDF filesystem is mounted from the game/content folder.

Inherits from: IUnknown

  • GetFile Get the file/folder/archive in the specified logical directory. paths are delimited using the / character and names are case sensitive. The /game/content folder in the MGDF install root folder is mounted as the root of the logical filesystem, and no access outside of this folder is permitted.

    BOOL GetFile ( const wchar_t * logicalPath , IMGDFReadOnlyFile ** file )
    Parameters
    logicalPath The vfs path to the file
    file Pointer to the file/folder/archive in the specified logical directory. paths are delimited using the / character and names are case sensitive
    Returns
    True if the file could be found

  • GetRoot Get the root node of the filesystem. In the physical filesystem this corresponds to the /game/content folder.

    void GetRoot ( IMGDFReadOnlyFile * * root )
    Parameters
    root Pointer to the root node of the filesystem

IMGDFRenderHost Provides an entrypoint for a module to interact with the MGDF host. This interface inherits from ICommonHost and provides additional methods which are safe to be used ONLY from the render thread.

Inherits from: IMGDFCommonHost

  • SetBackBufferRenderTarget Set the current back buffer as the render target for the specified d2d device context

    BOOL SetBackBufferRenderTarget ( ID2D1DeviceContext * context )
    Parameters
    context The d2d device context to set the render target for
    Returns
    True if the back buffer can be set as the render target for the device context

  • GetBackBuffer Gets the current back buffer texture.

    void GetBackBuffer ( ID3D11Texture2D * * backbuffer )
    Parameters
    backbuffer The current back buffer texture. The pointer returned by this method becomes invalid when the modules OnReset event is fired

  • GetDepthStencilBuffer Gets the current depth stencil buffer texture.

    void GetDepthStencilBuffer ( ID3D11Texture2D * * stencilBuffer )
    Parameters
    stencilBuffer The current stencil buffer texture. The pointer returned by this method becomes invalid when the modules OnReset event is fired

  • GetBackBufferDescription Gets the description of the backbuffer and depthStencilBuffer textures.

    void GetBackBufferDescription ( D3D11_TEXTURE2D_DESC * backBufferDesc , D3D11_TEXTURE2D_DESC * depthStencilBufferDesc )
    Parameters
    backBufferDesc The backbuffer description to populate. If null is passed, this field is not populated
    depthStencilBufferDesc The backbuffer description to populate. If null is passed, this field is not populated

  • CreateGPUCounter Create a performance counter for profiling GPU time taken in DirectX API calls. When no longer used it should be Released

    HRESULT CreateGPUCounter ( IMGDFMetric * metric , ID3D11DeviceContext * context , IMGDFPerformanceCounter * * counter )
    Parameters
    metric The metric the counter should update
    context The device context this counter measures
    counter Points to the created counter
    Returns
    E_FAIL if GPU counters are unsupported (using D3D_FEATURE_LEVEL_9_3 or less) otherwise returns S_OK

IMGDFRenderSettingsManager Provides an interface for getting and setting the hosts various display settings

Inherits from: IUnknown

  • GetSDRBackBufferFormat Gets the format of the backbuffer when rendering on an SDR display

    DXGI_FORMAT GetSDRBackBufferFormat ( )
    Returns
    The backbuffer format

  • GetHDRBackBufferFormat Gets the format of the backbuffer when rendering on an HDR display

    DXGI_FORMAT GetHDRBackBufferFormat ( )
    Returns
    The backbuffer format

  • GetMaxFrameLatency Gets the number of frames that the swap chain is allowed to queue for rendering.

    UINT32 GetMaxFrameLatency ( )
    Returns
    True if vsync is enabled

  • GetVSync Gets the current vsync setting

    BOOL GetVSync ( )
    Returns
    True if vsync is enabled

  • GetFullscreen Gets the current fullscreen setting

    void GetFullscreen ( MGDFFullScreenDesc * fullscreen )
    Parameters
    fullscreen A description of the current fullscreen settings

  • GetMultiSampleLevelCount Get the number of supported multisample levels

    UINT64 GetMultiSampleLevelCount ( )
    Returns
    The number of supported multisample levels

  • GetMultiSampleLevel Get the available multisample level supported by the display device at the given index ( 0 to GetMultiSampleLevelCount() - 1 )

    BOOL GetMultiSampleLevel ( UINT64 index , UINT32 * level )
    Parameters
    index The multisample index
    level Returns the multisample level at the given index
    Returns
    True if a supported multisample level is present at the given index, false otherwise.

  • GetBackBufferMultiSampleLevel Get the current multisample level in use by the device

    UINT32 GetBackBufferMultiSampleLevel ( )
    Returns
    The current multisample level in use by the device

  • GetCurrentMultiSampleLevel Get the current desired multisample level for off screen render targets

    UINT32 GetCurrentMultiSampleLevel ( UINT32 * quality )
    Parameters
    quality If specified this parameter will be initialized with the maximum multisampling quality setting for the current multisample level
    Returns
    The current desired multisample level for off screen render targets

  • GetPrimaryDisplayModeCount Get the number of supported display modes on the primary output

    UINT64 GetPrimaryDisplayModeCount ( )
    Returns
    The number of supported display modes

  • GetPrimaryDisplayMode Get a supported display mode for the primary output at the given index (0 to GetPrimaryDisplayModeCount - 1)

    BOOL GetPrimaryDisplayMode ( UINT64 index , MGDFDisplayMode * mode )
    Parameters
    index The display mode index
    mode Will be set to the the display mode at the given index
    Returns
    True if a display mode exists at a particular index

  • GetPrimaryDisplayModes Get all the supported display modes for the primary output

    void GetPrimaryDisplayModes ( MGDFDisplayMode * * modes )
    Parameters
    modes An array big enough to hold GetPrimaryDisplayModeCount() modes

  • GetPrimaryDisplayModeFromDimensions Get the display mode from the primary output matching the requested width and height, if no matching display mode is found, false is returned. If HDR is enabled, and supported an HDR display mode will be preferentially chosen

    BOOL GetPrimaryDisplayModeFromDimensions ( UINT32 width , UINT32 height , MGDFDisplayMode * mode )
    Parameters
    width The desired width of the display mode
    height The desired height of the display mode
    mode Will be set to the matching display mode found (if any)
    Returns
    True if a supported display mode exists for the given width and height

  • GetNativePrimaryDisplayMode Get the display mode matching the native width and height, of the primary output. If HDR is enabled, and supported an HDR display mode will be preferentially chosen

    BOOL GetNativePrimaryDisplayMode ( MGDFDisplayMode * mode )
    Parameters
    mode Will be set to the current display mode found
    Returns
    True if a supported display mode exists for the native output width & height

  • GetCurrentPrimaryDisplayMode Get the current display mode for the primary output being used when running in exclusive fullscreen mode

    MGDFDisplayMode * GetCurrentPrimaryDisplayMode ( MGDFDisplayMode * mode )
    Parameters
    mode Will be set to the current display mode being used.
    Returns
    The current display mode being used (a pointer to mode)

  • GetScreenX Get the current screen width, based on the primary display mode in exclusive fullscreen, or on the window dimensions otherwise

    UINT32 GetScreenX ( )
    Returns
    The current screen width

  • GetScreenY Get the current screen height, based on the current display mode in exclusive fullscreen, or on the window dimensions otherwise

    UINT32 GetScreenY ( )
    Returns
    Thr current screen height

  • GetHDREnabled Get whether HDR should be enabled when its supported by the current display output

    BOOL GetHDREnabled ( )
    Returns
    Is hdr enabled

  • GetCurrentOutputDisplayInfo Get information about the current display

    void GetCurrentOutputDisplayInfo ( MGDFOutputDisplayInfo * info )
    Parameters
    info A pointer to the display info structure to be filled in

  • GetCurrentOutputDPI Get the DPI of the current display output. This can change from frame to frame, from frame to frame, so shouldn't be cached.

    UINT GetCurrentOutputDPI ( )
    Returns
    The DPI of the current display output

  • CreatePendingSettingsChange Create a pending changeset to the render settings

    void CreatePendingSettingsChange ( IMGDFPendingRenderSettingsChange * * changeset )
    Parameters
    changeset A pointer to the pending changeset created

  • GetPreferences Gets the current persistable render settings.

    void GetPreferences ( IMGDFPreferenceSet * * preferences )
    Parameters
    preferences A pointer to a preference set that can be passed into the IMGDFGame SetPreferences method to set the preferences

IMGDFSaveManager An interface to control saving/loading gamestate data

Inherits from: IUnknown

  • GetSaveCount Get the number of saved gamestates available

    UINT64 GetSaveCount ( )
    Returns
    The number of saved gamestates available

  • GetSave Get the saved state at the given index.

    HRESULT GetSave ( UINT64 index , IMGDFGameState * * save )
    Parameters
    index Which gamestate, valid values are 0 to GetSaveCount - 1.
    save Pointer to the gamestate at the given index
    Returns
    S_OK if a valid gamestate exists at the given index, otherwise an error code is returned

  • DeleteSave Deletes a saved gamestate

    HRESULT DeleteSave ( IMGDFGameState * state )
    Parameters
    state A gamestate previously returned from GetSave
    Returns
    S_OK if the gamestate could be deleted, otherwise an error code is returned

  • CreateGameState Creates a new empty gamestate without metadata or any persisted data

    void CreateGameState ( IMGDFGameState * * save )
    Parameters
    save A pointer to the created gamestate.

IMGDFSimHost Provides an entrypoint for a module to interact with the MGDF host. This interface inherits from IMGDFCommonHost and provides additional methods which are safe to be used ONLY from the sim thread.

Inherits from: IMGDFCommonHost

  • GetSaves Gets the save manager

    void GetSaves ( IMGDFSaveManager * * save )
    Parameters
    save The save manager object

  • GetGame Get information regarding the current game and its preferences

    void GetGame ( IMGDFGame * * game )
    Parameters
    game Pointer to object containing information regarding the game and its preferences

  • GetSound Get the sound manager

    void GetSound ( IMGDFSoundManager * * sound )
    Parameters
    sound The sound manager, nullptr if the audio subsystem failed to initialize

  • GetStatistics Get the statistics manager

    void GetStatistics ( IMGDFStatisticsManager * * statistics )
    Parameters
    statistics The statistics manager

  • GetInput Get the input manager

    void GetInput ( IMGDFInputManager * * input )
    Parameters
    input Pointer to an input manager

  • ShutDown Tells the host to shut down the game immediately

    void ShutDown ( )

  • QueueShutDown Tells the host to invoke the modules shutdown callback

    void QueueShutDown ( )

  • CreateHttpRequest Create a pending http request. The request isn't actually sent until the Send method is called on the request object

    HRESULT CreateHttpRequest ( const small * url , IMGDFHttpClientRequest * * request )
    Parameters
    url The url to send the request to
    request The created request object
    Returns
    S_OK if the request could be created, otherwise an error code is returned

  • CreateHttpRequestGroup Create an http request group. These are used to group related requests and responses

    HRESULT CreateHttpRequestGroup ( IMGDFHttpClientRequestGroup * * group )
    Parameters
    group The created request group object
    Returns
    S_OK if the request group could be created, otherwise an error code is returned

  • CreateWebSocket Create a websocket connection

    HRESULT CreateWebSocket ( const small * url , IMGDFWebSocket ** socket )
    Parameters
    url The url to connect to
    socket The created websocket object
    Returns
    S_OK if the websocket could be created, otherwise an error code is returned

  • CreateWebServer Create a web server that can handle http and web socket requests

    HRESULT CreateWebServer ( unsigned int port , const small * websocketPath , IMGDFWebServer ** server )
    Parameters
    port For the server to listen on
    websocketPath Any requests matching this path glob will be upgraded to a websocket connection. If null, all requests will be treated as regular HTTP requests
    server The created web server object
    Returns
    S_OK if the webserver could be created, otherwise an error code is returned

IMGDFSound An sound source in 3d space

Inherits from: IUnknown

  • GetName The name of the sound

    HRESULT GetName ( wchar_t * name , UINT64 * length )
    Parameters
    name Buffer to store the sound name
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the name buffer was the correct length or was NULL, otherwise E_NOT_SUFFICIENT_BUFFER

  • GetPosition The position of the sound

    MGDFSoundPosition * GetPosition ( MGDFSoundPosition * position )
    Parameters
    position The position of the sound
    Returns
    The position of the sound

  • GetVelocity The velocity of the sound

    MGDFSoundPosition * GetVelocity ( MGDFSoundPosition * velocity )
    Parameters
    velocity The velocity of the sound
    Returns
    The velocity of the sound

  • SetPosition Set the position of the sound

    MGDFSoundPosition * SetPosition ( MGDFSoundPosition * position )
    Parameters
    position The position of the sound
    Returns
    The position of the sound

  • SetVelocity Set the velocity of the sound

    MGDFSoundPosition * SetVelocity ( MGDFSoundPosition * velocity )
    Parameters
    velocity The velocity of the sound
    Returns
    The velocity of the sound

  • GetInnerRange The distance (from the observer) at which the sound intensity reaches its maximum. Getting closer than this will not cause the sound intensity to get any greater

    float GetInnerRange ( )
    Returns
    The distance (from the observer) at which the sound intensity reaches its maximum. Getting closer than this will not cause the sound intensity to get any greater

  • SetInnerRange Set The distance (from the observer) at which the sound intensity reaches its maximum. Getting closer than this will not cause the sound intensity to get any greater

    void SetInnerRange ( float innerRange )
    Parameters
    innerRange The distance (from the observer) at which the sound intensity reaches its maximum. Getting closer than this will not cause the sound intensity to get any greater

  • GetOuterRange The distance (from the observer) at which the sound intensity reaches 0

    float GetOuterRange ( )
    Returns
    The distance (from the observer) at which the sound intensity reaches its 0

  • SetOuterRange Set The distance (from the observer) at which the sound intensity reaches 0

    void SetOuterRange ( float outerRange )
    Parameters
    outerRange The distance (from the observer) at which the sound intensity reaches 0

  • GetSourceRelative Does the sound stay relative to the listeners position or is it fixed in absolute space

    BOOL GetSourceRelative ( )
    Returns
    True if the sound is always relative to the listeners position

  • SetSourceRelative Does the sound stay relative to the listeners position or is it fixed in absolute space

    void SetSourceRelative ( BOOL sourceRelative )
    Parameters
    sourceRelative True if the sound is always relative to the listeners position

  • GetVolume Get the current volume of the sound (ignoring attenuation due to position)

    float GetVolume ( )
    Returns
    The current volume of the sound (ignoring attenuation due to position)

  • SetVolume Set the current volume of the sound (ignoring attenuation due to position)

    void SetVolume ( float volume )
    Parameters
    volume The current volume of the sound (ignoring attenuation due to position)

  • GetPitch Get the pitch of the current sound

    float GetPitch ( )
    Returns
    1.0 if the pitch is unchanged. between 0.5 and 1.0 is lower, and between 1.0 and 2.0 is higher pitched

  • SetPitch Set the pitch of the current sound

    void SetPitch ( float pitch )
    Parameters
    pitch 1.0 if the pitch is unchanged. between 0.5 and 1.0 is lower, and between 1.0 and 2.0 is higher pitched

  • SetPriority Set the priority used by the sound system to determine which sounds get deactivated if not enough sound sources are available to play all sounds

    void SetPriority ( INT32 priority )
    Parameters
    priority The priority to use for the sound. Higher values mean higher priority

  • GetPriority Get the priority used by the sound system to determine which sounds get deactivated if not enough sound sources are available to play all sounds

    INT32 GetPriority ( )
    Returns
    Priority the priority to use for the sound. Higher values mean higher priority

  • GetLooping Get whether the sound will loop playback continously

    BOOL GetLooping ( )
    Returns
    True if the sound should loop continously

  • SetLooping Set whether the sound will loop playback continously

    void SetLooping ( BOOL looping )
    Parameters
    looping True if the sound should loop playback, false otherwise
    Returns
    Looping true if the sound should loop continously

  • Stop Stop the playing of the current playlist if it was playing or paused (resets playlist to the beginning aswell)

    void Stop ( )

  • Pause Pause the playing of the current playlist (if it was playing)

    void Pause ( )

  • Play Resume the playing of the current playlist (if it was paused or stopped)

    void Play ( )

  • IsStopped Determines if the playlist has stopped play

    BOOL IsStopped ( )
    Returns
    True if the playlist has stopped play

  • IsPaused Determines if the playlist has paused play

    BOOL IsPaused ( )
    Returns
    True if the playlist has paused play

  • IsPlaying Determines if the playlist is playing

    BOOL IsPlaying ( )
    Returns
    True if the playlist is playing

  • IsActive Is the sound currently playing or has it been culled

    BOOL IsActive ( )
    Returns
    True if the sound manager has culled this sound source

IMGDFSoundManager An interface for controlling positional sounds as well as streaming sound sources

Inherits from: IUnknown

  • GetListenerPosition Determine the position of the listener (i.e. the player)

    MGDFSoundPosition * GetListenerPosition ( MGDFSoundPosition * listener )
    Parameters
    listener The position of the listener (i.e. the player)
    Returns
    The position of the listener (i.e. the player)

  • GetListenerVelocity Determine the velocity of the listener (i.e. the player)

    MGDFSoundPosition * GetListenerVelocity ( MGDFSoundPosition * velocity )
    Parameters
    velocity The velocity of the listener (i.e. the player)
    Returns
    The velocity of the listener (i.e. the player)

  • GetListenerOrientationForward Get the vector representing the forward direction of the listener (i.e. the player)

    MGDFSoundPosition * GetListenerOrientationForward ( MGDFSoundPosition * orientationForward )
    Parameters
    orientationForward The vector representing the forward direction of the listener
    Returns
    The vector representing the forward direction of the listener

  • GetListenerOrientationUp Get the vector representing the upward direction of the listener (i.e. the player)

    MGDFSoundPosition * GetListenerOrientationUp ( MGDFSoundPosition * orientationUp )
    Parameters
    orientationUp The vector representing the upward direction of the listener
    Returns
    The vector representing the upward direction of the listener

  • SetListenerPosition Set the position of the listener (i.e. the player)

    MGDFSoundPosition * SetListenerPosition ( MGDFSoundPosition * listener )
    Parameters
    listener The position of the listener (i.e. the player)
    Returns
    The position of the listener (i.e. the player)

  • SetListenerVelocity Set the velocity of the listener (i.e. the player)

    MGDFSoundPosition * SetListenerVelocity ( MGDFSoundPosition * velocity )
    Parameters
    velocity The velocity of the listener (i.e. the player)
    Returns
    The velocity of the listener (i.e. the player)

  • SetListenerOrientationForward Set the vector representing the forward direction of the listener (i.e. the player)

    MGDFSoundPosition * SetListenerOrientationForward ( MGDFSoundPosition * orientationForward )
    Parameters
    orientationForward The vector representing the forward direction of the listener
    Returns
    The vector representing the forward direction of the listener

  • SetListenerOrientationUp Set the vector representing the upward direction of the listener (i.e. the player)

    MGDFSoundPosition * SetListenerOrientationUp ( MGDFSoundPosition * orientationUp )
    Parameters
    orientationUp The vector representing the upward direction of the listener
    Returns
    The vector representing the upward direction of the listener

  • GetSoundVolume Get the master volume (0-1) All sounds volumes are relative to this setting

    float GetSoundVolume ( )
    Returns
    The master volume

  • SetSoundVolume Set the master volume (0-1) All sounds volumes are relative to this setting

    void SetSoundVolume ( float volume )
    Parameters
    volume The master volume

  • GetStreamVolume Get the master volume for streamed sounds (0-1) All streams volumes are relative to this setting

    float GetStreamVolume ( )
    Returns
    The master stream volume

  • SetStreamVolume Set the master volume for streamed sounds (0-1) All streams volumes are relative to this setting

    void SetStreamVolume ( float volume )
    Parameters
    volume The master stream volume

  • GetEnableAttenuation Get whether sounds should attenuate with thier distance from the listener

    BOOL GetEnableAttenuation ( )
    Returns
    True if sounds should attenuate with thier distance from the listener

  • SetEnableAttenuation Set whether sounds should attenuate with thier distance from the listener

    void SetEnableAttenuation ( BOOL enableAttenuation )
    Parameters
    enableAttenuation True if sounds should attenuate with thier distance from the listener

  • GetDopplerShiftFactor Get whether sounds will doppler shift based on thier relative velocity to the listener

    float GetDopplerShiftFactor ( )
    Returns
    Whether sounds will doppler shift based on thier relative velocity to the listener

  • SetDopplerShiftFactor Set whether sounds will doppler shift based on thier relative velocity to the listener

    void SetDopplerShiftFactor ( float dopplerShiftFactor )
    Parameters
    dopplerShiftFactor True if sounds should doppler shift based on thier relative velocity to the listener

  • GetSpeedOfSound Get the speed of sound used to calculate doppler shifting of sounds

    float GetSpeedOfSound ( )
    Returns
    The speed of sound used to calculate doppler shifting of sounds

  • SetSpeedOfSound Set the speed of sound used to calculate doppler shifting of sounds

    void SetSpeedOfSound ( float speedOfSound )
    Parameters
    speedOfSound The speed of sound used to calculate doppler shifting of sounds

  • CreateSound Create a sound by loading a file in the VFS into memory. When no INT32er used it should be Released

    HRESULT CreateSound ( IMGDFReadOnlyFile * file , INT32 priority , IMGDFSound * * sound )
    Parameters
    file The data source for the sound
    priority The priority of the sound (used to determine what should play if no free audio sources are available
    sound If the sound is created successfully, this will point to the created sound
    Returns
    S_OK if the sound was created successfully, otherwise an error code will be returned

  • CreateSoundStream Create a sound stream from a file in the VFS. When no longer used it should be Released

    HRESULT CreateSoundStream ( IMGDFReadOnlyFile * file , IMGDFSoundStream * * stream )
    Parameters
    file The data source for the sound stream
    stream If the stream is created successfully, this will point to the created stream
    Returns
    S_OK if the stream was created successfully, otherwise an error code will be returned

  • GetPreferences Gets the current persistable sound settings. Note: this only consists of master volume settings. Other settings like attenuation & speedOfSound need to be reset on startup

    void GetPreferences ( IMGDFPreferenceSet * * preferences )
    Parameters
    preferences A pointer to a preference set that can be passed into the IMGDFGame setPreferences method to set the preferences

IMGDFSoundStream A vorbis sound stream

Inherits from: IUnknown

  • GetName The name of the sound stream

    HRESULT GetName ( wchar_t * name , UINT64 * length )
    Parameters
    name Buffer to store the sound stream name
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the name buffer was the correct length or was NULL, otherwise E_NOT_SUFFICIENT_BUFFER

  • GetVolume Get the volume level (0-1)

    float GetVolume ( )
    Returns
    The volume level (0-1)

  • SetVolume Set the volume level (0-1)

    void SetVolume ( float volume )
    Parameters
    volume The volume level to set

  • GetPosition The position of playback in the stream (0 -> GetLength)

    UINT32 GetPosition ( )
    Returns
    The position of playback in the stream

  • GetLength The total length of the stream

    UINT32 GetLength ( )
    Returns
    The total length of the stream

  • Stop Stop the playing of the current stream if it was playing or paused (resets it to the beginning aswell)

    void Stop ( )

  • Pause Pause the playing of the current stream (if it was playing)

    void Pause ( )

  • Play Resume the playing of the current playlist (if it was paused or stopped)

    HRESULT Play ( )
    Returns
    Success if the sound could resume playing, otherwise returns an error code.

  • IsStopped Determines if the stream has stopped play

    BOOL IsStopped ( )
    Returns
    True if the stream has stopped play

  • IsPaused Determines if the stream has paused play

    BOOL IsPaused ( )
    Returns
    True if the stream has paused play

  • IsPlaying Determines if the stream is playing

    BOOL IsPlaying ( )
    Returns
    True if the stream is playing

IMGDFStatisticsManager Provides an interface for pushing statistics to a remote endpoint during a game session.

Inherits from: IUnknown

  • PushString Pushes a statistic to the remote statistics service (if one is specified)

    void PushString ( const small * name , const small * value , const MGDFTags * tags )
    Parameters
    name The name of the statistic tracker key
    value The value of the statistic
    tags Any tags to pass with the statistic (null if none are to be included)

  • PushMetric Pushes a metrics current value to the remote statistics service (if one is specified)

    void PushMetric ( IMGDFMetric * metric )
    Parameters
    metric The metric to push, this will be passed to the statistics service as a name/value pair

IMGDFTimer Provides an interface to the hosts high resolution CPU timer

Inherits from: IUnknown

  • GetCurrentTimeTicks Get the current system time in ticks

    LARGE_INTEGER GetCurrentTimeTicks ( )
    Returns
    The current system time in ticks

  • GetTimerFrequency Get the current system timer frequency

    LARGE_INTEGER GetTimerFrequency ( )
    Returns
    The current system timer frequency

  • ConvertDifferenceToSeconds Convert two system tick times into a duration in seconds

    double ConvertDifferenceToSeconds ( LARGE_INTEGER newTime , LARGE_INTEGER oldTime )
    Parameters
    newTime The newer of the two times
    oldTime The older of the two times
    Returns
    The difference betweeen the two parameters converted into seconds

IMGDFWebServer An interface for creating and managing a websocket server

Inherits from: IUnknown

  • RequestRecieved Get whether any new incoming requests were made. This should be called repeatedly until it returns false to process all incoming requests.

    BOOL RequestRecieved ( MGDFWebServerRequest * request )
    Parameters
    request . The type of incoming request, this is a union of either a websocket connection or a standard HTTP request.
    Returns
    True if a new incoming connection was made

  • Listening Whether the server is listening for incoming connections

    BOOL Listening ( )
    Returns
    True if the server is listening for incoming connections

IMGDFWebSocket An interface for sending and recieving websocket messages

Inherits from: IUnknown

  • Send Sends a message to the websocket server

    void Send ( void * data , UINT64 len , BOOL binary )
    Parameters
    data The data to send
    len The length of the data to send
    binary True if the data is binary, false if it is a string

  • CanRecieve Determines if there is a message available to be recieved

    BOOL CanRecieve ( UINT64 * len )
    Parameters
    len The length of the message to be recieved
    Returns
    True if a message is available to be recieved

  • Receive Recieves a message from the other end of the websocket connection

    HRESULT Receive ( void * message , UINT64 len , BOOL * binary )
    Parameters
    message The message to recieve
    len The length of the buffer to recieve the message
    binary True if the message is binary, false if it is a string
    Returns
    S_OK if there was a message to receive and the buffer was large enough to store it, otherwise E_NOT_SUFFICIENT_BUFFER is returned

  • GetConnectionStatus Gets the current status of the connection

    HRESULT GetConnectionStatus ( MGDFWebSocketConnectionStatus * status )
    Parameters
    status The current status of the connection. The LastError field should point to a buffer of at least LastErrorLength bytes
    Returns
    S_OK if the LastError buffer was large enough to store the error message, otherwise E_NOT_SUFFICIENT_BUFFER is returned & LastErrorLength will be set to the required length

IMGDFWriteableFile Provides an interface for navigating a writeable file/directory structure. These include writeable folders such as the working directory and save game folders.

Inherits from: IMGDFFile

  • Exists Does the file/folder exist

    BOOL Exists ( )
    Returns
    True if the file/folder exists

  • GetParent Gets the parent of this file. If this file is the root of the virtual filesystem, then this will be nullptr

    BOOL GetParent ( IMGDFWriteableFile * * parent )
    Parameters
    parent Pointer to the parent of this file.
    Returns
    If this file is the root of the filesystem then return false, otherwise true.

  • GetChild Gets a child of this file with the given name (if any)

    BOOL GetChild ( const wchar_t * name , IMGDFWriteableFile ** child )
    Parameters
    name The child name of this file
    child The child file of the current file
    Returns
    True if the child file could be found

  • GetAllChildren Get all the children of this file (non-recursive)

    HRESULT GetAllChildren ( IMGDFWriteableFile * * buffer , UINT64 * length )
    Parameters
    buffer An array to store the results
    length The length of the buffer provided to store the value above. Will be set to the length required.
    Returns
    S_OK if all the children could be stored in the provided buffer or the buffer was NULL, E_NOT_SUFFICIENT_BUFFER otherwise

  • OpenWrite Attempt to open the file for writing if the path to this file doesn't exist it will be created

    HRESULT OpenWrite ( IMGDFFileWriter * * writer )
    Parameters
    writer Pointer to a writer instance to be created
    Returns
    S_OK if the writer could be created, otherwise E_FAIL or E_ACCESSDENIED

  • CreateFolder Creates this as a folder (and any necessary parent folders along the way)

    HRESULT CreateFolder ( )
    Returns
    S_OK if the folder could be created, otherwise E_FAIL

  • Delete Deletes this file or folder (and its descendants). Note the root of a VFS cannot be deleted and will fail if attempted

    HRESULT Delete ( )
    Returns
    S_OK if the file or folder could be deleted, otherwise E_FAIL

  • MoveTo Moves this file or folder to the desired target location

    HRESULT MoveTo ( IMGDFWriteableFile * destination )
    Parameters
    destination The target location for this file/folder. If the destination exists it should be deleted first or else this call will fail.
    Returns
    S_OK if the file/folder could be moved, otherwise E_FAIL

  • CopyTo Copies this file or folder to the desired target location

    HRESULT CopyTo ( IMGDFWriteableFile * destination )
    Parameters
    destination The target location for this file/folder. If the destination exists it should be deleted first or else this call will fail.
    Returns
    S_OK if the file/folder could be copied, otherwise E_FAIL

IMGDFWriteableVirtualFileSystem Provides an interface for accessing the writable filesystem, which is used for save game folders and the working directory

Inherits from: IUnknown

  • GetFile Get the file/folder/archive in the specified logical directory. paths are delimited using the / character and names are case sensitive.

    BOOL GetFile ( const wchar_t * logicalPath , IMGDFWriteableFile ** file )
    Parameters
    logicalPath The vfs path to the file
    file Pointer to the file/folder/archive in the specified logical directory. paths are delimited using the / character and names are case sensitive
    Returns
    True if the file could be found

  • GetRoot Get the root node of the filesystem. In the physical filesystem this corresponds to the /game/content folder.

    void GetRoot ( IMGDFWriteableFile * * root )
    Parameters
    root Pointer to the root node of the filesystem

Structs

MGDFArchivePathSegment Part of a logical path to a file in the virtual filesystem representing either a folder or file

  • Start

    const wchar_t * Start

  • Length

    UINT64 Length

MGDFDisplayMode The display settings for a particular display mode

  • Width

    UINT32 Width

  • Height

    UINT32 Height

  • RefreshRateNumerator

    UINT32 RefreshRateNumerator

  • RefreshRateDenominator

    UINT32 RefreshRateDenominator

  • SupportsHDR

    BOOL SupportsHDR

  • IsNativeSize

    BOOL IsNativeSize

MGDFFullScreenDesc The current fullscreen options

  • FullScreen

    BOOL FullScreen

  • ExclusiveMode

    BOOL ExclusiveMode

MGDFOutputDisplayInfo The current outputs HDR display information

  • SupportsHDR

    BOOL SupportsHDR

  • MaxFullFrameLuminance

    FLOAT MaxFullFrameLuminance

  • MaxLuminance

    FLOAT MaxLuminance

  • MinLuminance

    FLOAT MinLuminance

  • SDRWhiteLevel

    ULONG SDRWhiteLevel

  • Width

    UINT32 Width

  • Height

    UINT32 Height

MGDFSoundPosition The position of a sound source in 3d space

  • x

    float x

  • y

    float y

  • z

    float z

MGDFTags Allows a metric to be tagged with a collection of name/value pairs

  • Names

    const small ** Names

  • Values

    const small ** Values

  • Count

    UINT64 Count

MGDFVersion Represents a version number

  • Major

    INT32 Major

  • Minor

    INT32 Minor

  • Build

    INT32 Build

  • Revision

    INT32 Revision

MGDFWebServerRequest Represents a request made to a webserver. Either a websocket connection or a standard HTTP request.

MGDFWebSocketConnectionStatus The combined status of a websocket connection including its current state and any recent errors

Enumerations

MGDFGamepadButton All the gamepad button types recognized by the input manager

Values
MGDF_GAMEPAD_DPAD_UP
MGDF_GAMEPAD_DPAD_DOWN
MGDF_GAMEPAD_DPAD_LEFT
MGDF_GAMEPAD_DPAD_RIGHT
MGDF_GAMEPAD_START
MGDF_GAMEPAD_BACK
MGDF_GAMEPAD_LEFT_THUMB
MGDF_GAMEPAD_RIGHT_THUMB
MGDF_GAMEPAD_LEFT_SHOULDER
MGDF_GAMEPAD_RIGHT_SHOULDER
MGDF_GAMEPAD_A
MGDF_GAMEPAD_B
MGDF_GAMEPAD_X
MGDF_GAMEPAD_Y

MGDFLogLevel The logging levels available, LOG_ERROR is of the highest importance with LOG_HIGH messages being of the least importance

Values
MGDF_LOG_ERROR
MGDF_LOG_LOW
MGDF_LOG_MEDIUM
MGDF_LOG_HIGH

MGDFMouse This is represents all the various mouse buttons that are recognized by the input manager

Values
MGDF_MOUSE_LEFT
MGDF_MOUSE_RIGHT
MGDF_MOUSE_MIDDLE

MGDFWebSocketConnectionState The state of a websocket connection

Values
MGDF_WEBSOCKET_CONNECTING
MGDF_WEBSOCKET_OPEN
MGDF_WEBSOCKET_CLOSED