* MojoShader; generate shader programs from bytecode of compiled

* Direct3D shaders.

*

* Please see the file LICENSE.txt in the source's root directory.

*

* This file written by Ryan C. Gordon.

*/

#ifndef _INCL_MOJOSHADER_H_

#define _INCL_MOJOSHADER_H_

#ifdef __cplusplus

extern "C" {

#endif

/* You can define this if you aren't generating mojoshader_version.h */

#ifndef MOJOSHADER_NO_VERSION_INCLUDE

#include "mojoshader_version.h"

#endif

#ifndef MOJOSHADER_VERSION

#endif

#ifndef MOJOSHADER_CHANGESET

#define MOJOSHADER_CHANGESET "???"

#endif

* For determining the version of MojoShader you are using:

* const int compiled_against = MOJOSHADER_VERSION;

* const int linked_against = MOJOSHADER_version();

*

* The version is a single integer that increments, not a major/minor value.

* const char *linked_against = MOJOSHADER_changeset();

*

* The version is an arbitrary, null-terminated ASCII string. It is probably

* a hash that represents a revision control changeset, and can't be

* compared to any other string to determine chronology.

*

* Do not attempt to free this string; it's statically allocated.

*/

const char *MOJOSHADER_changeset(void);

/*

* These allocators work just like the C runtime's malloc() and free()

* (in fact, they probably use malloc() and free() internally if you don't

* specify your own allocator, but don't rely on that behaviour).

* (data) is the pointer you supplied when specifying these allocator

* callbacks, in case you need instance-specific data...it is passed through

* to your allocator unmolested, and can be NULL if you like.

typedef void *(*MOJOSHADER_malloc)(int bytes, void *data);

typedef void (*MOJOSHADER_free)(void *ptr, void *data);

/*

* These are enum values, but they also can be used in bitmasks, so we can

* test if an opcode is acceptable: if (op->shader_types & ourtype) {} ...

*/

typedef enum

{

MOJOSHADER_TYPE_UNKNOWN = 0,

MOJOSHADER_TYPE_PIXEL = (1 << 0),

MOJOSHADER_TYPE_VERTEX = (1 << 1),

MOJOSHADER_TYPE_GEOMETRY = (1 << 2), /* (not supported yet.) */

MOJOSHADER_TYPE_ANY = 0xFFFFFFFF /* used for bitmasks */

} MOJOSHADER_shaderType;

/*

* Data types for vertex attribute streams.

*/

typedef enum

{

MOJOSHADER_ATTRIBUTE_BYTE,

MOJOSHADER_ATTRIBUTE_UBYTE,

MOJOSHADER_ATTRIBUTE_SHORT,

MOJOSHADER_ATTRIBUTE_USHORT,

MOJOSHADER_ATTRIBUTE_INT,

MOJOSHADER_ATTRIBUTE_UINT,

MOJOSHADER_ATTRIBUTE_FLOAT,

MOJOSHADER_ATTRIBUTE_DOUBLE,

MOJOSHADER_ATTRIBUTE_HALF_FLOAT, /* MAYBE available in your OpenGL! */

} MOJOSHADER_attributeType;

/*

* Data types for uniforms. See MOJOSHADER_uniform for more information.

*/

typedef enum

{

MOJOSHADER_UNIFORM_FLOAT,

MOJOSHADER_UNIFORM_INT,

MOJOSHADER_UNIFORM_BOOL,

/*

* These are the uniforms to be set for a shader. "Uniforms" are what Direct3D

* calls "Constants" ... IDirect3DDevice::SetVertexShaderConstantF() would

* need this data, for example. These integers are register indexes. So if

* index==6 and type==MOJOSHADER_UNIFORM_FLOAT, that means we'd expect a

* 4-float vector to be specified for what would be register "c6" in D3D

* assembly language, before drawing with the shader.

* (array_count) means this is an array of uniforms...this happens in some

* profiles when we see a relative address ("c0[a0.x]", not the usual "c0").

* In those cases, the shader was built to set some range of constant

* registers as an array. You should set this array with (array_count)

* elements from the constant register file, starting at (index) instead of

* just a single uniform. To be extra difficult, you'll need to fill in the

* correct values from the MOJOSHADER_constant data into the appropriate

* parts of the array, overriding the constant register file. Fun!

* (constant) says whether this is a constant array; these need to be loaded

* once at creation time, from the constant list and not ever updated from

* the constant register file. This is a workaround for limitations in some

* profiles.

* (name) is a profile-specific variable name; it may be NULL if it isn't

* applicable to the requested profile.

} MOJOSHADER_uniform;

/*

* These are the constants defined in a shader. These are data values

* hardcoded in a shader (with the DEF, DEFI, DEFB instructions), which

* override your Uniforms. This data is largely for informational purposes,

* since they are compiled in and can't be changed, like Uniforms can be.

* These integers are register indexes. So if index==6 and

* type==MOJOSHADER_UNIFORM_FLOAT, that means we'd expect a 4-float vector

* to be specified for what would be register "c6" in D3D assembly language,

* before drawing with the shader.

* (value) is the value of the constant, unioned by type.

*/

{

MOJOSHADER_uniformType type;

int index;

union

{

float f[4]; /* if type==MOJOSHADER_UNIFORM_FLOAT */

int i[4]; /* if type==MOJOSHADER_UNIFORM_INT */

int b; /* if type==MOJOSHADER_UNIFORM_BOOL */

} value;

} MOJOSHADER_constant;

/*

* Data types for samplers. See MOJOSHADER_sampler for more information.

*/

typedef enum

{

MOJOSHADER_SAMPLER_2D,

MOJOSHADER_SAMPLER_CUBE,

MOJOSHADER_SAMPLER_VOLUME,

} MOJOSHADER_samplerType;

/*

* These are the samplers to be set for a shader. ...

* IDirect3DDevice::SetTexture() would need this data, for example.

* These integers are the sampler "stage". So if index==6 and

* type==MOJOSHADER_SAMPLER_2D, that means we'd expect a regular 2D texture

* to be specified for what would be register "s6" in D3D assembly language,

* before drawing with the shader.

* (name) is a profile-specific variable name; it may be NULL if it isn't

* applicable to the requested profile.

{

MOJOSHADER_samplerType type;

int index;

} MOJOSHADER_sampler;

/*

* Data types for attributes. See MOJOSHADER_attribute for more information.

*/

typedef enum

{

MOJOSHADER_USAGE_POSITION,

MOJOSHADER_USAGE_BLENDWEIGHT,

MOJOSHADER_USAGE_BLENDINDICES,

MOJOSHADER_USAGE_NORMAL,

MOJOSHADER_USAGE_POINTSIZE,

MOJOSHADER_USAGE_TEXCOORD,

MOJOSHADER_USAGE_TANGENT,

MOJOSHADER_USAGE_BINORMAL,

MOJOSHADER_USAGE_TESSFACTOR,

MOJOSHADER_USAGE_POSITIONT,

MOJOSHADER_USAGE_COLOR,

MOJOSHADER_USAGE_FOG,

MOJOSHADER_USAGE_DEPTH,

MOJOSHADER_USAGE_SAMPLE,

} MOJOSHADER_usage;

/*

* These are the attributes to be set for a shader. "Attributes" are what

* Direct3D calls "Vertex Declarations Usages" ...

* IDirect3DDevice::CreateVertexDeclaration() would need this data, for

* example. Each attribute is associated with an array of data that uses one

* element per-vertex. So if usage==MOJOSHADER_USAGE_COLOR and index==1, that

* means we'd expect a secondary color array to be bound to this shader

* before drawing.

* (name) is a profile-specific variable name; it may be NULL if it isn't

* applicable to the requested profile.

{

MOJOSHADER_usage usage;

int index;

/*

* Use this if you want to specify newly-parsed code to swizzle incoming

* data. This can be useful if you know, at parse time, that a shader

* will be processing data on COLOR0 that should be RGBA, but you'll

* be passing it a vertex array full of ARGB instead.

*/

{

MOJOSHADER_usage usage;

unsigned int index;

unsigned char swizzles[4]; /* {0,1,2,3} == .xyzw, {2,2,2,2} == .zzzz */

} MOJOSHADER_swizzle;

/*

* MOJOSHADER_symbol data.

*

* These are used to expose high-level information in shader bytecode.

* They associate HLSL variables with registers. This data is used for both

* debugging and optimization.

*/

typedef enum

{

MOJOSHADER_SYMREGSET_BOOL,

MOJOSHADER_SYMREGSET_INT4,

MOJOSHADER_SYMREGSET_FLOAT4,

MOJOSHADER_SYMREGSET_SAMPLER,

} MOJOSHADER_symbolRegisterSet;

typedef enum

{

MOJOSHADER_SYMCLASS_SCALAR,

MOJOSHADER_SYMCLASS_VECTOR,

MOJOSHADER_SYMCLASS_MATRIX_ROWS,

MOJOSHADER_SYMCLASS_MATRIX_COLUMNS,

MOJOSHADER_SYMCLASS_OBJECT,

MOJOSHADER_SYMCLASS_STRUCT,

} MOJOSHADER_symbolClass;

typedef enum

{

MOJOSHADER_SYMTYPE_VOID,

MOJOSHADER_SYMTYPE_BOOL,

MOJOSHADER_SYMTYPE_INT,

MOJOSHADER_SYMTYPE_FLOAT,

MOJOSHADER_SYMTYPE_STRING,

MOJOSHADER_SYMTYPE_TEXTURE,

MOJOSHADER_SYMTYPE_TEXTURE1D,

MOJOSHADER_SYMTYPE_TEXTURE2D,

MOJOSHADER_SYMTYPE_TEXTURE3D,

MOJOSHADER_SYMTYPE_TEXTURECUBE,

MOJOSHADER_SYMTYPE_SAMPLER,

MOJOSHADER_SYMTYPE_SAMPLER1D,

MOJOSHADER_SYMTYPE_SAMPLER2D,

MOJOSHADER_SYMTYPE_SAMPLER3D,

MOJOSHADER_SYMTYPE_SAMPLERCUBE,

MOJOSHADER_SYMTYPE_PIXELSHADER,

MOJOSHADER_SYMTYPE_VERTEXSHADER,

MOJOSHADER_SYMTYPE_PIXELFRAGMENT,

MOJOSHADER_SYMTYPE_VERTEXFRAGMENT,

MOJOSHADER_SYMTYPE_UNSUPPORTED,

} MOJOSHADER_symbolType;

typedef struct MOJOSHADER_symbolStructMember MOJOSHADER_symbolStructMember;

typedef struct MOJOSHADER_symbolTypeInfo

{

MOJOSHADER_symbolClass parameter_class;

MOJOSHADER_symbolType parameter_type;

unsigned int rows;

unsigned int columns;

unsigned int elements;

unsigned int member_count;

MOJOSHADER_symbolStructMember *members;

} MOJOSHADER_symbolTypeInfo;

struct MOJOSHADER_symbolStructMember

{

const char *name;

MOJOSHADER_symbolTypeInfo info;

};

typedef struct MOJOSHADER_symbol

{

const char *name;

MOJOSHADER_symbolRegisterSet register_set;

unsigned int register_index;

unsigned int register_count;

MOJOSHADER_symbolTypeInfo info;

void *default_value;

} MOJOSHADER_symbol;

/*

* These are used with MOJOSHADER_error as special case positions.

*/

#define MOJOSHADER_POSITION_NONE (-3)

#define MOJOSHADER_POSITION_BEFORE (-2)

#define MOJOSHADER_POSITION_AFTER (-1)

{

/*

* Human-readable error, if there is one. Will be NULL if there was no

* error. The string will be UTF-8 encoded, and English only. Most of

* these shouldn't be shown to the end-user anyhow.

*/

const char *error;

* Filename where error happened. This can be NULL if the information

* isn't available.

*/

const char *filename;

* Position of error, if there is one. Will be MOJOSHADER_POSITION_NONE if

* there was no error, MOJOSHADER_POSITION_BEFORE if there was an error

* before processing started, and MOJOSHADER_POSITION_AFTER if there was

* an error during final processing. If >= 0, MOJOSHADER_parse() sets

* this to the byte offset (starting at zero) into the bytecode you

* supplied, and MOJOSHADER_assemble(), MOJOSHADER_parseAst(), and

* MOJOSHADER_compile() sets this to a a line number in the source code

* you supplied (starting at one).

*/

int error_position;

} MOJOSHADER_error;

/*

* Structure used to return data from parsing of a shader...

*/

/* !!! FIXME: most of these ints should be unsigned. */

typedef struct MOJOSHADER_parseData

{

/*

* The number of elements pointed to by (errors).

*/

int error_count;

/*

* (error_count) elements of data that specify errors that were generated

* by parsing this shader.

* This can be NULL if there were no errors or if (error_count) is zero.

*/

MOJOSHADER_error *errors;

/*

* The name of the profile used to parse the shader. Will be NULL on error.

*/

const char *profile;

/*

* Bytes of output from parsing. Most profiles produce a string of source

* code, but profiles that do binary output may not be text at all.

* Will be NULL on error.

*/

const char *output;

/*

* Byte count for output, not counting any null terminator. Most profiles

* produce an ASCII string of source code (which will be null-terminated

* even though that null char isn't included in output_len), but profiles

* that do binary output may not be text at all. Will be 0 on error.

*/

int output_len;

/*

* of the actual output, as the profile will probably grow or reduce

* the count (or for high-level languages, not have that information at

* all). Also, as with Microsoft's own assembler, this value is just a

* rough estimate, as unpredicable real-world factors make the actual

* value vary at least a little from this count. Still, it can give you

* a rough idea of the size of your shader. Will be zero on error.

*/

int instruction_count;

/*

* The type of shader we parsed. Will be MOJOSHADER_TYPE_UNKNOWN on error.

*/

MOJOSHADER_shaderType shader_type;

/*

* The shader's major version. If this was a "vs_3_0", this would be 3.

*/

int major_ver;

/*

* The shader's minor version. If this was a "ps_1_4", this would be 4.

* Two notes: for "vs_2_x", this is 1, and for "vs_3_sw", this is 255.

*/

int minor_ver;

/*

* The number of elements pointed to by (uniforms).

*/

int uniform_count;

/*

* (uniform_count) elements of data that specify Uniforms to be set for

* this shader. See discussion on MOJOSHADER_uniform for details.

*/

MOJOSHADER_uniform *uniforms;

/*

* The number of elements pointed to by (constants).

*/

int constant_count;

/*

* (constant_count) elements of data that specify constants used in

* this shader. See discussion on MOJOSHADER_constant for details.

* This can be NULL on error or if (constant_count) is zero.

* This is largely informational: constants are hardcoded into a shader.

* The constants that you can set like parameters are in the "uniforms"

* list.

*/

MOJOSHADER_constant *constants;

/*

* The number of elements pointed to by (samplers).

*/

int sampler_count;

/*

* (sampler_count) elements of data that specify Samplers to be set for

* this shader. See discussion on MOJOSHADER_sampler for details.

* This can be NULL on error or if (sampler_count) is zero.

*/

MOJOSHADER_sampler *samplers;

/*

* The number of elements pointed to by (attributes).

*/

int attribute_count;

/*

* (attribute_count) elements of data that specify Attributes to be set

* for this shader. See discussion on MOJOSHADER_attribute for details.

*/

MOJOSHADER_attribute *attributes;

/*

* The number of elements pointed to by (swizzles).

*/

int swizzle_count;

/*

* (swizzle_count) elements of data that specify swizzles the shader will

* apply to incoming attributes. This is a copy of what was passed to

* MOJOSHADER_parseData().

* This can be NULL on error or if (swizzle_count) is zero.

*/

MOJOSHADER_swizzle *swizzles;

/*

* The number of elements pointed to by (symbols).

*/

int symbol_count;

/*

* (symbol_count) elements of data that specify high-level symbol data

* for the shader. This will be parsed from the CTAB section

* in bytecode, and will be a copy of what you provide to

* MOJOSHADER_assemble(). This data is optional.

* This can be NULL on error or if (symbol_count) is zero.

*/

MOJOSHADER_symbol *symbols;

/*

* This is the malloc implementation you passed to MOJOSHADER_parse().

*/

MOJOSHADER_malloc malloc;

/*

* This is the free implementation you passed to MOJOSHADER_parse().

*/

MOJOSHADER_free free;

/*

* This is the pointer you passed as opaque data for your allocator.

*/

void *malloc_data;

} MOJOSHADER_parseData;

/*

* Profile string for Direct3D assembly language output.

*/

#define MOJOSHADER_PROFILE_D3D "d3d"

/*

* Profile string for passthrough of the original bytecode, unchanged.

*/

/*

* Profile string for GLSL: OpenGL high-level shader language output.

*/

#define MOJOSHADER_PROFILE_GLSL "glsl"

/*

* Profile string for GLSL 1.20: minor improvements to base GLSL spec.

*/

#define MOJOSHADER_PROFILE_GLSL120 "glsl120"

/*

* Profile string for OpenGL ARB 1.0 shaders: GL_ARB_(vertex|fragment)_program.

*/

#define MOJOSHADER_PROFILE_ARB1 "arb1"

/*

* Profile string for OpenGL ARB 1.0 shaders with Nvidia 2.0 extensions:

* GL_NV_vertex_program2_option and GL_NV_fragment_program2

*/

#define MOJOSHADER_PROFILE_NV2 "nv2"

/*

* Profile string for OpenGL ARB 1.0 shaders with Nvidia 3.0 extensions:

* GL_NV_vertex_program3 and GL_NV_fragment_program2

*/

/*

* Profile string for OpenGL ARB 1.0 shaders with Nvidia 4.0 extensions:

/*

* Determine the highest supported Shader Model for a profile.

*/

int MOJOSHADER_maxShaderModel(const char *profile);

/*

* Parse a compiled Direct3D shader's bytecode.

*

* This is your primary entry point into MojoShader. You need to pass it

* a compiled D3D shader and tell it which "profile" you want to use to

* convert it into useful data.

*

* The available profiles are the set of MOJOSHADER_PROFILE_* defines.

* Note that MojoShader may be built without support for all listed

* profiles (in which case using one here will return with an error).

*

* As parsing requires some memory to be allocated, you may provide a custom

* allocator to this function, which will be used to allocate/free memory.

* They function just like malloc() and free(). We do not use realloc().

* If you don't care, pass NULL in for the allocator functions. If your

* allocator needs instance-specific data, you may supply it with the

* (d) parameter. This pointer is passed as-is to your (m) and (f) functions.

*

* This function will never return NULL, even if the system is completely

* out of memory upon entry (in which case, this function returns a static

* MOJOSHADER_parseData object, which is still safe to pass to

* MOJOSHADER_freeParseData()).

*

* You can tell the generated program to swizzle certain inputs. If you know

* that COLOR0 should be RGBA but you're passing in ARGB, you can specify

* a swizzle of { MOJOSHADER_USAGE_COLOR, 0, {1,2,3,0} } to (swiz). If the

* input register in the code would produce reg.ywzx, that swizzle would

* change it to reg.wzxy ... (swiz) can be NULL.

*

* (tokenbuf) remains intact for the duration of the call. This allows you

* to parse several shaders on separate CPU cores at the same time.

*/

const MOJOSHADER_parseData *MOJOSHADER_parse(const char *profile,

const unsigned char *tokenbuf,

const unsigned int bufsize,

const MOJOSHADER_swizzle *swiz,

const unsigned int swizcount,

MOJOSHADER_free f,

void *d);

/*

* Call this to dispose of parsing results when you are done with them.

* This will call the MOJOSHADER_free function you provided to

* MOJOSHADER_parse multiple times, if you provided one.

* Passing a NULL here is a safe no-op.

*

* This function is thread safe, so long as any allocator you passed into

* MOJOSHADER_parse() is, too.

*/

void MOJOSHADER_freeParseData(const MOJOSHADER_parseData *data);

/* Effects interface... */ /* !!! FIXME: THIS API IS NOT STABLE YET! */

typedef struct MOJOSHADER_effectState

{

unsigned int type;

} MOJOSHADER_effectState;

typedef struct MOJOSHADER_effectPass

{

const char *name;

unsigned int state_count;

MOJOSHADER_effectState *states;

} MOJOSHADER_effectPass;

typedef struct MOJOSHADER_effectTechnique

{

const char *name;

unsigned int pass_count;

MOJOSHADER_effectPass *passes;

} MOJOSHADER_effectTechnique;

typedef struct MOJOSHADER_effectTexture

{

unsigned int param;

const char *name;

} MOJOSHADER_effectTexture;

typedef struct MOJOSHADER_effectShader

{

unsigned int technique;

unsigned int pass;

const MOJOSHADER_parseData *shader;

} MOJOSHADER_effectShader;

/*

* Structure used to return data from parsing of an effect file...

*/

/* !!! FIXME: most of these ints should be unsigned. */

typedef struct MOJOSHADER_effect

{

/*

* The number of elements pointed to by (errors).

*/

int error_count;

/*

* (error_count) elements of data that specify errors that were generated

* by parsing this shader.

* This can be NULL if there were no errors or if (error_count) is zero.

*/

MOJOSHADER_error *errors;

/*

* The name of the profile used to parse the shader. Will be NULL on error.

*/

const char *profile;

/*

* The number of elements pointed to by (techniques).

*/

int technique_count;

/*

* (technique_count) elements of data that specify techniques used in

* this effect. Each technique contains a series of passes, and each pass

* specifies state and shaders that affect rendering.

* This can be NULL on error or if (technique_count) is zero.

*/

MOJOSHADER_effectTechnique *techniques;

/*

* The number of elements pointed to by (textures).

*/

int texture_count;

/*

* (texture_count) elements of data that specify textures used in

* this effect.

* This can be NULL on error or if (texture_count) is zero.

*/

MOJOSHADER_effectTexture *textures;

/*

* The number of elements pointed to by (shaders).

*/

int shader_count;

/*

* (shader_count) elements of data that specify shaders used in

* this effect.

* This can be NULL on error or if (shader_count) is zero.

*/

MOJOSHADER_effectShader *shaders;

/*

* This is the malloc implementation you passed to MOJOSHADER_parseEffect().

*/

MOJOSHADER_malloc malloc;

/*

* This is the free implementation you passed to MOJOSHADER_parseEffect().

*/

MOJOSHADER_free free;

/*

* This is the pointer you passed as opaque data for your allocator.

*/

void *malloc_data;

} MOJOSHADER_effect;

/* !!! FIXME: document me. */

const MOJOSHADER_effect *MOJOSHADER_parseEffect(const char *profile,

const unsigned char *buf,

const unsigned int _len,

const MOJOSHADER_swizzle *swiz,

const unsigned int swizcount,

MOJOSHADER_malloc m,

MOJOSHADER_free f,

void *d);

/* !!! FIXME: document me. */

void MOJOSHADER_freeEffect(const MOJOSHADER_effect *effect);

/* Preprocessor interface... */

/*

* Structure used to pass predefined macros. Maps to D3DXMACRO.

*/

typedef struct MOJOSHADER_preprocessorDefine

{

const char *identifier;

const char *definition;

} MOJOSHADER_preprocessorDefine;

/*

* Used with the MOJOSHADER_includeOpen callback. Maps to D3DXINCLUDE_TYPE.

*/

typedef enum

{

MOJOSHADER_INCLUDETYPE_LOCAL, /* local header: #include "blah.h" */

MOJOSHADER_INCLUDETYPE_SYSTEM /* system header: #include <blah.h> */

} MOJOSHADER_includeType;

/*

* Structure used to return data from preprocessing of a shader...

*/

/* !!! FIXME: most of these ints should be unsigned. */

typedef struct MOJOSHADER_preprocessData

{

/*

* The number of elements pointed to by (errors).

*/

int error_count;

/*

* (error_count) elements of data that specify errors that were generated

* by parsing this shader.

* This can be NULL if there were no errors or if (error_count) is zero.

*/

MOJOSHADER_error *errors;

/*

* guarantee it to be NULL-terminated. Will be NULL on error.

*/

const char *output;

/*

* Byte count for output, not counting any null terminator.

* Will be 0 on error.

*/

int output_len;

/*

* This is the malloc implementation you passed to MOJOSHADER_parse().

*/

MOJOSHADER_malloc malloc;

/*

* This is the free implementation you passed to MOJOSHADER_parse().

*/

MOJOSHADER_free free;

/*

* This is the pointer you passed as opaque data for your allocator.

*/

void *malloc_data;

} MOJOSHADER_preprocessData;

/*

* This callback allows an app to handle #include statements for the

* preprocessor. When the preprocessor sees an #include, it will call this

* function to obtain the contents of the requested file. This is optional;

* this allows an app to retrieve data from something other than the

* traditional filesystem (for example, headers packed in a .zip file or

* headers generated on-the-fly).

*

* This function maps to ID3DXInclude::Open()

*

* (inctype) specifies the type of header we wish to include.

* (fname) specifies the name of the file specified on the #include line.

* (parent) is a string of the entire source file containing the include, in

* its original, not-yet-preprocessed state. Note that this is just the

* contents of the specific file, not all source code that the preprocessor

* has seen through other includes, etc.

* (outdata) will be set by the callback to a pointer to the included file's

* contents. The callback is responsible for allocating this however they

* see fit (we provide allocator functions, but you may ignore them). This

* pointer must remain valid until the includeClose callback runs. This

* string does not need to be NULL-terminated.

* (outbytes) will be set by the callback to the number of bytes pointed to

* by (outdata).

* (m),(f), and (d) are the allocator details that the application passed to

* MojoShader. If these were NULL, MojoShader may have replaced them with its

* own internal allocators.

*

* The callback returns zero on error, non-zero on success.

*

* If you supply an includeOpen callback, you must supply includeClose, too.

*/

typedef int (*MOJOSHADER_includeOpen)(MOJOSHADER_includeType inctype,

const char *fname, const char *parent,

const char **outdata, unsigned int *outbytes,

MOJOSHADER_malloc m, MOJOSHADER_free f, void *d);

/*

* This callback allows an app to clean up the results of a previous

* includeOpen callback.

*

* This function maps to ID3DXInclude::Close()

*

* (data) is the data that was returned from a previous call to includeOpen.

* It is now safe to deallocate this data.

* (m),(f), and (d) are the same allocator details that were passed to your

* includeOpen callback.

*

* If you supply an includeClose callback, you must supply includeOpen, too.

*/

typedef void (*MOJOSHADER_includeClose)(const char *data,

MOJOSHADER_malloc m, MOJOSHADER_free f, void *d);

/*

* This function is optional. Even if you are dealing with shader source

* code, you don't need to explicitly use the preprocessor, as the compiler

* and assembler will use it behind the scenes. In fact, you probably never

* need this function unless you are debugging a custom tool (or debugging

* MojoShader itself).

*

* Preprocessing roughly follows the syntax of an ANSI C preprocessor, as

* Microsoft's Direct3D assembler and HLSL compiler use this syntax. Please

* note that we try to match the output you'd get from Direct3D's

* preprocessor, which has some quirks if you're expecting output that matches

* a generic C preprocessor.

*

* This function maps to D3DXPreprocessShader().

*

* (filename) is a NULL-terminated UTF-8 filename. It can be NULL. We do not

* actually access this file, as we obtain our data from (source). This

* string is copied when we need to report errors while processing (source),

* as opposed to errors in a file referenced via the #include directive in

* (source). If this is NULL, then errors will report the filename as NULL,

* too.

*

* (source) is an string of UTF-8 text to preprocess. It does not need to be

* NULL-terminated.

*

* (sourcelen) is the length of the string pointed to by (source), in bytes.

*

* (defines) points to (define_count) preprocessor definitions, and can be

* NULL. These are treated by the preprocessor as if the source code started

* with one #define for each entry you pass in here.

*

* (include_open) and (include_close) let the app control the preprocessor's

* behaviour for #include statements. Both are optional and can be NULL, but

* both must be specified if either is specified.

*

* This will return a MOJOSHADER_preprocessorData. You should pass this

* return value to MOJOSHADER_freePreprocessData() when you are done with

* it.

*

* This function will never return NULL, even if the system is completely

* out of memory upon entry (in which case, this function returns a static

* MOJOSHADER_preprocessData object, which is still safe to pass to

* MOJOSHADER_freePreprocessData()).

*

* As preprocessing requires some memory to be allocated, you may provide a

* custom allocator to this function, which will be used to allocate/free

* memory. They function just like malloc() and free(). We do not use

* realloc(). If you don't care, pass NULL in for the allocator functions.

* If your allocator needs instance-specific data, you may supply it with the

* (d) parameter. This pointer is passed as-is to your (m) and (f) functions.

*

* This function is thread safe, so long as the various callback functions

* are, too, and that the parameters remains intact for the duration of the

* call. This allows you to preprocess several shaders on separate CPU cores

* at the same time.

*/

const MOJOSHADER_preprocessData *MOJOSHADER_preprocess(const char *filename,

const char *source, unsigned int sourcelen,

unsigned int define_count,

MOJOSHADER_includeOpen include_open,

MOJOSHADER_includeClose include_close,

MOJOSHADER_malloc m, MOJOSHADER_free f, void *d);

/*

* Call this to dispose of preprocessing results when you are done with them.

* This will call the MOJOSHADER_free function you provided to

* MOJOSHADER_preprocess() multiple times, if you provided one.

* Passing a NULL here is a safe no-op.

*

* This function is thread safe, so long as any allocator you passed into

* MOJOSHADER_preprocess() is, too.

*/

void MOJOSHADER_freePreprocessData(const MOJOSHADER_preprocessData *data);

/* Assembler interface... */

/*

* This function is optional. Use this to convert Direct3D shader assembly

* language into bytecode, which can be handled by MOJOSHADER_parse().

*

* (filename) is a NULL-terminated UTF-8 filename. It can be NULL. We do not

* actually access this file, as we obtain our data from (source). This

* string is copied when we need to report errors while processing (source),

* as opposed to errors in a file referenced via the #include directive in

* (source). If this is NULL, then errors will report the filename as NULL,

* too.

*

* (source) is an UTF-8 string of valid Direct3D shader assembly source code.

* It does not need to be NULL-terminated.

*

* (sourcelen) is the length of the string pointed to by (source), in bytes.

* can be NULL. These strings are inserted as comments in the bytecode.

*

* (symbols) points to (symbol_count) symbol structs, and can be NULL. These

* become a CTAB field in the bytecode. This is optional, but

* MOJOSHADER_parse() needs CTAB data for all arrays used in a program, or

* relative addressing will not be permitted, so you'll want to at least

* provide symbol information for those. The symbol data is 100% trusted

* at this time; it will not be checked to see if it matches what was

* assembled in any way whatsoever.

*

* (defines) points to (define_count) preprocessor definitions, and can be