Matchstick game development framework

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)

-vr: [Optional] Requests VR for this run without changing host.vr. The module must set MGDFGraphicsRequirements::VR to TRUE. See the VR guide.
-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.vr: Requests VR at startup ("1") or window rendering ("0"). Defaults to "0". The module must opt in through MGDFGraphicsRequirements::VR. Use SetVR on IMGDFPendingRenderSettingsChange to change this setting. If a headset session cannot start, the game continues in the window and keeps the saved preference. See the VR guide.
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.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.lowLatencyMode: The low latency mode: "0" (off), "1" (on) or "2" (on with boost). The host uses "0" when GetLowLatencyMode on IMGDFRenderSettingsManager does not list the mode. Defaults to "1"
host.frameGeneration: The number of generated frames per rendered frame. "0" turns frame generation off. The host limits the value to GetMaxGeneratedFrames on IMGDFRenderSettingsManager. Defaults to "0"
host.rayTracing: Whether the module should use ray tracing ("1") or not ("0"). The host uses "0" when GetRayTracingSupport on IMGDFRenderSettingsManager returns FALSE. The host does nothing else with it; the module reads it with GetRayTracing. 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 IMGDFStatisticsManager 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"}

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.

GetGraphicsRequirements Declares the module's D3D12 graphics requirements. The host reads these requirements before it creates the module.


                        
                            
                                HRESULT
                            
                        
                        GetGraphicsRequirements
                        (
                        
                        
                            
                                
                                
                                    
                                        MGDFGraphicsRequirements *
                                    
                                
                                requirements
                            
                        
                        )

Parameters: requirements The requirements to fill. Set MinFeatureLevel to the minimum D3D feature level and MinShaderModel to a D3D_SHADER_MODEL value. Set HDRFormat to the MGDFHDRFormat that the module writes while HDR output is on. Zero selects MGDF_HDR_FORMAT_SCRGB. Unknown HDRFormat values are errors. Set VR to TRUE only if the module renders both headset views and the window. Zero keeps VR unavailable.

Returns: Return S_OK after filling the requirements. Return an error code if the requirements cannot be supplied.

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

Use IMGDFSimHost on the simulation thread and IMGDFRenderHost on the render thread. Both inherit IMGDFCommonHost, which provides the D3D12 device and queues. Get the other interfaces through these hosts. See the VR guide for headset rendering and input.

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. Release device and queue references before acknowledging a device reset

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
GetDebug Get the debug overlay data and visibility 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 ( )
GetD3D12Device Gets an owned reference to the device, or null during device reset
void GetD3D12Device ( ID3D12Device10 ** device )

Parameters

device Points to the device
GetDirectQueue Gets an owned reference to the direct queue
void GetDirectQueue ( ID3D12CommandQueue ** queue )

Parameters

queue Points to the direct queue
GetComputeQueue Gets an owned reference to the compute queue
void GetComputeQueue ( ID3D12CommandQueue ** queue )

Parameters

queue Points to the compute queue
GetCopyQueue Gets an owned reference to the copy queue
void GetCopyQueue ( ID3D12CommandQueue ** queue )

Parameters

queue Points to the copy queue
GetUpscaleRenderSize Gets the render size for an upscale mode and output size
HRESULT GetUpscaleRenderSize ( MGDFUpscaleMode mode , UINT32 displayWidth , UINT32 displayHeight , MGDFUpscaleRenderSize * size )

Parameters

mode The upscale mode

displayWidth The output width

displayHeight The output height

size Receives the render size

Returns

S_OK, E_INVALIDARG for an unknown mode or a zero size, or E_NOTIMPL if IMGDFRenderSettingsManager::GetUpscaleMode does not list the mode

IMGDFDebug Debug overlay data. The host draws no overlay: a module that wants one draws it from GetOverlaySnapshot and decides itself when to show it

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)
GetOverlaySnapshot Copies the overlay data into a snapshot for the module to draw
HRESULT GetOverlaySnapshot ( IMGDFDebugOverlaySnapshot * * snapshot )

Parameters

snapshot Points to the created snapshot

Returns

S_OK if the snapshot could be created, otherwise an error code

IMGDFDebugOverlaySnapshot An immutable copy of the debug overlay data taken by IMGDFDebug::GetOverlaySnapshot. Release it when done with the data

Inherits from: IUnknown

GetData The copied overlay data
const MGDFDebugOverlayData * GetData ( )

Returns

The overlay data, valid while this snapshot is alive

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. Committing REPLACES the previous save contents wholesale, so anything that should survive across saves must be migrated into the pending VFS during the save - the previous save's data is exposed for exactly that purpose
HRESULT BeginSave ( IMGDFWriteableVirtualFileSystem * * pending , IMGDFReadOnlyVirtualFileSystem * * previous )

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

previous A readonly VFS mounted over the previous save's data (null for a new game state), valid until the pending VFS is released - gives the module the opportunity to move or merge prior contents into the new save

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

GetVRControllerCount Returns 2 controller objects: left and right, including with VR off
UINT64 GetVRControllerCount ( )

Returns

2, including while VR is off
GetVRControllers Fills GetVRControllerCount entries in hand order with owned COM references. Release each reference when no longer needed. Objects can be kept across session changes. Safe with VR off; a null array is ignored
void GetVRControllers ( IMGDFVRController ** controllers )

Parameters

controllers An array of two owned references, in left and right hand order; null is ignored
GetVRGaze Gets the current sim update's eye gaze sample. Safe with VR off
BOOL GetVRGaze ( MGDFVRPose * pose )

Parameters

pose Receives the current sim gaze pose; zero on FALSE

Returns

