1
2 ///////////////////////////////////////////////////////////////////////////////
3 // //
4 // dxcapi.h //
5 // Copyright (C) Microsoft Corporation. All rights reserved. //
6 // This file is distributed under the University of Illinois Open Source //
7 // License. See LICENSE.TXT for details. //
8 // //
9 // Provides declarations for the DirectX Compiler API entry point. //
10 // //
11 ///////////////////////////////////////////////////////////////////////////////
12
13 #ifndef __DXC_API__
14 #define __DXC_API__
15
16 #ifdef _WIN32
17 #ifndef DXC_API_IMPORT
18 #define DXC_API_IMPORT __declspec(dllimport)
19 #endif
20 #else
21 #ifndef DXC_API_IMPORT
22 #define DXC_API_IMPORT __attribute__ ((visibility ("default")))
23 #endif
24 #endif
25
26 #ifdef _WIN32
27
28 #ifndef CROSS_PLATFORM_UUIDOF
29 // Warning: This macro exists in WinAdapter.h as well
30 #define CROSS_PLATFORM_UUIDOF(interface, spec) \
31 struct __declspec(uuid(spec)) interface;
32 #endif
33
34 #else
35
nybble_from_hex(char c)36 constexpr uint8_t nybble_from_hex(char c) {
37 return ((c >= '0' && c <= '9')
38 ? (c - '0')
39 : ((c >= 'a' && c <= 'f')
40 ? (c - 'a' + 10)
41 : ((c >= 'A' && c <= 'F') ? (c - 'A' + 10)
42 : /* Should be an error */ -1)));
43 }
44
byte_from_hex(char c1,char c2)45 constexpr uint8_t byte_from_hex(char c1, char c2) {
46 return nybble_from_hex(c1) << 4 | nybble_from_hex(c2);
47 }
48
byte_from_hexstr(const char str[2])49 constexpr uint8_t byte_from_hexstr(const char str[2]) {
50 return nybble_from_hex(str[0]) << 4 | nybble_from_hex(str[1]);
51 }
52
guid_from_string(const char str[37])53 constexpr GUID guid_from_string(const char str[37]) {
54 return GUID{ static_cast<uint32_t>(byte_from_hexstr(str)) << 24 |
55 static_cast<uint32_t>(byte_from_hexstr(str + 2)) << 16 |
56 static_cast<uint32_t>(byte_from_hexstr(str + 4)) << 8 |
57 byte_from_hexstr(str + 6),
58 static_cast<uint16_t>(
59 static_cast<uint16_t>(byte_from_hexstr(str + 9)) << 8 |
60 byte_from_hexstr(str + 11)),
61 static_cast<uint16_t>(
62 static_cast<uint16_t>(byte_from_hexstr(str + 14)) << 8 |
63 byte_from_hexstr(str + 16)),
64 {byte_from_hexstr(str + 19), byte_from_hexstr(str + 21),
65 byte_from_hexstr(str + 24), byte_from_hexstr(str + 26),
66 byte_from_hexstr(str + 28), byte_from_hexstr(str + 30),
67 byte_from_hexstr(str + 32), byte_from_hexstr(str + 34)} };
68 }
69
70 #define CROSS_PLATFORM_UUIDOF(interface, spec) \
71 struct interface; \
72 template <> constexpr GUID uuidof<interface>() { \
73 constexpr IID _IID = guid_from_string(spec); \
74 return _IID; \
75 }
76
77
78 CROSS_PLATFORM_UUIDOF(INoMarshal, "ECC8691B-C1DB-4DC0-855E-65F6C551AF49")
79 struct INoMarshal : public IUnknown {};
80
81 CROSS_PLATFORM_UUIDOF(IMalloc, "00000002-0000-0000-C000-000000000046")
82 struct IMalloc : public IUnknown {
83 virtual void *Alloc(size_t size);
84 virtual void *Realloc(void *ptr, size_t size);
85 virtual void Free(void *ptr);
86 virtual HRESULT QueryInterface(REFIID riid, void **ppvObject);
87 };
88
89 CROSS_PLATFORM_UUIDOF(ISequentialStream, "0C733A30-2A1C-11CE-ADE5-00AA0044773D")
90 struct ISequentialStream : public IUnknown {
91 virtual HRESULT Read(void *pv, ULONG cb, ULONG *pcbRead) = 0;
92 virtual HRESULT Write(const void *pv, ULONG cb, ULONG *pcbWritten) = 0;
93 };
94
95 CROSS_PLATFORM_UUIDOF(IStream, "0000000c-0000-0000-C000-000000000046")
96 struct IStream : public ISequentialStream {
97 virtual HRESULT Seek(LARGE_INTEGER dlibMove, DWORD dwOrigin,
98 ULARGE_INTEGER *plibNewPosition) = 0;
99 virtual HRESULT SetSize(ULARGE_INTEGER libNewSize) = 0;
100 virtual HRESULT CopyTo(IStream *pstm, ULARGE_INTEGER cb,
101 ULARGE_INTEGER *pcbRead,
102 ULARGE_INTEGER *pcbWritten) = 0;
103
104 virtual HRESULT Commit(DWORD grfCommitFlags) = 0;
105
106 virtual HRESULT Revert(void) = 0;
107
108 virtual HRESULT LockRegion(ULARGE_INTEGER libOffset, ULARGE_INTEGER cb,
109 DWORD dwLockType) = 0;
110
111 virtual HRESULT UnlockRegion(ULARGE_INTEGER libOffset, ULARGE_INTEGER cb,
112 DWORD dwLockType) = 0;
113
114 virtual HRESULT Stat(STATSTG *pstatstg, DWORD grfStatFlag) = 0;
115
116 virtual HRESULT Clone(IStream **ppstm) = 0;
117 };
118
119 #endif
120
121 struct IMalloc;
122
123 struct IDxcIncludeHandler;
124
125 typedef HRESULT (__stdcall *DxcCreateInstanceProc)(
126 _In_ REFCLSID rclsid,
127 _In_ REFIID riid,
128 _Out_ LPVOID* ppv
129 );
130
131 typedef HRESULT(__stdcall *DxcCreateInstance2Proc)(
132 _In_ IMalloc *pMalloc,
133 _In_ REFCLSID rclsid,
134 _In_ REFIID riid,
135 _Out_ LPVOID* ppv
136 );
137
138 /// <summary>
139 /// Creates a single uninitialized object of the class associated with a specified CLSID.
140 /// </summary>
141 /// <param name="rclsid">
142 /// The CLSID associated with the data and code that will be used to create the object.
143 /// </param>
144 /// <param name="riid">
145 /// A reference to the identifier of the interface to be used to communicate
146 /// with the object.
147 /// </param>
148 /// <param name="ppv">
149 /// Address of pointer variable that receives the interface pointer requested
150 /// in riid. Upon successful return, *ppv contains the requested interface
151 /// pointer. Upon failure, *ppv contains NULL.</param>
152 /// <remarks>
153 /// While this function is similar to CoCreateInstance, there is no COM involvement.
154 /// </remarks>
155
156 extern "C"
157 DXC_API_IMPORT HRESULT __stdcall DxcCreateInstance(
158 _In_ REFCLSID rclsid,
159 _In_ REFIID riid,
160 _Out_ LPVOID* ppv
161 );
162
163 extern "C"
164 DXC_API_IMPORT HRESULT __stdcall DxcCreateInstance2(
165 _In_ IMalloc *pMalloc,
166 _In_ REFCLSID rclsid,
167 _In_ REFIID riid,
168 _Out_ LPVOID* ppv
169 );
170
171 // For convenience, equivalent definitions to CP_UTF8 and CP_UTF16.
172 #define DXC_CP_UTF8 65001
173 #define DXC_CP_UTF16 1200
174 // Use DXC_CP_ACP for: Binary; ANSI Text; Autodetect UTF with BOM
175 #define DXC_CP_ACP 0
176
177 // This flag indicates that the shader hash was computed taking into account source information (-Zss)
178 #define DXC_HASHFLAG_INCLUDES_SOURCE 1
179
180 // Hash digest type for ShaderHash
181 typedef struct DxcShaderHash {
182 UINT32 Flags; // DXC_HASHFLAG_*
183 BYTE HashDigest[16];
184 } DxcShaderHash;
185
186 #define DXC_FOURCC(ch0, ch1, ch2, ch3) ( \
187 (UINT32)(UINT8)(ch0) | (UINT32)(UINT8)(ch1) << 8 | \
188 (UINT32)(UINT8)(ch2) << 16 | (UINT32)(UINT8)(ch3) << 24 \
189 )
190 #define DXC_PART_PDB DXC_FOURCC('I', 'L', 'D', 'B')
191 #define DXC_PART_PDB_NAME DXC_FOURCC('I', 'L', 'D', 'N')
192 #define DXC_PART_PRIVATE_DATA DXC_FOURCC('P', 'R', 'I', 'V')
193 #define DXC_PART_ROOT_SIGNATURE DXC_FOURCC('R', 'T', 'S', '0')
194 #define DXC_PART_DXIL DXC_FOURCC('D', 'X', 'I', 'L')
195 #define DXC_PART_REFLECTION_DATA DXC_FOURCC('S', 'T', 'A', 'T')
196 #define DXC_PART_SHADER_HASH DXC_FOURCC('H', 'A', 'S', 'H')
197 #define DXC_PART_INPUT_SIGNATURE DXC_FOURCC('I', 'S', 'G', '1')
198 #define DXC_PART_OUTPUT_SIGNATURE DXC_FOURCC('O', 'S', 'G', '1')
199 #define DXC_PART_PATCH_CONSTANT_SIGNATURE DXC_FOURCC('P', 'S', 'G', '1')
200
201 // Some option arguments are defined here for continuity with D3DCompile interface
202 #define DXC_ARG_DEBUG L"-Zi"
203 #define DXC_ARG_SKIP_VALIDATION L"-Vd"
204 #define DXC_ARG_SKIP_OPTIMIZATIONS L"-Od"
205 #define DXC_ARG_PACK_MATRIX_ROW_MAJOR L"-Zpr"
206 #define DXC_ARG_PACK_MATRIX_COLUMN_MAJOR L"-Zpc"
207 #define DXC_ARG_AVOID_FLOW_CONTROL L"-Gfa"
208 #define DXC_ARG_PREFER_FLOW_CONTROL L"-Gfp"
209 #define DXC_ARG_ENABLE_STRICTNESS L"-Ges"
210 #define DXC_ARG_ENABLE_BACKWARDS_COMPATIBILITY L"-Gec"
211 #define DXC_ARG_IEEE_STRICTNESS L"-Gis"
212 #define DXC_ARG_OPTIMIZATION_LEVEL0 L"-O0"
213 #define DXC_ARG_OPTIMIZATION_LEVEL1 L"-O1"
214 #define DXC_ARG_OPTIMIZATION_LEVEL2 L"-O2"
215 #define DXC_ARG_OPTIMIZATION_LEVEL3 L"-O3"
216 #define DXC_ARG_WARNINGS_ARE_ERRORS L"-WX"
217 #define DXC_ARG_RESOURCES_MAY_ALIAS L"-res_may_alias"
218 #define DXC_ARG_ALL_RESOURCES_BOUND L"-all_resources_bound"
219 #define DXC_ARG_DEBUG_NAME_FOR_SOURCE L"-Zss"
220 #define DXC_ARG_DEBUG_NAME_FOR_BINARY L"-Zsb"
221
222 // IDxcBlob is an alias of ID3D10Blob and ID3DBlob
223 CROSS_PLATFORM_UUIDOF(IDxcBlob, "8BA5FB08-5195-40e2-AC58-0D989C3A0102")
224 struct IDxcBlob : public IUnknown {
225 public:
226 virtual LPVOID STDMETHODCALLTYPE GetBufferPointer(void) = 0;
227 virtual SIZE_T STDMETHODCALLTYPE GetBufferSize(void) = 0;
228 };
229
230 CROSS_PLATFORM_UUIDOF(IDxcBlobEncoding, "7241d424-2646-4191-97c0-98e96e42fc68")
231 struct IDxcBlobEncoding : public IDxcBlob {
232 public:
233 virtual HRESULT STDMETHODCALLTYPE GetEncoding(_Out_ BOOL *pKnown,
234 _Out_ UINT32 *pCodePage) = 0;
235 };
236
237 // Notes on IDxcBlobUtf16 and IDxcBlobUtf8
238 // These guarantee null-terminated text and the stated encoding.
239 // GetBufferSize() will return the size in bytes, including null-terminator
240 // GetStringLength() will return the length in characters, excluding the null-terminator
241 // Name strings will use IDxcBlobUtf16, while other string output blobs,
242 // such as errors/warnings, preprocessed HLSL, or other text will be based
243 // on the -encoding option.
244
245 // The API will use this interface for output name strings
246 CROSS_PLATFORM_UUIDOF(IDxcBlobUtf16, "A3F84EAB-0FAA-497E-A39C-EE6ED60B2D84")
247 struct IDxcBlobUtf16 : public IDxcBlobEncoding {
248 public:
249 virtual LPCWSTR STDMETHODCALLTYPE GetStringPointer(void) = 0;
250 virtual SIZE_T STDMETHODCALLTYPE GetStringLength(void) = 0;
251 };
252 CROSS_PLATFORM_UUIDOF(IDxcBlobUtf8, "3DA636C9-BA71-4024-A301-30CBF125305B")
253 struct IDxcBlobUtf8 : public IDxcBlobEncoding {
254 public:
255 virtual LPCSTR STDMETHODCALLTYPE GetStringPointer(void) = 0;
256 virtual SIZE_T STDMETHODCALLTYPE GetStringLength(void) = 0;
257 };
258
259 CROSS_PLATFORM_UUIDOF(IDxcIncludeHandler, "7f61fc7d-950d-467f-b3e3-3c02fb49187c")
260 struct IDxcIncludeHandler : public IUnknown {
261 virtual HRESULT STDMETHODCALLTYPE LoadSource(
262 _In_z_ LPCWSTR pFilename, // Candidate filename.
263 _COM_Outptr_result_maybenull_ IDxcBlob **ppIncludeSource // Resultant source object for included file, nullptr if not found.
264 ) = 0;
265 };
266
267 // Structure for supplying bytes or text input to Dxc APIs.
268 // Use Encoding = 0 for non-text bytes, ANSI text, or unknown with BOM.
269 typedef struct DxcBuffer {
270 LPCVOID Ptr;
271 SIZE_T Size;
272 UINT Encoding;
273 } DxcText;
274
275 struct DxcDefine {
276 LPCWSTR Name;
277 _Maybenull_ LPCWSTR Value;
278 };
279
280 CROSS_PLATFORM_UUIDOF(IDxcCompilerArgs, "73EFFE2A-70DC-45F8-9690-EFF64C02429D")
281 struct IDxcCompilerArgs : public IUnknown {
282 // Pass GetArguments() and GetCount() to Compile
283 virtual LPCWSTR* STDMETHODCALLTYPE GetArguments() = 0;
284 virtual UINT32 STDMETHODCALLTYPE GetCount() = 0;
285
286 // Add additional arguments or defines here, if desired.
287 virtual HRESULT STDMETHODCALLTYPE AddArguments(
288 _In_opt_count_(argCount) LPCWSTR *pArguments, // Array of pointers to arguments to add
289 _In_ UINT32 argCount // Number of arguments to add
290 ) = 0;
291 virtual HRESULT STDMETHODCALLTYPE AddArgumentsUTF8(
292 _In_opt_count_(argCount)LPCSTR *pArguments, // Array of pointers to UTF-8 arguments to add
293 _In_ UINT32 argCount // Number of arguments to add
294 ) = 0;
295 virtual HRESULT STDMETHODCALLTYPE AddDefines(
296 _In_count_(defineCount) const DxcDefine *pDefines, // Array of defines
297 _In_ UINT32 defineCount // Number of defines
298 ) = 0;
299 };
300
301 //////////////////////////
302 // Legacy Interfaces
303 /////////////////////////
304
305 // NOTE: IDxcUtils replaces IDxcLibrary
306 CROSS_PLATFORM_UUIDOF(IDxcLibrary, "e5204dc7-d18c-4c3c-bdfb-851673980fe7")
307 struct IDxcLibrary : public IUnknown {
308 virtual HRESULT STDMETHODCALLTYPE SetMalloc(_In_opt_ IMalloc *pMalloc) = 0;
309 virtual HRESULT STDMETHODCALLTYPE CreateBlobFromBlob(
310 _In_ IDxcBlob *pBlob, UINT32 offset, UINT32 length, _COM_Outptr_ IDxcBlob **ppResult) = 0;
311 virtual HRESULT STDMETHODCALLTYPE CreateBlobFromFile(
312 _In_z_ LPCWSTR pFileName, _In_opt_ UINT32* codePage,
313 _COM_Outptr_ IDxcBlobEncoding **pBlobEncoding) = 0;
314 virtual HRESULT STDMETHODCALLTYPE CreateBlobWithEncodingFromPinned(
315 _In_bytecount_(size) LPCVOID pText, UINT32 size, UINT32 codePage,
316 _COM_Outptr_ IDxcBlobEncoding **pBlobEncoding) = 0;
317 virtual HRESULT STDMETHODCALLTYPE CreateBlobWithEncodingOnHeapCopy(
318 _In_bytecount_(size) LPCVOID pText, UINT32 size, UINT32 codePage,
319 _COM_Outptr_ IDxcBlobEncoding **pBlobEncoding) = 0;
320 virtual HRESULT STDMETHODCALLTYPE CreateBlobWithEncodingOnMalloc(
321 _In_bytecount_(size) LPCVOID pText, IMalloc *pIMalloc, UINT32 size, UINT32 codePage,
322 _COM_Outptr_ IDxcBlobEncoding **pBlobEncoding) = 0;
323 virtual HRESULT STDMETHODCALLTYPE CreateIncludeHandler(
324 _COM_Outptr_ IDxcIncludeHandler **ppResult) = 0;
325 virtual HRESULT STDMETHODCALLTYPE CreateStreamFromBlobReadOnly(
326 _In_ IDxcBlob *pBlob, _COM_Outptr_ IStream **ppStream) = 0;
327 virtual HRESULT STDMETHODCALLTYPE GetBlobAsUtf8(
328 _In_ IDxcBlob *pBlob, _COM_Outptr_ IDxcBlobEncoding **pBlobEncoding) = 0;
329 virtual HRESULT STDMETHODCALLTYPE GetBlobAsUtf16(
330 _In_ IDxcBlob *pBlob, _COM_Outptr_ IDxcBlobEncoding **pBlobEncoding) = 0;
331 };
332
333 // NOTE: IDxcResult replaces IDxcOperationResult
334 CROSS_PLATFORM_UUIDOF(IDxcOperationResult, "CEDB484A-D4E9-445A-B991-CA21CA157DC2")
335 struct IDxcOperationResult : public IUnknown {
336 virtual HRESULT STDMETHODCALLTYPE GetStatus(_Out_ HRESULT *pStatus) = 0;
337
338 // GetResult returns the main result of the operation.
339 // This corresponds to:
340 // DXC_OUT_OBJECT - Compile() with shader or library target
341 // DXC_OUT_DISASSEMBLY - Disassemble()
342 // DXC_OUT_HLSL - Compile() with -P
343 // DXC_OUT_ROOT_SIGNATURE - Compile() with rootsig_* target
344 virtual HRESULT STDMETHODCALLTYPE GetResult(_COM_Outptr_result_maybenull_ IDxcBlob **ppResult) = 0;
345
346 // GetErrorBuffer Corresponds to DXC_OUT_ERRORS.
347 virtual HRESULT STDMETHODCALLTYPE GetErrorBuffer(_COM_Outptr_result_maybenull_ IDxcBlobEncoding **ppErrors) = 0;
348 };
349
350 // NOTE: IDxcCompiler3 replaces IDxcCompiler and IDxcCompiler2
351 CROSS_PLATFORM_UUIDOF(IDxcCompiler, "8c210bf3-011f-4422-8d70-6f9acb8db617")
352 struct IDxcCompiler : public IUnknown {
353 // Compile a single entry point to the target shader model
354 virtual HRESULT STDMETHODCALLTYPE Compile(
355 _In_ IDxcBlob *pSource, // Source text to compile
356 _In_opt_z_ LPCWSTR pSourceName, // Optional file name for pSource. Used in errors and include handlers.
357 _In_opt_z_ LPCWSTR pEntryPoint, // entry point name
358 _In_z_ LPCWSTR pTargetProfile, // shader profile to compile
359 _In_opt_count_(argCount) LPCWSTR *pArguments, // Array of pointers to arguments
360 _In_ UINT32 argCount, // Number of arguments
361 _In_count_(defineCount)
362 const DxcDefine *pDefines, // Array of defines
363 _In_ UINT32 defineCount, // Number of defines
364 _In_opt_ IDxcIncludeHandler *pIncludeHandler, // user-provided interface to handle #include directives (optional)
365 _COM_Outptr_ IDxcOperationResult **ppResult // Compiler output status, buffer, and errors
366 ) = 0;
367
368 // Preprocess source text
369 virtual HRESULT STDMETHODCALLTYPE Preprocess(
370 _In_ IDxcBlob *pSource, // Source text to preprocess
371 _In_opt_z_ LPCWSTR pSourceName, // Optional file name for pSource. Used in errors and include handlers.
372 _In_opt_count_(argCount) LPCWSTR *pArguments, // Array of pointers to arguments
373 _In_ UINT32 argCount, // Number of arguments
374 _In_count_(defineCount)
375 const DxcDefine *pDefines, // Array of defines
376 _In_ UINT32 defineCount, // Number of defines
377 _In_opt_ IDxcIncludeHandler *pIncludeHandler, // user-provided interface to handle #include directives (optional)
378 _COM_Outptr_ IDxcOperationResult **ppResult // Preprocessor output status, buffer, and errors
379 ) = 0;
380
381 // Disassemble a program.
382 virtual HRESULT STDMETHODCALLTYPE Disassemble(
383 _In_ IDxcBlob *pSource, // Program to disassemble.
384 _COM_Outptr_ IDxcBlobEncoding **ppDisassembly // Disassembly text.
385 ) = 0;
386 };
387
388 // NOTE: IDxcCompiler3 replaces IDxcCompiler and IDxcCompiler2
389 CROSS_PLATFORM_UUIDOF(IDxcCompiler2, "A005A9D9-B8BB-4594-B5C9-0E633BEC4D37")
390 struct IDxcCompiler2 : public IDxcCompiler {
391 // Compile a single entry point to the target shader model with debug information.
392 virtual HRESULT STDMETHODCALLTYPE CompileWithDebug(
393 _In_ IDxcBlob *pSource, // Source text to compile
394 _In_opt_z_ LPCWSTR pSourceName, // Optional file name for pSource. Used in errors and include handlers.
395 _In_opt_z_ LPCWSTR pEntryPoint, // Entry point name
396 _In_z_ LPCWSTR pTargetProfile, // Shader profile to compile
397 _In_opt_count_(argCount) LPCWSTR *pArguments, // Array of pointers to arguments
398 _In_ UINT32 argCount, // Number of arguments
399 _In_count_(defineCount)
400 const DxcDefine *pDefines, // Array of defines
401 _In_ UINT32 defineCount, // Number of defines
402 _In_opt_ IDxcIncludeHandler *pIncludeHandler, // user-provided interface to handle #include directives (optional)
403 _COM_Outptr_ IDxcOperationResult **ppResult, // Compiler output status, buffer, and errors
404 _Outptr_opt_result_z_ LPWSTR *ppDebugBlobName,// Suggested file name for debug blob. (Must be HeapFree()'d!)
405 _COM_Outptr_opt_ IDxcBlob **ppDebugBlob // Debug blob
406 ) = 0;
407 };
408
409 CROSS_PLATFORM_UUIDOF(IDxcLinker, "F1B5BE2A-62DD-4327-A1C2-42AC1E1E78E6")
410 struct IDxcLinker : public IUnknown {
411 public:
412 // Register a library with name to ref it later.
413 virtual HRESULT RegisterLibrary(
414 _In_opt_ LPCWSTR pLibName, // Name of the library.
415 _In_ IDxcBlob *pLib // Library blob.
416 ) = 0;
417
418 // Links the shader and produces a shader blob that the Direct3D runtime can
419 // use.
420 virtual HRESULT STDMETHODCALLTYPE Link(
421 _In_opt_ LPCWSTR pEntryName, // Entry point name
422 _In_ LPCWSTR pTargetProfile, // shader profile to link
423 _In_count_(libCount)
424 const LPCWSTR *pLibNames, // Array of library names to link
425 _In_ UINT32 libCount, // Number of libraries to link
426 _In_opt_count_(argCount) const LPCWSTR *pArguments, // Array of pointers to arguments
427 _In_ UINT32 argCount, // Number of arguments
428 _COM_Outptr_
429 IDxcOperationResult **ppResult // Linker output status, buffer, and errors
430 ) = 0;
431 };
432
433 /////////////////////////
434 // Latest interfaces. Please use these
435 ////////////////////////
436
437 // NOTE: IDxcUtils replaces IDxcLibrary
438 CROSS_PLATFORM_UUIDOF(IDxcUtils, "4605C4CB-2019-492A-ADA4-65F20BB7D67F")
439 struct IDxcUtils : public IUnknown {
440 // Create a sub-blob that holds a reference to the outer blob and points to its memory.
441 virtual HRESULT STDMETHODCALLTYPE CreateBlobFromBlob(
442 _In_ IDxcBlob *pBlob, UINT32 offset, UINT32 length, _COM_Outptr_ IDxcBlob **ppResult) = 0;
443
444 // For codePage, use 0 (or DXC_CP_ACP) for raw binary or ANSI code page
445
446 // Creates a blob referencing existing memory, with no copy.
447 // User must manage the memory lifetime separately.
448 // (was: CreateBlobWithEncodingFromPinned)
449 virtual HRESULT STDMETHODCALLTYPE CreateBlobFromPinned(
450 _In_bytecount_(size) LPCVOID pData, UINT32 size, UINT32 codePage,
451 _COM_Outptr_ IDxcBlobEncoding **pBlobEncoding) = 0;
452
453 // Create blob, taking ownership of memory allocated with supplied allocator.
454 // (was: CreateBlobWithEncodingOnMalloc)
455 virtual HRESULT STDMETHODCALLTYPE MoveToBlob(
456 _In_bytecount_(size) LPCVOID pData, IMalloc *pIMalloc, UINT32 size, UINT32 codePage,
457 _COM_Outptr_ IDxcBlobEncoding **pBlobEncoding) = 0;
458
459 ////
460 // New blobs and copied contents are allocated with the current allocator
461
462 // Copy blob contents to memory owned by the new blob.
463 // (was: CreateBlobWithEncodingOnHeapCopy)
464 virtual HRESULT STDMETHODCALLTYPE CreateBlob(
465 _In_bytecount_(size) LPCVOID pData, UINT32 size, UINT32 codePage,
466 _COM_Outptr_ IDxcBlobEncoding **pBlobEncoding) = 0;
467
468 // (was: CreateBlobFromFile)
469 virtual HRESULT STDMETHODCALLTYPE LoadFile(
470 _In_z_ LPCWSTR pFileName, _In_opt_ UINT32* pCodePage,
471 _COM_Outptr_ IDxcBlobEncoding **pBlobEncoding) = 0;
472
473 virtual HRESULT STDMETHODCALLTYPE CreateReadOnlyStreamFromBlob(
474 _In_ IDxcBlob *pBlob, _COM_Outptr_ IStream **ppStream) = 0;
475
476 // Create default file-based include handler
477 virtual HRESULT STDMETHODCALLTYPE CreateDefaultIncludeHandler(
478 _COM_Outptr_ IDxcIncludeHandler **ppResult) = 0;
479
480 // Convert or return matching encoded text blobs
481 virtual HRESULT STDMETHODCALLTYPE GetBlobAsUtf8(
482 _In_ IDxcBlob *pBlob, _COM_Outptr_ IDxcBlobUtf8 **pBlobEncoding) = 0;
483 virtual HRESULT STDMETHODCALLTYPE GetBlobAsUtf16(
484 _In_ IDxcBlob *pBlob, _COM_Outptr_ IDxcBlobUtf16 **pBlobEncoding) = 0;
485
486 virtual HRESULT STDMETHODCALLTYPE GetDxilContainerPart(
487 _In_ const DxcBuffer *pShader,
488 _In_ UINT32 DxcPart,
489 _Outptr_result_nullonfailure_ void **ppPartData,
490 _Out_ UINT32 *pPartSizeInBytes) = 0;
491
492 // Create reflection interface from serialized Dxil container, or DXC_PART_REFLECTION_DATA.
493 // TBD: Require part header for RDAT? (leaning towards yes)
494 virtual HRESULT STDMETHODCALLTYPE CreateReflection(
495 _In_ const DxcBuffer *pData, REFIID iid, void **ppvReflection) = 0;
496
497 virtual HRESULT STDMETHODCALLTYPE BuildArguments(
498 _In_opt_z_ LPCWSTR pSourceName, // Optional file name for pSource. Used in errors and include handlers.
499 _In_opt_z_ LPCWSTR pEntryPoint, // Entry point name. (-E)
500 _In_z_ LPCWSTR pTargetProfile, // Shader profile to compile. (-T)
501 _In_opt_count_(argCount) LPCWSTR *pArguments, // Array of pointers to arguments
502 _In_ UINT32 argCount, // Number of arguments
503 _In_count_(defineCount)
504 const DxcDefine *pDefines, // Array of defines
505 _In_ UINT32 defineCount, // Number of defines
506 _COM_Outptr_ IDxcCompilerArgs **ppArgs // Arguments you can use with Compile() method
507 ) = 0;
508
509 // Takes the shader PDB and returns the hash and the container inside it
510 virtual HRESULT STDMETHODCALLTYPE GetPDBContents(
511 _In_ IDxcBlob *pPDBBlob, _COM_Outptr_ IDxcBlob **ppHash, _COM_Outptr_ IDxcBlob **ppContainer) = 0;
512 };
513
514 // For use with IDxcResult::[Has|Get]Output dxcOutKind argument
515 // Note: text outputs returned from version 2 APIs are UTF-8 or UTF-16 based on -encoding option
516 typedef enum DXC_OUT_KIND {
517 DXC_OUT_NONE = 0,
518 DXC_OUT_OBJECT = 1, // IDxcBlob - Shader or library object
519 DXC_OUT_ERRORS = 2, // IDxcBlobUtf8 or IDxcBlobUtf16
520 DXC_OUT_PDB = 3, // IDxcBlob
521 DXC_OUT_SHADER_HASH = 4, // IDxcBlob - DxcShaderHash of shader or shader with source info (-Zsb/-Zss)
522 DXC_OUT_DISASSEMBLY = 5, // IDxcBlobUtf8 or IDxcBlobUtf16 - from Disassemble
523 DXC_OUT_HLSL = 6, // IDxcBlobUtf8 or IDxcBlobUtf16 - from Preprocessor or Rewriter
524 DXC_OUT_TEXT = 7, // IDxcBlobUtf8 or IDxcBlobUtf16 - other text, such as -ast-dump or -Odump
525 DXC_OUT_REFLECTION = 8, // IDxcBlob - RDAT part with reflection data
526 DXC_OUT_ROOT_SIGNATURE = 9, // IDxcBlob - Serialized root signature output
527 DXC_OUT_EXTRA_OUTPUTS = 10,// IDxcExtraResults - Extra outputs
528
529 DXC_OUT_FORCE_DWORD = 0xFFFFFFFF
530 } DXC_OUT_KIND;
531
532 CROSS_PLATFORM_UUIDOF(IDxcResult, "58346CDA-DDE7-4497-9461-6F87AF5E0659")
533 struct IDxcResult : public IDxcOperationResult {
534 virtual BOOL STDMETHODCALLTYPE HasOutput(_In_ DXC_OUT_KIND dxcOutKind) = 0;
535 virtual HRESULT STDMETHODCALLTYPE GetOutput(_In_ DXC_OUT_KIND dxcOutKind,
536 _In_ REFIID iid, _COM_Outptr_opt_result_maybenull_ void **ppvObject,
537 _COM_Outptr_ IDxcBlobUtf16 **ppOutputName) = 0;
538
539 virtual UINT32 GetNumOutputs() = 0;
540 virtual DXC_OUT_KIND GetOutputByIndex(UINT32 Index) = 0;
541 virtual DXC_OUT_KIND PrimaryOutput() = 0;
542 };
543
544 // Special names for extra output that should get written to specific streams
545 #define DXC_EXTRA_OUTPUT_NAME_STDOUT L"*stdout*"
546 #define DXC_EXTRA_OUTPUT_NAME_STDERR L"*stderr*"
547
548 CROSS_PLATFORM_UUIDOF(IDxcExtraOutputs, "319b37a2-a5c2-494a-a5de-4801b2faf989")
549 struct IDxcExtraOutputs : public IUnknown {
550
551 virtual UINT32 STDMETHODCALLTYPE GetOutputCount() = 0;
552 virtual HRESULT STDMETHODCALLTYPE GetOutput(_In_ UINT32 uIndex,
553 _In_ REFIID iid, _COM_Outptr_opt_result_maybenull_ void **ppvObject,
554 _COM_Outptr_opt_result_maybenull_ IDxcBlobUtf16 **ppOutputType,
555 _COM_Outptr_opt_result_maybenull_ IDxcBlobUtf16 **ppOutputName) = 0;
556 };
557
558 CROSS_PLATFORM_UUIDOF(IDxcCompiler3, "228B4687-5A6A-4730-900C-9702B2203F54")
559 struct IDxcCompiler3 : public IUnknown {
560 // Compile a single entry point to the target shader model,
561 // Compile a library to a library target (-T lib_*),
562 // Compile a root signature (-T rootsig_*), or
563 // Preprocess HLSL source (-P)
564 virtual HRESULT STDMETHODCALLTYPE Compile(
565 _In_ const DxcBuffer *pSource, // Source text to compile
566 _In_opt_count_(argCount) LPCWSTR *pArguments, // Array of pointers to arguments
567 _In_ UINT32 argCount, // Number of arguments
568 _In_opt_ IDxcIncludeHandler *pIncludeHandler, // user-provided interface to handle #include directives (optional)
569 _In_ REFIID riid, _Out_ LPVOID *ppResult // IDxcResult: status, buffer, and errors
570 ) = 0;
571
572 // Disassemble a program.
573 virtual HRESULT STDMETHODCALLTYPE Disassemble(
574 _In_ const DxcBuffer *pObject, // Program to disassemble: dxil container or bitcode.
575 _In_ REFIID riid, _Out_ LPVOID *ppResult // IDxcResult: status, disassembly text, and errors
576 ) = 0;
577 };
578
579 static const UINT32 DxcValidatorFlags_Default = 0;
580 static const UINT32 DxcValidatorFlags_InPlaceEdit = 1; // Validator is allowed to update shader blob in-place.
581 static const UINT32 DxcValidatorFlags_RootSignatureOnly = 2;
582 static const UINT32 DxcValidatorFlags_ModuleOnly = 4;
583 static const UINT32 DxcValidatorFlags_ValidMask = 0x7;
584
585 CROSS_PLATFORM_UUIDOF(IDxcValidator, "A6E82BD2-1FD7-4826-9811-2857E797F49A")
586 struct IDxcValidator : public IUnknown {
587 // Validate a shader.
588 virtual HRESULT STDMETHODCALLTYPE Validate(
589 _In_ IDxcBlob *pShader, // Shader to validate.
590 _In_ UINT32 Flags, // Validation flags.
591 _COM_Outptr_ IDxcOperationResult **ppResult // Validation output status, buffer, and errors
592 ) = 0;
593 };
594
595 CROSS_PLATFORM_UUIDOF(IDxcContainerBuilder, "334b1f50-2292-4b35-99a1-25588d8c17fe")
596 struct IDxcContainerBuilder : public IUnknown {
597 virtual HRESULT STDMETHODCALLTYPE Load(_In_ IDxcBlob *pDxilContainerHeader) = 0; // Loads DxilContainer to the builder
598 virtual HRESULT STDMETHODCALLTYPE AddPart(_In_ UINT32 fourCC, _In_ IDxcBlob *pSource) = 0; // Part to add to the container
599 virtual HRESULT STDMETHODCALLTYPE RemovePart(_In_ UINT32 fourCC) = 0; // Remove the part with fourCC
600 virtual HRESULT STDMETHODCALLTYPE SerializeContainer(_Out_ IDxcOperationResult **ppResult) = 0; // Builds a container of the given container builder state
601 };
602
603 CROSS_PLATFORM_UUIDOF(IDxcAssembler, "091f7a26-1c1f-4948-904b-e6e3a8a771d5")
604 struct IDxcAssembler : public IUnknown {
605 // Assemble dxil in ll or llvm bitcode to DXIL container.
606 virtual HRESULT STDMETHODCALLTYPE AssembleToContainer(
607 _In_ IDxcBlob *pShader, // Shader to assemble.
608 _COM_Outptr_ IDxcOperationResult **ppResult // Assembly output status, buffer, and errors
609 ) = 0;
610 };
611
612 CROSS_PLATFORM_UUIDOF(IDxcContainerReflection, "d2c21b26-8350-4bdc-976a-331ce6f4c54c")
613 struct IDxcContainerReflection : public IUnknown {
614 virtual HRESULT STDMETHODCALLTYPE Load(_In_ IDxcBlob *pContainer) = 0; // Container to load.
615 virtual HRESULT STDMETHODCALLTYPE GetPartCount(_Out_ UINT32 *pResult) = 0;
616 virtual HRESULT STDMETHODCALLTYPE GetPartKind(UINT32 idx, _Out_ UINT32 *pResult) = 0;
617 virtual HRESULT STDMETHODCALLTYPE GetPartContent(UINT32 idx, _COM_Outptr_ IDxcBlob **ppResult) = 0;
618 virtual HRESULT STDMETHODCALLTYPE FindFirstPartKind(UINT32 kind, _Out_ UINT32 *pResult) = 0;
619 virtual HRESULT STDMETHODCALLTYPE GetPartReflection(UINT32 idx, REFIID iid, void **ppvObject) = 0;
620 };
621
622 CROSS_PLATFORM_UUIDOF(IDxcOptimizerPass, "AE2CD79F-CC22-453F-9B6B-B124E7A5204C")
623 struct IDxcOptimizerPass : public IUnknown {
624 virtual HRESULT STDMETHODCALLTYPE GetOptionName(_COM_Outptr_ LPWSTR *ppResult) = 0;
625 virtual HRESULT STDMETHODCALLTYPE GetDescription(_COM_Outptr_ LPWSTR *ppResult) = 0;
626 virtual HRESULT STDMETHODCALLTYPE GetOptionArgCount(_Out_ UINT32 *pCount) = 0;
627 virtual HRESULT STDMETHODCALLTYPE GetOptionArgName(UINT32 argIndex, _COM_Outptr_ LPWSTR *ppResult) = 0;
628 virtual HRESULT STDMETHODCALLTYPE GetOptionArgDescription(UINT32 argIndex, _COM_Outptr_ LPWSTR *ppResult) = 0;
629 };
630
631 CROSS_PLATFORM_UUIDOF(IDxcOptimizer, "25740E2E-9CBA-401B-9119-4FB42F39F270")
632 struct IDxcOptimizer : public IUnknown {
633 virtual HRESULT STDMETHODCALLTYPE GetAvailablePassCount(_Out_ UINT32 *pCount) = 0;
634 virtual HRESULT STDMETHODCALLTYPE GetAvailablePass(UINT32 index, _COM_Outptr_ IDxcOptimizerPass** ppResult) = 0;
635 virtual HRESULT STDMETHODCALLTYPE RunOptimizer(IDxcBlob *pBlob,
636 _In_count_(optionCount) LPCWSTR *ppOptions, UINT32 optionCount,
637 _COM_Outptr_ IDxcBlob **pOutputModule,
638 _COM_Outptr_opt_ IDxcBlobEncoding **ppOutputText) = 0;
639 };
640
641 static const UINT32 DxcVersionInfoFlags_None = 0;
642 static const UINT32 DxcVersionInfoFlags_Debug = 1; // Matches VS_FF_DEBUG
643 static const UINT32 DxcVersionInfoFlags_Internal = 2; // Internal Validator (non-signing)
644
645 CROSS_PLATFORM_UUIDOF(IDxcVersionInfo, "b04f5b50-2059-4f12-a8ff-a1e0cde1cc7e")
646 struct IDxcVersionInfo : public IUnknown {
647 virtual HRESULT STDMETHODCALLTYPE GetVersion(_Out_ UINT32 *pMajor, _Out_ UINT32 *pMinor) = 0;
648 virtual HRESULT STDMETHODCALLTYPE GetFlags(_Out_ UINT32 *pFlags) = 0;
649 };
650
651 CROSS_PLATFORM_UUIDOF(IDxcVersionInfo2, "fb6904c4-42f0-4b62-9c46-983af7da7c83")
652 struct IDxcVersionInfo2 : public IDxcVersionInfo {
653 virtual HRESULT STDMETHODCALLTYPE GetCommitInfo(_Out_ UINT32 *pCommitCount, _Out_ char **pCommitHash) = 0;
654 };
655
656 // Note: __declspec(selectany) requires 'extern'
657 // On Linux __declspec(selectany) is removed and using 'extern' results in link error.
658 #ifdef _MSC_VER
659 #define CLSID_SCOPE __declspec(selectany) extern
660 #else
661 #define CLSID_SCOPE
662 #endif
663
664 CLSID_SCOPE const CLSID CLSID_DxcCompiler = {
665 0x73e22d93,
666 0xe6ce,
667 0x47f3,
668 {0xb5, 0xbf, 0xf0, 0x66, 0x4f, 0x39, 0xc1, 0xb0}};
669
670 // {EF6A8087-B0EA-4D56-9E45-D07E1A8B7806}
671 CLSID_SCOPE const GUID CLSID_DxcLinker = {
672 0xef6a8087,
673 0xb0ea,
674 0x4d56,
675 {0x9e, 0x45, 0xd0, 0x7e, 0x1a, 0x8b, 0x78, 0x6}};
676
677 // {CD1F6B73-2AB0-484D-8EDC-EBE7A43CA09F}
678 CLSID_SCOPE const CLSID CLSID_DxcDiaDataSource = {
679 0xcd1f6b73,
680 0x2ab0,
681 0x484d,
682 {0x8e, 0xdc, 0xeb, 0xe7, 0xa4, 0x3c, 0xa0, 0x9f}};
683
684 // {3E56AE82-224D-470F-A1A1-FE3016EE9F9D}
685 CLSID_SCOPE const CLSID CLSID_DxcCompilerArgs = {
686 0x3e56ae82,
687 0x224d,
688 0x470f,
689 {0xa1, 0xa1, 0xfe, 0x30, 0x16, 0xee, 0x9f, 0x9d}};
690
691 // {6245D6AF-66E0-48FD-80B4-4D271796748C}
692 CLSID_SCOPE const GUID CLSID_DxcLibrary = {
693 0x6245d6af,
694 0x66e0,
695 0x48fd,
696 {0x80, 0xb4, 0x4d, 0x27, 0x17, 0x96, 0x74, 0x8c}};
697
698 CLSID_SCOPE const GUID CLSID_DxcUtils = CLSID_DxcLibrary;
699
700 // {8CA3E215-F728-4CF3-8CDD-88AF917587A1}
701 CLSID_SCOPE const GUID CLSID_DxcValidator = {
702 0x8ca3e215,
703 0xf728,
704 0x4cf3,
705 {0x8c, 0xdd, 0x88, 0xaf, 0x91, 0x75, 0x87, 0xa1}};
706
707 // {D728DB68-F903-4F80-94CD-DCCF76EC7151}
708 CLSID_SCOPE const GUID CLSID_DxcAssembler = {
709 0xd728db68,
710 0xf903,
711 0x4f80,
712 {0x94, 0xcd, 0xdc, 0xcf, 0x76, 0xec, 0x71, 0x51}};
713
714 // {b9f54489-55b8-400c-ba3a-1675e4728b91}
715 CLSID_SCOPE const GUID CLSID_DxcContainerReflection = {
716 0xb9f54489,
717 0x55b8,
718 0x400c,
719 {0xba, 0x3a, 0x16, 0x75, 0xe4, 0x72, 0x8b, 0x91}};
720
721 // {AE2CD79F-CC22-453F-9B6B-B124E7A5204C}
722 CLSID_SCOPE const GUID CLSID_DxcOptimizer = {
723 0xae2cd79f,
724 0xcc22,
725 0x453f,
726 {0x9b, 0x6b, 0xb1, 0x24, 0xe7, 0xa5, 0x20, 0x4c}};
727
728 // {94134294-411f-4574-b4d0-8741e25240d2}
729 CLSID_SCOPE const GUID CLSID_DxcContainerBuilder = {
730 0x94134294,
731 0x411f,
732 0x4574,
733 {0xb4, 0xd0, 0x87, 0x41, 0xe2, 0x52, 0x40, 0xd2}};
734 #endif
735