API for dgVoodoo Version 2.8

API for dgVoodoo Version 2.8

This document contains information for 2 separate components available for use:

  • API Library
  • Addon interfaces

API Library is an external library that you can link to your application to get access to similar functionality that dgVoodoo CPL is also based on.

Addon interfaces provides the possibility to hook and modify certain events and functionality of dgVoodoo graphics API dll's from a third party component.


Addon interfaces for dgVoodoo Version 2.8

Addon interfaces for dgVoodoo Version 2.8

This version is very initial (and experimental) and provides the possibility for hooking the following components:

  • D3D12 Image presentation


Overview

dgVoodoo Addon documentation
Overview

Addons Overview

This section contains a short overview for Addons.

dgVoodoo graphics dll's can load third party dll's and call into them providing callback interfaces for interaction and registration for hooking certain type of events. As of writing this document the only notable implemented hookable event is the graphics image presentation. dgVoodoo provides this hook for modifying an image texture right before it goes through the final post-processing and get presented into the rendering window. This is the only hook type I include documentation for, in this document.

Of course I know this is what ReShade and other softwares drawing overlays over the original images are for, and it is not intended to replace them.

The reason I provide the ability for this hook is the fact that this way the custom image 'reshader' (or upscaler) can work with the non-postprocessed original image coming from a graphics API. No black bars and upscaled images to begin with when the image scaling is done on dgVoodoo's own. Maybe an enterprising person could implement SSAA or some other very fancy antialiasing algorithm replacing built-in MSAA which is often a missed functionality in dgVoodoo.

You can found an implemented sample addon amongst the samples (D3D12 Addon) which recolors the image into a sepia color and applies a transparent dirty glass image to give the output a withered looking.

Since I do not expect a significant interest for this in the beginning, to say the least, I only implemented the hook functionality for the D3D12 backend for the time being. D3D12 can be scary, not an easy API, but you don't have to worry: dgVoodoo publishes some parts of its internal D3D12 infrastructure to make things much more easier than coding from scatch. You do not have to use it however, and you can still write your own code for D3D12, there is only one mandatory rule: you have to record your commands into a command list coming from dgVoodoo (see the details in the proper section).

Overview topics:

  • Initializing and shutting down the library
  • D3D12 backend overview


Addon initialization and shutdown

Addon initialization and shutdown

As of writing this document, dgVoodoo only searches for a dll named 'SampleAddon.dll' and tries to call into it if the needed entry points are found.

  • Your addon need to export a function named AddonInit to provide dgVoodoo an initialization entry point.
    dgVoodoo will load your addon dll and call into this function each time dgVoodoo is being activated by initializing a graphics API.

    This function is mandatory - if not found then your dll will simply be ignored.

  • Your addon also need to export a function named AddonExit to provide dgVoodoo a shutdown entry point.
    dgVoodoo will call this function when it is being completely deactivated by shutting down the last active graphics API.

    This function is mandatory - if not found then your dll will simply be ignored.


D3D12 backend and infrastructure overview

D3D12 backend and infrastructure overview

The very base object in dgVoodoo's D3D12 infrastructure is D3D12Root. This is an object instance that is singleton and shared across the graphics API dll's. This object is created when the first graphics API is initialized in some of the graphics API dll's and released when the last graphics API is shut down. So, if multiple graphics API's are active in certain cases, like DirectDraw and Glide (DD for the menu and Glide for the 3D gameplay) or DirectDraw and Direct3D8 (Direct3D8 for the game itself and DirectDraw for movie playback through DirectShow), then D3D12Root is created when the first API in the row is initialized. All other subsequent graphics API initialization simply gets and uses the existing D3D12Root instance in a shared manner.

If an addon registers for observing D3D12Root (IAddonMainCallback::RegisterForCallback with IID_D3D12RootObserver) then dgVoodoo calls into the addon both when D3D12Root is created and about to be released. At those points the addon can create and release its own non-D3D12 related global objects needed for its later rendering operations. See callback methods ID3D12RootObserver::D3D12RootCreated and ID3D12RootObserver::D3D12RootReleased.

D3D12 adapters

dgVoodoo is capable of handling multiple GPU's at the same time. An adapter is a GPU with one or more display outputs attached. The available adapters are enlisted internally when D3D12Root is created. Depending on the frontend graphics API's each of the adapters can be initialized for usage with a given graphics API and also released later when no any API is using them. Each available adapter has an ID which is a plain integer, called adapterID. When initializing an adapter for usage then dgVoodoo creates the needed D3D12 objects for that adapter internally and calls into the addon interface ID3D12RootObserver::D3D12BeginUsingAdapter and also, it calls into ID3D12RootObserver::D3D12EndUsingAdapter and releases its internal objects respectively when the adapter is released. In those callbacks the addon gets the adapterID and it can also create/release its own objects on a per-adapter base. At the latest, all D3D12 objects and resources related to a given adapter has to be released when D3D12EndUsingAdapter is called.

D3D12 swapchains

D3D12 swapchains are image containers whose contents can be presented into a rendering window either in windowed or fullscreen mode. Each swapchain is tied to an adapter. All of the D3D12 resources a swapchain owns and uses must be factored on the given adapter. When a swapchain is created, modified or released then dgVoodoo calls into the addon interface ID3D12RootObserver::D3D12SwapchainCreated, ID3D12RootObserver::D3D12SwapchainChanged and ID3D12RootObserver::D3D12SwapchainReleased respectively. The callbacks only get the size and the pixel format of the swapchain but of course it has much more properties internally. The Change callback will be called even when size and format remains unchanged but some other property like refresh rate changes.
In those callbacks the addon can create, modify (re-create) and release its own objects on a per-swapchain basis.
dgVoodoo also calls into the callback interface method ID3D12RootObserver::D3D12SwapchainPresentBegin when an image coming from any of the frontend graphics API's is about to be presented, to let the addon do its own rendering and change the input for the D3D12 backend presenter. An addon cannot override the behavior of dgVoodoo's presenting algorithm: pixel multiplication, color adjustments and the likes are still applied. Only the presentation process input can be changed. When the swapchain has the postprocess source image drawn into it then the D3D12 backend presenter calls ID3D12RootObserver::D3D12SwapchainPresentEnd to give a final chance to the addon to draw additional overlay-like data into the swapchain, right before the actual presentation.

D3D12 rendering

There are 2 main rules that apply here:
  • dgVoodoo won't force the addon to use its internal D3D12 infrastructure but in any case makes it available partially, in a simplified form. The addon can get the ID3D12Device interface pointer for a given adapter and do its own resource allocation, resource management and tracking, and so on.
  • In the presentation callback the addon have to record its commands into dgVoodoo's graphics command list associated with the given adapter. This command list provides the standard ID3D12GraphicsCommandList interface pointer but the command list object implementation is a so called auto-flush type command list. For more, see below.

dgVoodoo D3D12 infrastructure

dgVoodoo publishes some parts of its internal D3D12 infrastructure to make coding for D3D12 much easier than it'd be from scratch. Again, an addon is not obligated to use it except the auto command list, see right below.

ID3D12GraphicsCommandListAuto

This is the only interface the addon must use from dgVoodoo's D3D12 infrastructure. Auto command list is inherited from the standard ID3D12GraphicsCommandList (see related D3D12 documents) but extends its functionality. The most important ones are:
  • An auto command list automatically flushes the recorded command list through an internally associated command queue and updates an internal fence with the current internal fence value when the execution of the command list is finished on the GPU. Therefore methods ID3D12GraphicsCommandList::Close and ID3D12GraphicsCommandList::Reset cannot be called on it and they always return with error. Whether what conditions need to be met for the command list to get flushed is up to the auto command list, do not make any assumption about that.

  • Any resource that is ever passed into ID3D12GraphicsCommandList::ResourceBarriers as part of a transition barrier automatically gets into the resource tracking system of the D3D12 backend. This requires the notification of the tracking system later from the addon side when the resource is about to be destroyed. See ID3D12Root::RTResourceDestroyed

If you do not want certain resources to be tracked by the D3D12 backend then you can temporarily disable tracking of unknown resources by ID3D12Root::RTEnableTrackingUnkownResources. Such a scenario can be when you need to call into some third party library that has internal resources invisible to the caller but the code records commands into the auto type command list and adds transition barriers by ID3D12GraphicsCommandList::ResourceBarrier. Unknown resource means any resource that are not already recorded in the tracking system. If the ResourceBarrier call encounters such an unknown resource then it simply ignores to make an entry for the resource. When the third party code has finished then you should enable tracking of all resources again.

You can lock the auto command list for flushing. There is an internal flush-lock counter and if that is not zero then the command list will not and can not be flushed. The default value is 0 and you can increase the counter by ID3D12GraphicsCommandListAuto::AFlushLock and can be descreased by ID3D12GraphicsCommandListAuto::AFlushUnlock. This can be used for defining command blocks that are guaranteed to be continuous in the command list and won't be interrupted and corrupted by an automatic flush. Since the flush-lock is counter based, those locked blocks can be nested, but make sure to call AFlushUnlock for each AFlushLock to not leave the counter in a non-zero state because the command list will grow into the infinity in that case and will never be flushed and executed.
The auto command list also filters out a lot of redundant calls but you still should minimize them from your side. To make that easier, auto command list can store a user-defined simple ID which can be used for storing the current "ownership" of the command list.
The internal fence object and the current fence value can be queried by ID3D12GraphicsCommandListAuto::AGetFence and ID3D12GraphicsCommandListAuto::GetFenceValue respectively to feed them into dynamic allocators if needed (see below).

ID3D12Root

This interface is the main interface for accessing the D3D12 backend in dgVoodoo. The pointer to it is passed into the addon callback interface ID3D12RootObserver::D3D12RootCreated. This interface basically provides accessing to "stock" allocators, auto-type command lists, swap chain proxy textures and also provides factoring methods for buffer resources.

Memory allocator types

  • Static allocator - There is no such a memory allocator. The allocation for a static resource is done at factoring time and remains constant until the resource lifecycle.
  • Heap page allocator - Memory chunks can be allocated and released on an adapter-wide shared heap, and also, the allocations can be associated with a fence in order to be safely released automatically and reused later.
  • Ringbuffer allocator - The memory allocated by a ringbuffer allocator is private to the object that uses the allocator. The allocations can be associated with a fence for safe automatic release and reuse. This is faster than the heap page allocator, in other words, it has less CPU-overhead for allocation operations.
You can get interface pointers to stock heap page allocators from the D3D12 backend for a given adapter. There are multiple instances of heap page allocators:
  • constant buffer heap allocator
  • vertex buffer heap allocator
  • index buffer heap allocator
  • upload heap allocator
  • readback heap allocator
The only difference between them is how they are parametrized, in other words, what object types they are optimized for and how their internal behavior is finetuned. The readback heap allocator is a bit of exception in regard that its heap does not consists of pages with 'write combine' caching attribute but the more common 'write back' that is suitable for CPU read operations.

There are no separate ringbuffer allocator objects because they are private to the buffer objects they are backing.

Buffer resources

You can create buffers by either ID3D12Root::CreateStaticBuffer or ID3D12Root::CreateDynamicBuffer.
For dynamic buffers you must specify a backing allocator: either one of the heap page allocators or the ringbuffer allocator.
Buffers must be released at the latest when the host adapter is being destroyed.

Descriptor heap allocator types

  • Static allocator - Continuous arrays of descriptors can be allocated on either GPU-visible or CPU-only visible descriptor heaps.
  • Ringbuffer allocator - A number of descriptors can be allocated continuously on a GPU-visible descriptor heap. The allocations are associated with a fence for safe release and reuse.

Descriptor allocators

There are multiple types of descriptors to work with: CBV, SRV, UAV, RTV, sampler descriptor, etc., see D3D12 documentation for the details.
You can get stock static allocators from the D3D12 backend for a given adapter with
ID3D12Root::GetCBV_SRV_UAV_DescAllocator
ID3D12Root::GetRTV_DescAllocator
ID3D12Root::GetDSV_DescAllocator
ID3D12Root::GetSampler_DescAllocator
calls. Those allocators allocates CPU-only visible descriptors.
For GPU-visible descriptors you can create a resource descriptor ring buffer with ID3D12Root::CreateResourceDescRingBuffer. This must be released at the latest when the host adapter is being destroyed.

Pipeline state caches

You can also get shared cached instances of graphics and compute pipelinestate objects from the D3D12 backend. You can get them by passing the pipeline descriptor structure itself into ID3D12Root::PLCacheGetGraphicsPipeline and ID3D12Root::PLCacheGetComputePipeline. The descriptor structures resemble the original ones from D3D12 but some elements have a pointer or ID3DBlob* type. Those are literally just pointers pointing to a descriptor structure of the rasterizer, blend, etc., and blobs contain shader codes. The rule is that once you feed the two cache method mentioned with a pipeline descriptor structure then you also have to notify the cache system later when such a pointer or a blob becomes invalid or the root signature is released to remove all the associated entries from the cache entries. The notifaction methods are
ID3D12Root::GPLRootSignatureReleased
ID3D12Root::GPLShaderReleased
ID3D12Root::GPLStreamOutputReleased
ID3D12Root::GPLRasterizerStateReleased
ID3D12Root::GPLInputLayoutReleased
ID3D12Root::CPLRootSignatureReleased
ID3D12Root::CPLShaderReleased

There are second-level caching methods to get a unique structure pointer from a structure itself, that can be included in the pipeline descriptor structure. See
ID3D12Root::PLCacheGetDepthStencilDesc
ID3D12Root::PLCacheGetBlend4Desc
ID3D12Root::PLCacheGetRasterizerDesc
ID3D12Root::PLCacheGetInputLayoutDesc

Threading

The frontend API's are not threadsafe and they are / should be protected by locks to avoid concurrent calls (it can even be the responsibility of the application). So, you could expect that calls into the backend made by the frontend are also one-thread-at-a-time, meaning that only one backend method can get called in some of the threads at a given time. But, D3D12 is an asynchronous backend that defers the execution of a lot of methods and lets the application and the fronted run on while the deferred code is executed on a background thread later, to have the frontend and the backend running in parallel for performance reasons. Whether or not the execution of the backend code is deferred, and if not, then which thread it is executed in, depends on the circumstances: the application can call into the frontend API on different threads (other than main) so even undeferred backend code can be executed on a random thread by default. Deferring execution depends on the current CPU core affinity and other criteria so do not make any assumptions about that.

The point is, the D3D12 backend code and so the addon callbacks can be executed on any thread. Each adapter can have a separate background thread for executing deferred code so backend and addon calls referring to a given adapter are always serialized (of course), you don't have to worry about concurrent execution. However calls made to different adapters (in extreme cases) can be executed concurrently. It means that D3D12 addon swapchain and presentation callbacks can be executed concurrently with different adapter ID's (see ID3D12RootObserver). If this is a problem for your code then you should guard the critical parts in it with a lock.

The general rule for D3D12 objects like command lists, buffers, allocators, etc. got from the D3D12 backend is that they are thread safe at interface level but not at instance level. So, for example you can create 2 different buffers for 2 different adapters and you can call into both instances concurrently on different threads. But you cannot call into one instance concurrently from different threads. The only exception is the ID3D12Root interface which is global for D3D12Root. Methods are threadsafe with different adapter ID's.


Reference

dgVoodoo Addon documentation
Reference

Addon Reference

This section contains reference information for the API elements available for addons.

  • Enumerations
  • Interfaces
  • Functions
  • Structures


Interfaces

Interfaces

This section contains reference information for Addons:

  • IAddonMainCallback
  • ID3D12Root
  • ID3D12RootObserver
  • ID3D12ResourceDescAllocator
  • ID3D12ResourceDescRingBuffer
  • ID3D12Buffer
  • ID3D12GraphicsCommandListAuto


IAddonMainCallback

IAddonMainCallback

This is the main interface passed into the addon entry point. The addon can call its various methods for factoring objects or registering for observing certain class of events.

Query | GetVersion
Interface registering | RegisterForCallback
 | UnregisterForCallback
Factoring | CreateIniParser
 | RSSizeOfResource
 | RSLoadResource (1)
 | RSLoadResource (2)
Debug | IssueInfo
 | IssueWarning
 | IssueError

Requirements

Namespace: dgVoodoo
Header: IAddonMainCallback.hpp


IAddonMainCallback::GetVersion

IAddonMainCallback::GetVersion

Returns the version of dgVoodoo graphics dll's.

UInt32     GetVersion () const;

Return value

A BCD-coded integer representing the version number.

Remarks

Each digit of the version number is encoded into 4 bit fields.
So, for example, 0x280 means version 2.80 (which is the same as 2.8).

Requirements

Header: IAddonMainCallback.hpp


IAddonMainCallback::RegisterForCallback

IAddonMainCallback::RegisterForCallback

Registers an implemented instance of an interface to be called from dgVoodoo graphics dll's.

bool     RegisterForCallback (
    REFIID iid,
    void* pCallbackObject
);

Parameters

iid
[in] The interface ID to register for
pCallbackObject
[in] A pointer to the implemented interface

Return value

True if the registration is successful and false otherwise.

Remarks

Possible interface ID's:

 IID_D3D12RootObserver
 D3D12 backend callback interface

An addon should register for callbacks when it is initialized (when the AddonInit entry point is called) because after initilization the registered instances are passed to the proper subsystem of dgVoodoo so instances registered later won't be available for them.

Requirements

Header: IAddonMainCallback.hpp
Library: dgVoodooAddon.lib


IAddonMainCallback::UnregisterForCallback

IAddonMainCallback::UnregisterForCallback

Cancels the registration of an implemented instance of an interface.

void     UnregisterForCallback (
    REFIID iid,
    void* pCallbackObject
);

Parameters

iid
[in] The interface ID to unregister for
pCallbackObject
[in] A pointer to the implemented interface

Remarks

If the given interface pointer is not registered then nothing happens.

Possible interface ID's:

 IID_D3D12RootObserver
 D3D12 backend callback interface

Unregistering for a callback type will have an effect only when the proper subsystem is released. So the best place for unregistering callback is when the addon exit entry point AddonExit is called.

Requirements

Header: IAddonMainCallback.hpp
Library: dgVoodooAddon.lib


IAddonMainCallback::CreateIniParser

IAddonMainCallback::CreateIniParser

Creates a new instance of an INI file parser. For INI parser documentation see the related documents in the API Library.

IIniParser*     CreateIniParser (
    const APIDebugObj* pDebugObj = NULL
);

Parameters

pDebug
[in] Optional debug object. This parameter can be NULL.

Return value

If successful, this function returns a pointer to an IIniParser interface.

NULL pointer is returned otherwise.

Remarks

When the object instance is no longer needed, you must release it explicitly by calling Release method of the object.

Requirements

Header: IAddonMainCallback.hpp


IAddonMainCallback::RSSizeOfResource

IAddonMainCallback::RSSizeOfResource

Helper method to get the size of a resource in a module.

UInt32     RSSizeOfResource (
    HMODULE hModule,
    LPCTSTR name,
    LPCTSTR type
);

Parameters

hModule
[in] The module where the resource is located in
name
[in] The name or the ordinal of the resource
type
[in] The type of the resource

Return value

If the resource is found then the size of it is returned in bytes.

Zero is returned otherwise.

Remarks

This method is for easily handling/loading module resources. See Win32 function SizeOfResource.

Requirements

Header: IAddonMainCallback.hpp


IAddonMainCallback::RSLoadResource

IAddonMainCallback::RSLoadResource

Helper method to load a module resource to a memory location.

bool     RSLoadResource (
    HMODULE hModule,
    LPCTSTR name,
    LPCTSTR type
    BYTE* dst
);

Parameters

hModule
[in] The module where the resource is located in
name
[in] The name or the ordinal of the resource
type
[in] The type of the resource
dst
[in] Pointer to the memory area to load the resource to

Return value

True if the resource is found and loaded.

False otherwise.

Remarks

This method is for easily handling/loading module resources. See Win32 function LoadResource.

Requirements

Header: IAddonMainCallback.hpp


IAddonMainCallback::RSLoadResource

IAddonMainCallback::RSLoadResource

Helper method to get a pointer to a module resource.

const BYTE*     RSLoadResource (
    HMODULE hModule,
    LPCTSTR name,
    LPCTSTR type
);

Parameters

hModule
[in] The module where the resource is located in
name
[in] The name or the ordinal of the resource
type
[in] The type of the resource

Return value

A pointer to the resource.

If the resource is not found then NULL pointer is returned.

Remarks

This method is for easily handling/loading module resources. See Win32 function LoadResource.

Requirements