TRUE with position and orientation; FALSE for no session, no input focus, unavailable eye tracking, no current sample or null output. Non-null output is zero on FALSE
ShowCursor Determines whether the OS cursor is displayed or not
void ShowCursor ( BOOL show )

Parameters

show Whether to show the cursor or not
SetCursorShape Sets the shape the OS cursor takes while it is shown. The shape applies from the next mouse move
void SetCursorShape ( MGDFCursor cursor )

Parameters

cursor The cursor shape
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 to ask the host to clear the backbuffer for this frame
RTAfterPresent Called by the host once per render frame after Present
void RTAfterPresent ( IMGDFRenderHost * host )

Parameters

host The render thread host
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
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 ( )
SetWindowAspectLock Sets whether the window keeps its client aspect ratio while the user resizes it. The lock only has an effect in windowed mode when window resizing is enabled. The setting is saved in the host.windowAspectLock preference
void SetWindowAspectLock ( BOOL enabled )

Parameters

enabled TRUE to keep the client aspect ratio that the window has when the user starts to resize it
SetLowLatencyMode Sets the low latency mode. The change applies on the next frame and does not change the back buffer. While frame generation runs the host uses at least MGDF_LOW_LATENCY_ON
BOOL SetLowLatencyMode ( MGDFLowLatencyMode mode )

Parameters

mode The low latency mode

Returns

False if IMGDFRenderSettingsManager::GetLowLatencyMode does not list the mode
SetFrameGeneration Sets the number of generated frames per rendered frame. A change schedules a back buffer change because the host must make a new swap chain
BOOL SetFrameGeneration ( UINT32 generatedFrames )

Parameters

generatedFrames 0 for no frame generation, otherwise 1 to IMGDFRenderSettingsManager::GetMaxGeneratedFrames

Returns

False if the value is more than the device supports
SetRayTracing Sets whether the module uses ray tracing. The host saves the value in the host.rayTracing preference and does nothing else with it. The change does not change the back buffer
BOOL SetRayTracing ( BOOL enabled )

Parameters

enabled TRUE to use ray tracing

Returns

False if enabled is TRUE and IMGDFRenderSettingsManager::GetRayTracingSupport returns FALSE
SetVR Requests headset output and saves the value in host.vr. Applying the change schedules RTBeforeBackBufferChange and RTBackBufferChange. A device change can also require RTBeforeDeviceReset and RTDeviceReset. A missing headset or a runtime failure leaves the window running. Check GetVR for the session state
BOOL SetVR ( BOOL enabled )

Parameters

enabled TRUE to request VR, FALSE to return to the window

Returns

TRUE when accepted; FALSE if GetVRSupport returns FALSE

IMGDFPerformanceCounter A names performance counter that can be used to time the duration of events. The results of these counters are part of the debug overlay snapshot

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. The module executes its command lists on the direct queue during RTDraw and may submit background work during RTAfterPresent. The host resolves GPU counters and signals the frame fence after RTAfterPresent. Join compute and copy work to the direct queue if the frame fence must cover it.

Inherits from: IMGDFCommonHost

GetBackBufferInfo Gets the current back buffer properties
void GetBackBufferInfo ( MGDFBackBufferInfo * info )

Parameters

info The back buffer properties to populate
SetHDRMetadata Sets the HDR content metadata. The host keeps it and applies it to each HDR10 swap chain (MGDF_HDR_FORMAT_HDR10 with HDR output on). Other swap chains get no metadata
HRESULT SetHDRMetadata ( const MGDFHDRMetadata * metadata )

Parameters

metadata The metadata, or null to clear it

Returns

S_OK, or E_INVALIDARG if a value is out of range
GetVRFrame Gets VR data on the render thread. Draw the window every frame. In RTDraw, S_OK provides two eyes and poses at this frame's predicted display time. Outside an eye frame, including RTBackBufferChange, S_FALSE provides target properties, focus, mask revision and feature flags; EyeCount is zero and poses and FOV angles are zero. Use Eyes to size resources at a back buffer change. Check pose validity and Features before using optional data
HRESULT GetVRFrame ( MGDFVRFrame * frame )

Parameters

frame Receives this frame's VR data; zero on error

Returns

S_OK with an eye frame; S_FALSE with a session but no eye frame; E_INVALIDARG for null output; E_ILLEGAL_METHOD_CALL without a session or on the wrong thread; E_FAIL after a runtime failure. Output is zero on error
GetVREyeMask Gets the hidden triangle mesh for eye 0 or 1 on the render thread. Counts are vertex and index capacities on input and required counts on output. Null buffers query counts; xy has two floats per vertex, indices are a UINT32 triangle list. Winding is counter-clockwise in x-right, y-up coordinates. Vertices are view-angle tangents at z=+1. Map to your projection with ndc.x = (2*x - (tan(AngleRight) + tan(AngleLeft))) / (tan(AngleRight) - tan(AngleLeft)); use up/down in the same way for y.
HRESULT GetVREyeMask ( UINT32 index , UINT32 * vertexCount , FLOAT * xy , UINT32 * indexCount , UINT32 * indices )

Parameters

index Eye index, 0 or 1

vertexCount Vertex capacity on input and required vertex count on output

xy Two floats per vertex; null to query the count

indexCount Index capacity on input and required index count on output

indices Triangle indices; null to query the count

Returns

S_OK; S_FALSE for an empty mesh; E_NOTIMPL without mask support; E_INVALIDARG for invalid index, null counts or insufficient buffer capacity (required counts are still returned); E_ILLEGAL_METHOD_CALL without a session or on the wrong thread; E_FAIL on runtime failure. Counts are zero on error except for insufficient capacity
SetVREyeDepthRange Enables reprojection depth for this eye in this RTDraw. Call for both eyes after writing their depth targets; otherwise no depth is submitted this frame. nearZ and farZ are positive distances in metres at depth values 0 and 1. For reverse-Z pass the distant plane as nearZ and the close plane as farZ. Positive infinity is allowed for either plane, but the two must differ.
HRESULT SetVREyeDepthRange ( UINT32 index , FLOAT nearZ , FLOAT farZ )

