Dismiss Notice

Register now to be one of the first members of this SharePoint Community! Click here it just takes seconds!

Dismiss Notice
Welcome Guest from Country Flag

DirectX Compiler APIs

Discussion in 'Official Microsoft News' started by Marcelo Lopez Ruiz - MSFT, Mar 28, 2017.

Thread Status:
Not open for further replies.
  1. Marcelo Lopez Ruiz - MSFT

    Marcelo Lopez Ruiz - MSFT Guest

    Blog Posts:
    If you are used to building HLSL with fxc.exe, your build process can now use dxc.exe to compile shaders with the new DirectX Shader compiler. This is convenient for standalone projects. Games, middleware and asset pipelines will often have a need to do this multiple times and/or from source code that doesn’t exist as a file on disk, and prefer to use a more direct mechanism.

    Compiling a shader in-memory is the main use case for the dxcompiler.dll APIs. While the design for d3dcompiler_47.dll was a set of plain Win32 APIs like D3DCompile, we opted to use a design more in line with Direct3D or other components such xmllite, with the following goals in mind.

    • Provide a simple mechanism for extensibility of the library as a whole.
    • Provide a robust mechanism for componentizing and versioning the areas of functionality within the library.
    • Remove some patterns that made it difficult to interoperate with other COM or .NET components.
    • Simplify some scenarios, especially the case of inclusion handlers.
    • Allow extensibility of the language for common scenarios.
    • Enable people to write languages that target DXIL.

    There will be a future post where we cover these in more detail. For this post, I want to focus on the mechanics of writing a program that can compile code on the fly. We’ll walk through a simple example that does this, omitting error checks for clarity.

    Let’s start a .cpp program with the following code.

    #include <windows.h>
    #include "include/dxc/dxcapi.h"

    void main() {
    // More code

    Now we’ll create an object to represent the program text, representing a blob of bytes with some specific text encoding. This is a very simple interface that provides a potentially large amount of text, specifying the encoding so there is no ambiguity (API arguments for short strings will typically be null-terminated wchar_t pointers). The interface provides lifetime management of the buffer (via the AddRef/Release mechanism), and allows efficient sub-blobs to be created.

    We’ll be lazy productive here and create a stock implementation that can reference some data on the stack – there are other convenience routines to create these from a file, from another blob, and other variations.

    const char Program[] = "float4 main() : SV_Target { return 1; }";
    IDxcLibrary *pLibrary;
    IDxcBlobEncoding *pSource;
    DxcCreateInstance(CLSID_DxcLibrary, __uuidof(IDxcLibrary), (void **)&pLibrary);
    pLibrary->CreateBlobWithEncodingFromPinned(Program, _countof(Program), CP_UTF8, &pSource);

    Now, we’ll create a compiler object and pass this program to it, with some extra arguments to make it more interesting.

    LPCWSTR ppArgs[] = { L"/Zi" }; // debug info
    IDxcCompiler *pCompiler;
    DxcCreateInstance(CLSID_DxcCompiler, __uuidof(IDxcCompiler), (void **)&pCompiler);

    IDxcOperationResult *pResult;
    pSource, // program text
    L"myfile.hlsl", // file name, mostly for error messages
    L"main", // entry point function
    L"ps_6_0", // target profile
    ppArgs, // compilation arguments
    _countof(ppArgs), // number of compilation arguments
    nullptr, 0, // name/value defines and their count
    nullptr, // handler for #include directives

    At this point, unless something happened that prevented compilation altogether, we’ll have an IDxcOperationResult instance. This provides us with the full results of compilation: whether a program was produced, and a buffer with errors and warnings that may have occurred. Here’s one way we can handle that.

    HRESULT hrCompilation;

    if (SUCCEEDED(hrCompilation)) {
    IDxcBlob *pResult;
    // Save to a file, disassemble and print, store somewhere ...
    else {
    IDxcBlobEncoding *pPrintBlob, *pPrintBlob16;
    // We can use the library to get our preferred encoding.
    pLibrary->GetBlobAsUtf16(pPrintBlob, &pPrintBlob16);
    wprintf(L"%*s", (int)pPrintBlob16->GetBufferSize()/2,(LPCWSTR)pPrintBlob16->GetBufferPointer());

    You will generally find we have a more fine-grained API than with d3dcompiler; the extra precision you get will lead to fewer buffer copies and more sharing – and, importantly, fewer surprises if you run on a system with a different default character encoding.


    Continue reading...
Thread Status:
Not open for further replies.

Share This Page

LiveZilla Live Chat Software