Header: IAddonMainCallback.hpp


IAddonMainCallback::IssueInfo

IAddonMainCallback::IssueInfo

Dumps an INFO type message to the debug output defined in the debug object.

void     IssueInfo (
    const APIDebugObj* pDebugObj,
    const char* pInfoMessage
);

Parameters

pDebugObj
[in] The debug object containing the INFO message severity and other needed parameters
pInfoMessage
[in] The message string to dump

Remarks

This method only works with the Debug and SpecRelease builds of dgVoodoo. With a plain Release version intended for regular usage it does nothing.

Requirements

Header: IAddonMainCallback.hpp


IAddonMainCallback::IssueWarning

IAddonMainCallback::IssueWarning

Dumps an WARNING type message to the debug output defined in the debug object.

void     IssueWarning (
    const APIDebugObj* pDebugObj,
    const char* pWarningMessage
);

Parameters

pDebugObj
[in] The debug object containing the WARNING message severity and other needed parameters
pWarningMessage
[in] The message string to dump

Remarks

This method only works with the Debug and SpecRelease builds of dgVoodoo. With a plain Release version intended for regular usage it does nothing.

Requirements

Header: IAddonMainCallback.hpp


IAddonMainCallback::IssueError

IAddonMainCallback::IssueError

Dumps an ERROR type message to the debug output defined in the debug object..

void     IssueError (
    const APIDebugObj* pDebugObj,
    const char* pErrorMessage
);

Parameters

pDebugObj
[in] The debug object containing the ERROR message severity and other needed parameters
pErrorMessage
[in] The message string to dump

Remarks

This method only works with the Debug and SpecRelease builds of dgVoodoo. With a plain Release version intended for regular usage it does nothing.

Requirements

Header: IAddonMainCallback.hpp


ID3D12RootObserver

ID3D12RootObserver

This is a hook interface for various notifications from dgVoodoo about the D3D12 backend.

Root object | D3D12RootCreated
 | D3D12RootReleased
Adapter usage | D3D12BeginUsingAdapter
 | D3D12EndUsingAdapter
Swapchains | D3D12SwapchainCreated
 | D3D12SwapchainChanged
 | D3D12SwapchainReleased
Image presentation | D3D12SwapchainPresentBegin
 | D3D12SwapchainPresentEnd

Requirements

Namespace: dgVoodoo
Header: ID3D12RootObserver.hpp


ID3D12RootObserver::D3D12RootCreated

ID3D12RootObserver::D3D12RootCreated

This method is called when dgVoodoo creates the global D3D12 object representing the root of the D3D12 backend.

bool     D3D12RootCreated (
    HMODULE hD3D12Dll,
    ID3D12Root* pD3D12Root
);

Parameters

hD3D12Dll
[in] The module handle for D3D12.dll
pD3D12Root
[in] The pointer to the main callback interface of D3D12 Root

Return value

If the addon successfully handles this hook then it must return true.

If for any reason it returns false then dgVoodoo cancels the creation of D3D12 Root.

Remarks

If the addon returns false then the creation of D3D12 Root is cancelled and the error rolls back to the top level factoring function in the given graphics API. In this case the proper graphics API function or method fails which can easily cause the application to fail to start. In extreme case the application can silently crash because of that.

Requirements

Header: ID3D12RootObserver.hpp


ID3D12RootObserver::D3D12RootReleased

ID3D12RootObserver::D3D12RootReleased

This method is called when dgVoodoo releases the global D3D12 object representing the root of the D3D12 backend.

void     D3D12RootReleased (
    ID3D12Root* pD3D12Root
);

Parameters

pD3D12Root
[in] The pointer to the main callback interface of D3D12 Root

Remarks

The pD3D12Root parameter is the same that is passed to D3D12RootCreated method.

Requirements

Header: ID3D12RootObserver.hpp


ID3D12RootObserver::D3D12BeginUsingAdapter

ID3D12RootObserver::D3D12BeginUsingAdapter

This method is called when the D3D12 backend initializes an adapter (GPU) for usage.

bool     D3D12BeginUsingAdapter (
    UInt32 adapterID
);

Parameters

adapterID
[in] The ID of the adapter.

Return value

If the addon successfully handles this hook then it must return true.

If for any reason it returns false then dgVoodoo cancels the initialization of the adapter.

Remarks

When this method called then the addon can create certain resources for the given adapter.

If the addon returns false then the initialization of the adapter is cancelled and the error rolls back to the top level factoring function in the given graphics API. This can cause a total fail in the application or the given adapter will just be invisible to the application in a better case.

Requirements

Header: ID3D12RootObserver.hpp


ID3D12RootObserver::D3D12EndUsingAdapter

ID3D12RootObserver::D3D12EndUsingAdapter

This method is called when the D3D12 backend stops using and adapter and releases all resources associated with it.

void     D3D12EndUsingAdapter (
    UInt32 adapterID
);

Parameters

adapterID
[in] The ID of the adapter.

Remarks

When this method is called then the addon must safely release all allocated resources for the given adapter.

Requirements

Header: ID3D12RootObserver.hpp


ID3D12RootObserver::D3D12SwapchainCreated

ID3D12RootObserver::D3D12SwapchainCreated

This method is called when the D3D12 backend creates a new swapchain for presentation on an adapter.

void     D3D12SwapchainCreated (
    UInt32 adapterID,
    ID3D12Swapchain* pSwapchain,
    const SwapchainData& swapchainData
);

Parameters

adapterID
[in] The ID of the adapter.
pSwapchain
[in] The pointer for the swapchain object created.
swapchainData
[in] The data describing the created swapchain object.

Remarks

When this method called then the addon can create certain resources for the given swapchain on the host adapter.

Requirements

Header: ID3D12RootObserver.hpp


ID3D12RootObserver::D3D12SwapchainChanged

ID3D12RootObserver::D3D12SwapchainChanged

This method is called when the D3D12 backend changes some properties of a swapchain on an adapter.

void     D3D12SwapchainChanged (
    UInt32 adapterID,
    ID3D12Swapchain* pSwapchain,
    const SwapchainData& swapchainData
);

Parameters

adapterID
[in] The ID of the adapter.
pSwapchain
[in] The pointer for the swapchain object that has changed.
swapchainData
[in] The data describing the changed swapchain object.

Remarks

There are multiple properties that can change, like swapchain image size, refresh rate, format, pixel multiplication size, etc. Only the properties defined in SwapchainData structure are passed to this callback, but this method is called even when only some other properties changes internally. When this method called then the addon can recreate or modify certain resources for the given swapchain on the host adapter.

Requirements

Header: ID3D12RootObserver.hpp


ID3D12RootObserver::D3D12SwapchainReleased

ID3D12RootObserver::D3D12SwapchainReleased

This method is called when the D3D12 backend releases a swapchain on an adapter.

void     D3D12SwapchainReleased (
    UInt32 adapterID,
    ID3D12Swapchain* pSwapchain
);

Parameters

adapterID
[in] The ID of the adapter.
pSwapchain
[in] The swapchain object being released.

Remarks

When this method called then the addon should safely release all resources associated with the given swapchain.

Requirements

Header: ID3D12RootObserver.hpp


ID3D12RootObserver::D3D12SwapchainPresentBegin

ID3D12RootObserver::D3D12SwapchainPresentBegin

This method is called right before the D3D12 backend is about to present an image into a window through a swapchain and starts it presentation process.

bool     D3D12SwapchainPresentBegin (
    UInt32 adapterID,
    const PresentContextInput& iCtx,
    PresentContextOutput& oCtx
);

Parameters

adapterID
[in] The ID of the adapter.
iCtx
[in] The context describing the input of the image presentation.
oCtx
[out] The context describing the data that the D3D12 presenter has to take into account to modify its input for the image presentation.

Return value

True if the presentation callback is successful and the data in the output context structure is valid.
False, if something went wrong, to tell the D3D12 presenter to completely ignore the callback and continue with the original input data.

Remarks

This method is called right before the image-postprocessing and image presentation algorithm of the D3D12 swapchain presenter takes place.

You can change the input of the presenter algorithm by defining an image texture in the PresentContextOutput output structure. The output texture size may not have the same size as the incoming one but the format of both the texture itself and the shader resource view (SRV) must be the same which is an unorm format defined in SwapchainData in the input context.

Basically there are 2 kinds of approaches to what to do in this callback:

  • If the addon don't want to do scaling (changing the size of the incoming texture) but only its content then it can utilize "stock" pre-allocated texture objects for the given swapchain. Those textures are called 'proxy' textures, there are always a minimum of 2 of them but the maximum number can be queried by ID3D12Root::GetMaxNumberOfProxyTextures. You can draw into them and give one of them back to the presenter in the output context as the new input. The proxy textures and the input texture always have the same size and format as the swapchain itself (see SwapchainData::imagePresentationSize and SwapchainData::format). The only thing you have to watch out for is the fact that the input texture itself can already be one of the proxy textures so pick them carefully when choosing the rendertarget. You can get a proxy texture by calling ID3D12Root::GetProxyTexture.
    The incoming context structure can also define only a sub-rect of the incoming texture as the ROI (region of interest) so it's always enough to process and draw only that region into the destination (output) texture, to save some GPU resource.
    There is a more optimal case: when the D3D12 presenter detects that no postprocessing is needed on dgVoodoo side so that the incoming texture could be presented directly then it gives the option to the addon to draw its output directly into the swapchain texture. The dst texture and rect defines a non-NULL texture with a valid destination rect to draw into in that case in the input context (PresentContextInput). If no such an optimal output is possible then the destination texture is always set to NULL. Even if the destination texture is non-NULL, the addon can still choose a proxy texture as an output and let the D3D12 presenter draw it into the swapchain. Remember, this is the case when the incoming source rect and the destination rect has different dimensions and the addon do not want to do image scaling. The point is, when the dimension are the same then it's worth to utilize drawing into the destination texture directly, again, for saving GPU resources.
    The attached sample addon completely implements this case. See the sample source for the details.

  • If the addon wants to change the dimensions of the incoming texture then it cannot use the swapchain proxy textures. In that case, the addon must create its own texture with the swapchain format and give it to the presenter through the output context structure. The best places for factoring/releasing such objects are the swapchain observing methods (ID3D12RootObserver::D3D12SwapchainCreated, ID3D12RootObserver::D3D12SwapchainChanged, ID3D12RootObserver::D3D12SwapchainReleased). The outgoing texture size can be arbitrary, however if it is too big then it may suffer information loss because the D3D12 backend presenter cannot do mipmapping for the downscaling and the sampling frequency will be too low (see Nyquist–Shannon sampling theorem). The swapchain property ID3D12RootObserver::SwapchainData::maxOverriddenInputTextureSize defines the maximum texture size for avoiding information loss.
    One more thing: if the outgoing texture is factored on your own then you have to know what resource-state it is in because you have to define the 'before' state in ResourceBarrier calls amongst your rendering calls. Well, the D3D12 presenter can transition it into any (unknown) state depending on what path the post-processing runs on but you can define a state (PresentContextOutput::outputTextureExpectedState) to transition your texture into after the presentation is done. If you don't care then just set this member to -1. You can safely do that for proxy-texture outputs because the D3D12 presenter passes their current state to the callback in PresentContextInput::srcTextureState and you also get it when getting a proxy-texture for a swapchain (ID3D12Root::GetProxyTexture) but for your own textures the "expected state after presentation" is the only viable way.

If this callback returns true and returns the incoming non-NULL destination texture (PresentContextInput::pDstTexture) as the output texture in PresentContextOutput::pOutputTexture then the D3D12 presenter takes it as the final image is already drawn into the swapchain and do nothing for the presentation (aside from drawing black bars if needed).

Requirements

Header: ID3D12RootObserver.hpp


ID3D12RootObserver::D3D12SwapchainPresentEnd

ID3D12RootObserver::D3D12SwapchainPresentEnd

This method is called right after the D3D12 backend has drawn a source image into a swapchain texture.

bool     D3D12SwapchainPresentEnd (
    UInt32 adapterID,
    const PresentEndContextInput& iCtx
);

Parameters

adapterID
[in] The ID of the adapter.
iCtx
[in] The context describing the input of the end of the image presentation process.

Remarks

This method always gets a valid swapchain drawing target in the input context structure so it can draw additional overlay-like data into the swapchain right before the presentation. If no such thing is required then this method should do nothing. The expected state of the source texture coming from ID3D12RootObserver::D3D12SwapchainPresentBegin is applied right before this callback is called.

Requirements

Header: ID3D12RootObserver.hpp


ID3D12Root

ID3D12Root

This is the main D3D12 interface passed to the D3D12 Root observers when the D3D12 Root is created. This is the main helper interface that exposes some of dgVoodoo's internal D3D12 infrastructure. The addons can utilize it for their own purposes but they are not obligated to. An addon can always choose to get the D3D12 device for a given adapter and do all kind of video memory allocation and pipeline state caching on its own.

Factoring | GetDevice
 | SerializeAndCreateRootSignature
 | CreateD3DBlob
 | GetCBV_SRV_UAV_DescAllocator
 | GetRTV_DescAllocator
 | GetDSV_DescAllocator
 | GetSampler_DescAllocator
 | GetGraphicsCommandListAuto
 | GetCopyCommandListAuto
 | GetHeapPageAllocator
 | GetCBV_SRV_UAV_RingBuffer
 | CreateResourceDescRingBuffer
 | CreateStaticBuffer
 | CreateDynamicBuffer
Swapchains | GetSwapchainData
 | GetMaxNumberOfProxyTextures
 | GetProxyTexture
Resource tracking | RTEnableTrackingUnkownResources
 | RTResourceDestroyed
 | RTObjectDestroyed
Pipeline object caches | PLCacheGetDepthStencilDesc
 | PLCacheGetBlend4Desc
 | PLCacheGetInputLayoutDesc
 | PLCacheGetGraphicsPipeline
 | PLCacheGetComputePipeline
Graphics pipeline state notification | GPLRootSignatureReleased
 | GPLShaderReleased
 | GPLStreamOutputReleased
 | GPLBlendStateReleased
 | GPLRasterizerStateReleased
 | GPLDepthStencilStateReleased
 | GPLInputLayoutReleased
Compute pipeline state notification | CPLRootSignatureReleased
 | CPLShaderReleased

Requirements

Namespace: -
Header: ID3D12Root.hpp


ID3D12Root::GetDevice

ID3D12Root::GetDevice

This method is for retrieving the ID3D12Device* pointer for a given adapter.

ID3D12Device*     GetDevice (
    UInt32 adapterID
);

Parameters

adapterID
[in] The ID of the adapter.

Return value

Always a non-NULL device pointer.

Remarks

The device returned is a device that is factored by the D3D12 backend when initializing an adapter for usage.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::SerializeAndCreateRootSignature

ID3D12Root::SerializeAndCreateRootSignature

This is a helper method for serializing a root signature object defined in high level structures and factor a D3D12 object for it in one step.

ID3D12RootSignature*     SerializeAndCreateRootSignature (
    UInt32 adapterID,
    D3D_ROOT_SIGNATURE_VERSION Version,
    const D3D12_ROOT_SIGNATURE_DESC* pRootSignatureDesc,
    ID3DBlob** ppErrorBlob
    );

Parameters

adapterID
[in] The ID of the adapter.
Version
[in] The version of the root signature descriptor.
pRootSignatureDesc
[in] Pointer to the high level root signature descriptor.
ppErrorBlob
[out] Pointer to place a blob object (containing the error string) to. It can be NULL.

Return value

An interface pointer to a D3D12 root signature object.
If the factoring fails then returns NULL and also an error blob is potentially returned containing the error string.

Remarks

See the related ID3DBlob, root signature serializer function and object factoring methods in the D3D12 (Windows) SDK. This is only a helper method for factoring a high level defined root signature in one step.

It's the responsibility of the addon to destroy this object.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::CreateD3DBlob

ID3D12Root::CreateD3DBlob

This is a general method for creating D3D blob containers (see the Windows SDK).

ID3DBlob*     CreateD3DBlob (
    UIntPtr dataSize,
    const void* pInitialData
    );

Parameters

dataSize
[in] Size of the container in bytes.
pInitialData
[in] Pointer to the content to initialize with. It can be NULL.

Return value

An interface pointer to a D3D blob object.
If the factoring fails then returns NULL.

Remarks

See the related ID3DBlob Windows SDK.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GetCBV_SRV_UAV_DescAllocator

ID3D12Root::GetCBV_SRV_UAV_DescAllocator

This method returns a static stock CBV_SRV_UAV descriptor allocator for a given adapter. The allocated heaps are CPU-only visible.

ID3D12ResourceDescAllocator*     GetCBV_SRV_UAV_DescAllocator (
    UInt32 adapterID
    );

Parameters

adapterID
[in] The ID of the adapter.

Return value

Always a valid pointer to the corresponding allocator for the given adapter.

Remarks

This allocator is created by the D3D12 backend when initializing an adapter for usage. The addon does not have to release it, only get a pointer and use it until the adapter is not released.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GetRTV_DescAllocator

ID3D12Root::GetRTV_DescAllocator

This method returns a static stock RTV (render target view) descriptor allocator for a given adapter. The allocated heaps are CPU-only visible.

ID3D12ResourceDescAllocator*     GetRTV_DescAllocator (
    UInt32 adapterID
    );

Parameters

adapterID
[in] The ID of the adapter.

Return value

Always a valid pointer to the corresponding allocator for the given adapter.

Remarks

This allocator is created by the D3D12 backend when initializing an adapter for usage. The addon does not have to release it, only get a pointer and use it until the adapter is not released.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GetDSV_DescAllocator

ID3D12Root::GetDSV_DescAllocator

This method returns a static stock DSV (depth-stencil view) descriptor allocator for a given adapter. The allocated heaps are CPU-only visible.

ID3D12ResourceDescAllocator*     GetDSV_DescAllocator (
    UInt32 adapterID
    );

Parameters

adapterID
[in] The ID of the adapter.

Return value

Always a valid pointer to the corresponding allocator for the given adapter.

Remarks

This allocator is created by the D3D12 backend when initializing an adapter for usage. The addon does not have to release it, only get a pointer and use it until the adapter is not released.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GetSampler_DescAllocator

ID3D12Root::GetSampler_DescAllocator

This method returns a stock static sampler descriptor allocator for a given adapter. The allocated heaps are CPU-only visible.

ID3D12ResourceDescAllocator*     GetSampler_DescAllocator (
    UInt32 adapterID
    );

Parameters

adapterID
[in] The ID of the adapter.

Return value

Always a valid pointer to the corresponding allocator for the given adapter.

Remarks

This allocator is created by the D3D12 backend when initializing an adapter for usage. The addon does not have to release it, only get a pointer and use it until the adapter is not released.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GetGraphicsCommandListAuto

ID3D12Root::GetGraphicsCommandListAuto

This method returns a stock auto-type graphics command list for a given adapter.

ID3D12GraphicsCommandListAuto*     GetGraphicsCommandListAuto (
    UInt32 adapterID
    );

Parameters

adapterID
[in] The ID of the adapter.

Return value

Always a valid pointer to the corresponding graphics command list for the given adapter.

Remarks

This command list is created by the D3D12 backend when initializing an adapter for usage. The addon does not have to release it, only get a pointer and use it until the adapter is not released.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GetCopyCommandListAuto

ID3D12Root::GetCopyCommandListAuto

This method returns a stock auto-type copy command list for a given adapter.

ID3D12GraphicsCommandListAuto*     GetCopyCommandListAuto (
    UInt32 adapterID
    );

Parameters

adapterID
[in] The ID of the adapter.

Return value

Always a valid pointer to the corresponding copy command list for the given adapter.

Remarks

This command list is created by the D3D12 backend when initializing an adapter for usage. The addon does not have to release it, only get a pointer and use it until the adapter is not released.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GetHeapPageAllocator

ID3D12Root::GetHeapPageAllocator

This method returns a stock videomemory page allocator for a given adapter.

ID3D12HeapPageAllocator*     GetHeapPageAllocator (
    UInt32 adapterID,
    DynamicAllocator allocator
    );

Parameters

adapterID
[in] The ID of the adapter.
allocator
[in] The allocator type.

Return value

Always a valid pointer to the corresponding allocator for the given adapter.

Remarks

This allocator is created by the D3D12 backend when initializing an adapter for usage. The addon does not have to release it, only get a pointer and use it until the adapter is not released.

The heap page allocators tracks page-based allocations on video memory heaps. The reason for multiple type of allocators is that each type is optimized for a given type of allocations. The allocation usecases (types) are the following:

DA_ConstBufferPageHeapAllocator
An allocator for dynamic constant buffers.

DA_VertexBufferPageHeapAllocator
An allocator for dynamic vertex buffers.

DA_IndexBufferPageHeapAllocator
An allocator for dynamic index buffers.

DA_UploadBufferPageHeapAllocator
An allocator for upload-type operations (transfer from system memory to video memory).

DA_ReadbackBufferPageHeapAllocator
An allocator for readback-type operations (transfer from video memory to system memory).
As you can see, dynamic buffers can be backed by a heap allocator. A heap allocator is global for an adapter so the heap is shared for allocation between all dynamic buffer instances. When a dynamic buffer is backed by a simple ringbuffer allocator then the allocated videomemory behind is private to the buffer object instance. It's much less optimal but provides the fastest allocation.

Do not use upload and readback allocators for dynamic buffers. The heap of the readback page allocator is a system memory heap with caching attribute 'write back' that is suitable for CPU read operations instead of 'write combine' which is optimized for writing continuous blocks of (large) data into the video memory by the CPU.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GetCBV_SRV_UAV_RingBuffer

ID3D12Root::GetCBV_SRV_UAV_RingBuffer

This method is for getting a stock CBV_SRV_UAV descriptor ringbuffer for a given adapter. This ring buffer is GPU-visible.

ID3D12ResourceDescRingBuffer*     GetCBV_SRV_UAV_RingBuffer (
    UInt32 adapterID
    );

Parameters

adapterID
[in] The ID of the adapter.

Return value

Always a valid pointer to the allocator.

Remarks

The ring buffer is created by the D3D12 backend when initializing an adapter for usage. The addon does not have to release it, only get a pointer and use it until the adapter is not released.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::CreateResourceDescRingBuffer

ID3D12Root::CreateResourceDescRingBuffer

This method is for creating your own GPU-visible descriptor ringbuffer.

ID3D12ResourceDescAllocator*     CreateResourceDescRingBuffer (
    UInt32 adapterID,
    D3D12_DESCRIPTOR_HEAP_TYPE heapType,
    UINT numDescriptors,
    D3D12_DESCRIPTOR_HEAP_FLAGS heapFlags
    );

Parameters

adapterID
[in] The ID of the adapter.
heapType
[in] The heap type used for the memory allocation.
numDescriptors
[in] Number of descriptors in an atomic allocation.
heapFlags
[in] Heap flags used for the memory allocation.

Return value

A pointer to an allocator instance if the method succeeds, NULL otherwise.

Remarks

If you need a CBV_SRV_UAV type descriptor ringbuffer then simply use the stock one (see ID3D12Root::GetCBV_SRV_UAV_RingBuffer) to spare GPU resources. If you need an other type of descripor ringbuffer then you can use this method to create one. Note that it's the responsibility of the addon to safely release it later. The latest point where it must be released is the releasing of the associated adapter itself.

Think of the ring buffer as a dynamic vertex/index buffer. When an atomic portion (a 'numDescriptors' length array) of it fills up and need a new one (discarding the data) then a new atomic portion is allocated or reused from previous allocations. With this in mind, do not specify a large number for numDescriptors. Depending on how often per frame sub-portions are allocated from the ringbuffer, keep it low but still optimal enough to avoid having a lot of allocated atomic portions internally. In other words, too many atomic portions and too often reallocation of them (too few descriptors per atomic portion) is as bad as having too many descriptors per atomic portion (too infrequent reallocation blocking reusability).

Requirements

Header: ID3D12Root.hpp


ID3D12Root::CreateStaticBuffer

ID3D12Root::CreateStaticBuffer

This method is for creating a plain static buffer for using it as a constant buffer, vertex/index buffer, etc.

ID3D12Buffer*     CreateStaticBuffer (
    UInt32 adapterID,
    UINT bufferSize,
    D3D12_HEAP_TYPE heapType,
    D3D12_HEAP_FLAGS heapFlags
    );

Parameters

adapterID
[in] The ID of the adapter.
bufferSize
[in] Size of the buffer in bytes.
heapType
[in] Heap type used for the memory allocation.
heapFlags
[in] Heap flags used for the allocation.

Return value

A pointer to a buffer object instance if the method succeeds, NULL otherwise.

Remarks

It's the responsibility of the addon to safely release it later. The latest point where it must be released is the releasing of the associated adapter itself.

If the buffer is created on a D3D12_HEAP_TYPE_UPLOAD type heap then its initial state is D3D12_RESOURCE_STATE_GENERIC_READ.

If the buffer is created on a D3D12_HEAP_TYPE_READBACK type heap then its initial state is D3D12_RESOURCE_STATE_COPY_DEST.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::CreateDynamicBuffer

ID3D12Root::CreateDynamicBuffer

This method is for creating a dynamic buffer for using it as a constant buffer, vertex/index buffer, etc.

ID3D12Buffer*     CreateDynamicBuffer (
    UInt32 adapterID,
    UINT bufferSize,
    DynamicAllocator allocatorType
    );

Parameters

adapterID
[in] The ID of the adapter.
bufferSize
[in] Size of the buffer in bytes.
allocatorType
[in] An allocator type for the allocator backing the buffer storage.

Return value

A pointer to a buffer object instance if the method succeeds, NULL otherwise.

Remarks

It's the responsibility of the addon to safely release it later. The latest point where it must be released is the releasing of the associated adapter itself.

The allocator type can be one of the following:

DA_RingAllocator
A simple ringbuffer allocator.

DA_ConstBufferPageHeapAllocator
An allocator for dynamic constant buffers.

DA_VertexBufferPageHeapAllocator
An allocator for dynamic vertex buffers.

DA_IndexBufferPageHeapAllocator
An allocator for dynamic index buffers.

The fastest allocator is the ringbuffer allocator. Data that is ever allocated by that is private to the buffer object instance. Do not create large buffers with this allocator and use it only if you need a buffer with the least allocation overhead performance wise for very frequent usage.
If those conditions are not met then use a heap page allocator instead. It's a little bit slower but it allocates from a heap shared between other buffer object instances.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GetSwapchainData

ID3D12Root::GetSwapchainData

This method returns the structure describing the properties of a swapchain.

SwapchainData     GetSwapchainData (
    ID3D12Swapchain* pSwapchain
    );

Parameters

pSwapchain
[in] The swapchain

Return value

The method always succeeds and returns the current properties of a swapchain.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GetMaxNumberOfProxyTextures

ID3D12Root::GetMaxNumberOfProxyTextures

This method is for retrieving maximum number of proxy textures for swapchains on a given adapter. This is always at least 2.

UInt32     GetMaxNumberOfProxyTextures (
    UInt32 adapterID
);

Parameters

adapterID
[in] The ID of the adapter.

Return value

The number of max proxy textures for the given adapter

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GetProxyTexture

ID3D12Root::GetProxyTexture

This method is for getting a proxy texture for a swapchain on a given adapter.

bool     GetProxyTexture (
    ID3D12Swapchain* pSwapchain,
    UInt32 idx,
    SwapchainProxyTextureData* pOutData
    );

Parameters

pSwapchain
[in] The swapchain.
idx
[in] Index of the proxy texture.
pOutData
[out] Pointer to the data structure to return the proxy texture data to.

Return value

If the method succeeds then it returns true and pOutData is filled with the data of the proxy texture.
If it fails then returns false and pOutputData content is invalid.

Remarks

The proxy texture index must be in the range of 0 and 'max number of proxy textures on the swapchain adapter'-1. If it's out of bounds then the method fails.

Proxy textures are factored on demand and released by the D3D12 backend. The addon does not have to release it, only use it. A proxy texture lifecycle is tied to that of the swapchain. In other words, proxy textures are released when their host swapchain itself is released.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::RTEnableTrackingUnkownResources

ID3D12Root::RTEnableTrackingUnkownResources

This method enables or disables the automatic recording of resources into the D3D12 backend tracking system that are not already recorded there.

bool     RTEnableTrackingUnkownResources (
    bool enable
    );

Parameters

enable
[in] The status for enabling tracking unknown resources.

Return value

The previous state of the tracking status.

Remarks

This method is useful for temporarily disabling resource tracking for unknown resources when the addon calls into third-party D3D12 code that records commands into an auto type command list of the D3D12 backend. Since third party code and libraries can have internal D3D12 resources that are invisible to the caller, the tracking system couldn't be notified when they are released. So, it's better to disable automatic tracking for D3D12 resources through ID3D12GraphicsCommandList::ResourceBarriers that are not already in the D3D12 tracking system and solve their tracking at the caller's level, say, making sure that the auto type command list is flushed and executed when the third party library releases its resources.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::RTResourceDestroyed

ID3D12Root::RTResourceDestroyed

This method notifies the resource tracking infrastructure of the D3D12 backend that a D3D12 resource is about to be released so it must be removed from the tracking records.

bool     RTResourceDestroyed (
    ID3D12Resource* pResource,
    bool waitForCompletion = true
    );

Parameters

pResource
[in] The resource to be removed.
waitForCompletion
[in] Whether to wait for GPU completion on this resource.

Return value

False if waiting for GPU completion was required but it could not be implemented. See remarks.

Remarks

Any resource that ever gets recorded into the tracking infrastructure of the D3D12 backend must be removed from there when the resource is released. In order for that, you must notify the tracking system that the resource in question is about to become invalid. By default this method also makes sure that the GPU is not working with this resource by the time it returns but you can disable the waiting for the GPU if needed. If you do not notify the tracking system then the pointer of the resource remains in the tracking entries and that will cause undefined problems if another D3D12 resource gets allocated onto the same pointer. So, it's a must. If pResource is not tracked by the system then nothing happens.

If you notify the system about releasing a resource bound into an auto-command list then the command list must be flushed first. It cannot be done if the command list itself is in locked state. If you require waiting for completion in such a case then this method returns false and effectively nothing happens. If this is the case then there is a problem in your API driving logic that must be resolved.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::RTObjectDestroyed

ID3D12Root::RTObjectDestroyed

This method notifies the resource tracking infrastructure of the D3D12 backend that a custom object is about to be released so it must be removed from the tracking records.

bool     RTObjectDestroyed (
    void* pObject,
    bool waitForCompletion = true
    );

Parameters

pObject
[in] The object to be removed.
waitForCompletion
[in] Whether to wait for GPU completion on this resource.

Return value

False if waiting for GPU completion was required but it could not be implemented. See remarks.

Remarks

Custom non-D3D12 objects can be put explicitly into the tracking system to be virtually tied to GPU command list processing. Any object that was ever put into the tracking infrastructure of the D3D12 backend must be removed from there when tracking is no longer needed for it. In order for that, you must notify the tracking system by this method to remove it from the tracking entry records. By default this method also makes sure that the GPU is not working with this tied object by the time it returns but you can disable the waiting for the GPU if needed. If you do not notify the tracking system then the object remains in the tracking entries and that will cause undefined problems if another object with the same pointer is put into the tracking system. So, it's a must. If pObject is not tracked by the system then nothing happens.

If you notify the system about releasing an object bound into an auto-command list then the command list must be flushed first. It cannot be done if the command list itself is in locked state. If you require waiting for completion in such a case then this method returns false and effectively nothing happens. If this is the case then there is a problem in your API driving logic that must be resolved.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::PLCacheGetDepthStencilDesc

ID3D12Root::PLCacheGetDepthStencilDesc

This is a graphics pipeline cache-method and returns a pointer as a unique id for a given depth-stencil descriptor structure.

D3D12_DEPTH_STENCIL_DESC*     PLCacheGetDepthStencilDesc (
    UInt32 adapterID,
    const D3D12_DEPTH_STENCIL_DESC& desc
    );

Parameters

adapterID
[in] The ID of the adapter.
desc
[in] The descriptor structure to get the pointer for.

Return value

A valid pointer associated to the content of the incoming descriptor structure or NULL in extreme error cases (out of memory).

Remarks

You can assign pointer values (as hash values) to D3D12_DEPTH_STENCIL_DESC descriptor structures. These returned pointers come from the internal caches of the D3D12 backend that are associated with a given adapter. The addon does not have to release them in any way, it's up to the D3D12 backend itself. Just use them until the adapter is valid.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::PLCacheGetBlend4Desc

ID3D12Root::PLCacheGetBlend4Desc

This is a graphics pipeline cache-method and returns a pointer as a unique id for a given blend descriptor structure.

D3D12_BLEND_DESC*     PLCacheGetBlend4Desc (
    UInt32 adapterID,
    const D3D12_BLEND_DESC& desc
    );

Parameters

adapterID
[in] The ID of the adapter.
desc
[in] The descriptor structure to get the pointer for.

Return value

A valid pointer associated to the content of the incoming descriptor structure or NULL in extreme error cases (out of memory).

Remarks

You can assign pointer values (as hash values) to D3D12_BLEND_DESC descriptor structures.
Important to note that only the first 4 rendertargets of the incoming blend structure is taken into account. Sorry about that.
These returned pointers come from the internal caches of the D3D12 backend that are associated with a given adapter. The addon does not have to release them in any way, it's up to the D3D12 backend itself. Just use them until the adapter is valid.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::PLCacheGetRasterizerDesc

ID3D12Root::PLCacheGetRasterizerDesc

This is a graphics pipeline cache-method and returns a pointer as a unique id for a given rasterizer descriptor structure.

D3D12_RASTERIZER_DESC*     PLCacheGetRasterizerDesc (
    UInt32 adapterID,
    const D3D12_RASTERIZER_DESC& desc
    );

Parameters

adapterID
[in] The ID of the adapter.
desc
[in] The descriptor structure to get the pointer for.

Return value

A valid pointer associated to the content of the incoming descriptor structure or NULL in extreme error cases (out of memory).

Remarks

You can assign pointer values (as hash values) to D3D12_RASTERIZER_DESC descriptor structures. These returned pointers come from the internal caches of the D3D12 backend that are associated with a given adapter. The addon does not have to release them in any way, it's up to the D3D12 backend itself. Just use them until the adapter is valid.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::PLCacheGetInputLayoutDesc

ID3D12Root::PLCacheGetInputLayoutDesc

This is a graphics pipeline cache-method and returns a pointer as a unique id for a given rasterizer descriptor structure.

D3D12_INPUT_LAYOUT_DESC*     PLCacheGetInputLayoutDesc (
    UInt32 adapterID,
    UInt32 numOfElements,
    const D3D12_INPUT_ELEMENT_DESC* pElements
    );

Parameters

adapterID
[in] The ID of the adapter.
numOfElements
[in] Number of input elements.
pElements
[in] Pointer to the input element structure array.

Return value

A valid pointer associated to the content of the incoming descriptor structure or NULL in extreme error cases (out of memory).

Remarks

You can assign pointer values (as hash values) to D3D12_INPUT_LAYOUT_DESC descriptor structures. These returned pointers come from the internal caches of the D3D12 backend that are associated with a given adapter. The addon does not have to release them in any way, it's up to the D3D12 backend itself. Just use them until the adapter is valid.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::PLCacheGetGraphicsPipeline

ID3D12Root::PLCacheGetGraphicsPipeline

This is a graphics pipeline cache-method and returns an interface pointer for an object representing the incoming graphics pipeline descriptor structure.

ID3D12PipelineState*     PLCacheGetGraphicsPipeline (
    UInt32 adapterID,
    const GraphicsPLDesc& desc
    );

Parameters

adapterID
[in] The ID of the adapter.
desc
[in] The graphics pipeline descriptor structure.

Return value

If the graphics pipeline descriptor structure is valid and no underlying factoring problems occur then a valid pointer to a ID3D12PipelineState object. NULL pointer otherwise.

Remarks

You can get a D3D12-level ID3D12PipelineState pipeline state object from a graphics pipeline descriptor structure. These objects come from the internal caches of the D3D12 backend that are associated with a given adapter. The addon does not have to release them in any way, it's up to the D3D12 backend itself. Just use them until the adapter is valid.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::PLCacheGetComputePipeline

ID3D12Root::PLCacheGetComputePipeline

This is a compute pipeline cache-method and returns an interface pointer for an object representing the incoming compute pipeline descriptor structure.

ID3D12PipelineState*     PLCacheGetComputePipeline (
    UInt32 adapterID,
    const ComputePLDesc& desc
    );

Parameters

adapterID
[in] The ID of the adapter.
desc
[in] The compute pipeline descriptor structure.

Return value

If the compute pipeline descriptor structure is valid and no underlying factoring problems occur then a valid pointer to a ID3D12PipelineState object. NULL pointer otherwise.

Remarks

You can get a D3D12-level ID3D12PipelineState pipeline state object from a compute pipeline descriptor structure. These objects come from the internal caches of the D3D12 backend that are associated with a given adapter. The addon does not have to release them in any way, it's up to the D3D12 backend itself. Just use them until the adapter is valid.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GPLRootSignatureReleased

ID3D12Root::GPLRootSignatureReleased

This is a method notifying the caches of the D3D12 backend that an own-factored root signature object is about to be released so remove it from the entry records.

void     GPLRootSignatureReleased (
    UInt32 adapterID,
    ID3D12RootSignature* pRootSignature
    );

Parameters

adapterID
[in] The ID of the adapter.
pRootSignature
[in] The root signature object that is about to be released.

Remarks

If you have an own-factored root signature object that got into the caches of the D3D12 backend by using it as input for PLCacheGetGraphicsPipeline then you must notify the cache system when it is about to be released so the caching system can remove all internal associated entries. It is a must because if you miss notifying the cache system then the invalid pointer will get stuck in the entry records and that causes undefined problems if another root signate object with the same reallocated pointer gets into the cache system later.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GPLShaderReleased

ID3D12Root::GPLShaderReleased

This is a method notifying the caches of the D3D12 backend that a shader object is about to be released so remove it from the entry records.

void     GPLShaderReleased (
    UInt32 adapterID,
    ID3DBlob* pShader
    );

Parameters

adapterID
[in] The ID of the adapter.
pShader
[in] The shader object that is about to be released.

Remarks

If you have a shader object that got into the caches of the D3D12 backend by using it as input for PLCacheGetGraphicsPipeline then you must notify the cache system when it is about to be released so the caching system can remove all internal associated entries. It is a must because if you miss notifying the cache system then the invalid pointer will get stuck in the entry records and that causes undefined problems if another shader object with the same reallocated pointer gets into the cache system later.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GPLStreamOutputReleased

ID3D12Root::GPLStreamOutputReleased

This is a method notifying the caches of the D3D12 backend that an own-factored stream-out pointer is about to get invalidated so remove it from the entry records.

void     GPLStreamOutputReleased (
    UInt32 adapterID,
    D3D12_STREAM_OUTPUT_DESC* pStreamOutput
    );

Parameters

adapterID
[in] The ID of the adapter.
pStreamOutput
[in] The stream-out pointer that is about to get invalidated.

Remarks

If you have an own-factored stream-out pointer that got into the caches of the D3D12 backend by using it as input for PLCacheGetGraphicsPipeline then you must notify the cache system when it is about to get invalidated so the caching system can remove all internal associated entries. It is a must because if you miss notifying the cache system then the invalid pointer will get stuck in the entry records and that causes undefined problems if another stream-out object with the same reallocated pointer gets into the cache system later.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GPLRasterizerStateReleased

ID3D12Root::GPLRasterizerStateReleased

This is a method notifying the caches of the D3D12 backend that an own-factored rasterizer-state pointer is about to get invalidated so remove it from the entry records.

void     GPLRasterizerStateReleased (
    UInt32 adapterID,
    D3D12_RASTERIZER_DESC* pRasterizerState
    );

Parameters

adapterID
[in] The ID of the adapter.
pRasterizerState
[in] The rasterizer-state pointer that is about to get invalidated.

Remarks

If you have an own-factored rasterizer-state pointer that got into the caches of the D3D12 backend by using it as input for PLCacheGetGraphicsPipeline then you must notify the cache system when it is about to get invalidated so the caching system can remove all internal associated entries. It is a must because if you miss notifying the cache system then the invalid pointer will get stuck in the entry records and that causes undefined problems if another rasterizer-state object with the same reallocated pointer gets into the cache system later.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GPLInputLayoutReleased

ID3D12Root::GPLInputLayoutReleased

This is a method notifying the caches of the D3D12 backend that an own-factored input layout pointer is about to get invalidated so remove it from the entry records.

void     GPLInputLayoutReleased (
    UInt32 adapterID,
    D3D12_INPUT_LAYOUT_DESC* pInputLayout
    );

Parameters

adapterID
[in] The ID of the adapter.
pInputLayout
[in] The input layout pointer that is about to get invalidated.

Remarks