Parameters

index Eye index, 0 or 1

nearZ Positive distance in metres at depth value 0

farZ Positive distance in metres at depth value 1; must differ from nearZ

Returns

S_OK; E_NOTIMPL without depth support; E_INVALIDARG for an invalid index or range; E_ILLEGAL_METHOD_CALL without a session, outside an eye frame or on the wrong thread; E_FAIL on runtime failure
SetVRPanel Shows one panel. The host copies the description. Changes apply next eye frame; null hides it immediately. Resizing invalidates old panel targets at the next RTDraw: release their references and descriptors by this RTAfterPresent. Release them also in RTBeforeBackBufferChange. Color is premultiplied alpha.
HRESULT SetVRPanel ( const MGDFVRPanel * panel )

Parameters

panel Panel size, pose and space; null hides the panel

Returns

S_OK; E_NOTIMPL if the runtime cannot show a panel; E_INVALIDARG for an invalid size, space or pose; E_ILLEGAL_METHOD_CALL without a session or on the wrong thread; E_FAIL on runtime failure. Deferred creation errors are reported by GetVRPanelTarget
GetVREyeTarget Gets an owned reference to this frame's eye texture during RTDraw. Its state is RENDER_TARGET. Leave it in that state when the frame's lists finish. Execute eye work on the direct queue before RTDraw returns; join work from other queues to it. The host records no work on the texture. Textures rotate until RTBeforeBackBufferChange; descriptors can be kept by resource until then
HRESULT GetVREyeTarget ( UINT32 index , ID3D12Resource ** target )

Parameters

index Less than MGDFVRFrame::EyeCount

target Receives the texture; release all references before a change

Returns

S_OK; E_INVALIDARG for an invalid index or null output; E_ILLEGAL_METHOD_CALL without a session, outside an eye frame or on the wrong thread; E_FAIL after a runtime failure. The output is null on error
GetVREyeDepthTarget Gets an owned reference to eye 0 or 1's depth image for this RTDraw. Size matches the eye target; use MGDFVREye::DepthFormat for a depth view. Release references and descriptors in RTBeforeBackBufferChange. The state is DEPTH_WRITE; leave it in that state. Submit work on the direct queue before RTDraw returns.
HRESULT GetVREyeDepthTarget ( UINT32 index , ID3D12Resource ** target )

Parameters

index Eye index, 0 or 1

target Receives an owned depth image reference; null on error

Returns

S_OK; E_NOTIMPL without depth support; E_INVALIDARG for an invalid index or null output; E_ILLEGAL_METHOD_CALL without a session, outside an eye frame or on the wrong thread; E_FAIL on runtime or resource failure. The output is null on error
GetVRPanelTarget Gets an owned reference to this frame's panel image during RTDraw. Write premultiplied alpha in MGDFVREye::Format. Release references and descriptors before a panel size change takes effect and in RTBeforeBackBufferChange. The state is RENDER_TARGET; leave it in that state. Submit work on the direct queue.
HRESULT GetVRPanelTarget ( ID3D12Resource ** target )

Parameters

target Receives an owned panel image reference; null except on S_OK

Returns

S_OK; S_FALSE while hidden or before the first panel frame; E_NOTIMPL without panel support; E_INVALIDARG for a null output; E_ILLEGAL_METHOD_CALL without a session, outside an eye frame or on the wrong thread; E_FAIL on runtime or resource failure. The output is null except on S_OK
GetCurrentFrame Gets the current frame. Its ordinal and slot stay fixed through RTAfterPresent
void GetCurrentFrame ( MGDFFrameInfo * frame )

Parameters

frame Receives the current frame
GetFrameFence Gets an owned reference to the host's frame fence. Modules must not signal it
void GetFrameFence ( ID3D12Fence ** fence )

Parameters

fence Points to the frame fence
CreateGPUCounter Creates a GPU timestamp counter bound to a direct-queue command list. Each scope must begin and end while recording and its list must execute in the same frame, before RTAfterPresent returns. Release each scope before closing its list. Use the SDK MGDF::D3D12CommandList helper for Close/Reset tracking; an untracked list returns E_INVALIDARG. A scope released after Close/Reset or the end of its frame is logged and discarded without recording a timestamp. Compute/copy lists are unsupported and return E_INVALIDARG.
HRESULT CreateGPUCounter ( IMGDFMetric * metric , ID3D12GraphicsCommandList * list , IMGDFPerformanceCounter ** counter )

Parameters

metric The metric the counter updates

list The direct-queue command list the counter scopes record into

counter Points to the created counter

Returns

S_OK if the counter could be created, otherwise an error code
SetFrameMarker Reports a point in the current frame for latency measurement. Does nothing while VR is on or if the host has no latency measurement for the device
void SetFrameMarker ( MGDFFrameMarker marker )

Parameters

marker The point in the frame
SetFrameConstants Sets the camera data for View 0 or 1, with or without VR. Call it once per used view per frame before Upscale and before RTDraw returns. Each view has separate history; either view may be omitted from a frame. Does nothing if GetUpscaleModeCount and GetMaxGeneratedFrames on IMGDFRenderSettingsManager both return 0
void SetFrameConstants ( const MGDFFrameConstants * constants )

Parameters

