Overview of Direct3D 11 - Practical Rendering and Computation with Direct3D 11 - page 13

This usage allows both the application and the Direct3D 11 runtime to share objects
with multiple references. When a resource is bound to the pipeline as a render target, it is
referenced by the runtime to ensure that the object is not deleted while it is being used.
Similarly, if both the application and the runtime have a reference to an object, and a
method call eliminates the runtime reference, the application can be sure that the object
will not be destroyed until it releases its reference, as well. This reference-counting object
management holds true for any Direct3D 11 object that inherits from the IUnknown inter-
face, and it must be followed to ensure that no objects are left unreleased after an applica-
tion is terminated.
Interface querying. As mentioned above, the IUnknown interface also provides some
methods for querying an object to find additional interfaces that it implements. This is
performed with the IUnknown::QueryInterface() method, which takes a universally unique
identifier (UUID) that identifies the desired interface, and then a pointer to a pointer, which
will be filled with an appropriate object reference if the object implements the requested
interface. If such a reference is successfully returned in the method call, the reference count
of the object is increased and should be managed in the same way as any other object.
In Direct3D, this mechanism is used primarily in conjunction with the ID3D1 IDevice
interface. There are several different situations in which additional device interfaces are re-
quested, such as acquiring the debug interface of the device or acquiring the DXGI device
interface from the Direct3D device. We will occasionally see this method in action in this
text, and the process will be noted as it arises.
Some other properties of COM objects are not used as frequently with Direct3D 11,
such as the language independence of the binary interface, or the fact that objects can be
instantiated and used from a remote computer. These uses are beyond the scope of this
topic, but are still interesting to know about. Further information about COM can be found
on the MSDN website, and there are also many additional resources available online, due
to the longevity of the technology.
Interpreting API Call Results
Direct3D 11 also implements a standard way of handling return codes from functions and
methods. In general, the success or failure of a method is indicated by a return code, which
is provided to the application as the returned value of the function call. This return code is
implemented as an HRESULT value, which is really just a long integer variable.
The list of possible return values can be found in the DXSDK documentation, and
additional return codes may added between releases. In some situations, these return codes
do not clearly indicate the success or failure of a method, and often the interpretation of
the codes depends on the context in which it is returned. To simplify testing of these return
codes, a simple macro can be used to test if a method has failed or not. Listing 1.1 shows
how the FAILED macro is used.