Explanation About Initilizing A DirextX3D Class

Posted 2021-02-05 cookiebox

DirectX11 Study Note

I will record the sequence of creating a direct3d graphics, and explanation the important point of every function accroding MSDN document.

Create a DirectX graphics interface factory.

        // Create a DirectX graphics interface factory.
    result = CreateDXGIFactory(__uuidof(IDXGIFactory), (void**)&factory);
    if(FAILED(result))
    {
        return false;
    }

IDXGIFactory interface

An IDXGIFactory interface implements methods for generating DXGI objects (which handle full screen transitions).

Methods
The IDXGIFactory interface has these methods.

Method	Description
IDXGIFactory::CreateSoftwareAdapter	Create an adapter interface that represents a software adapter.
IDXGIFactory::CreateSwapChain	Creates a swap chain.
IDXGIFactory::EnumAdapters	Enumerates the adapters (video cards).
IDXGIFactory::GetWindowAssociation	Get the window through which the user controls the transition to and from full screen.
IDXGIFactory::MakeWindowAssociation	Allows DXGI to monitor an application‘s message queue for the alt-enter key sequence (which causes the application to switch from windowed to full screen or vice versa).

Remarks
Create a factory by calling CreateDXGIFactory.

Because you can create a Direct3D device without creating a swap chain, you might need to retrieve the factory that is used to create the device in order to create a swap chain. You can request the IDXGIDevice interface from the Direct3D device and then use the IDXGIObject::GetParent method to locate the factory. The following code shows how.

IDXGIDevice * pDXGIDevice = nullptr;
hr = g_pd3dDevice->QueryInterface(__uuidof(IDXGIDevice), (void **)&pDXGIDevice);

IDXGIAdapter * pDXGIAdapter = nullptr;
hr = pDXGIDevice->GetAdapter( &pDXGIAdapter );

IDXGIFactory * pIDXGIFactory = nullptr;
pDXGIAdapter->GetParent(__uuidof(IDXGIFactory), (void **)&pIDXGIFactory);

Windows Phone 8: This API is supported.

Requirements

Target Platform Windows
Header dxgi.h

---

Use the factory to create an adapter

    // Use the factory to create an adapter for the primary graphics interface (video card).
    result = factory->EnumAdapters(0, &adapter);
    if(FAILED(result))
    {
        return false;
    }

IDXGIAdapter interface

The IDXGIAdapter interface represents a display subsystem (including one or more GPUs, DACs and video memory).

Methods
The IDXGIAdapter interface has these methods.

Method	Description
IDXGIAdapter::CheckInterfaceSupport	Checks whether the system supports a device interface for a graphics component.
IDXGIAdapter::EnumOutputs	Enumerate adapter (video card) outputs.
IDXGIAdapter::GetDesc	Gets a DXGI 1.0 description of an adapter (or video card).

Remarks
A display subsystem is often referred to as a video card, however, on some machines the display subsystem is part of the motherboard.

To enumerate the display subsystems, use IDXGIFactory::EnumAdapters.

To get an interface to the adapter for a particular device, use IDXGIDevice::GetAdapter.

To create a software adapter, use IDXGIFactory::CreateSoftwareAdapter.

Windows Phone 8: This API is supported.

Requirements

Target Platform Windows
Header dxgi.h

---

IDXGIAdapter::EnumOutputs method

Enumerate adapter (video card) outputs.

Syntax

HRESULT EnumOutputs(
  UINT        Output,
  IDXGIOutput **ppOutput
);

Parameters

Output

Type: UINT

The index of the output.

ppOutput

Type: IDXGIOutput

The address of a pointer to an IDXGIOutput interface at the position specified by the Output parameter.

Return Value
Type: HRESULT

A code that indicates success or failure (see DXGI_ERROR). DXGI_ERROR_NOT_FOUND is returned if the index is greater than the number of outputs.