constants The camera data
Upscale Records an upscale of the current frame into a direct-queue command list. The list must be recording and tracked by the SDK MGDF::D3D12CommandList helper. After the call the descriptor heaps, root signatures, pipeline state, render targets and viewports of the list are undefined; set them again before more work. Resource states do not change. View must be 0 or 1, with or without VR
HRESULT Upscale ( ID3D12GraphicsCommandList * list , const MGDFUpscaleDesc * desc )

Parameters

list The command list

desc The upscale inputs

Returns

S_OK, E_INVALIDARG for an untracked list, missing inputs or invalid View, E_ILLEGAL_METHOD_CALL if SetFrameConstants was not called for this View this frame, E_NOTIMPL if IMGDFRenderSettingsManager::GetUpscaleMode does not list the mode, or E_FAIL if the upscaler failed
SetFrameGenerationInputs Sets the frame generation inputs for the current frame. Call it before RTDraw returns in each frame that frame generation can use. A frame without inputs, or a null desc, pauses frame generation for that frame: use this for loading, pause and world changes
HRESULT SetFrameGenerationInputs ( const MGDFFrameGenerationDesc * desc )

Parameters

desc The inputs, or null to pause frame generation

Returns

S_OK, S_FALSE if frame generation is off, or E_INVALIDARG if Depth or MotionVectors is missing

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. The MGDFGraphicsRequirements::HDRFormat of the module selects it
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
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
GetWindowAspectLock Gets whether the window keeps its client aspect ratio while the user resizes it (see IMGDFPendingRenderSettingsChange SetWindowAspectLock)
BOOL GetWindowAspectLock ( )

Returns

TRUE if the window keeps its client aspect ratio during user resizing
GetWindowResizeEnabled Gets whether the user can resize the window in windowed mode. This value comes from the host.windowResize preference
BOOL GetWindowResizeEnabled ( )

Returns

TRUE if the user can resize the window
GetWindowSizeLimits Gets the largest client size that fits in the work area of the primary display, after the space for the window frame is removed
BOOL GetWindowSizeLimits ( UINT32 * width , UINT32 * height )

Parameters

width Receives the maximum client width in pixels

height Receives the maximum client height in pixels

Returns

FALSE if width or height is null or the work area cannot be read, TRUE otherwise
GetUpscaleModeCount Get the number of upscale modes the device supports. The list is valid from RTBeforeFirstDraw and can change after a device reset. It is empty with when the device has no upscaler
UINT64 GetUpscaleModeCount ( )

Returns

The number of supported upscale modes
GetUpscaleMode Get a supported upscale mode at the given index (0 to GetUpscaleModeCount() - 1). Use the mode with IMGDFCommonHost::GetUpscaleRenderSize and IMGDFRenderHost::Upscale
BOOL GetUpscaleMode ( UINT64 index , MGDFUpscaleMode * mode )

Parameters

index The upscale mode index

mode Receives the upscale mode at the given index

Returns

True if an upscale mode exists at the given index
GetMaxGeneratedFrames Get the largest number of generated frames per rendered frame that the device supports. Valid from RTBeforeFirstDraw; can change after a device reset
UINT32 GetMaxGeneratedFrames ( )

Returns

The largest number of generated frames, or 0 if frame generation is not supported
GetLowLatencyModeCount Get the number of low latency modes the device supports. The list always contains MGDF_LOW_LATENCY_OFF. Valid from RTBeforeFirstDraw; can change after a device reset
UINT64 GetLowLatencyModeCount ( )

Returns

The number of supported low latency modes
GetLowLatencyMode Get a supported low latency mode at the given index (0 to GetLowLatencyModeCount() - 1)
BOOL GetLowLatencyMode ( UINT64 index , MGDFLowLatencyMode * mode )

Parameters

index The low latency mode index

mode Receives the low latency mode at the given index

Returns

True if a low latency mode exists at the given index
GetCurrentLowLatencyMode Gets the low latency mode the user selected
MGDFLowLatencyMode GetCurrentLowLatencyMode ( )

Returns

The low latency mode
GetFrameGeneration Gets the number of generated frames per rendered frame the user selected
UINT32 GetFrameGeneration ( )

Returns

The number of generated frames, 0 if frame generation is off
GetRayTracingSupport Gets whether the device supports ray tracing: D3D12 raytracing tier 1.1 or higher and shader model 6.9 or higher (for HitObject and MaybeReorderThread). Valid from RTBeforeFirstDraw; can change after a device reset
BOOL GetRayTracingSupport ( MGDFRayTracingSupport * support )

Parameters

support If not null, receives the ray tracing properties. All fields are FALSE when ray tracing is not supported

Returns

TRUE if ray tracing is supported
GetRayTracing Gets whether the user selected ray tracing. Always FALSE while GetRayTracingSupport returns FALSE. The default is TRUE when ray tracing is supported
BOOL GetRayTracing ( )

Returns

TRUE if the module should use ray tracing
GetVRSupport Reports whether the module supports VR and an active OpenXR runtime is available for its graphics API. This query does not start a headset session
BOOL GetVRSupport ( )

Returns

TRUE if VR can be requested; a connected headset is not required
GetVR Reports whether VR mode has a headset session. Stays TRUE while the runtime pauses the session; draw only the window while GetVRFrame reports EyeCount zero. A failed VR request leaves this FALSE
BOOL GetVR ( )

Returns

TRUE while VR mode is active, including an idle headset session

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

IMGDFVRController One VR controller on the sim thread. Objects stay valid for the input manager's lifetime, including VR off and session changes. Without focus or connection, buttons are up, analog values are zero, profile is NONE and poses are invalid. Calls are safe with no session. Missing controls are zero or FALSE

Inherits from: IUnknown

