1/*2 * zdxc: an HLSL 2021 to DXIL and SPIR-V compiler.3 *4 * The C API. Link libzdxc statically (zig build -Dlinkage=static, the5 * default) or dynamically (-Dlinkage=dynamic); it needs nothing besides6 * the platform's C library. See docs/c-api.md.7 *8 * A compilation takes a dxc command line and returns its outputs in9 * memory:10 *11 * const char *args[] = {"-T", "ps_6_0", "-E", "PS"};12 * zdxc_compile_info info = {13 * .size = sizeof info,14 * .source = text, .source_size = text_size,15 * .source_name = "mesh.hlsl",16 * .args = args, .arg_count = 4,17 * };18 * zdxc_result *r = zdxc_compile(&info);19 * if (!r) { ... out of memory ... }20 * size_t size;21 * const char *diags = zdxc_result_output(r, ZDXC_OUTPUT_DIAGNOSTICS, &size);22 * if (zdxc_result_status(r) == ZDXC_STATUS_OK) {23 * const void *dxil = zdxc_result_output(r, ZDXC_OUTPUT_OBJECT, &size);24 * ...25 * }26 * zdxc_result_free(r);27 *28 * zdxc never writes files: -Fo, -Fi and -Frs only name the outputs. It29 * keeps no global state, so any number of threads may compile at once.30 */31#ifndef ZDXC_H32#define ZDXC_H3334#include <stddef.h>35#include <stdint.h>3637#ifdef __cplusplus38extern "C" {39#endif4041#define ZDXC_API_VERSION 14243typedef struct zdxc_result zdxc_result;4445/* A compilation's outcome. The values are dxc's exit codes. */46typedef enum zdxc_status {47 ZDXC_STATUS_OK = 0,48 /* Bad options, or an input that cannot be read. */49 ZDXC_STATUS_FAILED = 1,50 /* Errors in the source. */51 ZDXC_STATUS_COMPILE_FAILED = 552} zdxc_status;5354typedef enum zdxc_output {55 /* The DXIL container or SPIR-V module. */56 ZDXC_OUTPUT_OBJECT = 0,57 /* Errors, warnings and notes, as the command line prints them. Present58 * after a failure and, with warnings, after a success. */59 ZDXC_OUTPUT_DIAGNOSTICS = 1,60 /* The preprocessed source (-P). */61 ZDXC_OUTPUT_PREPROCESSED = 2,62 /* A container holding the root signature (-Frs). */63 ZDXC_OUTPUT_ROOT_SIGNATURE = 3,64 /* Other text the command line prints (-help, --version). */65 ZDXC_OUTPUT_TEXT = 466} zdxc_output;6768/*69 * Reads a file: the input when no source text is given, and every70 * #include candidate (the including file's directory, then each -I71 * directory). On success, set *data and *size and return 0; the memory72 * must stay valid until zdxc_compile returns. Return nonzero if the file73 * does not exist, and zdxc tries the next candidate.74 */75typedef int (*zdxc_read_file_fn)(void *user, const char *path, const char **data, size_t *size);7677typedef struct zdxc_compile_info {78 /* sizeof(zdxc_compile_info): lets later versions add fields. */79 uint32_t size;80 /* dxc command-line options, without the program name. A positional81 * argument names the input file. */82 const char *const *args;83 size_t arg_count;84 /* The main file's text (a trailing NUL is allowed), or NULL to read the85 * input file named in args with read_file. */86 const char *source;87 size_t source_size;88 /* The main file's name in diagnostics and for #include "...". NULL89 * means the input file in args, else "hlsl.hlsl". */90 const char *source_name;91 /* Reads files; NULL reads them from disk relative to the current92 * directory. */93 zdxc_read_file_fn read_file;94 void *user;95} zdxc_compile_info;9697/* Compiles. Returns NULL only when out of memory (or for a NULL or too98 * small info); every other failure is in the result. */99zdxc_result *zdxc_compile(const zdxc_compile_info *info);100101zdxc_status zdxc_result_status(const zdxc_result *result);102103/* One output: its bytes, followed by a NUL that *size does not count, or104 * NULL (and *size 0) if the compilation did not produce it. size may be105 * NULL. Valid until zdxc_result_free. */106const void *zdxc_result_output(const zdxc_result *result, zdxc_output output, size_t *size);107108/* The file name the options give an output (-Fo, -Fi, -Frs), or NULL. */109const char *zdxc_result_output_name(const zdxc_result *result, zdxc_output output);110111void zdxc_result_free(zdxc_result *result);112113/* zdxc's version, such as "0.1.0". */114const char *zdxc_version(void);115116#ifdef __cplusplus117}118#endif119120#endif /* ZDXC_H */121