If the adapter came from a device created using D3D_DRIVER_TYPE_WARP, then the adapter has no outputs, so DXGI_ERROR_NOT_FOUND is returned.

Remarks
Note If you call this API in a Session 0 process, it returns DXGI_ERROR_NOT_CURRENTLY_AVAILABLE.

When the EnumOutputs method succeeds and fills the ppOutput parameter with the address of the pointer to the output interface, EnumOutputs increments the output interface‘s reference count. To avoid a memory leak, when you finish using the output interface, call the Release method to decrement the reference count.
EnumOutputs first returns the output on which the desktop primary is displayed. This output corresponds with an index of zero. EnumOutputs then returns other outputs.

Examples
Enumerating Outputs

Here is an example of how to use EnumOutputs to enumerate all the outputs on an adapter:

UINT i = 0;
IDXGIOutput * pOutput;
std::vector<IDXGIOutput*> vOutputs;
while(pAdapter->EnumOutputs(i, &pOutput) != DXGI_ERROR_NOT_FOUND)
{
    vOutputs.push_back(pOutput);
    ++i;
}

Requirements

Target Platform Windows
Header dxgi.h
Library DXGI.lib

---

IDXGIOutput interface

An IDXGIOutput interface represents an adapter output (such as a monitor).

Methods

The IDXGIOutput interface has these methods.

Method	Description
IDXGIOutput::FindClosestMatchingMode	Finds the display mode that most closely matches the requested display mode.
IDXGIOutput::GetDesc	Get a description of the output.
IDXGIOutput::GetDisplayModeList	Gets the display modes that match the requested format and other input options.
IDXGIOutput::GetDisplaySurfaceData	Gets a copy of the current display surface.
IDXGIOutput::GetFrameStatistics	Gets statistics about recently rendered frames.
IDXGIOutput::GetGammaControl	Gets the gamma control settings.
IDXGIOutput::GetGammaControlCapabilities	Gets a description of the gamma-control capabilities.
IDXGIOutput::ReleaseOwnership	Releases ownership of the output.
IDXGIOutput::SetDisplaySurface	Changes the display mode.
IDXGIOutput::SetGammaControl	Sets the gamma controls.
IDXGIOutput::TakeOwnership	Takes ownership of an output.
IDXGIOutput::WaitForVBlank	Halt a thread until the next vertical blank occurs.

Remarks

To see the outputs available, use IDXGIAdapter::EnumOutputs. To see the specific output that the swap chain will update, use IDXGISwapChain::GetContainingOutput.

Requirements

Target Platform Windows
Header dxgi.h

---

CreateDXGIFactory function

Creates a DXGI 1.0 factory that you can use to generate other DXGI objects.

Syntax

Copy
HRESULT CreateDXGIFactory(
  REFIID riid,
  void   **ppFactory
);

Parameters
riid

Type: REFIID

The globally unique identifier (GUID) of the IDXGIFactory object referenced by the ppFactory parameter.

ppFactory

Type: void**

Address of a pointer to an IDXGIFactory object.

Return Value

Type: HRESULT

Returns S_OK if successful; otherwise, returns one of the following DXGI_ERROR.

Remarks
Use a DXGI factory to generate objects that enumerate adapters, create swap chains, and associate a window with the alt+enter key sequence for toggling to and from the fullscreen display mode.

If the CreateDXGIFactory function succeeds, the reference count on the IDXGIFactory interface is incremented. To avoid a memory leak, when you finish using the interface, call the IDXGIFactory::Release method to release the interface.

Examples
Creating a DXGI 1.0 Factory

The following code example demonstrates how to create a DXGI 1.0 factory. This example uses the __uuidof() intrinsic to obtain the REFIID, or GUID, of the IDXGIFactory interface.

IDXGIFactory * pFactory;

HRESULT hr = CreateDXGIFactory(__uuidof(IDXGIFactory), (void**)(&pFactory) );