GetHand Gets the hand assigned to this object
MGDFVRHand GetHand ( )

Returns

The left or right hand assigned to this object
IsConnected TRUE when connected with headset input focus
BOOL IsConnected ( )

Returns

TRUE when connected with headset input focus; otherwise FALSE
GetProfile Gets the current interaction profile, or NONE when disconnected
MGDFVRControllerProfile GetProfile ( )

Returns

The current profile, or MGDF_VR_PROFILE_NONE when disconnected
IsButtonDown TRUE while the button is held
BOOL IsButtonDown ( MGDFVRButton button )

Parameters

button The button to read

Returns

TRUE while the button is held; otherwise FALSE
IsButtonUp TRUE while the button is not held, including when disconnected
BOOL IsButtonUp ( MGDFVRButton button )

Parameters

button The button to read

Returns

TRUE while the button is up, including when disconnected
IsButtonPress TRUE once after a button was pressed and released, like IMGDFGamepad. Presses observed between sim updates are kept for the next update
BOOL IsButtonPress ( MGDFVRButton button )

Parameters

button The button to read

Returns

TRUE once after the button is pressed and released; otherwise FALSE
IsTouched TRUE while the named control is touched
BOOL IsTouched ( MGDFVRTouch touch )

Parameters

touch The touch control to read

Returns

TRUE while the control is touched; otherwise FALSE
GetTrigger Trigger level, 0..1
FLOAT GetTrigger ( )

Returns

Trigger level from 0 to 1; zero when unavailable
GetSqueeze Grip squeeze level, 0..1
FLOAT GetSqueeze ( )

Returns

Squeeze level from 0 to 1; zero when unavailable
GetThumbX Thumbstick or Vive trackpad X, -1..1; positive is right
FLOAT GetThumbX ( )

Returns

Thumbstick or trackpad X from -1 to 1; positive is right
GetThumbY Thumbstick or Vive trackpad Y, -1..1; positive is up. This differs from the IMGDFGamepad Y convention
FLOAT GetThumbY ( )

Returns

Thumbstick or trackpad Y from -1 to 1; positive is up
GetGripPose Gets the sim sample's LOCAL grip pose; invalid components are zero. A null output is ignored
void GetGripPose ( MGDFVRPose * pose )

Parameters

pose Receives the current sim sample grip pose; null is ignored
GetAimPose Gets the sim sample's LOCAL aim pose; invalid components are zero. A null output is ignored
void GetAimPose ( MGDFVRPose * pose )

Parameters

pose Receives the current sim sample aim pose; null is ignored
SetVibration Sets vibration level until changed; 0 stops. Values are clamped to 0..1; NaN means 0. Output stops without focus, connection or a session, and resumes at the stored level when these return. Safe with VR off
void SetVibration ( FLOAT amplitude )

Parameters

amplitude Vibration level from 0 to 1; zero stops output

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

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

MGDFBackBufferInfo The current back buffer properties, independent of the graphics API

Width
UINT32 Width
Height
UINT32 Height
Format
DXGI_FORMAT Format
SampleCount
UINT32 SampleCount

MGDFDebugCounter A performance counter as the debug overlay shows it

Name
const small * Name
GPU
BOOL GPU
Timing
MGDFDebugTiming Timing

MGDFDebugEntry One key/value a module set through IMGDFDebug::Set

Section
const small * Section
Key
const small * Key
Value
const small * Value

MGDFDebugOverlayData Everything the debug overlay shows. HasTimings is FALSE before the host has frame timings to report. Every pointer stays valid for the lifetime of the IMGDFDebugOverlaySnapshot that returned the struct

Version
const small * Version
InterfaceVersion
INT32 InterfaceVersion
HasTimings
BOOL HasTimings
ExpectedSimTime
double ExpectedSimTime
RenderTime
MGDFDebugTiming RenderTime
ActiveRenderTime
MGDFDebugTiming ActiveRenderTime
SimTime
MGDFDebugTiming SimTime
ActiveSimTime
MGDFDebugTiming ActiveSimTime
SimInputTime
MGDFDebugTiming SimInputTime
SimAudioTime
MGDFDebugTiming SimAudioTime
Counters
const MGDFDebugCounter * Counters
CounterCount
UINT64 CounterCount
Entries
const MGDFDebugEntry * Entries
EntryCount
UINT64 EntryCount
HasLatency TRUE when the driver reports low latency figures
BOOL HasLatency
RenderLatency Seconds from SIMULATION_START to the end of GPU work for the latest frame the driver reported
double RenderLatency
RenderedFrames Frames the module rendered since the device was created
UINT64 RenderedFrames
PresentedFrames Frames sent to the display since the device was created. More than RenderedFrames while frame generation runs
UINT64 PresentedFrames

MGDFDebugTiming An average with its per frame history behind it, in seconds. Samples run newest first and belong to the IMGDFDebugOverlaySnapshot they came from

Average
double Average
Samples
const double * Samples
SampleCount
UINT64 SampleCount

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

MGDFFrameConstants Camera data for upscaling and frame generation. Matrices are row-major (row vectors, v * M) and do not contain the jitter offset