If you have an own-factored rasterizer-state pointer that got into the caches of the D3D12 backend by using it as input for PLCacheGetGraphicsPipeline then you must notify the cache system when it is about to get invalidated so the caching system can remove all internal associated entries. It is a must because if you miss notifying the cache system then the invalid pointer will get stuck in the entry records and that causes undefined problems if another input layout object with the same reallocated pointer gets into the cache system later.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::CPLRootSignatureReleased

ID3D12Root::CPLRootSignatureReleased

This is a method notifying the caches of the D3D12 backend that an own-factored compute root signature object is about to be released so remove it from the entry records.

void     CPLRootSignatureReleased (
    UInt32 adapterID,
    ID3D12RootSignature* pRootSignature
    );

Parameters

adapterID
[in] The ID of the adapter.
pRootSignature
[in] The root signature object that is about to be released.

Remarks

If you have an own-factored root signature object that got into the caches of the D3D12 backend by using it as input for PLCacheGetComputePipeline then you must notify the cache system when it is about to be released so the caching system can remove all internal associated entries. It is a must because if you miss notifying the cache system then the invalid pointer will get stuck in the entry records and that causes undefined problems if another root signate object with the same reallocated pointer gets into the cache system later.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::CPLShaderReleased

ID3D12Root::CPLShaderReleased

This is a method notifying the caches of the D3D12 backend that a shader object is about to be released so remove it from the entry records.

void     CPLShaderReleased (
    UInt32 adapterID,
    ID3DBlob* pShader
    );

Parameters

adapterID
[in] The ID of the adapter.
pShader
[in] The shader object that is about to be released.

Remarks

If you have a shader object that got into the caches of the D3D12 backend by using it as input for PLCacheGetComputePipeline then you must notify the cache system when it is about to be released so the caching system can remove all internal associated entries. It is a must because if you miss notifying the cache system then the invalid pointer will get stuck in the entry records and that causes undefined problems if another shader object with the same reallocated pointer gets into the cache system later.

Requirements

Header: ID3D12Root.hpp


ID3D12ResourceDescAllocator

ID3D12ResourceDescAllocator

This is the inteface for static resource descriptor allocators.

Factoring | AllocDescriptorGroup
 | DeallocDescriptorGroup
Usage | GetSubGroupHandle
 | GetGPUDescHandle
 | GetCPUDescHandle
 | GetDescriptorHeap

Requirements

Namespace: -
Header: ID3D12Root.hpp


ID3D12ResourceDescAllocator::AllocDescriptorGroup

ID3D12ResourceDescAllocator::AllocDescriptorGroup

This method allocates a continuous descriptor block on descriptor heap and returns a handle identifying the first element of the array.

UInt32     AllocDescriptorGroup (
    UInt32 numOfContinuousDescriptors
    );

Parameters

numOfContinuousDescriptors
[in] Length of the descriptor array

Return value

If the allocation is successful then it returns a valid handle for the first element of the array.
If fails then the return value is -1.

Requirements

Header: ID3D12Root.hpp


ID3D12ResourceDescAllocator::DeallocDescriptorGroup

ID3D12ResourceDescAllocator::DeallocDescriptorGroup

This method deallocates a descriptor array on a descriptor heap identified by a handle.

void     DeallocDescriptorGroup (
    UInt32 handle,
    UInt32 numOfContinuousDescriptors,
    ID3D12Fence* pFence = NULL,
    UINT64 fenceValue = 0
    );

Parameters

handle
[in] The handle identifying the first array element
numOfContinuousDescriptors
[in] Length of the descriptor array to deallocate
pFence
[in] A fence object to tie the deallocation to
fenceValue
[in] The value of the fence object to tie the deallocaion to

Remarks

The handle can be a subgroup handle retrieved by GetSubGroupHandle. So, a previously allocated descriptor array can be deallocated partially but it is the responsibility of the caller to keep track which elements are freed. You can also feed the method with a fence object with a fence value telling the allocator that the descriptors in question shouldn't be freed until the fence reaches the value. Altough the descriptors may not be visible to the GPU, this can come in handy in a multithreaded driving model. If pFence is NULL then the descriptors are freed at once, before the method returns.

Requirements

Header: ID3D12Root.hpp


ID3D12ResourceDescAllocator::GetSubGroupHandle

ID3D12ResourceDescAllocator::GetSubGroupHandle

This method gets a handle for the first element of a subarray in a previously allocated descriptor array.

UInt32     GetSubGroupHandle (
    UInt32 handle,
    UInt32 descIndex
    );

Parameters

handle
[in] The handle identifying the first element of an array
descIndex
[in] The 0-based descriptor index in the array

Return value

The handle identifying the first element of the array starting at descIndex position of the incoming array.

Requirements

Header: ID3D12Root.hpp


ID3D12ResourceDescAllocator::GetGPUDescHandle

ID3D12ResourceDescAllocator::GetGPUDescHandle

This method returns the GPU descriptor handle for an element in a descriptor array.

D3D12_GPU_DESCRIPTOR_HANDLE     GetGPUDescHandle (
    UInt32 handle,
    UInt32 descIndex
    );

Parameters

handle
[in] The handle identifying the first element of an array
descIndex
[in] The 0-based descriptor index in the array

Return value

The GPU descriptor handle for the element at the descIndex position. This call is invalid if the underlying descriptor heaps are not visible to the GPU.

Requirements

Header: ID3D12Root.hpp


ID3D12ResourceDescAllocator::GetCPUDescHandle

ID3D12ResourceDescAllocator::GetCPUDescHandle

This method returns the CPU descriptor handle for an element in a descriptor array.

D3D12_CPU_DESCRIPTOR_HANDLE     GetCPUDescHandle (
    UInt32 handle,
    UInt32 descIndex
    );

Parameters

handle
[in] The handle identifying the first element of an array
descIndex
[in] The 0-based descriptor index in the array

Return value

The CPU descriptor handle for the element at the descIndex position.

Requirements

Header: ID3D12Root.hpp


ID3D12ResourceDescAllocator::GetDescriptorHeap

ID3D12ResourceDescAllocator::GetDescriptorHeap

This method returns the D3D12 heap object for a previously allocated descriptor array.

ID3D12DescriptorHeap*     GetDescriptorHeap (
    UInt32 handle
    );

Parameters

handle
[in] The handle identifying the first element of an array

Return value

A valid pointer for a ID3D12DescriptorHeap object representing the physical heap on which the descriptor array was allocated.

Requirements

Header: ID3D12Root.hpp


ID3D12ResourceDescRingBuffer

ID3D12ResourceDescRingBuffer

This is the inteface for the GPU-visible dynamic resource descriptor ring buffer allocator.

Factoring | Release
Allocation | Alloc

Requirements

Namespace: -
Header: ID3D12Root.hpp


ID3D12ResourceDescRingBuffer::Alloc

ID3D12ResourceDescRingBuffer::Alloc

This method allocates a continuous descriptor block.

bool     Alloc (
    UInt32 numOfDescriptors,
    ID3D12Fence* pFence,
    UINT64 fenceValue,
    AllocData& allocData
    );

Parameters

numOfDescriptors
[in] Length of the descriptor array to alloc
pFence
[in] The fence to be associated with the allocation
fenceValue
[in] The fence value to be associated with the allocation
allocData
[out] A reference to the outgoing allocation descriptor

Return value

If the allocation is successful then it returns true and allocData is valid.
If fails then it returns false and allocData is invalid.

Remarks

The allocation is associated with a fence and a fence value. It guarantees that the allocation will not be reused in subsequent Alloc calls until pFence reaches fenceValue.

The number of descriptors to allocate (numOfDescriptors) cannot be larger than the 'atomic allocation size' of the ringbuffer. See ID3D12Root::CreateResourceDescRingBuffer

Requirements

Header: ID3D12Root.hpp


ID3D12ResourceDescRingBuffer::Release

ID3D12ResourceDescRingBuffer::Release

This method releases the ring buffer allocator object.

void     Release ();

Remarks

This is not a COM object. If this method is called then the allocator is released and its interface pointer becomes invalid.

It is the caller's responsibility to make sure that no GPU operation is being done on or scheduled for the ring buffer, to safely release it.

Requirements

Header: ID3D12Root.hpp


ID3D12Buffer

ID3D12Buffer

This is the inteface for plain data buffers.

Factoring | Release
Allocation | Lock
 | Unlock
Query | HasAddressChanged
 | ClearAddressChangedFlag
 | GetAndClearAddressChangedBit

Requirements

Namespace: -
Header: ID3D12Root.hpp


ID3D12Buffer::Lock

ID3D12Buffer::Lock

This method returns a pointer to the buffer data for CPU access and increases the internal lock-counter.

LockData     Lock (
    LockType lockType,
    ID3D12Fence* pFence = NULL,
    UInt64 fenceValue = 0
    );

Parameters

lockType
[in] Buffer data access type
pFence
[in] A fence to associate with the lock
fenceValue
[in] A fence value for the fence to associate with the lock

Return value

If the allocation is successful then LockData::pBuffer is a valid pointer. The method will fail if the lock counter is not zero.
If fails then LockData::pBuffer is NULL.

Remarks

A fence object with a value can be associated to the allocation made and returned by the buffer object. It guarantees that the currently allocated memory will not be reallocated again in subsequent Lock calls (or in any other way through other object instances using the underlying allocator) until the fence object reaches the given value. Possible buffer data access types (lock type):

LT_Default
The Lock method potentially waits for the GPU to finish the work on the current buffer data allocation if the associated fence has not yet reached the required value. This access type is intended for static buffers. It should work with dynamic buffers as well but their goal is to never wait for the GPU so do not use this for them.

LT_NoOverwrite
Valid only for dynamic buffers. The Lock method simply returns a pointer to the latest allocation independently on the latest associated fence. It is the responsibility of the caller to keep track of portions of the allocation that the GPU may be working on to avoid CPU/GPU read/write conflicts.

LT_Discard
Valid only for dynamic buffers. The Lock method either allocates a new chunk of memory or just takes the latest one and returns a pointer to it. If the fence associated with the latest allocation has not yet reached the required value then a new chunk of memory is allocated.

If you call this method with LT_NoOverwrite lock type then the associated fence and fence value for the current allocation are still updated to the incoming parameters.

Make sure you do not call this method with LT_Default when the underlying static buffer is already used in a currently flush-locked autoflush-command list. If a static buffer allocation is associated with a fence and fence value coming from an autoflush-command list then the Lock method may tries to force flushing of the command list and wait for the fence to finish. If the command list is locked for flush then it cannot be flushed so waiting for the fence will cause a deadlock. Updating static buffers in this way is a bad driving pattern anyway, static buffers should be there to contain constant data or be updated infrequently.

If the pFence parameter is NULL then no fence will be associated with the current allocation so it cannot be tracked for GPU usage and so it will be returned for subsequent Lock calls.

When a new chunk of memory is allocated internally then the old allocation gets recorded in the D3D12 tracking system to guarantee not to be freed until the associated fence finishes.

Because of performance reasons, like binding vertex/index buffer addresses into the graphics command list only when the address of the current buffer allocation effectively changes, you may have to query the info about the change. That is what ID3D12Buffer::HasAddressChanged, ID3D12Buffer::ClearAddressChangedFlag and ID3D12Buffer::GetAndClearAddressChangedBit methods are for. Each time a new chunk of memory is allocated then all of the 32 bits of an internal variable is set to 1. You can query and clear those bits to keep track of allocation changes.

Dynamic buffers will do their first memory allocation in the first Lock call in their life cycle. When no memory is yet allocated then LT_NoOverwrite is equivalent to LT_Discard.

You should always call Unlock after the Lock call. Unlock does nothing effectively but keeps track of the lock counter. Lock will fail with lock counter other than 0.

Requirements

Header: ID3D12Root.hpp


ID3D12Buffer::Unlock

ID3D12Buffer::Unlock

This method just decreases the lock counter of the buffer object.

void     Unlock ();

Remarks

You should always call this method after calling Lock to decrease the lock counter to 0. Lock will fail if the lock counter is not 0.

Requirements

Header: ID3D12Root.hpp


ID3D12Buffer::HasAddressChanged

ID3D12Buffer::HasAddressChanged

Returns if a new memory allocation has happened since the last query.

bool     HasAddressChanged ();

Return value

Returns true if any bit of the internal address-change variable is set to 1. Returns false otherwise.

Remarks

If you only need a simple information about the allocation change then you can call this method. You can clear the change information with ClearAddressChangedFlag.

Requirements

Header: ID3D12Root.hpp


ID3D12Buffer::ClearAddressChangedFlag

ID3D12Buffer::ClearAddressChangedFlag

Clears the information about the address change coming from a new memory chunk allocation.

void     ClearAddressChangedFlag ();

Remarks

If you only need a simple information about the allocation change then you can call ID3D12Buffer::HasAddressChanged

Requirements

Header: ID3D12Root.hpp


ID3D12Buffer::GetAndClearAddressChangedBit

ID3D12Buffer::GetAndClearAddressChangedBit

Returns the result of the bit-test-and-clear operation made on the internal variable storing the allocation address change information.

bool     GetAndClearAddressChangedBit (
    UInt32 idx
    );

Parameters

idx
[in] Bit index (0-31)

Return value

The bit value of the address-change variable.

Remarks

When an new chunk of memory is allocated internally then all of the 32 bits of the address-change variable are set to 1. You can query and clear this replicated information on the buffer object.

Requirements

Header: ID3D12Root.hpp


ID3D12Buffer::Release

ID3D12Buffer::Release

This method releases the buffer object.

void     Release ();

Remarks

This is not a COM object. If this method is called then the buffer is released and its interface pointer becomes invalid.

For static buffers it is the caller's responsibility to make sure that no GPU operation is being done on or scheduled for the buffer, to safely release it. For dynamic buffers it is the responsibility of the underlying allocator.

Requirements

Header: ID3D12Root.hpp


ID3D12GraphicsCommandListAuto

ID3D12GraphicsCommandListAuto

This is the inteface for the auto-flush type of D3D12 command list.

Query | GetCommandListInterface
 | AGetFence
 | GetFenceValue
 | AGetLastFlushFenceValue
Ownership | IsCurrentId
 | ChangeId
Flush management | AFlush
 | AFlushLock
 | AFlushUnlock
Helpers | HIUpdateSubBuffer
 | HIUpdateSubTexture

Requirements

Namespace: -
Header: ID3D12Root.hpp


ID3D12GraphicsCommandListAuto::GetCommandListInterface

ID3D12GraphicsCommandListAuto::GetCommandListInterface

This method returns a pointer to a standard ID3D12GraphicsCommandList interface.

ID3D12GraphicsCommandList*     GetCommandListInterface ();

Return value

Always a valid pointer to a ID3D12GraphicsCommandList interface.

Remarks

The interface implements the standard ID3D12GraphicsCommandList from D3D12. However, it does not supports querying higher version of graphics command list interfaces.

Requirements

Header: ID3D12Root.hpp


ID3D12GraphicsCommandListAuto::IsCurrentId

ID3D12GraphicsCommandListAuto::IsCurrentId

This method checks out if the current owner ID is the same as the parameter and returns the result.

bool     IsCurrentId (
    void* id
    );

Parameters

id
[in] The ID to check against

Return value

If the current owner ID is the same as parameter 'id' then returns true. It returns false otherwise.

Remarks

Each command list can store a user defined ID. The command list object knows nothing about it, it only stores one. This ID can be used for indicating the current owner of the command list and deciding whether partial or full state update is needed when recording commands into the list.

When the command list gets flushed then the user defined ID is set to zero.

Requirements

Header: ID3D12Root.hpp


ID3D12GraphicsCommandListAuto::ChangeId

ID3D12GraphicsCommandListAuto::ChangeId

This method stores the new owner ID and returns if the old one was the same as the new one.

bool     ChangeId (
    void* newId
    );

Parameters

newId
[in] The new ID to store

Return value

If the current owner ID is the same as parameter 'newId' then returns true. It returns false otherwise.

Remarks

Each command list can store a user defined ID. The command list object knows nothing about it, it only stores one. This ID can be used for indicating the current owner of the command list and deciding whether partial or full state update is needed when recording commands into the list.

When the command list gets flushed then the user defined ID is set to zero.

Requirements

Header: ID3D12Root.hpp


ID3D12GraphicsCommandListAuto::GetFenceValue

ID3D12GraphicsCommandListAuto::GetFenceValue

This method returns the fence value associated with the command list.

UINT64     GetFenceValue ();

Return value

Always a valid fence value. Default is 0.

Remarks

Auto type command lists always have a fence and manage it automatically. For auto type command lists this method returns the fence value that the fence will be updated to when the execution of the currently recorded commands are finised by the GPU.

Requirements

Header: ID3D12Root.hpp


ID3D12GraphicsCommandListAuto::AGetLastFlushFenceValue

ID3D12GraphicsCommandListAuto::AGetLastFlushFenceValue

This method returns the fence value that the associated fence was updated to when the command list was flushed last time.

UINT64     AGetLastFlushFenceValue ();

Return value

Always a valid fence value. Default is 0.

Remarks

Auto type command lists always have a fence and manages it automatically. When an auto type command list is flushed then the associated fence object will update to the associated fence value when the execution of the command list is finished by the GPU. This method returns the last used value which is not necessarily the same as the "current one-1" so do not make assumptions about it.

Requirements

Header: ID3D12Root.hpp


ID3D12GraphicsCommandListAuto::AGetFence

ID3D12GraphicsCommandListAuto::AGetFence

This method returns the fence object associated with the auto type command list.

ID3D12Fence*     AGetFence ();

Return value

Always a valid fence interface pointer.

Remarks

Each command list can have an associated fence and a fence value. Auto type command lists always have a fence and manage it automatically. When an auto type command list is flushed then the associated fence object will update to the associated fence value when the execution of the command list is finished by the GPU.

Requirements

Header: ID3D12Root.hpp


ID3D12GraphicsCommandListAuto::AFlush

ID3D12GraphicsCommandListAuto::AFlush

This method closes the internal command list and submits it to execution.

bool     AFlush  (
    bool waitForCompletion = false
    );

Parameters

waitForCompletion
[in] Whether to wait for the GPU to execute the complete command list before the method returns

Return value

True if the command list is flushed. False if it is a locked state and the flush has failed.

Remarks

Submitting short command lists to execution heavily degrades performance. You should only use this method in a reasonable case like transitioning a resource between different command lists, like the auto type copy- and graphics-command list. Let the the command list and the D3D12 backend themselves handle the flush operation otherwise.

Calling this method with waiting-for-completion is useful and very recommended only at cleanup time: if you have resources to be released that are not tracked by the D3D12 backend system so it is needed to flush an auto type command list to finish the GPU work scheduled for them then you can make sure about it by this way, for a safe release. Keep in mind that waiting for completion is a very slow operation, if you call it frequently then it will drastically degrade the performance.

Requirements

Header: ID3D12Root.hpp


ID3D12GraphicsCommandListAuto::AFlushLock

ID3D12GraphicsCommandListAuto::AFlushLock

This method increments the flush-lock counter.

void     AFlushLock ();

Remarks

An auto type command list has an internal flush-lock counter. The command list can only be flushed when the counter is zero (which is the default value). You can use this method to prevent the command list from getting flushed out when recording your commands. By this way you can make sure that all of your commands recorded between an AFlushLock and AFlushUnlock call will form a continuous block in the command list and they won't be interrupted and corrupted by a flush. Since the flush-lock is counter based, nesting of AFlushLock/AFlushUnlock calls (blocks) are possible and it is a usual scenario in practice. But make sure to always call AFlushUnlock for each AFlushLock and do not let the counter to get stuck into a non-zero state because then the command list cannot be flushed anymore.

Requirements

Header: ID3D12Root.hpp


ID3D12GraphicsCommandListAuto::AFlushUnlock

ID3D12GraphicsCommandListAuto::AFlushUnlock

This method decrements the flush-lock counter and tries a forced flush if it is required.

void     AFlushUnlock (
    bool forceFlush = false
    );

Parameters

forcFlush
[in] Whether to initiate a flush operation after decreasing the flush-lock counter

Remarks

An auto type command list has an internal flush-lock counter. The command list can only be flushed when the counter is zero (which is the default value). You should call this method to restore the flush-prevention state to the previous one, when AFlushLock was called. If parameter forceFlush is true then the auto command list object tries to flush the internal command list (close it and submit it to execution) but it will only succeed if the flush-lock counter reaches zero. If it is not zero after the decrement then the flush operation will simply be ignored.

Requirements

Header: ID3D12Root.hpp