ViewToClip View space to clip space
FLOAT[16] ViewToClip
ClipToView Clip space to view space
FLOAT[16] ClipToView
ClipToPreviousClip Current clip space to previous frame clip space
FLOAT[16] ClipToPreviousClip
PreviousClipToClip Previous frame clip space to current clip space
FLOAT[16] PreviousClipToClip
JitterOffset Jitter offset in render pixels
FLOAT[2] JitterOffset
MotionVectorScale Scale that converts motion vector values to the -1 to 1 range
FLOAT[2] MotionVectorScale
CameraPosition Camera position in world space
FLOAT[3] CameraPosition
CameraUp Camera basis vectors in world space; they must be orthonormal
FLOAT[3] CameraUp
CameraRight
FLOAT[3] CameraRight
CameraForward
FLOAT[3] CameraForward
Near
FLOAT Near
Far
FLOAT Far
VerticalFOV Vertical field of view in radians
FLOAT VerticalFOV
AspectRatio View width divided by view height
FLOAT AspectRatio
DepthInverted TRUE if depth values closer to the camera are higher
BOOL DepthInverted
MotionVectorsJittered TRUE if motion vectors contain the jitter
BOOL MotionVectorsJittered
MotionVectorsDilated TRUE if motion vectors are already dilated
BOOL MotionVectorsDilated
CameraMotionIncluded TRUE if motion vectors contain camera motion
BOOL CameraMotionIncluded
ResetHistory TRUE if this frame has no relation to the previous frame
BOOL ResetHistory
View View index, 0 or 1, with or without VR. Each view has its own history
UINT32 View

MGDFFrameGenerationDesc Inputs for frame generation. Each resource must keep its content and State until the frame is presented. The default region of Depth and MotionVectors is the full resource. HudlessColor and UIColorAndAlpha are optional, but give much better results with UI. They must have the back buffer size. UIColorAndAlpha has premultiplied color and zero alpha where there is no UI. Frame generation needs an SDR or MGDF_HDR_FORMAT_HDR10 back buffer

Depth
MGDFFrameResource Depth
MotionVectors
MGDFFrameResource MotionVectors
HudlessColor The final scene color without UI, in the back buffer color space and encoding (PQ with HDR10)
MGDFFrameResource HudlessColor
UIColorAndAlpha In the back buffer encoding: back buffer = UI.rgb + (1 - UI.a) * hudless. The alpha needs more than 2 bits, so do not use DXGI_FORMAT_R10G10B10A2_UNORM
MGDFFrameResource UIColorAndAlpha

MGDFFrameInfo The current D3D12 frame. BackBuffer is borrowed until RTBeforeBackBufferChange; release any additional references in that callback. It enters RTDraw in PRESENT state. Every module command list touching it must leave it in PRESENT state.

FrameOrdinal Frame fence value the host signals after this frame's RTAfterPresent
UINT64 FrameOrdinal
CompletedOrdinal Highest completed frame fence value
UINT64 CompletedOrdinal
FrameSlot FrameOrdinal modulo FramesInFlight; safe to reuse on entry to RTDraw
UINT32 FrameSlot
FramesInFlight
UINT32 FramesInFlight
BackBufferIndex
UINT32 BackBufferIndex
BackBuffer
ID3D12Resource * BackBuffer
BackBufferRTV
D3D12_CPU_DESCRIPTOR_HANDLE BackBufferRTV
BackBufferDesc
D3D12_RESOURCE_DESC BackBufferDesc

MGDFFrameResource A texture the host gives to the upscaler or to frame generation. State is the state the resource has when the GPU runs the work that uses it. The host does not change resource states. A zero Width or Height selects the default region

Resource
ID3D12Resource * Resource
State
D3D12_RESOURCE_STATES State
Left
UINT32 Left
Top
UINT32 Top
Width
UINT32 Width
Height
UINT32 Height

MGDFFullScreenDesc The current fullscreen options

FullScreen
BOOL FullScreen
ExclusiveMode
BOOL ExclusiveMode

MGDFGraphicsRequirements The graphics requirements returned by the module's GetGraphicsRequirements export

MinFeatureLevel
D3D_FEATURE_LEVEL MinFeatureLevel
MinShaderModel Minimum D3D_SHADER_MODEL value
UINT32 MinShaderModel
HDRFormat The HDR output format the module writes. The host selects the HDR back buffer format and color space from it. An unknown value is an error
MGDFHDRFormat HDRFormat
VR TRUE if the module renders headset views. FALSE makes VR unavailable
BOOL VR

MGDFHDRMetadata HDR10 content metadata, in nits. The host reports Rec.709 primaries and a D65 white point, because the content of both HDR formats stays inside Rec.709

MaxContentLightLevel Maximum content light level (MaxCLL), 0 to 65535
FLOAT MaxContentLightLevel
MaxFrameAverageLightLevel Maximum frame-average light level (MaxFALL), 0 to MaxContentLightLevel
FLOAT MaxFrameAverageLightLevel
MaxMasteringLuminance Mastering display maximum luminance, more than 0 and up to 10000
FLOAT MaxMasteringLuminance
MinMasteringLuminance Mastering display minimum luminance, 0 or more and less than the maximum
FLOAT MinMasteringLuminance

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

MGDFRayTracingSupport Ray tracing properties of the device

ShaderExecutionReordering TRUE when shader execution reordering does real work (D3D12 raytracing tier 1.2 or higher). Without it MaybeReorderThread does nothing
BOOL ShaderExecutionReordering

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

MGDFUpscaleDesc Inputs for IMGDFRenderHost::Upscale. The default region of ColorIn, Depth, MotionVectors and BiasCurrentColor is RenderWidth x RenderHeight at the origin. The default region of ColorOut is OutputWidth x OutputHeight at the origin. Exposure and BiasCurrentColor are optional (null Resource)

Mode
MGDFUpscaleMode Mode
RenderWidth
UINT32 RenderWidth
RenderHeight
UINT32 RenderHeight
OutputWidth
UINT32 OutputWidth
OutputHeight
UINT32 OutputHeight
ColorHDR TRUE if the color input is linear HDR, FALSE if it is tonemapped
BOOL ColorHDR
ColorIn Jittered color at render size
MGDFFrameResource ColorIn
ColorOut Upscaled color at output size. Needs unordered access
MGDFFrameResource ColorOut
Depth
MGDFFrameResource Depth
MotionVectors
MGDFFrameResource MotionVectors
Exposure 1x1 exposure texture. Without it the upscaler uses automatic exposure
MGDFFrameResource Exposure
BiasCurrentColor 0 to 1 per pixel: 1 rejects the history and uses the current color
MGDFFrameResource BiasCurrentColor
View View index, 0 or 1, with or without VR. Each view has its own history
UINT32 View

MGDFUpscaleRenderSize The render size for an upscale mode and output size. The Min and Max fields give the range for dynamic resolution. They equal Width and Height if the upscaler gives no range

Width
UINT32 Width
Height
UINT32 Height
MinWidth
UINT32 MinWidth
MinHeight
UINT32 MinHeight
MaxWidth
UINT32 MaxWidth
MaxHeight
UINT32 MaxHeight

MGDFVersion Represents a version number

Major
INT32 Major
Minor
INT32 Minor
Build
INT32 Build
Revision
INT32 Revision

MGDFVREye One eye at this frame's predicted display time. Pose is in LOCAL space, in metres, with +X right, +Y up and +Z forward. The quaternion order is x, y, z, w. Write linear color to an sRGB target. Release target references and descriptors in RTBeforeBackBufferChange

Position
FLOAT[3] Position
Orientation
FLOAT[4] Orientation
AngleLeft Field of view in radians; left and down are negative
FLOAT AngleLeft
AngleRight
FLOAT AngleRight
AngleUp
FLOAT AngleUp
AngleDown
FLOAT AngleDown
Width
UINT32 Width
Height
UINT32 Height
Format
DXGI_FORMAT Format
DepthFormat UNKNOWN when reprojection depth is unavailable
DXGI_FORMAT DepthFormat

MGDFVRFrame VR data for one display frame. Eye 0 is left and eye 1 is right. Index Grip and Aim with MGDFVRHand. Poses use LOCAL space and the MGDFVRPose convention. Pose and FOV data are valid only during RTDraw with EyeCount 2; otherwise they are zero. Unsupported or untracked controller and gaze poses are invalid

EyeCount
UINT32 EyeCount
Focused
BOOL Focused
Eyes
MGDFVREye[2] Eyes
Grip
MGDFVRPose[2] Grip
Aim
MGDFVRPose[2] Aim
Gaze
MGDFVRPose Gaze
MaskVersion Reload masks when this changes, including after session or eye target recreation. Zero without mask support
UINT64 MaskVersion
PoseEpoch Reset temporal history when this counter changes. It advances when a session starts and on the first frame at or after a LOCAL or floor space change time, including frames with no eye output. Compare with the last rendered frame
UINT64 PoseEpoch
FloorHeight Floor Y in LOCAL space, in metres. Sampled at the eye display time. Subtract this from a LOCAL head Y to get height above the floor
FLOAT FloorHeight
FloorHeightValid FALSE without STAGE or LOCAL_FLOOR support, or while the floor pose is invalid
BOOL FloorHeightValid
Features Bit set of MGDFVRFeature values
UINT32 Features

MGDFVRPanel One headset panel. Pose uses +X right, +Y up, +Z forward and metres, with quaternion x, y, z, w. VIEW is relative to the head; LOCAL is fixed in the room. The image format is MGDFVREye::Format; write linear color with premultiplied alpha

PixelWidth
UINT32 PixelWidth
PixelHeight
UINT32 PixelHeight
Position
FLOAT[3] Position
Orientation
FLOAT[4] Orientation
Width
FLOAT Width
Height
FLOAT Height
Space
MGDFVRSpace Space

MGDFVRPose Pose in LOCAL space, in metres: +X right, +Y up, +Z forward. Quaternion is x, y, z, w. Check validity separately for position and orientation. Invalid components are zero. Gaze and aim point along the pose's rotated +Z axis

Position
FLOAT[3] Position
Orientation
FLOAT[4] Orientation
PositionValid
BOOL PositionValid
OrientationValid
BOOL OrientationValid

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

WebSocket
IMGDFWebSocket * WebSocket
HttpRequest
IMGDFHttpServerRequest * HttpRequest

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

State
MGDFWebSocketConnectionState State
LastError
small * LastError
LastErrorLength
UINT64 LastErrorLength

MGDFCursor The OS cursor shapes a module can ask for while the cursor is shown

Values: MGDF_CURSOR_ARROW; MGDF_CURSOR_HAND; MGDF_CURSOR_SIZE_NWSE; MGDF_CURSOR_SIZE_NS; MGDF_CURSOR_SIZE_WE; MGDF_CURSOR_SIZE_ALL

MGDFFrameMarker Points in the current frame that the module reports for latency measurement. The host reports the frame start and the present itself

Values: MGDF_FRAME_MARKER_SIMULATION_START The frame starts to use simulation state; MGDF_FRAME_MARKER_SIMULATION_END The frame has the simulation state it needs; MGDF_FRAME_MARKER_RENDER_SUBMIT_START The module starts to record and submit GPU work for the frame; MGDF_FRAME_MARKER_RENDER_SUBMIT_END The module has submitted all GPU work for the frame; MGDF_FRAME_MARKER_INPUT_SAMPLE The module read controller input for the frame

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

MGDFHDRFormat The back buffer format and color space the host uses while HDR output is on. SDR output does not change