ID3D12GraphicsCommandListAuto::HIUpdateSubBuffer

ID3D12GraphicsCommandListAuto::HIUpdateSubBuffer

This is a helper method to load data from system memory to a buffer type D3D12 resource resided in video memory.

bool     HIUpdateSubBuffer (
    ID3D12Resource* pMADBuffer,
    ID3D12HeapPageAllocator* pAllocator,
    UInt32 begin,
    UInt32 end,
    const void* pSrcData,
    bool setToUnmappedState = false
    );

Parameters

pMADBuffer
[in] The D3D12 buffer to upload data to
pAllocator
[in] A page allocator to use for the operation
begin
[in] The offset of start of the destination range in the buffer in bytes
end
[in] The offset of end of the destination range in the buffer in bytes
pSrcData
[in] Pointer to the user data to upload
setToUnmappedState
[in] See remarks

Return value

If the operation is successful then it returns true or false otherwise.

Remarks

This method resembles ID3D11DeviceContext::UpdateSubResource from D3D11 but it is restricted to buffer type resources. Also, this method only records commands into the command list performing the upload operation so the effective data upload will be executed when the command list is flushed (it is the general case, but see below). The data pointed by pSrcData do not have to remain valid after the method returns because it copies the data to an area allocated by the page allocator.

The D3D12 backend can handle UMA and NUMA GPU architectures separately. On UMA systems the video memory can be mapped into the CPU address space and can be manipulated directly. If this method detects that pMADBuffer (MAD - memory architecture dependent) is a mappable resource (allocated on a heap with type D3D12_HEAP_TYPE_CUSTOM) then it first waits for the GPU to finish on the resource and then maps it (if it weren't already) and copies the user data into it directly with the CPU. The last parameter setToUnmappedState tells the method whether resource should be unmapped after the copy or remain in mapped state. Since the persistent mapped state is the suggested usage in D3D12 the method will not unmap the resource by default. If the resource is not allocated on a mappable heap then the upload is done on the GPU when the command list gets flushed and being executed.

Requirements

Header: ID3D12Root.hpp


ID3D12GraphicsCommandListAuto::HIUpdateSubTexture

ID3D12GraphicsCommandListAuto::HIUpdateSubTexture

This is a helper method to load data from system memory to a texture type D3D12 resource resided in video memory.

bool     HIUpdateSubTexture (
    ID3D12Resource* pMADTexture,
    UInt32 dstSubResIdx,
    ID3D12HeapPageAllocator* pAllocator,
    const D3D12_BOX& dstBox,
    UInt32 srcPitch,
    UInt32 srcDepth
    );

Parameters

pMADTexture
[in] The D3D12 texture resource
dstSubResIdx
[in] The index of the subresource of the texture to upload data to
pAllocator
[in] A page allocator to use for the operation
dstBox
[in] The box describing the destination in the subresource
srcPitch
[in] The distance between two consecutive lines in bytes in the src data
srcDepth
[in] The distance between two consecutive depth-slices in bytes (3D textures) in the src data

Return value

If the operation is successful then it returns true or false otherwise.

Remarks

This method resembles ID3D11DeviceContext::UpdateSubResource from D3D11 but it is restricted to texture type resources. Also, this method only records commands into the command list performing the upload operation so the effective data upload will be executed when the command list is flushed (it is the general case, but see below). The data pointed by pSrcData do not have to remain valid after the method returns because it copies the data to an area allocated by the page allocator.

The D3D12 backend can handle UMA and NUMA GPU architectures separately. On UMA systems the video memory can be mapped into the CPU address space and can be manipulated directly. If this method detects that pMADTexture (MAD - memory architecture dependent) is a mappable resource (allocated on a heap with type D3D12_HEAP_TYPE_CUSTOM) and also, the texture format is not planar, then it first waits for the GPU to finish on the resource and then maps it (if it weren't already) and copies the user data into it directly with the CPU through graphics driver functions. If the resource is not allocated on a mappable heap or has a planar format (like depth with stencil) then the upload is done on the GPU when the command list gets flushed and being executed.

Requirements

Header: ID3D12Root.hpp


Functions

Functions

This section contains reference information for Addon funtions:

  • AddonInit
  • AddonExit


AddonInit

AddonInit

This is a mandatory public entry point in the addon that gets called when dgVoodoo is being activated by initializing the 'first' graphics API.

bool	API_EXPORT 	AddonInit (
    dgVoodoo::IAddonMainCallback* pAddonMain
);

Parameters

pAddonMain
[in] A pointer to dgVoodoo's main callback interface IAddonMainCallback

Return value

If the addon initialization is successful then it should return true.

If the addon initialization fails and this function return false then the addon dll is unloaded and ignored until it gets loaded again because of a subsequent round of dgVoodoo activation.

Remarks

If multiple graphics API's are initialized subsequently, for e.g. DirectDraw and later Glide, then this entry point will only be called when the first API is initialized in the row because that is the time when dgVoodoo is activated.

Requirements

Header: AddonDefs.hpp


AddonExit

AddonExit

This is a mandatory public entry point in the addon that gets called when dgVoodoo is being deactivated by shutting down the 'last' graphics API.

void	API_EXPORT 	AddonExit ();

Remarks

If multiple graphics API's are initialized subsequently, then this entry point only gets called when the last active API is being shut down because that is the point where dgVoodoo is deactivated.

Requirements

Header: AddonDefs.hpp


Structures

Structures

This section contains reference information for API structures:

  • ID3D12RootObserver::PresentBeginContextInput
  • ID3D12RootObserver::PresentBeginContextOutput
  • ID3D12RootObserver::PresentEndContextInput
  • ID3D12Root::SwapchainData
  • ID3D12Root::GraphicsPLDesc
  • ID3D12Root::ComputePLDesc
  • ID3D12Root::SwapchainProxyTextureData
  • ID3D12ResourceDescRingBuffer::AllocData


ID3D12RootObserver::SwapchainDrawingTarget

ID3D12RootObserver::SwapchainDrawingTarget

This structure describes the swapchain texture drawing target data for a D3D12 swapchain. This structure is part of ID3D12RootObserver::PresentBeginContextInput and ID3D12RootObserver::PresentEndContextInput

struct SwapchainDrawingTarget
{
    RECT                          dstRect;
    ID3D12Resource*               pDstTexture;
    D3D12_CPU_DESCRIPTOR_HANDLE   rtvCPUHandle;
    UINT                          dstTextureState;
};

Remarks

This structure always contains a valid non-NULL rendertarget for ID3D12RootObserver::D3D12SwapchainPresentEnd observer method. It may or may not contain a valid rendertarget for ID3D12RootObserver::D3D12SwapchainPresentBegin.

Requirements

Header: ID3D12RootObserver.hpp


ID3D12RootObserver::PresentBeginContextInput

ID3D12RootObserver::PresentBeginContextInput

This structure contains information about the default input of the D3D12 backend presenter system and also, a suggested destination texture with a destination rect to draw into (the drawing target) if no additional postprocess operation is needed for the presentation. This is an input structure for the D3D12 presentation callback method ID3D12RootObserver::D3D12SwapchainPresentBegin

struct PresentBeginContextInput
{
    ID3D12Swapchain*                 pSwapchain;
    SwapchainDrawingTarget           drawingTarget;

    RECT                             srcRect;
    ID3D12Resource*                  pSrcTexture;
    D3D12_CPU_DESCRIPTOR_HANDLE      srvCPUHandle;
    UINT                             srcTextureState;
};

Remarks

If a suggested destination texture is available then the dimensions of SwapchainDrawingTarget::dstRect does not necessarily have the same dimensions as SwapchainData::imagePresentationSize because dstRect is calculated from the aspect ratio of the source rect to present.
If the aspect ratio of the source rect is the same as that of the image presentation size then dstRect has the same dimensions as imagePresentationSize but not otherwise.

Requirements

Header: ID3D12RootObserver.hpp


ID3D12RootObserver::PresentBeginContextOutput

ID3D12RootObserver::PresentBeginContextOutput

This structure contains information about the overridden input of the D3D12 backend presenter system This is an output structure for the D3D12 presentation callback method ID3D12RootObserver::D3D12SwapchainPresentBegin

struct PresentBeginContextOutput
{
    ID3D12Resource*                  pOutputTexture;
    D3D12_CPU_DESCRIPTOR_HANDLE      outputTexSRVCPUHandle;
    UINT                             outputTextureExpectedState;
};

Remarks

If outputTextureExpectedState is set to -1 then the presenter system won't transition pOutputTexture into any state, leaving it in an unknown state.

Requirements

Header: ID3D12RootObserver.hpp


ID3D12RootObserver::PresentEndContextInput

ID3D12RootObserver::PresentEndContextInput

This structure contains information about a valid drawing target for the ID3D12RootObserver::D3D12SwapchainPresentEnd callback method.

struct PresentEndContextInput
{
    ID3D12Swapchain*                 pSwapchain;
    SwapchainDrawingTarget           drawingTarget;
};

Requirements

Header: ID3D12RootObserver.hpp


ID3D12Root::SwapchainData

ID3D12Root::SwapchainData

This structure describes some basic properties of a D3D12 swapchain.

struct SwapchainData
{
    SIZE                 imageSize;
    SIZE                 imagePresentationSize;
    DXGI_FORMAT          format;
    SIZE                 maxOverriddenInputTextureSize;
};

Remarks

imageSize is the size of the image presentable through the swapchain. You can expect source textures with this size in the presentation callback.

imagePresentationSize is the potentially scaled size of the image for the presentation. You can consider this size as the scaled size of the swapchain.

An addon can override the default input of the D3D12 backend presenter with an arbitrary size texture in ID3D12RootObserver::D3D12SwapchainPresentBegin. However, if the texture is too big then the presenter may not able to apply the mipmapping step in the presentation process and the downsampled image will suffer information loss. maxOverriddenInputTextureSize is the maximum size guaranteeing no information loss for downscaling.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GraphicsPLDesc

ID3D12Root::GraphicsPLDesc

This structure resembles the original graphics pipeline structure D3D12_GRAPHICS_PIPELINE_STATE_DESC from D3D12 but some sub-descriptor structures are referenced by plain pointers here and the shaders are referenced by ID3DBlob objects instead of plain pointers. You can feed this structure to the caching system of the D3D12 backend system to get a "stock" shared graphics pipeline object for rendering usage. See ID3D12Root::PLCacheGetGraphicsPipeline.

struct GraphicsPLDesc
{
    ID3D12RootSignature*                pRootSignature;
    ID3DBlob*                           pVS;
    ID3DBlob*                           pPS;
    ID3DBlob*                           pDS;
    ID3DBlob*                           pHS;
    ID3DBlob*                           pGS;
    D3D12_STREAM_OUTPUT_DESC*           pStreamOutput;
    D3D12_BLEND_DESC*                   pBlendState;
    UINT                                SampleMask;
    D3D12_RASTERIZER_DESC*              pRasterizerState;
    D3D12_DEPTH_STENCIL_DESC*           pDepthStencilState;
    D3D12_INPUT_LAYOUT_DESC*            pInputLayout;
    D3D12_INDEX_BUFFER_STRIP_CUT_VALUE  IBStripCutValue;
    D3D12_PRIMITIVE_TOPOLOGY_TYPE       PrimitiveTopologyType;
    UINT                                NumRenderTargets;
    DXGI_FORMAT                         RTVFormats[8];
    DXGI_FORMAT                         DSVFormat;
    DXGI_SAMPLE_DESC                    SampleDesc;
    UINT                                NodeMask;
    D3D12_PIPELINE_STATE_FLAGS          Flags;
};

Remarks

If a structure or ID3DBlob pointer in this structure becomes invalid for any reason or the root signature is about to be released then you must notify the D3D12 caching system about it. See ID3D12Root::GPL*Released methods.

You can also get stock pointers for the descriptor structures by the ID3D12Root::PLCacheGet*Desc methods.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::ComputePLDesc

ID3D12Root::ComputePLDesc

This structure resembles the original compute pipeline structure D3D12_COMPUTE_PIPELINE_STATE_DESC from D3D12 but the shader is referenced by a ID3DBlob object instead of a plain pointer. You can feed this structure to caching system of the D3D12 backend system to get a "stock" shared compute pipeline object for dispatching usage. See ID3D12Root::PLCacheGetComputePipeline.

struct ComputePLDesc
{
    ID3D12RootSignature*                pRootSignature;
    ID3DBlob*                           pCS;
    UINT                                NodeMask;
    D3D12_PIPELINE_STATE_FLAGS          Flags;
};

Remarks

If the ID3DBlob pointer in this structure becomes invalid or the root signature is about to be released for any reason then you must notify the D3D12 caching system about it. See ID3D12Root::CPL*Released methods.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::SwapchainProxyTextureData

ID3D12Root::SwapchainProxyTextureData

This structure describes some basic properties of a proxy texture associated to a D3D12 swapchain.

struct SwapchainProxyTextureData
{
    ID3D12Resource*                pTexture;
    UINT                           texState;
    D3D12_CPU_DESCRIPTOR_HANDLE    srvHandle;
    D3D12_CPU_DESCRIPTOR_HANDLE    rtvHandle;
    DXGI_FORMAT                    rtvFormat;
};

Remarks

texState defines the current (scheduled in a command list) resource state of the swapchain texture. It can vary when querying this data more than once, depending on the usage of the texture between the query calls. rtvFormat is always the same as the swapchain format.

Requirements

Header: ID3D12Root.hpp


ID3D12ResourceDescRingBuffer::AllocData

ID3D12ResourceDescRingBuffer::AllocData

This structure describes the allocation data coming from a resource descriptor ring buffer. See ID3D12ResourceDescRingBuffer::Alloc.

struct AllocData
{
    D3D12_GPU_DESCRIPTOR_HANDLE     gpuDescHandle;
    D3D12_CPU_DESCRIPTOR_HANDLE     cpuDescHandle;
    ID3D12DescriptorHeap*           pHeap;
    UInt32                          incrementSize;
};

Requirements

Header: ID3D12Root.hpp


ID3D12Buffer::LockData

ID3D12Buffer::LockData

This structure describes the allocation data coming from a buffer object. See ID3D12Buffer::Lock.

struct LockData
{
    UInt64            gpuAddress;
    void*             ptr;
    ID3D12Resource*   pBuffer;
};

Requirements

Header: ID3D12Root.hpp


Enumerations

Enumerations

This section contains reference information for API enumerations:

  • ID3D12Root::DynamicAllocator
  • ID3D12Buffer::LockType


ID3D12Root::DynamicAllocator

ID3D12Root::DynamicAllocator

This enumeration defines the stock dynamic (video) memory allocator types of the D3D12 backend.

enum DynamicAllocator
{
     DA_RingAllocator                      = 0,
     DA_ConstBufferPageHeapAllocator,
     DA_VertexBufferPageHeapAllocator,
     DA_IndexBufferPageHeapAllocator,
     DA_UploadBufferPageHeapAllocator,
     DA_ReadbackBufferPageHeapAllocator
};

Requirements

Header: ID3D12Root.hpp


ID3D12Buffer::LockType

ID3D12Buffer::LockType

This enumeration defines a lock and memory allocation type for a buffer object. See ID3D12Buffer::Lock.

enum LockType
{
     LT_Default                      = 0,
     LT_NoOverwrite,
     LT_Discard
};

Requirements

Header: ID3D12Root.hpp


API Library for dgVoodoo Version 2.8

API Library for dgVoodoo Version 2.8

Previous API Library versions are compatible with dgVoodoo 2.8.

This version contains the following components that you can utilize in your application:

  • Control Panel DDI interfaces (ICPLDDI)
  • dgVoodoo config file read/write interfaces (IConfig)
  • INI Parser interfaces (IINIParser)

The implementation of those C++ interfaces are compiled into a dll (dgVoodooAPI.dll).

dgVoodoo components rely on those interfaces too, but they are linked statically against the library.


Overview

dgVoodoo API Library documentation
Overview

API Library Overview

This section contains a (very) short overview for API Library.

API Library is intended for developers/modders who would like to distribute their patched games or other stuffs bundled with dgVoodoo
and go beyond the possibilities the CPL configuration utility provides, by their custom configuration frontends.

So, this version of the library provides access to 3 main separate areas as of the functionality:

  • Reading, writing and validating dgVoodoo configuration files (or, I'd say property sets)
  • Getting information about the underlying graphics hardware and their display outputs
  • A general parser for INI-property sets for optional custom usage

The structure of the API consists of

  • Some functions for initializing/shutting down the library
  • Instanced objects with pure C++ interfaces (similar to Microsoft's COM - but these are not COM objects)
  • Structures and enumerations within structures for describing various data

Overview topics:

  • Initializing and shutting down the library
  • Configuration data and its input/output
  • Information for graphics hardware and display outputs
  • INI parser


Library version, initializing and shutting down

Library version, initializing and shutting down

  • Altough you know what version of the library you are coding your stuff for, you may need to make sure about the correct version.
    Simply call dgVoodoo_API_GetVersion to query the library version.
    This function can be called without initializing the library itself.

  • The very first thing you need to do is initialize the library before doing anything else.
    Function dgVoodoo_API_Init both initializes the library and returns an interface pointer to the singleton object IMainFactory.
    You can reach out and create other object instances through that factory object. If library init fails then NULL pointer is returned and you cannot continue.

  • After you finished with the library and released all instances of created objects, you must call function dgVoodoo_API_Exit to avoid memory and resource leaks.


Configuration data and its input/output

Configuration data and its input/output

dgVoodoo's configuration data is simply stored in a structure. The main structure consists of more sub-structures for various classes of dgVoodoo's configurable data.
Sub-structuring reflects the sections of the INI format and the tab pages of the CPL. The CPL however does not exposes all the sections of the configuration.

This data structure has its own inline default constructors, so if you simply declare

dgVoodoo::Config config;
then you have a config instance containing dgVoodoo's default configuration.
There are no functions or methods for modifying the elements of the structure. You can access its members directly, for example
dgVoodoo::Config config;

config.general.centerAppWindow = true;
config.directX.cardType = dgVoodoo::ConfigDirectX::Geforce4Ti4800;

I think structure members and its valid values are mostly clear and self-speaking, except the following areas:
  • Ordinals of graphics adapters and display outputs.
    Adapters and outputs are enumerated on a local system, so their ordinals can change machine by machine.
    Say, if a system has two graphics adapters then the ordinal of the first is 1 and the ordinal of the second is 2.
    This value is written to ConfigGeneral::rendererDevice. 0 means 'AdapterAll' and this is the default.
    It's not recommended at all to distribute a config file with a non-0 adapter ordinal because dgVoodoo may fail to initialize on other systems that have less graphics adapters available than the ordinal defines.
    Always let the user change it locally on his/her system if it needed at all.

    Ordinals of display outputs in fact is defined in the same way.
    Say, a system has one graphics adapter with two monitors attached to it, then ordinals are the following:
    • Adapter ordinal: 1
    • Monitor1 ordinal: 1
    • Monitor2 ordinal: 2
    Monitor ordinal is written to ConfigGeneral::renderingOutput.
    Value 0 means 'default'. It's recommended to handle display output ordinals in the same way as adapter ordinals, for the same reason.
    A given display output is always identified in a unique way only by a pair of (adapter ordinal, output ordinal).
  • Members describing resolution and refresh rate (for both Glide and DirectX)
    Defining a resolution is simple: just write the desired horizontal and vertical values into Config*::resWidth and Config*::resHeight.
    There are however special values for unforced and dynamic resolutions. Enumeration ConfigGeneral::Resolution defines them.
    For defining such a special resolution value, just write the desired enumeration value into the resolution members, like
    config.directX.resWidth = config.directX.resHeight = dgVoodoo::ConfigGeneral::R_Max_ISF;

    All dynamic resolutions can have an additional integer scaling parameter. If you want it to be other than the default 1, you can define it in the height parameter. Values between 0 and 255 are valid:
    config.directX.resWidth = dgVoodoo::ConfigGeneral::R_MaxFHD;
config.directX.resHeight = 2;
    Note that this integer scale parameter is mandatory for dynamic resolution R_IntegerScaled. So, you always have to define it in the following way (for e.g. 3x application resolution):
    config.directX.resWidth = dgVoodoo::ConfigGeneral::R_IntegerScaled;
config.directX.resHeight = 3;

    Refresh rates are defined in rational form instead of a single integer value, to describe the monitor refresh rate as precisely as possible.
    For example, for a monitor having refresh rate of 60.01 Hz, this value can be defined as 6001/100, so the appropriate structure members are filled like this:
    config.directX.refRateNumerator = 6001;
config.directX.refRateDenominator = 100;
    You always obtain supported refresh rate values through an ICPLDDI object.

    Extra enumerable resolutions for DirectX can also have special values max, max_4_3 and max_16_9 defining the desktop resolution itself and maximum resolutions calculated from the desktop resolution with 4:3 and 16:9 aspect ratios, respectively.
    Fill the members like
    config.directX.extraResolutions[0].width = dgVoodoo::ConfigGeneral::R_Max;
config.directX.extraResolutions[0].height = dgVoodoo::ConfigGeneral::R_Max;
    and
    config.directX.extraResolutions[0].width = dgVoodoo::ConfigGeneral::R_Max;
config.directX.extraResolutions[0].height = dgVoodoo::ConfigGeneral::PR_Max_4_3;
    and
    config.directX.extraResolutions[0].width = dgVoodoo::ConfigGeneral::R_Max;
config.directX.extraResolutions[0].height = dgVoodoo::ConfigGeneral::PR_Max_16_9;
    for defining them.
    Refresh rates for extra resolutions are simple integers because they are user-defined and are not obtained from and ICPLDDI object.
  • Members describing Display ROI
    ROI position can either be defined as a pixel position, like
    config.generalExt.displayROIPosX = 320;
config.generalExt.displayROIPosY = 200;
    or it can be a predefined value, currently one is existing:
    config.generalExt.displayROIPosX = dgVoodoo::ConfigGeneralExt::DROI_Centered;
config.generalExt.displayROIPosY = dgVoodoo::ConfigGeneralExt::DROI_Centered;

    ROI size can either be defined as a pixel size, like
    config.generalExt.displayROISizeX = 640;
config.generalExt.displayROISizeY = 400;
    or it can be a proportion (size X / size Y), say, defining a 21:9 aspect ratio is done like this:
    config.generalExt.displayROISizeX = dgVoodoo::ConfigGeneralExt::DROI_Rational;
config.generalExt.displayROISizeY = (21L << 16) | (9L << 0);

For managing configuration data input/output, you must query the interface of the singleton IConfig object.
There are some variants of methods for data reading and writing, including reading/writing from/to file, file handle and custom implemented streams.
A short example for a simple config data modification:
dgVoodoo::IConfig* pConfig = pMainFactory->GetIConfig ();
if (pConfig != NULL) {

    dgVoodoo::Config config;
    if (pConfig->ReadConfig (config, "myconfigfile.conf")) {

        config.directX.resWidth = 1280;
        config.directX.resHeight = 1024;

        if (pConfig->WriteConfig (config, "myconfigfile.conf", NULL)) {
            // we are happy - just modified DirectX resolution to 1280x1024
        }
    }
}
The example above reads a dgVoodoo configuration from file "myconfigfile.conf" which can be either an INI-format or a binary one.
Some structure members are modified and the configuration is written back to the same file.
Write method writes binary format in this case because NULL pointer is defined for the INI-template.

Hmm... how to write an INI format config file? If you are happy with dgVoodoo's default template then just query it from IConfig:

// This function shouldn't return NULL - but if it does, then the written config file will just be binary

const char* pIniTemplate = pConfig->GetINITemplate ();

if (pConfig->WriteConfig (config, "myconfigfile.conf", pIniTemplate)) {
    // succeeded
}
Well, it's a bit lame for the time being, but IConfig can only write INI format through templates that contains all the properties that the default template does and their order must even match.
In other words, you can only create your own template by removing/adding comments to the default template. There is no way to write partial INI property set through IConfig.

Sometimes you may want to ensure that your Config data structure contains valid values and you aren't working with some garbage.
IConfig::ValidateConfig tells you the answer. Originally I intended that method for debugging purposes so the debug layer gives you extended feedback about the detected problems.

And at last, there is a utility method. IConfig::IsResolutionTypeDynamic tells you if a resolution is dynamic or static.

if (pConfig->IsResolutionTypeDynamic (config.glide.resWidth, config.glide.resHeight)) {
    // don't display the values to the user - needs more interpretation
} else {
    // resWidth and resHeight contains single values immediately
}


Control Panel DDI (CPLDDI)

Control Panel DDI (CPLDDI)

You can use CPL DDI object interface to query information about the underlying graphics hardware, the attached display outputs and their supported resolutions and MSAA levels.
A CPL DDI object is API-specific. All the information queried is coming from the API that the CPL DDI objects is backed by.
CPL DDI objects are singletons and interface pointers can be queried for them through IMainFactory.

CPL DDI objects can be in activated and inactivated state. When activated, its backing API (e.g. Direct3D11) is initialized and is in usage. Only one CPL DDI object can be active at a time, to avoid conflicts between multiple backing API's.
When a CPL DDI object becomes activated then all the information like available adapters, display outputs and resolutions are (re)collected.
All kind of objects are accessible through indexing. You just retrieve the number of the objects of the required type and reference to them as indexes from 0 to (num-1).

  • Adapter: denotes a video card (or an integrated GPU) that can have display outputs attached to it.
  • Display output: denotes a monitor or any other device that can display output image coming from the adapter. A display output is identified as a pair of (adapter index, output index).
  • Resolution: A list of supported resolutions is always specific to a display output.
  • MSAA level: A list of supported MSAA levels is always specific to an adapter.

For more, see the sample application.


IniParser

IniParser

INI property sets are textual (ASCII) data containing

  • Properties: consist of a name and zero or more values and zero or more subproperties
  • Sections: Named subsets of properties for grouping; each property name is only unique in the section in which it's declared
IniParser objects provide functionality for
  • parsing data containers (file or custom implemented stream) as INI property sets and storing parsed data
  • querying the parsed and stored data set

Format of INI property sets

Sections

  • Each section has a name.
  • When declaring a section, its name must be enclosed by squared brackets.
  • The only exception is the global (default) section that has no name. Empty square brackets denotes the global section.
  • More than one section can be included within a line.

Properties

  • Each property is included in one of the sections.
  • Only one property can be declared within a line.
  • A property can have values and subproperties.
  • A property name is always followed by an equal sign '=' even if the property has no any value or subproperty.
  • Property values are separated by white spaces or commas from each other; Values can be enclosed by quotation marks - its unavoidable if the value contains space characters.
  • Subproperties are enumerated after value items; they also have a name and a mandatory value, separated by a colon without white spaces.

Comments

  • Comment delimiter character is ';'
  • Any character after the delimiter character is treated as comment up to the end of the line

Example

Color1 = BLUE                         ; we have just declared a property named "Color1" with one value, "BLUE" in the global section

[Geometry]
Shapes1 = rectangle, triangle         ; Entering section 'Geometry' and declared 'Shapes1' property with two values, "rectangle" and "triangle"
Shapes2 = "rotated rectangle" circle  ; Declaring 'Shapes2' property with two values, "rotated rectangle" and "circle"
Shapes3 =                             ; Declaring 'Shapes3' property with no values

[Topology] []                         ; Declared empty section 'Topology' and then declared the global section again, returning to that

Color2 = red R:255 G:0 B:0            ; Declared property 'Color2' with one value 'red' and 3 subproperties R, G, B with subproperty values 255, 0, 0 respectively

Using IniParser objects

IniParser objects are instanced objects and any number of them can be created through IMainFactory::CreateINIParser method.
After creation, it contains an empty property set. To fill it with some useful data, you must parse a property set by one of the IIniParser::Parse methods.
Each sections, properties within sections, values within properties and subproperties within properties are referenced by indexing. Use the proper IIniParser methods to query the number of each of them.
When an IniParser object is no longer needed you must release it explicitly by calling its Release method.

Say, we have the property set of the example written to a file 'properties.ini'.
dgVoodoo::IIniParser* pSet = pMainFactory->CreateINIParser ();
if (pSet != NULL) {

    if (pSet->Parse ("properties.ini", dgVoodoo::IIniParser::LowerCase)) {

        // Ok, if method succeeds then format of the file was ok and pSet contains the following set, converted to lower case

        // Number of sections: 3
        // Section 0 name: "" (it's the global section)
        //      Property 0: name "color1", value 0: "blue", no subproperties
        //      Property 1: name "color2", value 0: "red",
        //                  subproperty 0 name: "r", value: "255", subproperty 1 name: "g", value: "0", subproperty 2 name: "b", value: "0"
        // Section 1 name: "geometry"
        //      Property 0: name "shapes1", value 0: "rectangle", value 1: "triangle"
        //      Property 1: name "shapes2", value 0: "rotated rectangle", value 1: "circle"
        //      Property 2: name "shapes3", no values
        // Section 2 name: "topology"
        //      no properties

        // Query the information above with the appropriate methods
    }
    pSet->Release ();
}


Reference

dgVoodoo API Library documentation
Reference

API Library Reference

This section contains reference information for the API elements of API Library.

  • Enumerations
  • Interfaces
  • Functions
  • Structures


Interfaces

Interfaces

This section contains reference information for API interfaces:

  • APIObject
  • IMainFactory
  • IConfig
  • ICPLDDI
  • IIniParser


APIObject

APIObject

Some of the objects created by API Library are inherited from this base interface.

Destruction Release

Requirements

Header: APIObject.hpp
Library: dgVoodooAPI.lib


APIObject::Release

APIObject::Release

Releases the instance of an object inherited from this interface.

void     Release ();

Remarks

Altough this mechanism is similar to IUnkonwn interface of Microsoft's COM, dgVoodoo API objects are not reference counted.
After this method returns, the object instance is deleted and becomes invalid.

Requirements

Header: APIObject.hpp
Library: dgVoodooAPI.lib


IMainFactory

IMainFactory

Applications use this interface either to retrieve pointers to other interfaces or create new objects.

Retrieving interfaces | GetCPLDDIObject
 | GetIConfig
Creating objects | CreateIniParser

Requirements

Header: IMainFactory.hpp
Library: dgVoodooAPI.lib

See Also

dgVoodoo_API_Init


IMainFactory::CreateIniParser

IMainFactory::CreateIniParser

Creates a new instance of an INI property set parser object.

IIniParser*	CreateIniParser (
    const APIDebugObj* pDebug = NULL
);

Parameters

pDebug
[in] Optional debug object. This parameter can be NULL.

Return value

If successful, this function returns a pointer to an IIniParser interface.

NULL pointer is returned otherwise.

Remarks

When the object instance is no longer needed, you must release it explicitly by calling Release method of the object.

Requirements

Header: IMainFactory.hpp
Library: dgVoodooAPI.lib


IMainFactory::GetCPLDDIObject

IMainFactory::GetCPLDDIObject

Returns a pointer to one of the CPL DDI singleton objects.

ICPLDDI*	GetCPLDDIObject (
    ConfigGeneral::RendererAPI api,
    const APIDebugObj* pDebug = NULL
);

Parameters

api
[in] Required API type

 API_Direct3D12_FL12_0
 Direct3D 12 with feature level 12.0

 API_Direct3D12_FL11_0
 Direct3D 12 with feature level 11.0

 API_Direct3D11_FL11_0
 Direct3D 11 with feature level 11.0

 API_Direct3D11_FL10_1
 Direct3D 11 with feature level 10.1

 API_Direct3D11_FL10_0
 Direct3D 11 with feature level 10.0

 API_Direct3D11_MS_WARP_FL10_1
 Direct3D 11 WARP with feature level 10.1

 API_BestAvailable

pDebug
[in] Optional debug object. This parameter can be NULL.

Return value

If successful, this function returns a pointer to an ICPLDDI interface.

NULL pointer can be returned if the required API type is not available for some reason.

Remarks

When defining RendererAPI::API_BestAvailable for the required API then the library returns the interface for the object representing the best API currently available on the system. In this version D3D12 is never chosen automatically because of some known issues that are planned to be resolved in subsequent releases. Also, feature level only defines a minimum for D3D12. Unlike in D3D11, feature levels cannot be forced in D3D12. It always initializes itself at the maximum available that is greater-equal to the specified minimum.

Requirements

Header: IMainFactory.hpp
Library: dgVoodooAPI.lib


IMainFactory::GetIConfig

IMainFactory::GetIConfig

Returns a pointer to the singleton object providing functionality for handling dgVoodoo config files.

IConfig*	GetIConfig ();

Return value

A pointer to the config file handling IConfig object. This method always succeeds.

Remarks

Requirements

Header: IMainFactory.hpp
Library: dgVoodooAPI.lib


ICPLDDI

ICPLDDI

Applications use this interface to retrieve information about the underlying graphics hardware and display outputs.

Activation | Activate
 | Deactivate
Information | GetAPIName
 | GetAPI
 | GetAPIType
 | GetAdapterName
 | GetNumberOfAdapters
 | GetNumberOfMSAALevels
 | GetNumberOfOutputs
 | GetNumberOfResolutions
 | GetMSAALevel
 | GetOutputDesc
 | GetRefreshRateSimple
 | GetResolution

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


ICPLDDI::Activate

Activates a CPL DDI object which means enumerating all the adapters (GPU's) that are available through the API type the object representing.
Also, all the additional information like attached display outputs, supported resolutions and MSAA levels are collected.

bool	Activate ();

Return value

Returns true if object activation is successful and there is at least one system adapter supporting the given API.

Returns false in the following cases (and the object remains unactivated):

  • Another CPL DDI object is currently being active
  • There is no any adapter supporting the given API
  • Initializing the API fails for some reasons

Remarks

Only one CPL DDI object can be in activated state at a time.

When a CPL DDI object gets activated then potential changes in the state of available adapters and their outputs since the last activation are detected and information is recollected.
For example, if a display output is removed from one of the adapters then reactivating the CPL DDI takes it into account.

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


ICPLDDI::Deactivate

ICPLDDI::Deactivate

Deactivates a CPL DDI object representing a given API type.

void	Deactivate ();

Return value

This method has no return value.

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


ICPLDDI::GetAdapterName

ICPLDDI::GetAdapterName

Returns the name of the adapter.

bool   GetAdapterName (
    UInt32 adapterIdx,
    WCHAR* pName
);

Parameters

adapterIdx
[in] Index of the adapter
pName
[out] Pointer to a buffer to be filled with a zero terminated string.

Return value

Returns true if the method succeeds.
If adapterIdx is out of range or pName is invalid then returns false.

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


ICPLDDI::GetAPIName

ICPLDDI::GetAPIName

Returns the name of the API the object is representing.

const char*    GetAPIName ()

Return value

A const pointer to a zero terminated ASCII string.

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


ICPLDDI::GetAPI

ICPLDDI::GetAPI

Returns the API the object is representing.

ConfigGeneral::RendererAPI          GetAPI ();

Return value

One of the elements of enumeration ConfigGeneral::RendererAPI.

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


ICPLDDI::GetAPIType

ICPLDDI::GetAPIType

Returns the API type the object is representing. This method is changed compared to previous API versions.

APIType          GetAPIType ();

Return value

One of the elements of enumeration ICPLDDI::APIType.

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


ICPLDDI::GetMSAALevel

ICPLDDI::GetMSAALevel

Returns a supported MSAA level.

UInt32     GetMSAALevel (
    UInt32 adapterIdx,
    UInt32 idx
);

Parameters

adapterIdx
[in] Index of the adapter
idx
[in] Index of the MSAA level to be queried

Return value

If the method succeeds then the level of MSAA.
Zero if adapterIdx or idx is out of range.

Remarks

Returned integer represents an MSAA level. For example, 2 represents 2x MSAA, 4 is 4x MSAA, and so forth.
dgVoodoo supports 16x as a maximum.
Value 1 means no MSAA which is always supported so it is not enumerated by this method.
Value 0 is an invalid MSAA level meaning an error.

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


ICPLDDI::GetNumberOfAdapters

ICPLDDI::GetNumberOfAdapters

Returns the number of adapters that are accessible through this object.

UInt32     GetNumberOfAdapters ();

Return value

Number of adapters. Adapters can be indexed from 0 to (number of adapters)-1.

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


ICPLDDI::GetNumberOfMSAALevels

ICPLDDI::GetNumberOfMSAALevels

Returns the number of MSAA levels supported by the adapter.

UInt32     GetNumberOfMSAALevels (
    UInt32 adapterIdx
);

Parameters

adapterIdx
[in] Index of the adapter

Return value

If adapterIdx is valid then number of supported MSAA levels.
Zero if adapterIdx is out of range.

Remarks

MSAA levels can be indexed from 0 to (number of MSAA levels)-1.

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


ICPLDDI::GetNumberOfOutputs

ICPLDDI::GetNumberOfOutputs

Returns the number of display outputs that are attached to the adapter.

UInt32     GetNumberOfOutputs (
    UInt32 adapterIdx
);

Parameters

adapterIdx
[in] Index of the adapter

Return value

If adapterIdx is valid then number of attached display outputs.
Zero if adapterIdx is out of range.

Remarks

Display output can be indexed from 0 to (number of outputs)-1.

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


ICPLDDI::GetNumberOfResolutions

ICPLDDI::GetNumberOfResolutions

Returns the number of supported resolutions on the display output attached to an adapter.

UInt32     GetNumberOfResolutions (
    UInt32 adapterIdx,
    UInt32 outputIndex,
    ConfigGeneral::ScanlineOrder scanlineOrder
);

Parameters

adapterIdx
[in] Index of the adapter
outputIndex
[in] Index of the display output
scanlineOrder
[in] Scan line ordering mode

Return value

If the method succeeds then the number of supported resolutions.
Zero if adapterIdx or outputIndex is out of range or scanlineOrder is invalid.

Remarks

Resolutions can be indexed from 0 to (number of resolutions)-1.
Scan line ordering can only be

  • SO_OutputDefault: All the resolution supported including interlaced display modes.
  • SO_Progressive: Resolution only that are available with progressive scanline order.

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


ICPLDDI::GetOutputDesc

ICPLDDI::GetOutputDesc

Returns information about a display output attached to the adapter.

bool     GetOutputDesc (
    UInt32 adapterIdx,
    UInt32 outputIdx,
    OutputDesc* pDesc
);

Parameters

adapterIdx
[in] Index of the adapter
outputIdx
[in] Index of the display output
pDesc
[out] Pointer to an OutputDesc structure to be filled with information

Return value

True if the methods succeeds.
False if adapterIdx or outputIdx is out of range or pDesc is invalid.

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


ICPLDDI::GetRefreshRateSimple

ICPLDDI::GetRefreshRateSimple

Returns the simple form of a refresh rate given in rational form.

UInt32     GetRefreshRateSimple (
    UInt32 refRateNumerator,
    UInt32 refRateDenominator
);

Parameters

refRateNumerator
[in] Numerator of the rational form
refRateDenominator
[in] Denominator of the rational form

Return value

Simple (non-rational) form of a refresh value.

Remarks

This is a utility method for converting refresh rates from rational to single form.

0/0 and 0/1 are valid and their simple form is 0. Value 0 denotes undefinied refresh rate.

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


ICPLDDI::GetResolution

ICPLDDI::GetResolution

Returns information about a display mode.

bool     GetResolution (
    UInt32 adapterIdx,
    UInt32 outputIdx,
    UInt32 resIdx,
    ConfigGeneral::ScanlineOrder scanlineOrder,
    ModeDesc* pDesc
);

Parameters

adapterIdx
[in] Index of the adapter
outputIdx
[in] Index of the display output
resIdx
[in] Index of the display mode
scanlineOrder
[in] Mode of the scanline ordering - this parameter denotes the resolution list to return information from
pDesc
[out] Pointer to an ModeDesc structure to be filled with information

Return value

True if the methods succeeds.
False if adapterIdx, outputIdx or resIdx is out of range or scanlineOrder, pDesc is invalid.

Remarks

Resolutions can be indexed from 0 to (number of resolutions)-1.
Parameter scan line ordering selects the display mode list to pick up a resolution from

  • SO_OutputDefault: All the resolution supported including interlaced display modes.
  • SO_Progressive: Resolution only that are available with progressive scanline order.

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


IConfig

IConfig

Applications use this interface to read and write dgVoodoo configuration structures.

Read | Read (file, c-string)
 | Read (file, widechar-string)
 | Read (handle)
 | Read (stream)
Write | Write (file, c-string)
 | Write (file, widechar-string)
 | Write (handle)
 | Write (stream)
Miscellaneous | GetINITemplate
 | IsResolutionTypeDynamic

Requirements

Header: IConfig.hpp
Library: dgVoodooAPI.lib


IConfig::GetINITemplate

IConfig::GetINITemplate

Returns the default template of an INI-format config property set.

const char*     GetINITemplate ();

Return value

A const pointer to the template. This can be directly fed into the Write methods.

Requirements

Header: IConfig.hpp
Library: dgVoodooAPI.lib


IConfig::IsResolutionTypeDynamic

IConfig::IsResolutionTypeDynamic

Returns if width/height members of a resolution defines a dynamic resolution.

bool     IsResolutionTypeDynamic (
    UInt32 width,
    UInt32 height
);

Parameters

width
[in] Width of the resolution
height
[in] Height of the resolution

Return value

True if the resolution is a dynamic one. If it is then its values needs further interpretation.

Requirements

Header: IConfig.hpp
Library: dgVoodooAPI.lib


IConfig::ReadConfig

IConfig::ReadConfig

Reads dgVoodoo configuration from a file.

bool     ReadConfig (
    Config& toConfig,
    const char* pFileName,
    const APIDebugObj* pDebug = NULL
);

Parameters

toConfig
[out] Reference to a Config structure to read the configuration into
pFileName
[in] Zero terminated c-string of the file path to read from
pDebug
[in] Optional Debug object to use for debug output. This parameter can be NULL.

Return value

True if the methods succeeds, false if pFileName is invalid or some error occured during the read.

Remarks

This method can read both binary and INI version of config files, file denoted by pPFilename can be of both type. All config file versions from 2.5 to current version are supported.

Requirements

Header: IConfig.hpp
Library: dgVoodooAPI.lib


IConfig::ReadConfig

IConfig::ReadConfig

Reads dgVoodoo configuration from a file.

bool     ReadConfig (
    Config& toConfig,
    const wchar_t* pFileName,
    const APIDebugObj* pDebug = NULL
);

Parameters

toConfig
[out] Reference to a Config structure to read the configuration into
pFileName
[in] Zero terminated widechar-string of the file path to read from
pDebug
[in] Optional Debug object to use for debug output. This parameter can be NULL.

Return value

True if the methods succeeds, false if pFileName is invalid or some error occured during the read.

Remarks

This method can read both binary and INI version of config files, file denoted by pPFilename can be of both type. All config file versions from 2.5 to current version are supported.

Requirements

Header: IConfig.hpp
Library: dgVoodooAPI.lib


IConfig::ReadConfig

IConfig::ReadConfig

Reads dgVoodoo configuration from an opened file identified by a file handle.

bool     ReadConfig (
    Config& toConfig,
    HANDLE hFile,
    const APIDebugObj* pDebug = NULL
);

Parameters

toConfig
[out] Reference to a Config structure to read the configuration into
hFile
[in] Handle of the file
pDebug
[in] Optional Debug object to use for debug output. This parameter can be NULL.

Return value

True if the methods succeeds, false if file handle is invalid or some error occured during the read.

Remarks

This method can read both binary and INI version of config files, file identified by hFile can be of both type. All config file versions from 2.5 to current version are supported.
Note that config is always tried to be read from the beginning of the file and the file should contain no other data than the config itself.
Current file position is undefined after the method returns.

Requirements

Header: IConfig.hpp
Library: dgVoodooAPI.lib


IConfig::ReadConfig

IConfig::ReadConfig

Reads dgVoodoo configuration from an IAPIDataStream object.

bool     ReadConfig (
    Config& toConfig,
    IAPIDataStream* pStream,
    const APIDebugObj* pDebug = NULL
);

Parameters

toConfig
[out] Reference to a Config structure to read the configuration into
pStream
[in] The stream to read from
pDebug
[in] Optional Debug object to use for debug output. This parameter can be NULL.

Return value

True if the methods succeeds, false if pStream is invalid or some error occurs during the read.

Remarks

This method can read both binary and INI version of config files, file identified by pStream can be of both type. All config file versions from 2.5 to current version are supported.
Stream should implement GetSize, Seek and Read to succeed. Note that config is always tried to be read from the beginning of the stream and the stream should contain no other data than the config itself.
Current stream position is undefined after the method returns.

Requirements

Header: IConfig.hpp
Library: dgVoodooAPI.lib


IConfig::WriteConfig

IConfig::WriteConfig

Writes dgVoodoo configuration into a file.

bool     WriteConfig (
    const Config& fromConfig,
    const char* pFileName,
    const char* pINITemplate = NULL,
    const APIDebugObj* pDebug = NULL
);

Parameters

fromConfig
[in] Reference to a Config structure to write the configuration from
pFileName
[in] Zero terminated c-string of the file path to write to
pINITemplate
[in] Template of an INI file
pDebug
[in] Optional Debug object to use for debug output. This parameter can be NULL.

Return value

True if the methods succeeds, false if pFileName is invalid or some error occured during the write.

Remarks

This method can write both binary and INI version of config files, versioned to the current library version.
If pINITemplate is NULL then binary version is written. If an INI-template is specified then it must contain all of the configuration properties, in the same order as dgVoodoo default config file.

Requirements

Header: IConfig.hpp
Library: dgVoodooAPI.lib


IConfig::WriteConfig

IConfig::WriteConfig

Writes dgVoodoo configuration into a file.

bool     WriteConfig (
    const Config& fromConfig,
    const wchar_t* pFileName,
    const char* pINITemplate = NULL,
    const APIDebugObj* pDebug = NULL
);

Parameters

fromConfig
[in] Reference to a Config structure to write the configuration from
pFileName
[in] Zero terminated widechar-string of the file path to write to
pINITemplate
[in] Template of an INI file
pDebug
[in] Optional Debug object to use for debug output. This parameter can be NULL.

Return value

True if the methods succeeds, false if pFileName is invalid or some error occured during the write.

Remarks

This method can write both binary and INI version of config files, versioned to the current library version.
If pINITemplate is NULL then binary version is written. If an INI-template is specified then it must contain all of the configuration properties, in the same order as dgVoodoo default config file.

Requirements

Header: IConfig.hpp
Library: dgVoodooAPI.lib


IConfig::WriteConfig

IConfig::WriteConfig

Writes dgVoodoo configuration into a file denoted by a file handle.

bool     WriteConfig (
    const Config& fromConfig,
    const HANDLE* hFile,
    const char* pINITemplate = NULL,
    const APIDebugObj* pDebug = NULL
);

Parameters

fromConfig
[in] Reference to a Config structure to write the configuration from
hFile
[in] Opened handle of a writable file
pINITemplate
[in] Template of an INI file
pDebug
[in] Optional Debug object to use for debug output. This parameter can be NULL.

Return value

True if the methods succeeds, false if hFile is invalid or some error occured during the write.

Remarks

This method can write both binary and INI version of config files, versioned to the current library version.
If pINITemplate is NULL then binary version is written. If an INI-template is specified then it must contain all of the configuration properties, in the same order as dgVoodoo default config file.

Note that data is written to the current file position and its offseted by the size of the written data when the method returns.

Requirements

Header: IConfig.hpp
Library: dgVoodooAPI.lib


IConfig::WriteConfig

IConfig::WriteConfig

Writes dgVoodoo configuration into a file denoted by a file handle.

bool     WriteConfig (
    const Config& fromConfig,
    IAPIDataStream* pToStream,
    const char* pINITemplate = NULL,
    const APIDebugObj* pDebug = NULL
);

Parameters

fromConfig
[in] Reference to a Config structure to write the configuration from
pToStream
[in] Stream object to write to
pINITemplate
[in] Template of an INI file
pDebug
[in] Optional Debug object to use for debug output. This parameter can be NULL.

Return value

True if the methods succeeds, false if hFile is invalid or some error occured during the write.

Remarks

This method can write both binary and INI version of config files, versioned to the current library version.
If pINITemplate is NULL then binary version is written. If an INI-template is specified then it must contain all of the configuration properties, in the same order as dgVoodoo default config file.

Note that data is written to the current stream position. Stream object must implement Write to succeed.

Requirements

Header: IConfig.hpp
Library: dgVoodooAPI.lib


IIniParser

IIniParser

Applications use this interface to parse an INI property set and get its properties and property values. Inherits from APIObject.

Parsing | Parse (file, c-string)
 | Parse (file, widechar-string)
 | Parse (stream)
Sections | GetNumberOfSections
 | GetSectionName
Properties | GetNumberOfProperties
 | GetPropertyName
Property values | GetNumberOfPropertyValues
 | GetPropertyValueAsString
 | GetPropertyValueAsInt
Subproperty values | GetNumberOfSubProperties
 | GetSubPropertyName
 | GetSubPropertyValueAsString
 | GetSubPropertyValueAsInt

Requirements

Header: IIniParser.hpp
Library: dgVoodooAPI.lib


IIniParser::DbgDump

IIniParser::DbgDump

Dumps the entire property set currenty stored in the object.

void     DbgDump ();

Remarks

Dump is written to the current debug output.
Also, this method is only available in Debug and SpecRelease builds and serves only debugging purposes. In Release builds it does nothing.

Requirements

Header: IIniParser.hpp
Library: dgVoodooAPI.lib


IIniParser::Parse

IIniParser::Parse

Parses an INI-format property set from a file and stores them in the object, overwriting the current set.

bool     Parse (
    const char* pFileName,
    StringType* stringType
);

Parameters

pFileName
[in] Zero terminated c-string of the file path to parse from
stringType
[in] StringType method for converting the strings when storing them as a set

Return value

True if the methods succeeds, false if pFileName is invalid or some error occured during parsing.

Requirements

Header: IIniParser.hpp
Library: dgVoodooAPI.lib


IIniParser::Parse

IIniParser::Parse

Parses an INI-format property set from a file and stores them in the object, overwriting the current set.

bool     Parse (
    const wchar_t* pFileName,
    StringType* stringType
);

Parameters

pFileName
[in] Zero terminated widechar-string of the file path to parse from
stringType
[in] StringType method for converting the strings when storing them as a set

Return value

True if the methods succeeds, false if pFileName is invalid or some error occured during parsing.

Requirements

Header: IIniParser.hpp
Library: dgVoodooAPI.lib


IIniParser::Parse

IIniParser::Parse

Parses an INI-format property set from the beginning of a stream and stores them in the object, overwriting the current set.

bool     Parse (
    IAPIDataStream* pStream,
    StringType* stringType
);

Parameters

pStream
[in] A stream implementation to parse from
stringType
[in] StringType method for converting the strings when storing them as a set

Return value

True if the methods succeeds, false if pStream is invalid or some error occured during parsing.

Remarks

Stream object must implement Seek and Read to succeed.
Note that parsing is always done from the beginning of the stream which should contain no other data than the INI property set itself.

Requirements

Header: IIniParser.hpp
Library: dgVoodooAPI.lib


IIniParser::GetNumberOfProperties

IIniParser::GetNumberOfProperties

Returns the number of properties the given section is containing.

UInt32     GetNumberOfProperties (
    UInt32 sectionIdx
);

Return value

Number of properties in the given section.

Remarks

If a given section is defined in the INI property set but has no properties then this method returns 0.
Also, 0 is returned if sectiondIdx is out of range.
Properties can be indexed from 0 to (number of properties)-1 when referencing them.

Requirements

Header: IIniParser.hpp
Library: dgVoodooAPI.lib


IIniParser::GetNumberOfPropertValues

IIniParser::GetNumberOfPropertValues

Returns the number of values that a property in the given section has.

UInt32     GetNumberOfPropertValues (
    UInt32 sectionIdx,
    UInt32 propertyIdx
);

Parameters

sectionIdx
[in] Index of the section
propertyIdx
[in] Index of the property in the section

Return value

Number of property values.

Remarks

Zero is returned if sectionIdx or propertyIdx is out of range or the property has no values defined.
Values can be indexed from 0 to (number of values)-1.

Requirements

Header: IIniParser.hpp
Library: dgVoodooAPI.lib


IIniParser::GetNumberOfSections

IIniParser::GetNumberOfSections

Returns the number of sections in the property set.

UInt32     GetNumberOfSections ();

Return value

Number of sections in the propery set.

Remarks

Note that the global section (the one that has no name) is always included in the property set even if it has no properties.
Sections can be indexed from 0 to (number of sections)-1 when referencing them.

Requirements

Header: IIniParser.hpp
Library: dgVoodooAPI.lib


IIniParser::GetNumberOfSubProperties

IIniParser::GetNumberOfSubProperties

Returns the number of subproperties of the given property.

UInt32     GetNumberOfSubProperties (
    UInt32 sectionIdx,
    UInt32 propertyIdx
);

Return value

Number of subproperties for the given property.

Remarks

Zero is returned if sectionIdx or propertyIdx is out of range, or the given property has no subproperties defined.
Subproperties can be indexed from 0 to (number of subproperties)-1 when referencing them.

Requirements

Header: IIniParser.hpp
Library: dgVoodooAPI.lib


IIniParser::GetPropertyName

IIniParser::GetPropertyName

Returns the name of a property in the given section.

const char*     GetPropertyName (
    UInt32 sectionIdx,
    UInt32 propertyIdx
);

Parameters

sectionIdx
[in] Index of the section
propertyIdx
[in] Index of the property in the section

Return value

A const pointer to the zero terminated c-string of the property name.

Remarks

NULL pointers are returned if sectionIdx or propertyIdx is out of range.

Requirements

Header: IIniParser.hpp
Library: dgVoodooAPI.lib


IIniParser::GetPropertyValueAsInt

IIniParser::GetPropertyValueAsInt

Interprets and returns a property value as an integer number.

bool     GetPropertyValueAsInt (
    UInt32 sectionIdx,
    UInt32 propertyIdx,
    UInt32 valueIdx,
    Int32& value
);

Parameters

sectionIdx
[in] Index of the section
propertyIdx
[in] Index of the property in the section
valueIdx
[in] Index of the property value
value
[out] Reference to an Int32 to store the interpreted value

Return value

If a property value can be interpreted as an integer then this method returs true.
False is returned otherwise.

Remarks

Reference to value is filled by the parsed integer value if the method succeeds.

Requirements

Header: IIniParser.hpp
Library: dgVoodooAPI.lib


IIniParser::GetPropertValueAsString

IIniParser::GetPropertValueAsString

Returns a value of a property as a zero terminated c-string.

const char*     GetPropertyValueAsString (
    UInt32 sectionIdx,
    UInt32 propertyIdx,
    UInt32 valueIdx
);

Parameters

sectionIdx
[in] Index of the section
propertyIdx
[in] Index of the property in the section
valueIdx
[in] Index of the property value

Return value

A const pointer to the c-string.

Remarks

NULL pointer is returned if sectionIdx, propertyIdx or valueIdx is out of range.

Requirements

Header: IIniParser.hpp
Library: dgVoodooAPI.lib


IIniParser::GetSectionName

IIniParser::GetSectionName

Returns the name of the given section.

const char*     GetSectionName (
    UInt32 sectionIdx
);

Parameters

sectionIdx
[in] Index of the section

Return value

A const pointer to the zero terminated c-string of the name.

Remarks

Global section has no name and the function returns NULL pointer for that one.
Also, NULL pointer is returned if sectionIdx is out of range.

Requirements

Header: IIniParser.hpp
Library: dgVoodooAPI.lib


IIniParser::GetSubPropertyName

IIniParser::GetSubPropertyName

Returns the name of a subproperty for a given property.

const char*     GetSubPropertyName (
    UInt32 sectionIdx,
    UInt32 propertyIdx,
    UInt32 subPropertyIdx
);

Parameters

sectionIdx
[in] Index of the section
propertyIdx
[in] Index of the property in the section
subPropertyIdx
[in] Index of the subproperty for the given property

Return value

A const pointer to the zero terminated c-string of the property name.

Remarks

NULL pointers are returned if sectionIdx, propertyIdx or subPropertyIdx is out of range.

Requirements

Header: IIniParser.hpp
Library: dgVoodooAPI.lib


IIniParser::GetSubPropertyValueAsInt

IIniParser::GetSubPropertyValueAsInt

Interprets and returns a subproperty value as an integer number.

bool     GetSubPropertyValueAsInt (
    UInt32 sectionIdx,
    UInt32 propertyIdx,
    UInt32 subPropertyIdx,
    Int32& value
);

Parameters

sectionIdx
[in] Index of the section
propertyIdx
[in] Index of the property in the section
subPropertyIdx
[in] Index of subproperty for the given property
value
[out] Reference to an Int32 to store the interpreted value

Return value

If a subproperty value can be interpreted as an integer then this method returs true.
False is returned otherwise.

Remarks

Reference to value is filled by the parsed integer value if the method succeeds.

Requirements

Header: IIniParser.hpp
Library: dgVoodooAPI.lib


IIniParser::GetSubPropertyValueAsString

IIniParser::GetSubPropertyValueAsString

Returns a value of a property as a zero terminated c-string.

const char*     GetSubPropertyValueAsString (
    UInt32 sectionIdx,
    UInt32 propertyIdx,
    UInt32 subPropertyIdx
);

Parameters

sectionIdx
[in] Index of the section
propertyIdx
[in] Index of the property in the section
subPropertyIdx
[in] Index of subproperty for the give property

Return value

A const pointer to the c-string.

Remarks

NULL pointer is returned if sectionIdx, propertyIdx or subPropertyIdx is out of range.

Requirements

Header: IIniParser.hpp
Library: dgVoodooAPI.lib


Enumerations

Enumerations

This section contains reference information for API enumerations:

  • IIniParser::StringType


ICPLDDI::APIType

ICPLDDI::APIType

This enumeration defines graphics API types for CPL DDI objects.

enum APIType
{
     AT_Unknown    = 0,
     AT_D3D11,
     AT_D3D12
};

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


IIniParser::StringType

IIniParser::StringType

This enumeration has members for defining how to convert the strings of an INI property set when reading.

enum StringType
{
    CaseSensitive   = 0,
    LowerCase,
    UpperCase
};

Remarks

Every single string including section/property/subproperty and value names of an INI property set are affected.

Requirements

Header: IIniParser.hpp
Library: dgVoodooAPI.lib


Functions

Functions

This section contains reference information for API funtions:

  • dgVoodoo_API_GetVersion
  • dgVoodoo_API_Init
  • dgVoodoo_API_Exit


dgVoodoo_API_Init

dgVoodoo API Library documentation
dgVoodoo_API_Init

dgVoodoo_API_Init ()

Initializes dgVoodoo API library and returns the interface for the main factory object.

This is the function that must be called before using any other library component.

 IMainFactory	API_EXPORT *	dgVoodoo_API_Init ();

Return value

If successful, this function returns a pointer to a IMainFactory interface.

If initialization fails then NULL pointer is returned.

Remarks

When finished with the library, the application must call dgVoodoo_API_Exit to do the needed cleanup.

Requirements

Header: IMainFactory.hpp
Library: dgVoodooAPI.lib


dgVoodoo_API_Exit

dgVoodoo API Library documentation
dgVoodoo_API_Exit

dgVoodoo_API_Exit ()

This function does the cleanup and shuts down the library.

void	API_EXPORT	dgVoodoo_API_Exit ();

Return value

This function has no return value.

Remarks

It must be called when the library is no longer needed, to avoid memory- and resource leaks.

Requirements

Header: IMainFactory.hpp
Library: dgVoodooAPI.lib


dgVoodoo_API_GetVersion

dgVoodoo API Library documentation
dgVoodoo_API_GetVersion

dgVoodoo_API_GetVersion ()

This function returns the version of the API library. This is the only function that can be called without initializing the library.

UInt32 	API_EXPORT	dgVoodoo_API_GetVersion ();

Return value

A BCD-coded integer representing the version number.

Remarks

Each digit of the version number is encoded into 4 bit fields.
So, for example, 0x274 means version 2.74.

Requirements

Header: IMainFactory.hpp
Library: dgVoodooAPI.lib


Structures

Structures

This section contains reference information for API structures:

  • APIDebugObj
  • Config
  • ConfigDebug
  • ConfigDirectX
  • ConfigDirectXExt
  • ConfigGeneral
  • ConfigGeneralExt
  • ConfigGlide
  • ConfigGlideExt
  • ICPLDDI::OutputDesc
  • ICPLDDI::ModeDesc


APIDebugObj

APIDebugObj

This is a simple container structure describing severity/tracing levels, output string prefix and an optional output stream for debug layer feedback.

struct APIDebugObj
{
    enum InfoLevel
    {
        DisableInfo       = 0,
        EnableInfo,
        EnableInfoAndBreak
    };

    enum WarningLevel
    {
        DisableWarning    = 0,
        EnableWarning,
        EnableWarningAndBreak
    };

    enum ErrorLevel
    {
        DisableError      = 0,
        EnableError,
        EnableErrorAndBreak
    };

    InfoLevel           infoLevel;
    WarningLevel        warningLevel;
    ErrorLevel          errorLevel;
    const char*         pPrefixString;
    UInt32              maxTraceLevel;
    IAPIDataStream*     pOutputStream;

    InfoLevel       inline          GetInfoLevel () const;
    WarningLevel    inline          GetWarningLevel () const;
    ErrorLevel      inline          GetErrorLevel () const;
    UInt32          inline          GetMaxTraceLevel () const;
    void            inline          SetDebugInfo (InfoLevel _infoLevel,
                                                  WarningLevel _warningLevel,
                                                  ErrorLevel _errorLevel,
                                                  const char* _pPrefixString,
                                                  UInt32 _maxTraceLevel,
                                                  IAPIDataStream* _pOutputStream = NULL);

    APIDebugObj (InfoLevel _infoLevel,
                 WarningLevel _warningLevel,
                 ErrorLevel _errorLevel,
                 const char* _pPrefixString,
                 UInt32 _maxTraceLevel,
                 IAPIDataStream* _pOutputStream = NULL);
};

Requirements

Header: APIDebugObj.hpp
Library: dgVoodooAPI.lib


Config

Config

This structure contains dgVoodoo configuration data.

struct Config
{
    ConfigGeneral        general;
    ConfigGlide          glide;
    ConfigDirectX        directX;

    ConfigGeneralExt     generalExt;
    ConfigGlideExt       glideExt;
    ConfigDirectXExt     directXExt;

    ConfigDebug          debug;
};

Requirements

Header: dgVoodooConfig.hpp
Library: dgVoodooAPI.lib


ConfigDebug

ConfigDebug

This structure contains Debug dgVoodoo options.

struct ConfigDebug
{
    enum Severity
    {
        D_Disable,
        D_Enable,
        D_EnableBreak
    };

    Severity     info;
    Severity     warning;
    Severity     error;
    UInt32       maxTraceLevel;
    bool         logToFile;

    ConfigDebug ():
        info            (D_Enable),
        warning         (D_Enable),
        error           (D_Enable),
        maxTraceLevel   (0),
        logToFile       (false)
    {
    }
};

Requirements

Header: dgVoodooConfig.hpp
Library: dgVoodooAPI.lib


ConfigDirectX

ConfigDirectX

This structure contains DirectX dgVoodoo options that are exposed through the Control Panel.

struct ConfigDirectX
{
    enum CardType
    {
        SVGA                = 0,
        Virtual3D,
        Geforce4Ti4800,
        Radeon8500,
        MatroxParhelia512,
        GeforceFX5700Ultra,
        Geforce9800GT

        NumOfCardTypes
    };

    enum TexFilterType
    {
        TF_AppDriven        = 0,
        TF_ForcePoint       = 0x100,
        TF_ForceBilinear    = 0x200,
        TF_ForceLinearMip   = 0x300,
        TF_ForceTrilinear   = 0x400,
        TF_ForceAniso1x     = 1,
        TF_ForceAniso2x     = 2,
        TF_ForceAniso3x     = 3,
        TF_ForceAniso4x     = 4,
        TF_ForceAniso5x     = 5,
        TF_ForceAniso6x     = 6,
        TF_ForceAniso7x     = 7,
        TF_ForceAniso8x     = 8,
        TF_ForceAniso9x     = 9,
        TF_ForceAniso10x    = 10,
        TF_ForceAniso11x    = 11,
        TF_ForceAniso12x    = 12,
        TF_ForceAniso13x    = 13,
        TF_ForceAniso14x    = 14,
        TF_ForceAniso15x    = 15,
        TF_ForceAniso16x    = 16,

        TF_AnisoMask        = 0xFF
    };

    CardType     cardType;
    UInt32       videoMemSize;
    UInt32       resWidth;
    UInt32       resHeight;
    UInt32       msaaLevel;
    UInt32       refRateNumerator;
    UInt32       refRateDenominator;
    UInt32       texFilterType;
    bool         disabledAndPassThru;
    bool         appControlledScreenState;
    bool         disableAltEnter;
    bool         watermark;
    bool         linearBltStretch;
    bool         applyPhongShading;
    bool         forceVSync;
    bool         disableMipmapping;
    bool         keepFilterIfPointSampled;
    bool         fastVideoMemAccess;

    ConfigDirectX ():
        cardType                    (Virtual3D),
        videoMemSize                (64*1024*1024),
        resWidth                    (0),
        resHeight                   (0),
        msaaLevel                   (0),
        refRateNumerator            (0),
        refRateDenominator          (0),
        texFilterType               (TF_AppDriven),
        disabledAndPassThru         (false),
        appControlledScreenState    (true),
        disableAltEnter             (true),
        watermark                   (true),
        linearBltStretch            (false),
        applyPhongShading           (false),
        forceVSync                  (false),
        disableMipmapping           (false),
        keepFilterIfPointSampled    (false),
        fastVideoMemAccess          (false)
    {
    }
};

Requirements

Header: dgVoodooConfig.hpp
Library: dgVoodooAPI.lib


ConfigDirectXExt

ConfigDirectXExt

This structure contains DirectX dgVoodoo options that are not exposed through the Control Panel by default.

#define MAX_NUM_OF_DX_EXTRA_RESOLUTIONS    16

struct ConfigDirectXExt
{
    enum AdapterIDType
    {
        AIDT_Default      =  0,
        AIDT_nVidia,
        AIDT_AMD,
        AIDT_Intel
    };

    enum DitheringEffect
    {
        DE_Pure32Bit      =  0,
        DE_Ordered2x2,
        DE_Ordered4x4,

        NumOfDitheringEffects,
    };

    enum Dithering
    {
        DT_Disabled       =  0,
        DT_AppDriven,
        DT_ForceOn16Bit,
        DT_ForceAlways,

        NumOfDitheringBehaviors
    };

    enum DepthBufferBitDepth
    {
        DBD_AppDriven     =  0,
        DBD_ForceMin24,
        DBD_Force32,

        NumOfDepthBufferBitDepths
    };

    enum Default3DRenderFormat
    {
        D3DRF_ARGB8888,
        D3DRF_ARGB2101010,

        NumOfDefault3DRenderFormats
    };

    enum DefEnumResolutions
    {
        DER_None          =  0,
        DER_Classics,
        DER_All,

        NumOfDefEnumResolutions
    };

    enum EnumResBitDepths
    {
        ERBD_8            =   0x1,
        ERBD_16           =   0x2,
        ERBD_32           =   0x4,
        ERBD_All          =   0x7
    };

    struct ExtraResolution
    {
        UInt32   width;
        UInt32   height;
        UInt32   refRate;
    };

    AdapterIDType            adapterIDType;
    UInt32                   vendorID;
    UInt32                   deviceID;
    UInt32                   subSysID;
    UInt32                   revisionID;
    ExtraResolution          extraResolutions[MAX_NUM_OF_DX_EXTRA_RESOLUTIONS];
    DitheringEffect          ditheringEffect;
    Dithering                dithering;
    UInt32                   ditherOrderedMatrixSizeScale;
    DepthBufferBitDepth      depthBuffersBitDepth;
    Default3DRenderFormat    default3DRenderFormat;
    DefEnumResolutions       defaultEnumeratedResolutions;
    UInt32                   enumeratedResolutionBitDepths;
    UInt32                   maxVSConstRegisters;
    UInt32                   nPatchTesselationLevel;
    UInt32                   renderingOutputEnablingMask;
    bool                     msD3DDeviceNames;
    bool                     rtTexturesForceScaleAndMSAA;
    bool                     smoothedDepthSampling;
    bool                     deferredScreenModeSwitch;
    bool                     primarySurfaceBatchedUpdate;

    ConfigDirectXExt () :
        adapterIDType                   (AIDT_Default),
        vendorID                        (0x0),
        deviceID                        (0x0),
        subSysID                        (0x0),
        revisionID                      (0x0),
        ditheringEffect                 (DE_Pure32Bit),
        dithering                       (DT_ForceAlways),
        ditherOrderedMatrixSizeScale    (0),
        depthBuffersBitDepth            (DBD_AppDriven),
        default3DRenderFormat           (D3DRF_ARGB8888),
        defaultEnumeratedResolutions    (DER_All),
        enumeratedResolutionBitDepths   (ERBD_All),
        maxVSConstRegisters             (256),
        nPatchTesselationLevel          (0),
        renderingOutputEnablingMask     (0xFFFFFFFF),
        msD3DDeviceNames                (false),
        rtTexturesForceScaleAndMSAA     (true),
        smoothedDepthSampling           (true),
        deferredScreenModeSwitch        (false),
        primarySurfaceBatchedUpdate     (false)
    {
        memset (extraResolutions, 0, sizeof (extraResolutions));
    }
};

Requirements

Header: dgVoodooConfig.hpp
Library: dgVoodooAPI.lib


ConfigGeneral structure

dgVoodoo API Library documentation
ConfigGeneral structure

ConfigGeneral

This structure contains general dgVoodoo options that are exposed through the Control Panel.

struct ConfigGeneral
{
    enum RendererAPI
    {
        API_BestAvailable               = 0,
        API_Direct3D11_FL10_0,
        API_Direct3D11_FL10_1,
        API_Direct3D11_MS_WARP_FL10_1,
        API_Direct3D11_FL11_0,
        API_Direct3D12_FL11_0,
        API_Direct3D12_FL12_0,

        NumOfAPITypes
    };

    enum Adapter
    {
        AdapterAll                      = 0
    };

    enum ScanlineOrder
    {
        SO_OutputDefault                = 0,
        SO_Progressive,
        SO_Undefined,

        NumOfScanlineOrders
    };

    enum ScalingMode
    {
        SM_Unspecified                  = 0,
        SM_Centered,
        SM_Stretched,
        SM_AspectRatio,
        SM_AspectRatio4_3,
        SM_AspectRatio4_3_CRTLike,
        SM_AspectRatio4_3_C64Like,
        SM_CenteredAspectRatio,
        SM_AspectRatio_CRTLike,

        NumOfScalingModes
    };

    enum Resolution
    {
        R_Unforced                      = 0,

        // All dynamic resolutions can have an integer scale value parameter (0 - 255)

        R_Max                           = 0xFFFFFFFF,          // It can have the aspect ratio as parameter
        R_Max_ISF                       = 0xFFFFFFFE,
        R_MaxFHD                        = 0xFFFFFFFD,
        R_MaxFHD_ISF                    = 0xFFFFFFFC,
        R_MaxQHD                        = 0xFFFFFFFB,
        R_MaxQHD_ISF                    = 0xFFFFFFFA,
        R_IntegerScaled                 = 0xFFFFFFF9,          // It always has the integer scale value parameter
        R_Desktop                       = 0xFFFFFFF8,

        // Optional parameters for R_Max

        PR_Max_4_3                      = 0x100,
        PR_Max_16_9                     = 0x101
    };

    RendererAPI      rendererAPI;
    UInt32           rendererDevice;                    //  AdapterAll or adapter ordinal
    UInt32           renderingOutput;                   //  0 == default
    UInt32           brightnessScale;
    UInt32           colorScale;
    UInt32           contrastScale;
    ScanlineOrder    scanlineOrder;
    ScalingMode      scalingMode;
    bool             windowed;
    bool             keepApectRatio;
    bool             enumerateRefreshRates;
    bool             captureMouse;
    bool             centerAppWindow;
    bool             inheritColorProfile;

    ConfigGeneral ():
        rendererAPI             (API_BestAvailable),
        rendererDevice          (0),
        renderingOutput         (0),
        brightnessScale         (100),
        colorScale              (100),
        contrastScale           (100),
        scanlineOrder           (SO_OutputDefault),
        scalingMode             (SM_Unspecified),
        windowed                (false),
        keepApectRatio          (true),
        enumerateRefreshRates   (false),
        captureMouse            (true),
        centerAppWindow         (false),
        inheritColorProfile     (false)
    {
    }
};

Requirements

Header: dgVoodooConfig.hpp
Library: dgVoodooAPI.lib


ConfigGeneralExt

ConfigGeneralExt

This structure contains general dgVoodoo options that are not exposed through the Control Panel by default.

struct ConfigGeneralExt
{
    enum Environment
    {
        Env_Unspecified         = 0,
        Env_DosBox,
        Env_QEmu
    };

    enum WindowedAttributes
    {
        WA_DefaultAttributes    = 0x0,

        WA_BorderlessFlag       = 0x1,
        WA_AlwaysOnTop          = 0x2,
        WA_FullscreenSize       = 0x4,

        WA_FlagsMask            = 0x7
    };

    enum FullscreenAttributes
    {
        FSA_DefaultAttributes   = 0x0,

        FSA_Fake                = 0x1,

        FSA_FlagsMask           = 0x1
    };

    enum DisplayROIPosition
    {
        DROI_Centered           = 0xFFFFFFFF
    };

    enum DisplayROISize
    {
        DROI_Rational           = 0xFFFFFFFF
    };

    enum Resampling
    {
        RS_PointSampled         = 0,
        RS_Bilinear,
        RS_Bicubic,
        RS_Lanczos_2,
        RS_Lanczos_3
    };

    enum PresentationModel
    {
        PM_Automatic            = 0,
        PM_Discard,
        PM_Sequential,
        PM_FlipDiscard,
        PM_FlipSequential
    };

    UInt32               desktopResWidth;
    UInt32               desktopResHeight;
    UInt32               desktopRefRateNumerator;
    UInt32               desktopRefRateDenominator;
    UInt32               desktopBitDepth;
    UInt32               deframerSize;
    UInt32               imageXScaleFactor;
    UInt32               imageYScaleFactor;
    UInt32               cursorScaleFactor;
    UInt32               displayROIPosX;
    UInt32               displayROIPosY;
    UInt32               displayROISizeX;
    UInt32               displayROISizeY;
    Environment          environment;
    UInt32               windowedAttributes;
    UInt32               fullscreenAttributes;
    Resampling           resampling;
    PresentationModel    presentationModel;
    UInt32               fpsLimitNumerator;
    UInt32               fpsLimitDenominator;
    bool                 freeMouse;
    bool                 enableGDIHooking;

    ConfigGeneralExt ():
        desktopResWidth             (0),
        desktopResHeight            (0),
        desktopRefRateNumerator     (0),
        desktopRefRateDenominator   (0),
        desktopBitDepth             (0),
        deframerSize                (1),
        imageXScaleFactor           (1),
        imageYScaleFactor           (1),
        cursorScaleFactor           (0),
        displayROIPosX              (0),
        displayROIPosY              (0),
        displayROISizeX             (0),
        displayROISizeY             (0),
        environment                 (Env_Unspecified),
        windowedAttributes          (WA_DefaultAttributes),
        fullscreenAttributes        (FSA_DefaultAttributes),
        resampling                  (RS_Bilinear),
        presentationModel           (PM_Automatic),
        fpsLimitNumerator           (0),
        fpsLimitDenominator         (0),
        freeMouse                   (false),
        enableGDIHooking            (false)
    {
    }
};

Requirements

Header: dgVoodooConfig.hpp
Library: dgVoodooAPI.lib


ConfigGlide

ConfigGlide

This structure contains Glide dgVoodoo options that are exposed through the Control Panel.

struct ConfigGlide
{
    enum CardType
    {
        VoodooGraphics      =   0,
        VoodooRush          =   1,
        Voodoo2             =   2,
        VoodooBanshee       =   3,
        Other               =   4,

        NumOfCardTypes
    };

    enum TexFilterType
    {
        TF_AppDriven        =   0,
        TF_ForcePoint       =   0x100,
        TF_ForceBilinear    =   0x200
    };

    CardType         cardType;
    UInt32           onBoardMemSize;
    UInt32           texMemSize;
    Int32            numOfTMUs;
    UInt32           resWidth;
    UInt32           resHeight;
    UInt32           msaaLevel;
    UInt32           refRateNumerator;
    UInt32           refRateDenominator;
    TexFilterType    texFilterType;
    bool             disableMipMapping;
    bool             enableGammaRamp;
    bool             pointCastPalette;
    bool             forceVSync;
    bool             forceEmulateLfbPCI;
    bool             use16BitDepthBuffer;
    bool             enable3DfxWaterMark;
    bool             enableSplashScreen;
    bool             enableInactiveAppState;

    ConfigGlide ():
        cardType                (Voodoo2),
        onBoardMemSize          (8*1024*1024),
        texMemSize              (4*1024*1024),
        numOfTMUs               (2),
        resWidth                (0),
        resHeight               (0),
        msaaLevel               (0),
        refRateNumerator        (0),
        refRateDenominator      (0),
        texFilterType           (TF_AppDriven),
        disableMipMapping       (false),
        enableGammaRamp         (true),
        pointCastPalette        (false),
        forceVSync              (true),
        forceEmulateLfbPCI      (false),
        use16BitDepthBuffer     (false),
        enable3DfxWaterMark     (true),
        enableSplashScreen      (false),
        enableInactiveAppState  (false)
    {
    }
};

Requirements

Header: dgVoodooConfig.hpp
Library: dgVoodooAPI.lib


ConfigGlideExt

ConfigGlideExt

This structure contains Glide dgVoodoo options that are not exposed through the Control Panel by default.

struct ConfigGlideExt
{
    enum DitheringEffect
    {
        DE_Pure32Bit    = 0,
        DE_Dither2x2,
        DE_Dither4x4,

        NumOfDitherinEffects,
    };

    enum Dithering
    {
        DT_Disabled     = 0,
        DT_AppDriven,
        DT_ForceAlways,

        NumOfDitheringBehaviors
    };

    DitheringEffect      ditheringEffect;
    Dithering            dithering;
    UInt32               ditherOrderedMatrixSizeScale;

    ConfigGlideExt ():
        ditheringEffect                 (DE_Pure32Bit),
        dithering                       (DT_ForceAlways),
        ditherOrderedMatrixSizeScale    (0)
    {
    }
};

Requirements

Header: dgVoodooConfig.hpp
Library: dgVoodooAPI.lib


ICPLDDI::OutputDesc

ICPLDDI::OutputDesc

This structure contains the description of a display output attached to an adapter.

struct OutputDesc
{
    WCHAR        name[32];
    WCHAR        desc[128];
    HMONITOR     hMonitor;
};

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


ICPLDDI::ModeDesc

ICPLDDI::ModeDesc

This structure contains the description of a display mode.

struct ModeDesc
{
    UInt32	xRes;
    UInt32	yRes;
    UInt32	refreshRateNumerator;
    UInt32	refreshRateDenominator;
    UInt32	refreshRateSimple;

    ModeDesc ():
        xRes                    (0),
        yRes                    (0),
        refreshRateNumerator    (0),
        refreshRateDenominator  (0),
        refreshRateSimple       (0)
    {
    }
};

Requirements

Header: ICPLDDI.hpp
Library: dgVoodooAPI.lib


ID3D12Root::GPLBlendStateReleased

ID3D12Root::GPLBlendStateReleased

This is a method notifying the caches of the D3D12 backend that an own-factored blend-state pointer is about to get invalidated so remove it from the entry records.

void     GPLBlendStateReleased (
    UInt32 adapterID,
    D3D12_BLEND_DESC* pBlendState
    );

Parameters

adapterID
[in] The ID of the adapter.
pBlendState
[in] The blend-state pointer that is about to get invalidated.

Remarks

If you have an own-factored blend-state pointer that got into the caches of the D3D12 backend by using it as input for PLCacheGetGraphicsPipeline then you must notify the cache system when it is about to get invalidated so the caching system can remove all internal associated entries. It is a must because if you miss notifying the cache system then the invalid pointer will get stuck in the entry records and that causes undefined problems if another blend-state object with the same reallocated pointer gets into the cache system later.

Requirements

Header: ID3D12Root.hpp


ID3D12Root::GPLDepthStencilStateReleased

ID3D12Root::GPLDepthStencilStateReleased

This is a method notifying the caches of the D3D12 backend that an own-factored depth-stencil-state pointer is about to get invalidated so remove it from the entry records.

void     GPLDepthStencilStateReleased (
    UInt32 adapterID,
    D3D12_DEPTH_STENCIL_DESC* pDepthStencilState
    );

Parameters

adapterID
[in] The ID of the adapter.
pDepthStencilState
[in] The depth-stencil-state pointer that is about to get invalidated.

Remarks

If you have an own-factored rasterizer-state pointer that got into the caches of the D3D12 backend by using it as input for PLCacheGetGraphicsPipeline then you must notify the cache system when it is about to get invalidated so the caching system can remove all internal associated entries. It is a must because if you miss notifying the cache system then the invalid pointer will get stuck in the entry records and that causes undefined problems if another depth-stencil-state object with the same reallocated pointer gets into the cache system later.

Requirements

Header: ID3D12Root.hpp