Values: MGDF_HDR_FORMAT_SCRGB scRGB: DXGI_FORMAT_R16G16B16A16_FLOAT, DXGI_COLOR_SPACE_RGB_FULL_G10_NONE_P709. Linear Rec.709 primaries, 1.0 is 80 nits. Frame generation is not available; MGDF_HDR_FORMAT_HDR10 HDR10: DXGI_FORMAT_R10G10B10A2_UNORM, DXGI_COLOR_SPACE_RGB_FULL_G2084_NONE_P2020. Rec.2020 primaries with ST 2084 (PQ) encoding, 1.0 is 10000 nits. The module writes encoded values, so it must blend in linear light before the encode

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

MGDFLowLatencyMode Low latency modes. Boost also keeps GPU clocks high, which costs power

Values: MGDF_LOW_LATENCY_OFF; MGDF_LOW_LATENCY_ON; MGDF_LOW_LATENCY_BOOST

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

MGDFUpscaleMode Upscale quality modes. DLAA renders at the output size and only does anti-aliasing

Values: MGDF_UPSCALE_MODE_DLAA; MGDF_UPSCALE_MODE_QUALITY; MGDF_UPSCALE_MODE_BALANCED; MGDF_UPSCALE_MODE_PERFORMANCE; MGDF_UPSCALE_MODE_ULTRA_PERFORMANCE

MGDFVRButton VR controller buttons; use MGDFVRTouch for touch state

Values: MGDF_VR_BUTTON_A; MGDF_VR_BUTTON_B; MGDF_VR_BUTTON_X; MGDF_VR_BUTTON_Y; MGDF_VR_BUTTON_STICK; MGDF_VR_BUTTON_MENU; MGDF_VR_BUTTON_TRACKPAD

MGDFVRControllerProfile The current VR controller interaction profile

Values: MGDF_VR_PROFILE_NONE; MGDF_VR_PROFILE_TOUCH; MGDF_VR_PROFILE_INDEX; MGDF_VR_PROFILE_VIVE; MGDF_VR_PROFILE_WMR; MGDF_VR_PROFILE_SIMPLE; MGDF_VR_PROFILE_OTHER

MGDFVRFeature Optional VR features supported by this session. Individual calls can fail

Values: MGDF_VR_FEATURE_MASK; MGDF_VR_FEATURE_DEPTH; MGDF_VR_FEATURE_PANEL; MGDF_VR_FEATURE_GAZE

MGDFVRHand VR hands; other values are invalid

Values: MGDF_VR_HAND_LEFT; MGDF_VR_HAND_RIGHT

MGDFVRSpace Reference frame for a headset panel

Values: MGDF_VR_SPACE_LOCAL; MGDF_VR_SPACE_VIEW

MGDFVRTouch Capacitive touch controls, separate from pressed buttons

Values: MGDF_VR_TOUCH_A; MGDF_VR_TOUCH_B; MGDF_VR_TOUCH_X; MGDF_VR_TOUCH_Y; MGDF_VR_TOUCH_STICK; MGDF_VR_TOUCH_TRIGGER; MGDF_VR_TOUCH_THUMBREST; MGDF_VR_TOUCH_TRACKPAD

MGDFWebSocketConnectionState The state of a websocket connection

Values: MGDF_WEBSOCKET_CONNECTING; MGDF_WEBSOCKET_OPEN; MGDF_WEBSOCKET_CLOSED

Configuration Options

Command line options and tools

Running core.exe from command line

Running GamesManager.exe from command line

PackageGen.exe

Example output

Game.json configuration

Game.json schema

Built in host preferences

Game update manifest

Game update manifest schema

Statistics service

Request fields

Response fields

Crash reporting service

Request fields

Response fields

Functions

GetGraphicsRequirements Declares the module's D3D12 graphics requirements. The host reads these requirements before it creates the module.

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

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

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

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

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. Release device and queue references before acknowledging a device reset

Inherits from: IMGDFLogger

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

GetRenderSettings Get the render settings manager

GetTimer Get the host timer

GetMGDFVersion Gets the current version of the framework

GetVFS Get the readonly content filesystem

GetWorkingVFS Get the read/write working folder

GetDebug Get the debug overlay data and visibility interface

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

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

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

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

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

GetD3D12Device Gets an owned reference to the device, or null during device reset

GetDirectQueue Gets an owned reference to the direct queue

GetComputeQueue Gets an owned reference to the compute queue

GetCopyQueue Gets an owned reference to the copy queue

GetUpscaleRenderSize Gets the render size for an upscale mode and output size

IMGDFDebug Debug overlay data. The host draws no overlay: a module that wants one draws it from GetOverlaySnapshot and decides itself when to show it

Inherits from: IUnknown

Set Set some data to display in the overlay

Clear Clear some data out of the overlay

GetOverlaySnapshot Copies the overlay data into a snapshot for the module to draw

IMGDFDebugOverlaySnapshot An immutable copy of the debug overlay data taken by IMGDFDebug::GetOverlaySnapshot. Release it when done with the data

Inherits from: IUnknown

GetData The copied overlay data

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

IsFolder Determines if the file entity is a folder

IsOpen Determines 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.

GetLastWriteTime Find the last write time of the file

GetPhysicalName Gets the physical name of this file on disk

GetPhysicalPath Gets the physical path to this file

GetLogicalName Gets the logical name of this file

GetLogicalPath Gets the logical path to this file

IMGDFFileReader Provides an interface for reading data from a file

Inherits from: IUnknown

Read Reads the specified number of bytes into the buffer

SetPosition Sets the read position of the file in bytes

GetPosition Get the current read position of the file in bytes

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

GetSize Get the size of the file in bytes

IMGDFFileWriter Provides an interface for writing data to a file

Inherits from: IUnknown

Write Writes the specified number of bytes into the buffer

SetPosition Sets the write position of the file in bytes

GetPosition Get the current write position of the file in bytes

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

GetUid Get the uid of the current game running