mojoshader.h
author Ryan C. Gordon <icculus@icculus.org>
Sat, 09 Jul 2016 01:44:57 -0400
changeset 1179 6dd73a80629b
parent 1164 006194daea99
permissions -rw-r--r--
Sort register lists by register type first, then register number.

This groups all the registers by type first, which is useful for packing
heterogeneous uniform buffers later.
     1 /**
     2  * MojoShader; generate shader programs from bytecode of compiled
     3  *  Direct3D shaders.
     4  *
     5  * Please see the file LICENSE.txt in the source's root directory.
     6  *
     7  *  This file written by Ryan C. Gordon.
     8  */
     9 
    10 #ifndef _INCL_MOJOSHADER_H_
    11 #define _INCL_MOJOSHADER_H_
    12 
    13 #ifdef __cplusplus
    14 extern "C" {
    15 #endif
    16 
    17 /* You can define this if you aren't generating mojoshader_version.h */
    18 #ifndef MOJOSHADER_NO_VERSION_INCLUDE
    19 #include "mojoshader_version.h"
    20 #endif
    21 
    22 #ifndef MOJOSHADER_VERSION
    23 #define MOJOSHADER_VERSION -1
    24 #endif
    25 
    26 #ifndef MOJOSHADER_CHANGESET
    27 #define MOJOSHADER_CHANGESET "???"
    28 #endif
    29 
    30 #ifndef DECLSPEC
    31 #ifdef _WIN32
    32 #define DECLSPEC __declspec(dllexport)
    33 #else
    34 #define DECLSPEC
    35 #endif
    36 #endif
    37 
    38 #ifndef MOJOSHADERCALL
    39 #ifdef _WIN32
    40 #define MOJOSHADERCALL __stdcall
    41 #else
    42 #define MOJOSHADERCALL
    43 #endif
    44 #endif
    45 
    46 /*
    47  * For determining the version of MojoShader you are using:
    48  *    const int compiled_against = MOJOSHADER_VERSION;
    49  *    const int linked_against = MOJOSHADER_version();
    50  *
    51  * The version is a single integer that increments, not a major/minor value.
    52  */
    53 DECLSPEC int MOJOSHADER_version(void);
    54 
    55 /*
    56  * For determining the revision control changeset of MojoShader you are using:
    57  *    const char *compiled_against = MOJOSHADER_CHANGESET;
    58  *    const char *linked_against = MOJOSHADER_changeset();
    59  *
    60  * The version is an arbitrary, null-terminated ASCII string. It is probably
    61  *  a hash that represents a revision control changeset, and can't be
    62  *  compared to any other string to determine chronology.
    63  *
    64  * Do not attempt to free this string; it's statically allocated.
    65  */
    66 DECLSPEC const char *MOJOSHADER_changeset(void);
    67 
    68 /*
    69  * These allocators work just like the C runtime's malloc() and free()
    70  *  (in fact, they probably use malloc() and free() internally if you don't
    71  *  specify your own allocator, but don't rely on that behaviour).
    72  * (data) is the pointer you supplied when specifying these allocator
    73  *  callbacks, in case you need instance-specific data...it is passed through
    74  *  to your allocator unmolested, and can be NULL if you like.
    75  */
    76 typedef void *(MOJOSHADERCALL *MOJOSHADER_malloc)(int bytes, void *data);
    77 typedef void (MOJOSHADERCALL *MOJOSHADER_free)(void *ptr, void *data);
    78 
    79 
    80 /*
    81  * These are enum values, but they also can be used in bitmasks, so we can
    82  *  test if an opcode is acceptable: if (op->shader_types & ourtype) {} ...
    83  */
    84 typedef enum
    85 {
    86     MOJOSHADER_TYPE_UNKNOWN  = 0,
    87     MOJOSHADER_TYPE_PIXEL    = (1 << 0),
    88     MOJOSHADER_TYPE_VERTEX   = (1 << 1),
    89     MOJOSHADER_TYPE_GEOMETRY = (1 << 2),  /* (not supported yet.) */
    90     MOJOSHADER_TYPE_ANY = 0xFFFFFFFF   /* used for bitmasks */
    91 } MOJOSHADER_shaderType;
    92 
    93 /*
    94  * Data types for vertex attribute streams.
    95  */
    96 typedef enum
    97 {
    98     MOJOSHADER_ATTRIBUTE_UNKNOWN = -1,  /* housekeeping; not returned. */
    99     MOJOSHADER_ATTRIBUTE_BYTE,
   100     MOJOSHADER_ATTRIBUTE_UBYTE,
   101     MOJOSHADER_ATTRIBUTE_SHORT,
   102     MOJOSHADER_ATTRIBUTE_USHORT,
   103     MOJOSHADER_ATTRIBUTE_INT,
   104     MOJOSHADER_ATTRIBUTE_UINT,
   105     MOJOSHADER_ATTRIBUTE_FLOAT,
   106     MOJOSHADER_ATTRIBUTE_DOUBLE,
   107     MOJOSHADER_ATTRIBUTE_HALF_FLOAT,  /* MAYBE available in your OpenGL! */
   108 } MOJOSHADER_attributeType;
   109 
   110 /*
   111  * Data types for uniforms. See MOJOSHADER_uniform for more information.
   112  */
   113 typedef enum
   114 {
   115     MOJOSHADER_UNIFORM_UNKNOWN = -1, /* housekeeping value; never returned. */
   116     MOJOSHADER_UNIFORM_FLOAT,
   117     MOJOSHADER_UNIFORM_INT,
   118     MOJOSHADER_UNIFORM_BOOL,
   119 } MOJOSHADER_uniformType;
   120 
   121 /*
   122  * These are the uniforms to be set for a shader. "Uniforms" are what Direct3D
   123  *  calls "Constants" ... IDirect3DDevice::SetVertexShaderConstantF() would
   124  *  need this data, for example. These integers are register indexes. So if
   125  *  index==6 and type==MOJOSHADER_UNIFORM_FLOAT, that means we'd expect a
   126  *  4-float vector to be specified for what would be register "c6" in D3D
   127  *  assembly language, before drawing with the shader.
   128  * (array_count) means this is an array of uniforms...this happens in some
   129  *  profiles when we see a relative address ("c0[a0.x]", not the usual "c0").
   130  *  In those cases, the shader was built to set some range of constant
   131  *  registers as an array. You should set this array with (array_count)
   132  *  elements from the constant register file, starting at (index) instead of
   133  *  just a single uniform. To be extra difficult, you'll need to fill in the
   134  *  correct values from the MOJOSHADER_constant data into the appropriate
   135  *  parts of the array, overriding the constant register file. Fun!
   136  * (constant) says whether this is a constant array; these need to be loaded
   137  *  once at creation time, from the constant list and not ever updated from
   138  *  the constant register file. This is a workaround for limitations in some
   139  *  profiles.
   140  * (name) is a profile-specific variable name; it may be NULL if it isn't
   141  *  applicable to the requested profile.
   142  */
   143 typedef struct MOJOSHADER_uniform
   144 {
   145     MOJOSHADER_uniformType type;
   146     int index;
   147     int array_count;
   148     int constant;
   149     const char *name;
   150 } MOJOSHADER_uniform;
   151 
   152 /*
   153  * These are the constants defined in a shader. These are data values
   154  *  hardcoded in a shader (with the DEF, DEFI, DEFB instructions), which
   155  *  override your Uniforms. This data is largely for informational purposes,
   156  *  since they are compiled in and can't be changed, like Uniforms can be.
   157  * These integers are register indexes. So if index==6 and
   158  *  type==MOJOSHADER_UNIFORM_FLOAT, that means we'd expect a 4-float vector
   159  *  to be specified for what would be register "c6" in D3D assembly language,
   160  *  before drawing with the shader.
   161  * (value) is the value of the constant, unioned by type.
   162  */
   163 typedef struct MOJOSHADER_constant
   164 {
   165     MOJOSHADER_uniformType type;
   166     int index;
   167     union
   168     {
   169         float f[4];  /* if type==MOJOSHADER_UNIFORM_FLOAT */
   170         int i[4];    /* if type==MOJOSHADER_UNIFORM_INT */
   171         int b;       /* if type==MOJOSHADER_UNIFORM_BOOL */
   172     } value;
   173 } MOJOSHADER_constant;
   174 
   175 /*
   176  * Data types for samplers. See MOJOSHADER_sampler for more information.
   177  */
   178 typedef enum
   179 {
   180     MOJOSHADER_SAMPLER_UNKNOWN = -1, /* housekeeping value; never returned. */
   181     MOJOSHADER_SAMPLER_2D,
   182     MOJOSHADER_SAMPLER_CUBE,
   183     MOJOSHADER_SAMPLER_VOLUME,
   184 } MOJOSHADER_samplerType;
   185 
   186 /*
   187  * These are the samplers to be set for a shader. ...
   188  *  IDirect3DDevice::SetTexture() would need this data, for example.
   189  * These integers are the sampler "stage". So if index==6 and
   190  *  type==MOJOSHADER_SAMPLER_2D, that means we'd expect a regular 2D texture
   191  *  to be specified for what would be register "s6" in D3D assembly language,
   192  *  before drawing with the shader.
   193  * (name) is a profile-specific variable name; it may be NULL if it isn't
   194  *  applicable to the requested profile.
   195  * (texbem) will be non-zero if a TEXBEM opcode references this sampler. This
   196  *  is only used in legacy shaders (ps_1_1 through ps_1_3), but it needs some
   197  *  special support to work, as we have to load a magic uniform behind the
   198  *  scenes to support it. Most code can ignore this field in general, and no
   199  *  one has to touch it unless they really know what they're doing.
   200  */
   201 typedef struct MOJOSHADER_sampler
   202 {
   203     MOJOSHADER_samplerType type;
   204     int index;
   205     const char *name;
   206     int texbem;
   207 } MOJOSHADER_sampler;
   208 
   209 
   210 /*
   211  * This struct is used if you have to force a sampler to a specific type.
   212  *  Generally, you can ignore this, but if you have, say, a ps_1_1
   213  *  shader, you might need to specify what the samplers are meant to be
   214  *  to get correct results, as Shader Model 1 samples textures according
   215  *  to what is bound to a sampler at the moment instead of what the shader
   216  *  is hardcoded to expect.
   217  */
   218 typedef struct MOJOSHADER_samplerMap
   219 {
   220     int index;
   221     MOJOSHADER_samplerType type;
   222 } MOJOSHADER_samplerMap;
   223 
   224 /*
   225  * Data types for attributes. See MOJOSHADER_attribute for more information.
   226  */
   227 typedef enum
   228 {
   229     MOJOSHADER_USAGE_UNKNOWN = -1,  /* housekeeping value; never returned. */
   230     MOJOSHADER_USAGE_POSITION,
   231     MOJOSHADER_USAGE_BLENDWEIGHT,
   232     MOJOSHADER_USAGE_BLENDINDICES,
   233     MOJOSHADER_USAGE_NORMAL,
   234     MOJOSHADER_USAGE_POINTSIZE,
   235     MOJOSHADER_USAGE_TEXCOORD,
   236     MOJOSHADER_USAGE_TANGENT,
   237     MOJOSHADER_USAGE_BINORMAL,
   238     MOJOSHADER_USAGE_TESSFACTOR,
   239     MOJOSHADER_USAGE_POSITIONT,
   240     MOJOSHADER_USAGE_COLOR,
   241     MOJOSHADER_USAGE_FOG,
   242     MOJOSHADER_USAGE_DEPTH,
   243     MOJOSHADER_USAGE_SAMPLE,
   244     MOJOSHADER_USAGE_TOTAL,  /* housekeeping value; never returned. */
   245 } MOJOSHADER_usage;
   246 
   247 /*
   248  * These are the attributes to be set for a shader. "Attributes" are what
   249  *  Direct3D calls "Vertex Declarations Usages" ...
   250  *  IDirect3DDevice::CreateVertexDeclaration() would need this data, for
   251  *  example. Each attribute is associated with an array of data that uses one
   252  *  element per-vertex. So if usage==MOJOSHADER_USAGE_COLOR and index==1, that
   253  *  means we'd expect a secondary color array to be bound to this shader
   254  *  before drawing.
   255  * (name) is a profile-specific variable name; it may be NULL if it isn't
   256  *  applicable to the requested profile.
   257  */
   258 typedef struct MOJOSHADER_attribute
   259 {
   260     MOJOSHADER_usage usage;
   261     int index;
   262     const char *name;
   263 } MOJOSHADER_attribute;
   264 
   265 /*
   266  * Use this if you want to specify newly-parsed code to swizzle incoming
   267  *  data. This can be useful if you know, at parse time, that a shader
   268  *  will be processing data on COLOR0 that should be RGBA, but you'll
   269  *  be passing it a vertex array full of ARGB instead.
   270  */
   271 typedef struct MOJOSHADER_swizzle
   272 {
   273     MOJOSHADER_usage usage;
   274     unsigned int index;
   275     unsigned char swizzles[4];  /* {0,1,2,3} == .xyzw, {2,2,2,2} == .zzzz */
   276 } MOJOSHADER_swizzle;
   277 
   278 
   279 /*
   280  * MOJOSHADER_symbol data.
   281  *
   282  * These are used to expose high-level information in shader bytecode.
   283  *  They associate HLSL variables with registers. This data is used for both
   284  *  debugging and optimization.
   285  */
   286 
   287 typedef enum
   288 {
   289     MOJOSHADER_SYMREGSET_BOOL,
   290     MOJOSHADER_SYMREGSET_INT4,
   291     MOJOSHADER_SYMREGSET_FLOAT4,
   292     MOJOSHADER_SYMREGSET_SAMPLER,
   293 } MOJOSHADER_symbolRegisterSet;
   294 
   295 typedef enum
   296 {
   297     MOJOSHADER_SYMCLASS_SCALAR,
   298     MOJOSHADER_SYMCLASS_VECTOR,
   299     MOJOSHADER_SYMCLASS_MATRIX_ROWS,
   300     MOJOSHADER_SYMCLASS_MATRIX_COLUMNS,
   301     MOJOSHADER_SYMCLASS_OBJECT,
   302     MOJOSHADER_SYMCLASS_STRUCT,
   303 } MOJOSHADER_symbolClass;
   304 
   305 typedef enum
   306 {
   307     MOJOSHADER_SYMTYPE_VOID,
   308     MOJOSHADER_SYMTYPE_BOOL,
   309     MOJOSHADER_SYMTYPE_INT,
   310     MOJOSHADER_SYMTYPE_FLOAT,
   311     MOJOSHADER_SYMTYPE_STRING,
   312     MOJOSHADER_SYMTYPE_TEXTURE,
   313     MOJOSHADER_SYMTYPE_TEXTURE1D,
   314     MOJOSHADER_SYMTYPE_TEXTURE2D,
   315     MOJOSHADER_SYMTYPE_TEXTURE3D,
   316     MOJOSHADER_SYMTYPE_TEXTURECUBE,
   317     MOJOSHADER_SYMTYPE_SAMPLER,
   318     MOJOSHADER_SYMTYPE_SAMPLER1D,
   319     MOJOSHADER_SYMTYPE_SAMPLER2D,
   320     MOJOSHADER_SYMTYPE_SAMPLER3D,
   321     MOJOSHADER_SYMTYPE_SAMPLERCUBE,
   322     MOJOSHADER_SYMTYPE_PIXELSHADER,
   323     MOJOSHADER_SYMTYPE_VERTEXSHADER,
   324     MOJOSHADER_SYMTYPE_PIXELFRAGMENT,
   325     MOJOSHADER_SYMTYPE_VERTEXFRAGMENT,
   326     MOJOSHADER_SYMTYPE_UNSUPPORTED,
   327 } MOJOSHADER_symbolType;
   328 
   329 typedef struct MOJOSHADER_symbolStructMember MOJOSHADER_symbolStructMember;
   330 
   331 typedef struct MOJOSHADER_symbolTypeInfo
   332 {
   333     MOJOSHADER_symbolClass parameter_class;
   334     MOJOSHADER_symbolType parameter_type;
   335     unsigned int rows;
   336     unsigned int columns;
   337     unsigned int elements;
   338     unsigned int member_count;
   339     MOJOSHADER_symbolStructMember *members;
   340 } MOJOSHADER_symbolTypeInfo;
   341 
   342 struct MOJOSHADER_symbolStructMember
   343 {
   344     const char *name;
   345     MOJOSHADER_symbolTypeInfo info;
   346 };
   347 
   348 typedef struct MOJOSHADER_symbol
   349 {
   350     const char *name;
   351     MOJOSHADER_symbolRegisterSet register_set;
   352     unsigned int register_index;
   353     unsigned int register_count;
   354     MOJOSHADER_symbolTypeInfo info;
   355 } MOJOSHADER_symbol;
   356 
   357 
   358 /*
   359  * These are used with MOJOSHADER_error as special case positions.
   360  */
   361 #define MOJOSHADER_POSITION_NONE (-3)
   362 #define MOJOSHADER_POSITION_BEFORE (-2)
   363 #define MOJOSHADER_POSITION_AFTER (-1)
   364 
   365 typedef struct MOJOSHADER_error
   366 {
   367     /*
   368      * Human-readable error, if there is one. Will be NULL if there was no
   369      *  error. The string will be UTF-8 encoded, and English only. Most of
   370      *  these shouldn't be shown to the end-user anyhow.
   371      */
   372     const char *error;
   373 
   374     /*
   375      * Filename where error happened. This can be NULL if the information
   376      *  isn't available.
   377      */
   378     const char *filename;
   379 
   380     /*
   381      * Position of error, if there is one. Will be MOJOSHADER_POSITION_NONE if
   382      *  there was no error, MOJOSHADER_POSITION_BEFORE if there was an error
   383      *  before processing started, and MOJOSHADER_POSITION_AFTER if there was
   384      *  an error during final processing. If >= 0, MOJOSHADER_parse() sets
   385      *  this to the byte offset (starting at zero) into the bytecode you
   386      *  supplied, and MOJOSHADER_assemble(), MOJOSHADER_parseAst(), and
   387      *  MOJOSHADER_compile() sets this to a a line number in the source code
   388      *  you supplied (starting at one).
   389      */
   390     int error_position;
   391 } MOJOSHADER_error;
   392 
   393 
   394 /* !!! FIXME: document me. */
   395 typedef enum MOJOSHADER_preshaderOpcode
   396 {
   397     MOJOSHADER_PRESHADEROP_NOP,
   398     MOJOSHADER_PRESHADEROP_MOV,
   399     MOJOSHADER_PRESHADEROP_NEG,
   400     MOJOSHADER_PRESHADEROP_RCP,
   401     MOJOSHADER_PRESHADEROP_FRC,
   402     MOJOSHADER_PRESHADEROP_EXP,
   403     MOJOSHADER_PRESHADEROP_LOG,
   404     MOJOSHADER_PRESHADEROP_RSQ,
   405     MOJOSHADER_PRESHADEROP_SIN,
   406     MOJOSHADER_PRESHADEROP_COS,
   407     MOJOSHADER_PRESHADEROP_ASIN,
   408     MOJOSHADER_PRESHADEROP_ACOS,
   409     MOJOSHADER_PRESHADEROP_ATAN,
   410     MOJOSHADER_PRESHADEROP_MIN,
   411     MOJOSHADER_PRESHADEROP_MAX,
   412     MOJOSHADER_PRESHADEROP_LT,
   413     MOJOSHADER_PRESHADEROP_GE,
   414     MOJOSHADER_PRESHADEROP_ADD,
   415     MOJOSHADER_PRESHADEROP_MUL,
   416     MOJOSHADER_PRESHADEROP_ATAN2,
   417     MOJOSHADER_PRESHADEROP_DIV,
   418     MOJOSHADER_PRESHADEROP_CMP,
   419     MOJOSHADER_PRESHADEROP_MOVC,
   420     MOJOSHADER_PRESHADEROP_DOT,
   421     MOJOSHADER_PRESHADEROP_NOISE,
   422     MOJOSHADER_PRESHADEROP_SCALAR_OPS,
   423     MOJOSHADER_PRESHADEROP_MIN_SCALAR = MOJOSHADER_PRESHADEROP_SCALAR_OPS,
   424     MOJOSHADER_PRESHADEROP_MAX_SCALAR,
   425     MOJOSHADER_PRESHADEROP_LT_SCALAR,
   426     MOJOSHADER_PRESHADEROP_GE_SCALAR,
   427     MOJOSHADER_PRESHADEROP_ADD_SCALAR,
   428     MOJOSHADER_PRESHADEROP_MUL_SCALAR,
   429     MOJOSHADER_PRESHADEROP_ATAN2_SCALAR,
   430     MOJOSHADER_PRESHADEROP_DIV_SCALAR,
   431     MOJOSHADER_PRESHADEROP_DOT_SCALAR,
   432     MOJOSHADER_PRESHADEROP_NOISE_SCALAR,
   433 } MOJOSHADER_preshaderOpcode;
   434 
   435 typedef enum MOJOSHADER_preshaderOperandType
   436 {
   437     MOJOSHADER_PRESHADEROPERAND_INPUT,
   438     MOJOSHADER_PRESHADEROPERAND_OUTPUT,
   439     MOJOSHADER_PRESHADEROPERAND_LITERAL,
   440     MOJOSHADER_PRESHADEROPERAND_TEMP,
   441 } MOJOSHADER_preshaderOperandType;
   442 
   443 typedef struct MOJOSHADER_preshaderOperand
   444 {
   445     MOJOSHADER_preshaderOperandType type;
   446     unsigned int index;
   447     unsigned int array_register_count;
   448     unsigned int *array_registers;
   449 } MOJOSHADER_preshaderOperand;
   450 
   451 typedef struct MOJOSHADER_preshaderInstruction
   452 {
   453     MOJOSHADER_preshaderOpcode opcode;
   454     unsigned int element_count;
   455     unsigned int operand_count;
   456     MOJOSHADER_preshaderOperand operands[4];
   457 } MOJOSHADER_preshaderInstruction;
   458 
   459 typedef struct MOJOSHADER_preshader
   460 {
   461     unsigned int literal_count;
   462     double *literals;
   463     unsigned int temp_count;  /* scalar, not vector! */
   464     unsigned int symbol_count;
   465     MOJOSHADER_symbol *symbols;
   466     unsigned int instruction_count;
   467     MOJOSHADER_preshaderInstruction *instructions;
   468     unsigned int register_count;
   469     float *registers;
   470     MOJOSHADER_malloc malloc;
   471     MOJOSHADER_free free;
   472     void *malloc_data;
   473 } MOJOSHADER_preshader;
   474 
   475 /*
   476  * Structure used to return data from parsing of a shader...
   477  */
   478 /* !!! FIXME: most of these ints should be unsigned. */
   479 typedef struct MOJOSHADER_parseData
   480 {
   481     /*
   482      * The number of elements pointed to by (errors).
   483      */
   484     int error_count;
   485 
   486     /*
   487      * (error_count) elements of data that specify errors that were generated
   488      *  by parsing this shader.
   489      * This can be NULL if there were no errors or if (error_count) is zero.
   490      */
   491     MOJOSHADER_error *errors;
   492 
   493     /*
   494      * The name of the profile used to parse the shader. Will be NULL on error.
   495      */
   496     const char *profile;
   497 
   498     /*
   499      * Bytes of output from parsing. Most profiles produce a string of source
   500      *  code, but profiles that do binary output may not be text at all.
   501      *  Will be NULL on error.
   502      */
   503     const char *output;
   504 
   505     /*
   506      * Byte count for output, not counting any null terminator. Most profiles
   507      *  produce an ASCII string of source code (which will be null-terminated
   508      *  even though that null char isn't included in output_len), but profiles
   509      *  that do binary output may not be text at all. Will be 0 on error.
   510      */
   511     int output_len;
   512 
   513     /*
   514      * Count of Direct3D instruction slots used. This is meaningless in terms
   515      *  of the actual output, as the profile will probably grow or reduce
   516      *  the count (or for high-level languages, not have that information at
   517      *  all). Also, as with Microsoft's own assembler, this value is just a
   518      *  rough estimate, as unpredicable real-world factors make the actual
   519      *  value vary at least a little from this count. Still, it can give you
   520      *  a rough idea of the size of your shader. Will be zero on error.
   521      */
   522     int instruction_count;
   523 
   524     /*
   525      * The type of shader we parsed. Will be MOJOSHADER_TYPE_UNKNOWN on error.
   526      */
   527     MOJOSHADER_shaderType shader_type;
   528 
   529     /*
   530      * The shader's major version. If this was a "vs_3_0", this would be 3.
   531      */
   532     int major_ver;
   533 
   534     /*
   535      * The shader's minor version. If this was a "ps_1_4", this would be 4.
   536      *  Two notes: for "vs_2_x", this is 1, and for "vs_3_sw", this is 255.
   537      */
   538     int minor_ver;
   539 
   540     /*
   541      * This is the main function name of the shader. This will be the
   542      *  caller-supplied string even if a given profile ignores it (GLSL,
   543      *  for example, always uses "main" in the shader output out of necessity,
   544      *  and Direct3D assembly has no concept of a "main function", etc).
   545      *  Otherwise, it'll be a default name chosen by the profile ("main") or
   546      *  whatnot.
   547      */
   548     const char *mainfn;
   549 
   550     /*
   551      * The number of elements pointed to by (uniforms).
   552      */
   553     int uniform_count;
   554 
   555     /*
   556      * (uniform_count) elements of data that specify Uniforms to be set for
   557      *  this shader. See discussion on MOJOSHADER_uniform for details.
   558      * This can be NULL on error or if (uniform_count) is zero.
   559      */
   560     MOJOSHADER_uniform *uniforms;
   561 
   562     /*
   563      * The number of elements pointed to by (constants).
   564      */
   565     int constant_count;
   566 
   567     /*
   568      * (constant_count) elements of data that specify constants used in
   569      *  this shader. See discussion on MOJOSHADER_constant for details.
   570      * This can be NULL on error or if (constant_count) is zero.
   571      *  This is largely informational: constants are hardcoded into a shader.
   572      *  The constants that you can set like parameters are in the "uniforms"
   573      *  list.
   574      */
   575     MOJOSHADER_constant *constants;
   576 
   577     /*
   578      * The number of elements pointed to by (samplers).
   579      */
   580     int sampler_count;
   581 
   582     /*
   583      * (sampler_count) elements of data that specify Samplers to be set for
   584      *  this shader. See discussion on MOJOSHADER_sampler for details.
   585      * This can be NULL on error or if (sampler_count) is zero.
   586      */
   587     MOJOSHADER_sampler *samplers;
   588 
   589     /* !!! FIXME: this should probably be "input" and not "attribute" */
   590     /*
   591      * The number of elements pointed to by (attributes).
   592      */
   593     int attribute_count;
   594 
   595     /* !!! FIXME: this should probably be "input" and not "attribute" */
   596     /*
   597      * (attribute_count) elements of data that specify Attributes to be set
   598      *  for this shader. See discussion on MOJOSHADER_attribute for details.
   599      * This can be NULL on error or if (attribute_count) is zero.
   600      */
   601     MOJOSHADER_attribute *attributes;
   602 
   603     /*
   604      * The number of elements pointed to by (outputs).
   605      */
   606     int output_count;
   607 
   608     /*
   609      * (output_count) elements of data that specify outputs this shader
   610      *  writes to. See discussion on MOJOSHADER_attribute for details.
   611      * This can be NULL on error or if (output_count) is zero.
   612      */
   613     MOJOSHADER_attribute *outputs;
   614 
   615     /*
   616      * The number of elements pointed to by (swizzles).
   617      */
   618     int swizzle_count;
   619 
   620     /* !!! FIXME: this should probably be "input" and not "attribute" */
   621     /*
   622      * (swizzle_count) elements of data that specify swizzles the shader will
   623      *  apply to incoming attributes. This is a copy of what was passed to
   624      *  MOJOSHADER_parseData().
   625      * This can be NULL on error or if (swizzle_count) is zero.
   626      */
   627     MOJOSHADER_swizzle *swizzles;
   628 
   629     /*
   630      * The number of elements pointed to by (symbols).
   631      */
   632     int symbol_count;
   633 
   634     /*
   635      * (symbol_count) elements of data that specify high-level symbol data
   636      *  for the shader. This will be parsed from the CTAB section
   637      *  in bytecode, and will be a copy of what you provide to
   638      *  MOJOSHADER_assemble(). This data is optional.
   639      * This can be NULL on error or if (symbol_count) is zero.
   640      */
   641     MOJOSHADER_symbol *symbols;
   642 
   643     /*
   644      * !!! FIXME: document me.
   645      * This can be NULL on error or if no preshader was available.
   646      */
   647     MOJOSHADER_preshader *preshader;
   648 
   649     /*
   650      * This is the malloc implementation you passed to MOJOSHADER_parse().
   651      */
   652     MOJOSHADER_malloc malloc;
   653 
   654     /*
   655      * This is the free implementation you passed to MOJOSHADER_parse().
   656      */
   657     MOJOSHADER_free free;
   658 
   659     /*
   660      * This is the pointer you passed as opaque data for your allocator.
   661      */
   662     void *malloc_data;
   663 } MOJOSHADER_parseData;
   664 
   665 
   666 /*
   667  * Profile string for Direct3D assembly language output.
   668  */
   669 #define MOJOSHADER_PROFILE_D3D "d3d"
   670 
   671 /*
   672  * Profile string for passthrough of the original bytecode, unchanged.
   673  */
   674 #define MOJOSHADER_PROFILE_BYTECODE "bytecode"
   675 
   676 /*
   677  * Profile string for GLSL: OpenGL high-level shader language output.
   678  */
   679 #define MOJOSHADER_PROFILE_GLSL "glsl"
   680 
   681 /*
   682  * Profile string for GLSL 1.20: minor improvements to base GLSL spec.
   683  */
   684 #define MOJOSHADER_PROFILE_GLSL120 "glsl120"
   685 
   686 /*
   687  * Profile string for GLSL ES: minor changes to GLSL output for ES compliance.
   688  */
   689 #define MOJOSHADER_PROFILE_GLSLES "glsles"
   690 
   691 /*
   692  * Profile string for OpenGL ARB 1.0 shaders: GL_ARB_(vertex|fragment)_program.
   693  */
   694 #define MOJOSHADER_PROFILE_ARB1 "arb1"
   695 
   696 /*
   697  * Profile string for OpenGL ARB 1.0 shaders with Nvidia 2.0 extensions:
   698  *  GL_NV_vertex_program2_option and GL_NV_fragment_program2
   699  */
   700 #define MOJOSHADER_PROFILE_NV2 "nv2"
   701 
   702 /*
   703  * Profile string for OpenGL ARB 1.0 shaders with Nvidia 3.0 extensions:
   704  *  GL_NV_vertex_program3 and GL_NV_fragment_program2
   705  */
   706 #define MOJOSHADER_PROFILE_NV3 "nv3"
   707 
   708 /*
   709  * Profile string for OpenGL ARB 1.0 shaders with Nvidia 4.0 extensions:
   710  *  GL_NV_gpu_program4
   711  */
   712 #define MOJOSHADER_PROFILE_NV4 "nv4"
   713 
   714 /*
   715  * Profile string for Metal: Apple's lowlevel API's high-level shader language.
   716  */
   717 #define MOJOSHADER_PROFILE_METAL "metal"
   718 
   719 /*
   720  * Determine the highest supported Shader Model for a profile.
   721  */
   722 DECLSPEC int MOJOSHADER_maxShaderModel(const char *profile);
   723 
   724 
   725 /*
   726  * Parse a compiled Direct3D shader's bytecode.
   727  *
   728  * This is your primary entry point into MojoShader. You need to pass it
   729  *  a compiled D3D shader and tell it which "profile" you want to use to
   730  *  convert it into useful data.
   731  *
   732  * The available profiles are the set of MOJOSHADER_PROFILE_* defines.
   733  *  Note that MojoShader may be built without support for all listed
   734  *  profiles (in which case using one here will return with an error).
   735  *
   736  * As parsing requires some memory to be allocated, you may provide a custom
   737  *  allocator to this function, which will be used to allocate/free memory.
   738  *  They function just like malloc() and free(). We do not use realloc().
   739  *  If you don't care, pass NULL in for the allocator functions. If your
   740  *  allocator needs instance-specific data, you may supply it with the
   741  *  (d) parameter. This pointer is passed as-is to your (m) and (f) functions.
   742  *
   743  * This function returns a MOJOSHADER_parseData.
   744  *
   745  * This function will never return NULL, even if the system is completely
   746  *  out of memory upon entry (in which case, this function returns a static
   747  *  MOJOSHADER_parseData object, which is still safe to pass to
   748  *  MOJOSHADER_freeParseData()).
   749  *
   750  * You can tell the generated program to swizzle certain inputs. If you know
   751  *  that COLOR0 should be RGBA but you're passing in ARGB, you can specify
   752  *  a swizzle of { MOJOSHADER_USAGE_COLOR, 0, {1,2,3,0} } to (swiz). If the
   753  *  input register in the code would produce reg.ywzx, that swizzle would
   754  *  change it to reg.wzxy ... (swiz) can be NULL.
   755  *
   756  * You can force the shader to expect samplers of certain types. Generally
   757  *  you don't need this, as Shader Model 2 and later always specify what they
   758  *  expect samplers to be (2D, cubemap, etc). Shader Model 1, however, just
   759  *  uses whatever is bound to a given sampler at draw time, but this doesn't
   760  *  work in OpenGL, etc. In these cases, MojoShader will default to
   761  *  2D texture sampling (or cubemap sampling, in cases where it makes sense,
   762  *  like the TEXM3X3TEX opcode), which works 75% of the time, but if you
   763  *  really needed something else, you'll need to specify it here. This can
   764  *  also be used, at your own risk, to override DCL opcodes in shaders: if
   765  *  the shader explicit says 2D, but you want Cubemap, for example, you can
   766  *  use this to override. If you aren't sure about any of this stuff, you can
   767  *  (and should) almost certainly ignore it: (smap) can be NULL.
   768  *
   769  * (bufsize) is the size in bytes of (tokenbuf). If (bufsize) is zero,
   770  *  MojoShader will attempt to figure out the size of the buffer, but you
   771  *  risk a buffer overflow if you have corrupt data, etc. Supply the value
   772  *  if you can.
   773  *
   774  * You should pass a name for your shader's main function in here, via the
   775  *  (mainfn) param. Some profiles need this name to be unique. Passing a NULL
   776  *  here will pick a reasonable default, and most profiles will ignore it
   777  *  anyhow. As the name of the shader's main function, etc, so make it a
   778  *  simple name that would match C's identifier rules. Keep it simple!
   779  *
   780  * This function is thread safe, so long as (m) and (f) are too, and that
   781  *  (tokenbuf) remains intact for the duration of the call. This allows you
   782  *  to parse several shaders on separate CPU cores at the same time.
   783  */
   784 DECLSPEC const MOJOSHADER_parseData *MOJOSHADER_parse(const char *profile,
   785                                                       const char *mainfn,
   786                                                       const unsigned char *tokenbuf,
   787                                                       const unsigned int bufsize,
   788                                                       const MOJOSHADER_swizzle *swiz,
   789                                                       const unsigned int swizcount,
   790                                                       const MOJOSHADER_samplerMap *smap,
   791                                                       const unsigned int smapcount,
   792                                                       MOJOSHADER_malloc m,
   793                                                       MOJOSHADER_free f,
   794                                                       void *d);
   795 
   796 
   797 /*
   798  * Call this to dispose of parsing results when you are done with them.
   799  *  This will call the MOJOSHADER_free function you provided to
   800  *  MOJOSHADER_parse multiple times, if you provided one.
   801  *  Passing a NULL here is a safe no-op.
   802  *
   803  * This function is thread safe, so long as any allocator you passed into
   804  *  MOJOSHADER_parse() is, too.
   805  */
   806 DECLSPEC void MOJOSHADER_freeParseData(const MOJOSHADER_parseData *data);
   807 
   808 
   809 /*
   810  * You almost certainly don't need this function, unless you absolutely know
   811  *  why you need it without hesitation. This is useful if you're doing
   812  *  extremely low-level shader work or building specialized tools.
   813  *
   814  * Parse a preshader structure. This expects a buffer of bytes that represents
   815  *  the preshader data starting with its magic number token and ending at
   816  *  the end of the comment tokens that contain this preshader. Note that it
   817  *  does _not_ start at the beginning of the comment tokens.
   818  *
   819  * On success, this will return a MOJOSHADER_preshader. This can be
   820  *  deallocated later by calling MOJOSHADER_freePreshader(). On failure,
   821  *  this will return NULL. Unlike other MojoShader APIs, this assumes you
   822  *  either have a complete and valid buffer of preshader tokens or you have
   823  *  incomplete/corrupted data, so there is no explicit error reporting. Please
   824  *  note that if the system runs out of memory, this function will also return
   825  *  NULL without distinction.
   826  *
   827  * This function is thread safe, so long as any allocator you passed into
   828  *  MOJOSHADER_parsePreshader() is, too.
   829  */
   830 DECLSPEC const MOJOSHADER_preshader *MOJOSHADER_parsePreshader(const unsigned char *buf,
   831                                                                const unsigned int len,
   832                                                                MOJOSHADER_malloc m,
   833                                                                MOJOSHADER_free f,
   834                                                                void *d);
   835 
   836 
   837 /*
   838  * You almost certainly don't need this function, unless you absolutely know
   839  *  why you need it without hesitation. This is useful if you're doing
   840  *  extremely low-level shader work or building specialized tools.
   841  *
   842  * Call this to dispose of preshader parsing results when you are done with
   843  *  them. This will call the MOJOSHADER_free function you provided to
   844  *  MOJOSHADER_parsePreshader() multiple times, if you provided one.
   845  *  Passing a NULL here is a safe no-op.
   846  *
   847  * You only need to call this function for results from a call to
   848  *  MOJOSHADER_parsePreshader(). Other MojoShader structures with a preshader
   849  *  field, such as MOJOSHADER_parseData(), should not use this function, as
   850  *  the preshader will be deallocated with everything else in
   851  *  MOJOSHADER_freeParseData(), etc.
   852  *
   853  * This function is thread safe, so long as any allocator you passed into
   854  *  MOJOSHADER_parsePreshader() is, too.
   855  */
   856 DECLSPEC void MOJOSHADER_freePreshader(const MOJOSHADER_preshader *preshader);
   857 
   858 
   859 /* Effects interface... */
   860 #include "mojoshader_effects.h"
   861 
   862 
   863 /* Preprocessor interface... */
   864 
   865 /*
   866  * Structure used to pass predefined macros. Maps to D3DXMACRO.
   867  *  You can have macro arguments: set identifier to "a(b, c)" or whatever.
   868  */
   869 typedef struct MOJOSHADER_preprocessorDefine
   870 {
   871     const char *identifier;
   872     const char *definition;
   873 } MOJOSHADER_preprocessorDefine;
   874 
   875 /*
   876  * Used with the MOJOSHADER_includeOpen callback. Maps to D3DXINCLUDE_TYPE.
   877  */
   878 typedef enum
   879 {
   880     MOJOSHADER_INCLUDETYPE_LOCAL,   /* local header: #include "blah.h" */
   881     MOJOSHADER_INCLUDETYPE_SYSTEM   /* system header: #include <blah.h> */
   882 } MOJOSHADER_includeType;
   883 
   884 
   885 /*
   886  * Structure used to return data from preprocessing of a shader...
   887  */
   888 /* !!! FIXME: most of these ints should be unsigned. */
   889 typedef struct MOJOSHADER_preprocessData
   890 {
   891     /*
   892      * The number of elements pointed to by (errors).
   893      */
   894     int error_count;
   895 
   896     /*
   897      * (error_count) elements of data that specify errors that were generated
   898      *  by parsing this shader.
   899      * This can be NULL if there were no errors or if (error_count) is zero.
   900      */
   901     MOJOSHADER_error *errors;
   902 
   903     /*
   904      * Bytes of output from preprocessing. This is a UTF-8 string. We
   905      *  guarantee it to be NULL-terminated. Will be NULL on error.
   906      */
   907     const char *output;
   908 
   909     /*
   910      * Byte count for output, not counting any null terminator.
   911      *  Will be 0 on error.
   912      */
   913     int output_len;
   914 
   915     /*
   916      * This is the malloc implementation you passed to MOJOSHADER_parse().
   917      */
   918     MOJOSHADER_malloc malloc;
   919 
   920     /*
   921      * This is the free implementation you passed to MOJOSHADER_parse().
   922      */
   923     MOJOSHADER_free free;
   924 
   925     /*
   926      * This is the pointer you passed as opaque data for your allocator.
   927      */
   928     void *malloc_data;
   929 } MOJOSHADER_preprocessData;
   930 
   931 
   932 /*
   933  * This callback allows an app to handle #include statements for the
   934  *  preprocessor. When the preprocessor sees an #include, it will call this
   935  *  function to obtain the contents of the requested file. This is optional;
   936  *  the preprocessor will open files directly if no callback is supplied, but
   937  *  this allows an app to retrieve data from something other than the
   938  *  traditional filesystem (for example, headers packed in a .zip file or
   939  *  headers generated on-the-fly).
   940  *
   941  * This function maps to ID3DXInclude::Open()
   942  *
   943  * (inctype) specifies the type of header we wish to include.
   944  * (fname) specifies the name of the file specified on the #include line.
   945  * (parent) is a string of the entire source file containing the include, in
   946  *  its original, not-yet-preprocessed state. Note that this is just the
   947  *  contents of the specific file, not all source code that the preprocessor
   948  *  has seen through other includes, etc.
   949  * (outdata) will be set by the callback to a pointer to the included file's
   950  *  contents. The callback is responsible for allocating this however they
   951  *  see fit (we provide allocator functions, but you may ignore them). This
   952  *  pointer must remain valid until the includeClose callback runs. This
   953  *  string does not need to be NULL-terminated.
   954  * (outbytes) will be set by the callback to the number of bytes pointed to
   955  *  by (outdata).
   956  * (m),(f), and (d) are the allocator details that the application passed to
   957  *  MojoShader. If these were NULL, MojoShader may have replaced them with its
   958  *  own internal allocators.
   959  *
   960  * The callback returns zero on error, non-zero on success.
   961  *
   962  * If you supply an includeOpen callback, you must supply includeClose, too.
   963  */
   964 typedef int (MOJOSHADERCALL *MOJOSHADER_includeOpen)(MOJOSHADER_includeType inctype,
   965                             const char *fname, const char *parent,
   966                             const char **outdata, unsigned int *outbytes,
   967                             MOJOSHADER_malloc m, MOJOSHADER_free f, void *d);
   968 
   969 /*
   970  * This callback allows an app to clean up the results of a previous
   971  *  includeOpen callback.
   972  *
   973  * This function maps to ID3DXInclude::Close()
   974  *
   975  * (data) is the data that was returned from a previous call to includeOpen.
   976  *  It is now safe to deallocate this data.
   977  * (m),(f), and (d) are the same allocator details that were passed to your
   978  *  includeOpen callback.
   979  *
   980  * If you supply an includeClose callback, you must supply includeOpen, too.
   981  */
   982 typedef void (MOJOSHADERCALL *MOJOSHADER_includeClose)(const char *data,
   983                             MOJOSHADER_malloc m, MOJOSHADER_free f, void *d);
   984 
   985 
   986 /*
   987  * This function is optional. Even if you are dealing with shader source
   988  *  code, you don't need to explicitly use the preprocessor, as the compiler
   989  *  and assembler will use it behind the scenes. In fact, you probably never
   990  *  need this function unless you are debugging a custom tool (or debugging
   991  *  MojoShader itself).
   992  *
   993  * Preprocessing roughly follows the syntax of an ANSI C preprocessor, as
   994  *  Microsoft's Direct3D assembler and HLSL compiler use this syntax. Please
   995  *  note that we try to match the output you'd get from Direct3D's
   996  *  preprocessor, which has some quirks if you're expecting output that matches
   997  *  a generic C preprocessor.
   998  *
   999  * This function maps to D3DXPreprocessShader().
  1000  *
  1001  * (filename) is a NULL-terminated UTF-8 filename. It can be NULL. We do not
  1002  *  actually access this file, as we obtain our data from (source). This
  1003  *  string is copied when we need to report errors while processing (source),
  1004  *  as opposed to errors in a file referenced via the #include directive in
  1005  *  (source). If this is NULL, then errors will report the filename as NULL,
  1006  *  too.
  1007  *
  1008  * (source) is an string of UTF-8 text to preprocess. It does not need to be
  1009  *  NULL-terminated.
  1010  *
  1011  * (sourcelen) is the length of the string pointed to by (source), in bytes.
  1012  *
  1013  * (defines) points to (define_count) preprocessor definitions, and can be
  1014  *  NULL. These are treated by the preprocessor as if the source code started
  1015  *  with one #define for each entry you pass in here.
  1016  *
  1017  * (include_open) and (include_close) let the app control the preprocessor's
  1018  *  behaviour for #include statements. Both are optional and can be NULL, but
  1019  *  both must be specified if either is specified.
  1020  *
  1021  * This will return a MOJOSHADER_preprocessorData. You should pass this
  1022  *  return value to MOJOSHADER_freePreprocessData() when you are done with
  1023  *  it.
  1024  *
  1025  * This function will never return NULL, even if the system is completely
  1026  *  out of memory upon entry (in which case, this function returns a static
  1027  *  MOJOSHADER_preprocessData object, which is still safe to pass to
  1028  *  MOJOSHADER_freePreprocessData()).
  1029  *
  1030  * As preprocessing requires some memory to be allocated, you may provide a
  1031  *  custom allocator to this function, which will be used to allocate/free
  1032  *  memory. They function just like malloc() and free(). We do not use
  1033  *  realloc(). If you don't care, pass NULL in for the allocator functions.
  1034  *  If your allocator needs instance-specific data, you may supply it with the
  1035  *  (d) parameter. This pointer is passed as-is to your (m) and (f) functions.
  1036  *
  1037  * This function is thread safe, so long as the various callback functions
  1038  *  are, too, and that the parameters remains intact for the duration of the
  1039  *  call. This allows you to preprocess several shaders on separate CPU cores
  1040  *  at the same time.
  1041  */
  1042 DECLSPEC const MOJOSHADER_preprocessData *MOJOSHADER_preprocess(const char *filename,
  1043                              const char *source, unsigned int sourcelen,
  1044                              const MOJOSHADER_preprocessorDefine *defines,
  1045                              unsigned int define_count,
  1046                              MOJOSHADER_includeOpen include_open,
  1047                              MOJOSHADER_includeClose include_close,
  1048                              MOJOSHADER_malloc m, MOJOSHADER_free f, void *d);
  1049 
  1050 
  1051 /*
  1052  * Call this to dispose of preprocessing results when you are done with them.
  1053  *  This will call the MOJOSHADER_free function you provided to
  1054  *  MOJOSHADER_preprocess() multiple times, if you provided one.
  1055  *  Passing a NULL here is a safe no-op.
  1056  *
  1057  * This function is thread safe, so long as any allocator you passed into
  1058  *  MOJOSHADER_preprocess() is, too.
  1059  */
  1060 DECLSPEC void MOJOSHADER_freePreprocessData(const MOJOSHADER_preprocessData *data);
  1061 
  1062 
  1063 /* Assembler interface... */
  1064 
  1065 /*
  1066  * This function is optional. Use this to convert Direct3D shader assembly
  1067  *  language into bytecode, which can be handled by MOJOSHADER_parse().
  1068  *
  1069  * (filename) is a NULL-terminated UTF-8 filename. It can be NULL. We do not
  1070  *  actually access this file, as we obtain our data from (source). This
  1071  *  string is copied when we need to report errors while processing (source),
  1072  *  as opposed to errors in a file referenced via the #include directive in
  1073  *  (source). If this is NULL, then errors will report the filename as NULL,
  1074  *  too.
  1075  *
  1076  * (source) is an UTF-8 string of valid Direct3D shader assembly source code.
  1077  *  It does not need to be NULL-terminated.
  1078  *
  1079  * (sourcelen) is the length of the string pointed to by (source), in bytes.
  1080  *
  1081  * (comments) points to (comment_count) NULL-terminated UTF-8 strings, and
  1082  *  can be NULL. These strings are inserted as comments in the bytecode.
  1083  *
  1084  * (symbols) points to (symbol_count) symbol structs, and can be NULL. These
  1085  *  become a CTAB field in the bytecode. This is optional, but
  1086  *  MOJOSHADER_parse() needs CTAB data for all arrays used in a program, or
  1087  *  relative addressing will not be permitted, so you'll want to at least
  1088  *  provide symbol information for those. The symbol data is 100% trusted
  1089  *  at this time; it will not be checked to see if it matches what was
  1090  *  assembled in any way whatsoever.
  1091  *
  1092  * (defines) points to (define_count) preprocessor definitions, and can be
  1093  *  NULL. These are treated by the preprocessor as if the source code started
  1094  *  with one #define for each entry you pass in here.
  1095  *
  1096  * (include_open) and (include_close) let the app control the preprocessor's
  1097  *  behaviour for #include statements. Both are optional and can be NULL, but
  1098  *  both must be specified if either is specified.
  1099  *
  1100  * This will return a MOJOSHADER_parseData, like MOJOSHADER_parse() would,
  1101  *  except the profile will be MOJOSHADER_PROFILE_BYTECODE and the output
  1102  *  will be the assembled bytecode instead of some other language. This output
  1103  *  can be pushed back through MOJOSHADER_parseData() with a different profile.
  1104  *
  1105  * This function will never return NULL, even if the system is completely
  1106  *  out of memory upon entry (in which case, this function returns a static
  1107  *  MOJOSHADER_parseData object, which is still safe to pass to
  1108  *  MOJOSHADER_freeParseData()).
  1109  *
  1110  * As assembling requires some memory to be allocated, you may provide a
  1111  *  custom allocator to this function, which will be used to allocate/free
  1112  *  memory. They function just like malloc() and free(). We do not use
  1113  *  realloc(). If you don't care, pass NULL in for the allocator functions.
  1114  *  If your allocator needs instance-specific data, you may supply it with the
  1115  *  (d) parameter. This pointer is passed as-is to your (m) and (f) functions.
  1116  *
  1117  * This function is thread safe, so long as the various callback functions
  1118  *  are, too, and that the parameters remains intact for the duration of the
  1119  *  call. This allows you to assemble several shaders on separate CPU cores
  1120  *  at the same time.
  1121  */
  1122 DECLSPEC const MOJOSHADER_parseData *MOJOSHADER_assemble(const char *filename,
  1123                              const char *source, unsigned int sourcelen,
  1124                              const char **comments, unsigned int comment_count,
  1125                              const MOJOSHADER_symbol *symbols,
  1126                              unsigned int symbol_count,
  1127                              const MOJOSHADER_preprocessorDefine *defines,
  1128                              unsigned int define_count,
  1129                              MOJOSHADER_includeOpen include_open,
  1130                              MOJOSHADER_includeClose include_close,
  1131                              MOJOSHADER_malloc m, MOJOSHADER_free f, void *d);
  1132 
  1133 
  1134 /* High level shading language support... */
  1135 
  1136 /*
  1137  * Source profile strings for HLSL: Direct3D High Level Shading Language.
  1138  */
  1139 #define MOJOSHADER_SRC_PROFILE_HLSL_VS_1_1 "hlsl_vs_1_1"
  1140 #define MOJOSHADER_SRC_PROFILE_HLSL_VS_2_0 "hlsl_vs_2_0"
  1141 #define MOJOSHADER_SRC_PROFILE_HLSL_VS_3_0 "hlsl_vs_3_0"
  1142 #define MOJOSHADER_SRC_PROFILE_HLSL_PS_1_1 "hlsl_ps_1_1"
  1143 #define MOJOSHADER_SRC_PROFILE_HLSL_PS_1_2 "hlsl_ps_1_2"
  1144 #define MOJOSHADER_SRC_PROFILE_HLSL_PS_1_3 "hlsl_ps_1_3"
  1145 #define MOJOSHADER_SRC_PROFILE_HLSL_PS_1_4 "hlsl_ps_1_4"
  1146 #define MOJOSHADER_SRC_PROFILE_HLSL_PS_2_0 "hlsl_ps_2_0"
  1147 #define MOJOSHADER_SRC_PROFILE_HLSL_PS_3_0 "hlsl_ps_3_0"
  1148 
  1149 
  1150 /* Abstract Syntax Tree interface... */
  1151 
  1152 /*
  1153  * ATTENTION: This adds a lot of stuff to the API, but almost everyone can
  1154  *  ignore this section. Seriously, go ahead and skip over anything that has
  1155  *  "AST" in it, unless you know why you'd want to use it.
  1156  *
  1157  * ALSO: This API is still evolving! We make no promises at this time to keep
  1158  *  source or binary compatibility for the AST pieces.
  1159  *
  1160  * Important notes:
  1161  *  - ASTs are the result of parsing the source code: a program that fails to
  1162  *    compile will often parse successfully. Undeclared variables,
  1163  *    type incompatibilities, etc, aren't detected at this point.
  1164  *  - Vector swizzles (the ".xyzw" part of "MyVec4.xyzw") will look like
  1165  *    structure dereferences. We don't realize these are actually swizzles
  1166  *    until semantic analysis.
  1167  *  - MOJOSHADER_astDataType info is not reliable when returned from
  1168  *    MOJOSHADER_parseAst()! Most of the datatype info will be missing or have
  1169  *    inaccurate data types. We sort these out during semantic analysis, which
  1170  *    happens after the AST parsing is complete. A few are filled in, or can
  1171  *    be deduced fairly trivially by processing several pieces into one.
  1172  *    It's enough that you can reproduce the original source code, more or
  1173  *    less, from the AST.
  1174  */
  1175 
  1176 /* High-level datatypes for AST nodes. */
  1177 typedef enum MOJOSHADER_astDataTypeType
  1178 {
  1179     MOJOSHADER_AST_DATATYPE_NONE,
  1180     MOJOSHADER_AST_DATATYPE_BOOL,
  1181     MOJOSHADER_AST_DATATYPE_INT,
  1182     MOJOSHADER_AST_DATATYPE_UINT,
  1183     MOJOSHADER_AST_DATATYPE_FLOAT,
  1184     MOJOSHADER_AST_DATATYPE_FLOAT_SNORM,
  1185     MOJOSHADER_AST_DATATYPE_FLOAT_UNORM,
  1186     MOJOSHADER_AST_DATATYPE_HALF,
  1187     MOJOSHADER_AST_DATATYPE_DOUBLE,
  1188     MOJOSHADER_AST_DATATYPE_STRING,
  1189     MOJOSHADER_AST_DATATYPE_SAMPLER_1D,
  1190     MOJOSHADER_AST_DATATYPE_SAMPLER_2D,
  1191     MOJOSHADER_AST_DATATYPE_SAMPLER_3D,
  1192     MOJOSHADER_AST_DATATYPE_SAMPLER_CUBE,
  1193     MOJOSHADER_AST_DATATYPE_SAMPLER_STATE,
  1194     MOJOSHADER_AST_DATATYPE_SAMPLER_COMPARISON_STATE,
  1195     MOJOSHADER_AST_DATATYPE_STRUCT,
  1196     MOJOSHADER_AST_DATATYPE_ARRAY,
  1197     MOJOSHADER_AST_DATATYPE_VECTOR,
  1198     MOJOSHADER_AST_DATATYPE_MATRIX,
  1199     MOJOSHADER_AST_DATATYPE_BUFFER,
  1200     MOJOSHADER_AST_DATATYPE_FUNCTION,
  1201     MOJOSHADER_AST_DATATYPE_USER,
  1202 } MOJOSHADER_astDataTypeType;
  1203 #define MOJOSHADER_AST_DATATYPE_CONST (1 << 31)
  1204 
  1205 typedef union MOJOSHADER_astDataType MOJOSHADER_astDataType;
  1206 
  1207 // This is just part of DataTypeStruct, never appears outside of it.
  1208 typedef struct MOJOSHADER_astDataTypeStructMember
  1209 {
  1210     const MOJOSHADER_astDataType *datatype;
  1211     const char *identifier;
  1212 } MOJOSHADER_astDataTypeStructMember;
  1213 
  1214 typedef struct MOJOSHADER_astDataTypeStruct
  1215 {
  1216     MOJOSHADER_astDataTypeType type;
  1217     const MOJOSHADER_astDataTypeStructMember *members;
  1218     int member_count;
  1219 } MOJOSHADER_astDataTypeStruct;
  1220 
  1221 typedef struct MOJOSHADER_astDataTypeArray
  1222 {
  1223     MOJOSHADER_astDataTypeType type;
  1224     const MOJOSHADER_astDataType *base;
  1225     int elements;
  1226 } MOJOSHADER_astDataTypeArray;
  1227 
  1228 typedef MOJOSHADER_astDataTypeArray MOJOSHADER_astDataTypeVector;
  1229 
  1230 typedef struct MOJOSHADER_astDataTypeMatrix
  1231 {
  1232     MOJOSHADER_astDataTypeType type;
  1233     const MOJOSHADER_astDataType *base;
  1234     int rows;
  1235     int columns;
  1236 } MOJOSHADER_astDataTypeMatrix;
  1237 
  1238 typedef struct MOJOSHADER_astDataTypeBuffer
  1239 {
  1240     MOJOSHADER_astDataTypeType type;
  1241     const MOJOSHADER_astDataType *base;
  1242 } MOJOSHADER_astDataTypeBuffer;
  1243 
  1244 typedef struct MOJOSHADER_astDataTypeFunction
  1245 {
  1246     MOJOSHADER_astDataTypeType type;
  1247     const MOJOSHADER_astDataType *retval;
  1248     const MOJOSHADER_astDataType **params;
  1249     int num_params;
  1250     int intrinsic;  /* non-zero for built-in functions */
  1251 } MOJOSHADER_astDataTypeFunction;
  1252 
  1253 typedef struct MOJOSHADER_astDataTypeUser
  1254 {
  1255     MOJOSHADER_astDataTypeType type;
  1256     const MOJOSHADER_astDataType *details;
  1257     const char *name;
  1258 } MOJOSHADER_astDataTypeUser;
  1259 
  1260 union MOJOSHADER_astDataType
  1261 {
  1262     MOJOSHADER_astDataTypeType type;
  1263     MOJOSHADER_astDataTypeArray array;
  1264     MOJOSHADER_astDataTypeStruct structure;
  1265     MOJOSHADER_astDataTypeVector vector;
  1266     MOJOSHADER_astDataTypeMatrix matrix;
  1267     MOJOSHADER_astDataTypeBuffer buffer;
  1268     MOJOSHADER_astDataTypeUser user;
  1269     MOJOSHADER_astDataTypeFunction function;
  1270 };
  1271 
  1272 /* Structures that make up the parse tree... */
  1273 
  1274 typedef enum MOJOSHADER_astNodeType
  1275 {
  1276     MOJOSHADER_AST_OP_START_RANGE,         /* expression operators. */
  1277 
  1278     MOJOSHADER_AST_OP_START_RANGE_UNARY,   /* unary operators. */
  1279     MOJOSHADER_AST_OP_PREINCREMENT,
  1280     MOJOSHADER_AST_OP_PREDECREMENT,
  1281     MOJOSHADER_AST_OP_NEGATE,
  1282     MOJOSHADER_AST_OP_COMPLEMENT,
  1283     MOJOSHADER_AST_OP_NOT,
  1284     MOJOSHADER_AST_OP_POSTINCREMENT,
  1285     MOJOSHADER_AST_OP_POSTDECREMENT,
  1286     MOJOSHADER_AST_OP_CAST,
  1287     MOJOSHADER_AST_OP_END_RANGE_UNARY,
  1288 
  1289     MOJOSHADER_AST_OP_START_RANGE_BINARY,  /* binary operators. */
  1290     MOJOSHADER_AST_OP_COMMA,
  1291     MOJOSHADER_AST_OP_MULTIPLY,
  1292     MOJOSHADER_AST_OP_DIVIDE,
  1293     MOJOSHADER_AST_OP_MODULO,
  1294     MOJOSHADER_AST_OP_ADD,
  1295     MOJOSHADER_AST_OP_SUBTRACT,
  1296     MOJOSHADER_AST_OP_LSHIFT,
  1297     MOJOSHADER_AST_OP_RSHIFT,
  1298     MOJOSHADER_AST_OP_LESSTHAN,
  1299     MOJOSHADER_AST_OP_GREATERTHAN,
  1300     MOJOSHADER_AST_OP_LESSTHANOREQUAL,
  1301     MOJOSHADER_AST_OP_GREATERTHANOREQUAL,
  1302     MOJOSHADER_AST_OP_EQUAL,
  1303     MOJOSHADER_AST_OP_NOTEQUAL,
  1304     MOJOSHADER_AST_OP_BINARYAND,
  1305     MOJOSHADER_AST_OP_BINARYXOR,
  1306     MOJOSHADER_AST_OP_BINARYOR,
  1307     MOJOSHADER_AST_OP_LOGICALAND,
  1308     MOJOSHADER_AST_OP_LOGICALOR,
  1309     MOJOSHADER_AST_OP_ASSIGN,
  1310     MOJOSHADER_AST_OP_MULASSIGN,
  1311     MOJOSHADER_AST_OP_DIVASSIGN,
  1312     MOJOSHADER_AST_OP_MODASSIGN,
  1313     MOJOSHADER_AST_OP_ADDASSIGN,
  1314     MOJOSHADER_AST_OP_SUBASSIGN,
  1315     MOJOSHADER_AST_OP_LSHIFTASSIGN,
  1316     MOJOSHADER_AST_OP_RSHIFTASSIGN,
  1317     MOJOSHADER_AST_OP_ANDASSIGN,
  1318     MOJOSHADER_AST_OP_XORASSIGN,
  1319     MOJOSHADER_AST_OP_ORASSIGN,
  1320     MOJOSHADER_AST_OP_DEREF_ARRAY,
  1321     MOJOSHADER_AST_OP_END_RANGE_BINARY,
  1322 
  1323     MOJOSHADER_AST_OP_START_RANGE_TERNARY,  /* ternary operators. */
  1324     MOJOSHADER_AST_OP_CONDITIONAL,
  1325     MOJOSHADER_AST_OP_END_RANGE_TERNARY,
  1326 
  1327     MOJOSHADER_AST_OP_START_RANGE_DATA,     /* expression operands. */
  1328     MOJOSHADER_AST_OP_IDENTIFIER,
  1329     MOJOSHADER_AST_OP_INT_LITERAL,
  1330     MOJOSHADER_AST_OP_FLOAT_LITERAL,
  1331     MOJOSHADER_AST_OP_STRING_LITERAL,
  1332     MOJOSHADER_AST_OP_BOOLEAN_LITERAL,
  1333     MOJOSHADER_AST_OP_END_RANGE_DATA,
  1334 
  1335     MOJOSHADER_AST_OP_START_RANGE_MISC,     /* other expression things. */
  1336     MOJOSHADER_AST_OP_DEREF_STRUCT,
  1337     MOJOSHADER_AST_OP_CALLFUNC,
  1338     MOJOSHADER_AST_OP_CONSTRUCTOR,
  1339     MOJOSHADER_AST_OP_END_RANGE_MISC,
  1340     MOJOSHADER_AST_OP_END_RANGE,
  1341 
  1342     MOJOSHADER_AST_COMPUNIT_START_RANGE,    /* things in global scope. */
  1343     MOJOSHADER_AST_COMPUNIT_FUNCTION,
  1344     MOJOSHADER_AST_COMPUNIT_TYPEDEF,
  1345     MOJOSHADER_AST_COMPUNIT_STRUCT,
  1346     MOJOSHADER_AST_COMPUNIT_VARIABLE,
  1347     MOJOSHADER_AST_COMPUNIT_END_RANGE,
  1348 
  1349     MOJOSHADER_AST_STATEMENT_START_RANGE,   /* statements in function scope. */
  1350     MOJOSHADER_AST_STATEMENT_EMPTY,
  1351     MOJOSHADER_AST_STATEMENT_BREAK,
  1352     MOJOSHADER_AST_STATEMENT_CONTINUE,
  1353     MOJOSHADER_AST_STATEMENT_DISCARD,
  1354     MOJOSHADER_AST_STATEMENT_BLOCK,
  1355     MOJOSHADER_AST_STATEMENT_EXPRESSION,
  1356     MOJOSHADER_AST_STATEMENT_IF,
  1357     MOJOSHADER_AST_STATEMENT_SWITCH,
  1358     MOJOSHADER_AST_STATEMENT_FOR,
  1359     MOJOSHADER_AST_STATEMENT_DO,
  1360     MOJOSHADER_AST_STATEMENT_WHILE,
  1361     MOJOSHADER_AST_STATEMENT_RETURN,
  1362     MOJOSHADER_AST_STATEMENT_TYPEDEF,
  1363     MOJOSHADER_AST_STATEMENT_STRUCT,
  1364     MOJOSHADER_AST_STATEMENT_VARDECL,
  1365     MOJOSHADER_AST_STATEMENT_END_RANGE,
  1366 
  1367     MOJOSHADER_AST_MISC_START_RANGE,        /* misc. syntactic glue. */
  1368     MOJOSHADER_AST_FUNCTION_PARAMS,
  1369     MOJOSHADER_AST_FUNCTION_SIGNATURE,
  1370     MOJOSHADER_AST_SCALAR_OR_ARRAY,
  1371     MOJOSHADER_AST_TYPEDEF,
  1372     MOJOSHADER_AST_PACK_OFFSET,
  1373     MOJOSHADER_AST_VARIABLE_LOWLEVEL,
  1374     MOJOSHADER_AST_ANNOTATION,
  1375     MOJOSHADER_AST_VARIABLE_DECLARATION,
  1376     MOJOSHADER_AST_STRUCT_DECLARATION,
  1377     MOJOSHADER_AST_STRUCT_MEMBER,
  1378     MOJOSHADER_AST_SWITCH_CASE,
  1379     MOJOSHADER_AST_ARGUMENTS,
  1380     MOJOSHADER_AST_MISC_END_RANGE,
  1381 
  1382     MOJOSHADER_AST_END_RANGE
  1383 } MOJOSHADER_astNodeType;
  1384 
  1385 typedef struct MOJOSHADER_astNodeInfo
  1386 {
  1387     MOJOSHADER_astNodeType type;
  1388     const char *filename;
  1389     unsigned int line;
  1390 } MOJOSHADER_astNodeInfo;
  1391 
  1392 typedef enum MOJOSHADER_astVariableAttributes
  1393 {
  1394     MOJOSHADER_AST_VARATTR_EXTERN = (1 << 0),
  1395     MOJOSHADER_AST_VARATTR_NOINTERPOLATION = (1 << 1),
  1396     MOJOSHADER_AST_VARATTR_SHARED = (1 << 2),
  1397     MOJOSHADER_AST_VARATTR_STATIC = (1 << 3),
  1398     MOJOSHADER_AST_VARATTR_UNIFORM = (1 << 4),
  1399     MOJOSHADER_AST_VARATTR_VOLATILE = (1 << 5),
  1400     MOJOSHADER_AST_VARATTR_CONST = (1 << 6),
  1401     MOJOSHADER_AST_VARATTR_ROWMAJOR = (1 << 7),
  1402     MOJOSHADER_AST_VARATTR_COLUMNMAJOR = (1 << 8)
  1403 } MOJOSHADER_astVariableAttributes;
  1404 
  1405 typedef enum MOJOSHADER_astIfAttributes
  1406 {
  1407     MOJOSHADER_AST_IFATTR_NONE,
  1408     MOJOSHADER_AST_IFATTR_BRANCH,
  1409     MOJOSHADER_AST_IFATTR_FLATTEN,
  1410     MOJOSHADER_AST_IFATTR_IFALL,
  1411     MOJOSHADER_AST_IFATTR_IFANY,
  1412     MOJOSHADER_AST_IFATTR_PREDICATE,
  1413     MOJOSHADER_AST_IFATTR_PREDICATEBLOCK,
  1414 } MOJOSHADER_astIfAttributes;
  1415 
  1416 typedef enum MOJOSHADER_astSwitchAttributes
  1417 {
  1418     MOJOSHADER_AST_SWITCHATTR_NONE,
  1419     MOJOSHADER_AST_SWITCHATTR_FLATTEN,
  1420     MOJOSHADER_AST_SWITCHATTR_BRANCH,
  1421     MOJOSHADER_AST_SWITCHATTR_FORCECASE,
  1422     MOJOSHADER_AST_SWITCHATTR_CALL
  1423 } MOJOSHADER_astSwitchAttributes;
  1424 
  1425 /* You can cast any AST node pointer to this. */
  1426 typedef struct MOJOSHADER_astGeneric
  1427 {
  1428     MOJOSHADER_astNodeInfo ast;
  1429 } MOJOSHADER_astGeneric;
  1430 
  1431 typedef struct MOJOSHADER_astExpression
  1432 {
  1433     MOJOSHADER_astNodeInfo ast;
  1434     const MOJOSHADER_astDataType *datatype;
  1435 } MOJOSHADER_astExpression;
  1436 
  1437 typedef struct MOJOSHADER_astArguments
  1438 {
  1439     MOJOSHADER_astNodeInfo ast;  /* Always MOJOSHADER_AST_ARGUMENTS */
  1440     MOJOSHADER_astExpression *argument;
  1441     struct MOJOSHADER_astArguments *next;
  1442 } MOJOSHADER_astArguments;
  1443 
  1444 typedef struct MOJOSHADER_astExpressionUnary
  1445 {
  1446     MOJOSHADER_astNodeInfo ast;
  1447     const MOJOSHADER_astDataType *datatype;
  1448     MOJOSHADER_astExpression *operand;
  1449 } MOJOSHADER_astExpressionUnary;
  1450 
  1451 typedef struct MOJOSHADER_astExpressionBinary
  1452 {
  1453     MOJOSHADER_astNodeInfo ast;
  1454     const MOJOSHADER_astDataType *datatype;
  1455     MOJOSHADER_astExpression *left;
  1456     MOJOSHADER_astExpression *right;
  1457 } MOJOSHADER_astExpressionBinary;
  1458 
  1459 typedef struct MOJOSHADER_astExpressionTernary
  1460 {
  1461     MOJOSHADER_astNodeInfo ast;
  1462     const MOJOSHADER_astDataType *datatype;
  1463     MOJOSHADER_astExpression *left;
  1464     MOJOSHADER_astExpression *center;
  1465     MOJOSHADER_astExpression *right;
  1466 } MOJOSHADER_astExpressionTernary;
  1467 
  1468 /* Identifier indexes aren't available until semantic analysis phase completes.
  1469  *  It provides a unique id for this identifier's variable.
  1470  *  It will be negative for global scope, positive for function scope
  1471  *  (global values are globally unique, function values are only
  1472  *  unique within the scope of the given function). There's a different
  1473  *  set of indices if this identifier is a function (positive for
  1474  *  user-defined functions, negative for intrinsics).
  1475  *  May be zero for various reasons (unknown identifier, etc).
  1476  */
  1477 typedef struct MOJOSHADER_astExpressionIdentifier
  1478 {
  1479     MOJOSHADER_astNodeInfo ast;  /* Always MOJOSHADER_AST_OP_IDENTIFIER */
  1480     const MOJOSHADER_astDataType *datatype;
  1481     const char *identifier;
  1482     int index;
  1483 } MOJOSHADER_astExpressionIdentifier;
  1484 
  1485 typedef struct MOJOSHADER_astExpressionIntLiteral
  1486 {
  1487     MOJOSHADER_astNodeInfo ast;  /* Always MOJOSHADER_AST_OP_INT_LITERAL */
  1488     const MOJOSHADER_astDataType *datatype;  /* always AST_DATATYPE_INT */
  1489     int value;
  1490 } MOJOSHADER_astExpressionIntLiteral;
  1491 
  1492 typedef struct MOJOSHADER_astExpressionFloatLiteral
  1493 {
  1494     MOJOSHADER_astNodeInfo ast;  /* Always MOJOSHADER_AST_OP_FLOAT_LITERAL */
  1495     const MOJOSHADER_astDataType *datatype;  /* always AST_DATATYPE_FLOAT */
  1496     double value;
  1497 } MOJOSHADER_astExpressionFloatLiteral;
  1498 
  1499 typedef struct MOJOSHADER_astExpressionStringLiteral
  1500 {
  1501     MOJOSHADER_astNodeInfo ast;  /* Always MOJOSHADER_AST_OP_STRING_LITERAL */
  1502     const MOJOSHADER_astDataType *datatype;  /* always AST_DATATYPE_STRING */
  1503     const char *string;
  1504 } MOJOSHADER_astExpressionStringLiteral;
  1505 
  1506 typedef struct MOJOSHADER_astExpressionBooleanLiteral
  1507 {
  1508     MOJOSHADER_astNodeInfo ast;  /* Always MOJOSHADER_AST_OP_BOOLEAN_LITERAL */
  1509     const MOJOSHADER_astDataType *datatype;  /* always AST_DATATYPE_BOOL */
  1510     int value;  /* Always 1 or 0. */
  1511 } MOJOSHADER_astExpressionBooleanLiteral;
  1512 
  1513 typedef struct MOJOSHADER_astExpressionConstructor
  1514 {
  1515     MOJOSHADER_astNodeInfo ast;  /* Always MOJOSHADER_AST_OP_CONSTRUCTOR */
  1516     const MOJOSHADER_astDataType *datatype;
  1517     MOJOSHADER_astArguments *args;
  1518 } MOJOSHADER_astExpressionConstructor;
  1519 
  1520 typedef struct MOJOSHADER_astExpressionDerefStruct
  1521 {
  1522     MOJOSHADER_astNodeInfo ast;  /* Always MOJOSHADER_AST_OP_DEREF_STRUCT */
  1523     const MOJOSHADER_astDataType *datatype;
  1524     /* !!! FIXME:
  1525      *  "identifier" is misnamed; this might not be an identifier at all:
  1526      *    x = FunctionThatReturnsAStruct().SomeMember;
  1527      */
  1528     MOJOSHADER_astExpression *identifier;
  1529     const char *member;
  1530     int isswizzle;  /* Always 1 or 0. Never set by parseAst()! */
  1531     int member_index;  /* Never set by parseAst()! */
  1532 } MOJOSHADER_astExpressionDerefStruct;
  1533 
  1534 typedef struct MOJOSHADER_astExpressionCallFunction
  1535 {
  1536     MOJOSHADER_astNodeInfo ast;  /* Always MOJOSHADER_AST_OP_CALLFUNC */
  1537     const MOJOSHADER_astDataType *datatype;
  1538     MOJOSHADER_astExpressionIdentifier *identifier;
  1539     MOJOSHADER_astArguments *args;
  1540 } MOJOSHADER_astExpressionCallFunction;
  1541 
  1542 typedef struct MOJOSHADER_astExpressionCast
  1543 {
  1544     MOJOSHADER_astNodeInfo ast;  /* Always MOJOSHADER_AST_OP_CAST */
  1545     const MOJOSHADER_astDataType *datatype;
  1546     MOJOSHADER_astExpression *operand;
  1547 } MOJOSHADER_astExpressionCast;
  1548 
  1549 typedef struct MOJOSHADER_astCompilationUnit
  1550 {
  1551     MOJOSHADER_astNodeInfo ast;
  1552     struct MOJOSHADER_astCompilationUnit *next;
  1553 } MOJOSHADER_astCompilationUnit;
  1554 
  1555 typedef enum MOJOSHADER_astFunctionStorageClass
  1556 {
  1557     MOJOSHADER_AST_FNSTORECLS_NONE,
  1558     MOJOSHADER_AST_FNSTORECLS_INLINE
  1559 } MOJOSHADER_astFunctionStorageClass;
  1560 
  1561 typedef enum MOJOSHADER_astInputModifier
  1562 {
  1563     MOJOSHADER_AST_INPUTMOD_NONE,
  1564     MOJOSHADER_AST_INPUTMOD_IN,
  1565     MOJOSHADER_AST_INPUTMOD_OUT,
  1566     MOJOSHADER_AST_INPUTMOD_INOUT,
  1567     MOJOSHADER_AST_INPUTMOD_UNIFORM
  1568 } MOJOSHADER_astInputModifier;
  1569 
  1570 typedef enum MOJOSHADER_astInterpolationModifier
  1571 {
  1572     MOJOSHADER_AST_INTERPMOD_NONE,
  1573     MOJOSHADER_AST_INTERPMOD_LINEAR,
  1574     MOJOSHADER_AST_INTERPMOD_CENTROID,
  1575     MOJOSHADER_AST_INTERPMOD_NOINTERPOLATION,
  1576     MOJOSHADER_AST_INTERPMOD_NOPERSPECTIVE,
  1577     MOJOSHADER_AST_INTERPMOD_SAMPLE
  1578 } MOJOSHADER_astInterpolationModifier;
  1579 
  1580 typedef struct MOJOSHADER_astFunctionParameters
  1581 {
  1582     MOJOSHADER_astNodeInfo ast;
  1583     const MOJOSHADER_astDataType *datatype;
  1584     MOJOSHADER_astInputModifier input_modifier;
  1585     const char *identifier;
  1586     const char *semantic;
  1587     MOJOSHADER_astInterpolationModifier interpolation_modifier;
  1588     MOJOSHADER_astExpression *initializer;
  1589     struct MOJOSHADER_astFunctionParameters *next;
  1590 } MOJOSHADER_astFunctionParameters;
  1591 
  1592 typedef struct MOJOSHADER_astFunctionSignature
  1593 {
  1594     MOJOSHADER_astNodeInfo ast;
  1595     const MOJOSHADER_astDataType *datatype;
  1596     const char *identifier;
  1597     MOJOSHADER_astFunctionParameters *params;
  1598     MOJOSHADER_astFunctionStorageClass storage_class;
  1599     const char *semantic;
  1600 } MOJOSHADER_astFunctionSignature;
  1601 
  1602 typedef struct MOJOSHADER_astScalarOrArray
  1603 {
  1604     MOJOSHADER_astNodeInfo ast;
  1605     const char *identifier;
  1606     int isarray;  /* boolean: 1 or 0 */
  1607     MOJOSHADER_astExpression *dimension;
  1608 } MOJOSHADER_astScalarOrArray;
  1609 
  1610 typedef struct MOJOSHADER_astAnnotations
  1611 {
  1612     MOJOSHADER_astNodeInfo ast;
  1613     const MOJOSHADER_astDataType *datatype;
  1614     MOJOSHADER_astExpression *initializer;
  1615     struct MOJOSHADER_astAnnotations *next;
  1616 } MOJOSHADER_astAnnotations;
  1617 
  1618 typedef struct MOJOSHADER_astPackOffset
  1619 {
  1620     MOJOSHADER_astNodeInfo ast;
  1621     const char *ident1;   /* !!! FIXME: rename this. */
  1622     const char *ident2;
  1623 } MOJOSHADER_astPackOffset;
  1624 
  1625 typedef struct MOJOSHADER_astVariableLowLevel
  1626 {
  1627     MOJOSHADER_astNodeInfo ast;
  1628     MOJOSHADER_astPackOffset *packoffset;
  1629     const char *register_name;
  1630 } MOJOSHADER_astVariableLowLevel;
  1631 
  1632 typedef struct MOJOSHADER_astStructMembers
  1633 {
  1634     MOJOSHADER_astNodeInfo ast;
  1635     const MOJOSHADER_astDataType *datatype;
  1636     const char *semantic;
  1637     MOJOSHADER_astScalarOrArray *details;
  1638     MOJOSHADER_astInterpolationModifier interpolation_mod;
  1639     struct MOJOSHADER_astStructMembers *next;
  1640 } MOJOSHADER_astStructMembers;
  1641 
  1642 typedef struct MOJOSHADER_astStructDeclaration
  1643 {
  1644     MOJOSHADER_astNodeInfo ast;
  1645     const MOJOSHADER_astDataType *datatype;
  1646     const char *name;
  1647     MOJOSHADER_astStructMembers *members;
  1648 } MOJOSHADER_astStructDeclaration;
  1649 
  1650 typedef struct MOJOSHADER_astVariableDeclaration
  1651 {
  1652     MOJOSHADER_astNodeInfo ast;
  1653     int attributes;
  1654     const MOJOSHADER_astDataType *datatype;
  1655     MOJOSHADER_astStructDeclaration *anonymous_datatype;
  1656     MOJOSHADER_astScalarOrArray *details;
  1657     const char *semantic;
  1658     MOJOSHADER_astAnnotations *annotations;
  1659     MOJOSHADER_astExpression *initializer;
  1660     MOJOSHADER_astVariableLowLevel *lowlevel;
  1661     struct MOJOSHADER_astVariableDeclaration *next;
  1662 } MOJOSHADER_astVariableDeclaration;
  1663 
  1664 typedef struct MOJOSHADER_astStatement
  1665 {
  1666     MOJOSHADER_astNodeInfo ast;
  1667     struct MOJOSHADER_astStatement *next;
  1668 } MOJOSHADER_astStatement;
  1669 
  1670 typedef MOJOSHADER_astStatement MOJOSHADER_astEmptyStatement;
  1671 typedef MOJOSHADER_astStatement MOJOSHADER_astBreakStatement;
  1672 typedef MOJOSHADER_astStatement MOJOSHADER_astContinueStatement;
  1673 typedef MOJOSHADER_astStatement MOJOSHADER_astDiscardStatement;
  1674 
  1675 /* something enclosed in "{}" braces. */
  1676 typedef struct MOJOSHADER_astBlockStatement
  1677 {
  1678     MOJOSHADER_astNodeInfo ast;
  1679     MOJOSHADER_astStatement *next;
  1680     MOJOSHADER_astStatement *statements;  /* list of child statements. */
  1681 } MOJOSHADER_astBlockStatement;
  1682 
  1683 typedef struct MOJOSHADER_astReturnStatement
  1684 {
  1685     MOJOSHADER_astNodeInfo ast;
  1686     MOJOSHADER_astStatement *next;
  1687     MOJOSHADER_astExpression *expr;
  1688 } MOJOSHADER_astReturnStatement;
  1689 
  1690 typedef struct MOJOSHADER_astExpressionStatement
  1691 {
  1692     MOJOSHADER_astNodeInfo ast;
  1693     MOJOSHADER_astStatement *next;
  1694     MOJOSHADER_astExpression *expr;
  1695 } MOJOSHADER_astExpressionStatement;
  1696 
  1697 typedef struct MOJOSHADER_astIfStatement
  1698 {
  1699     MOJOSHADER_astNodeInfo ast;
  1700     MOJOSHADER_astStatement *next;
  1701     int attributes;
  1702     MOJOSHADER_astExpression *expr;
  1703     MOJOSHADER_astStatement *statement;
  1704     MOJOSHADER_astStatement *else_statement;
  1705 } MOJOSHADER_astIfStatement;
  1706 
  1707 typedef struct MOJOSHADER_astSwitchCases
  1708 {
  1709     MOJOSHADER_astNodeInfo ast;
  1710     MOJOSHADER_astExpression *expr;
  1711     MOJOSHADER_astStatement *statement;
  1712     struct MOJOSHADER_astSwitchCases *next;
  1713 } MOJOSHADER_astSwitchCases;
  1714 
  1715 typedef struct MOJOSHADER_astSwitchStatement
  1716 {
  1717     MOJOSHADER_astNodeInfo ast;
  1718     MOJOSHADER_astStatement *next;
  1719     int attributes;
  1720     MOJOSHADER_astExpression *expr;
  1721     MOJOSHADER_astSwitchCases *cases;
  1722 } MOJOSHADER_astSwitchStatement;
  1723 
  1724 typedef struct MOJOSHADER_astWhileStatement
  1725 {
  1726     MOJOSHADER_astNodeInfo ast;
  1727     MOJOSHADER_astStatement *next;
  1728     int unroll;  /* # times to unroll, 0 to loop, < 0 == compiler's choice. */
  1729     MOJOSHADER_astExpression *expr;
  1730     MOJOSHADER_astStatement *statement;
  1731 } MOJOSHADER_astWhileStatement;
  1732 
  1733 typedef MOJOSHADER_astWhileStatement MOJOSHADER_astDoStatement;
  1734 
  1735 typedef struct MOJOSHADER_astForStatement
  1736 {
  1737     MOJOSHADER_astNodeInfo ast;
  1738     MOJOSHADER_astStatement *next;
  1739     int unroll;  /* # times to unroll, 0 to loop, < 0 == compiler's choice. */
  1740     MOJOSHADER_astVariableDeclaration *var_decl;  /* either this ... */
  1741     MOJOSHADER_astExpression *initializer;        /*  ... or this will used. */
  1742     MOJOSHADER_astExpression *looptest;
  1743     MOJOSHADER_astExpression *counter;
  1744     MOJOSHADER_astStatement *statement;
  1745 } MOJOSHADER_astForStatement;
  1746 
  1747 typedef struct MOJOSHADER_astTypedef
  1748 {
  1749     MOJOSHADER_astNodeInfo ast;
  1750     const MOJOSHADER_astDataType *datatype;
  1751     int isconst;  /* boolean: 1 or 0 */
  1752     MOJOSHADER_astScalarOrArray *details;
  1753 } MOJOSHADER_astTypedef;
  1754 
  1755 typedef struct MOJOSHADER_astTypedefStatement
  1756 {
  1757     MOJOSHADER_astNodeInfo ast;
  1758     MOJOSHADER_astStatement *next;
  1759     MOJOSHADER_astTypedef *type_info;
  1760 } MOJOSHADER_astTypedefStatement;
  1761 
  1762 typedef struct MOJOSHADER_astVarDeclStatement
  1763 {
  1764     MOJOSHADER_astNodeInfo ast;
  1765     MOJOSHADER_astStatement *next;
  1766     MOJOSHADER_astVariableDeclaration *declaration;
  1767 } MOJOSHADER_astVarDeclStatement;
  1768 
  1769 typedef struct MOJOSHADER_astStructStatement
  1770 {
  1771     MOJOSHADER_astNodeInfo ast;
  1772     MOJOSHADER_astStatement *next;
  1773     MOJOSHADER_astStructDeclaration *struct_info;
  1774 } MOJOSHADER_astStructStatement;
  1775 
  1776 typedef struct MOJOSHADER_astCompilationUnitFunction
  1777 {
  1778     MOJOSHADER_astNodeInfo ast;
  1779     MOJOSHADER_astCompilationUnit *next;
  1780     MOJOSHADER_astFunctionSignature *declaration;
  1781     MOJOSHADER_astStatement *definition;
  1782     int index;  /* unique id. Will be 0 until semantic analysis runs. */
  1783 } MOJOSHADER_astCompilationUnitFunction;
  1784 
  1785 typedef struct MOJOSHADER_astCompilationUnitTypedef
  1786 {
  1787     MOJOSHADER_astNodeInfo ast;
  1788     MOJOSHADER_astCompilationUnit *next;
  1789     MOJOSHADER_astTypedef *type_info;
  1790 } MOJOSHADER_astCompilationUnitTypedef;
  1791 
  1792 typedef struct MOJOSHADER_astCompilationUnitStruct
  1793 {
  1794     MOJOSHADER_astNodeInfo ast;
  1795     MOJOSHADER_astCompilationUnit *next;
  1796     MOJOSHADER_astStructDeclaration *struct_info;
  1797 } MOJOSHADER_astCompilationUnitStruct;
  1798 
  1799 typedef struct MOJOSHADER_astCompilationUnitVariable
  1800 {
  1801     MOJOSHADER_astNodeInfo ast;
  1802     MOJOSHADER_astCompilationUnit *next;
  1803     MOJOSHADER_astVariableDeclaration *declaration;
  1804 } MOJOSHADER_astCompilationUnitVariable;
  1805 
  1806 
  1807 /* this is way cleaner than all the nasty typecasting. */
  1808 typedef union MOJOSHADER_astNode
  1809 {
  1810     MOJOSHADER_astNodeInfo ast;
  1811     MOJOSHADER_astGeneric generic;
  1812     MOJOSHADER_astExpression expression;
  1813     MOJOSHADER_astArguments arguments;
  1814     MOJOSHADER_astExpressionUnary unary;
  1815     MOJOSHADER_astExpressionBinary binary;
  1816     MOJOSHADER_astExpressionTernary ternary;
  1817     MOJOSHADER_astExpressionIdentifier identifier;
  1818     MOJOSHADER_astExpressionIntLiteral intliteral;
  1819     MOJOSHADER_astExpressionFloatLiteral floatliteral;
  1820     MOJOSHADER_astExpressionStringLiteral stringliteral;
  1821     MOJOSHADER_astExpressionBooleanLiteral boolliteral;
  1822     MOJOSHADER_astExpressionConstructor constructor;
  1823     MOJOSHADER_astExpressionDerefStruct derefstruct;
  1824     MOJOSHADER_astExpressionCallFunction callfunc;
  1825     MOJOSHADER_astExpressionCast cast;
  1826     MOJOSHADER_astCompilationUnit compunit;
  1827     MOJOSHADER_astFunctionParameters params;
  1828     MOJOSHADER_astFunctionSignature funcsig;
  1829     MOJOSHADER_astScalarOrArray soa;
  1830     MOJOSHADER_astAnnotations annotations;
  1831     MOJOSHADER_astPackOffset packoffset;
  1832     MOJOSHADER_astVariableLowLevel varlowlevel;
  1833     MOJOSHADER_astStructMembers structmembers;
  1834     MOJOSHADER_astStructDeclaration structdecl;
  1835     MOJOSHADER_astVariableDeclaration vardecl;
  1836     MOJOSHADER_astStatement stmt;
  1837     MOJOSHADER_astEmptyStatement emptystmt;
  1838     MOJOSHADER_astBreakStatement breakstmt;
  1839     MOJOSHADER_astContinueStatement contstmt;
  1840     MOJOSHADER_astDiscardStatement discardstmt;
  1841     MOJOSHADER_astBlockStatement blockstmt;
  1842     MOJOSHADER_astReturnStatement returnstmt;
  1843     MOJOSHADER_astExpressionStatement exprstmt;
  1844     MOJOSHADER_astIfStatement ifstmt;
  1845     MOJOSHADER_astSwitchCases cases;
  1846     MOJOSHADER_astSwitchStatement switchstmt;
  1847     MOJOSHADER_astWhileStatement whilestmt;
  1848     MOJOSHADER_astDoStatement dostmt;
  1849     MOJOSHADER_astForStatement forstmt;
  1850     MOJOSHADER_astTypedef typdef;
  1851     MOJOSHADER_astTypedefStatement typedefstmt;
  1852     MOJOSHADER_astVarDeclStatement vardeclstmt;
  1853     MOJOSHADER_astStructStatement structstmt;
  1854     MOJOSHADER_astCompilationUnitFunction funcunit;
  1855     MOJOSHADER_astCompilationUnitTypedef typedefunit;
  1856     MOJOSHADER_astCompilationUnitStruct structunit;
  1857     MOJOSHADER_astCompilationUnitVariable varunit;
  1858 } MOJOSHADER_astNode;
  1859 
  1860 
  1861 /*
  1862  * Structure used to return data from parsing of a shader into an AST...
  1863  */
  1864 /* !!! FIXME: most of these ints should be unsigned. */
  1865 typedef struct MOJOSHADER_astData
  1866 {
  1867     /*
  1868      * The number of elements pointed to by (errors).
  1869      */
  1870     int error_count;
  1871 
  1872     /*
  1873      * (error_count) elements of data that specify errors that were generated
  1874      *  by parsing this shader.
  1875      * This can be NULL if there were no errors or if (error_count) is zero.
  1876      *  Note that this will only produce errors for syntax problems. Most of
  1877      *  the things we expect a compiler to produce errors for--incompatible
  1878      *  types, unknown identifiers, etc--are not checked at all during
  1879      *  initial generation of the syntax tree...bogus programs that would
  1880      *  fail to compile will pass here without error, if they are syntactically
  1881      *  correct!
  1882      */
  1883     MOJOSHADER_error *errors;
  1884 
  1885     /*
  1886      * The name of the source profile used to parse the shader. Will be NULL
  1887      *  on error.
  1888      */
  1889     const char *source_profile;
  1890 
  1891     /*
  1892      * The actual syntax tree. You are responsible for walking it yourself.
  1893      *  CompilationUnits are always the top of the tree (functions, typedefs,
  1894      *  global variables, etc). Will be NULL on error.
  1895      */
  1896     const MOJOSHADER_astNode *ast;
  1897 
  1898     /*
  1899      * This is the malloc implementation you passed to MOJOSHADER_parse().
  1900      */
  1901     MOJOSHADER_malloc malloc;
  1902 
  1903     /*
  1904      * This is the free implementation you passed to MOJOSHADER_parse().
  1905      */
  1906     MOJOSHADER_free free;
  1907 
  1908     /*
  1909      * This is the pointer you passed as opaque data for your allocator.
  1910      */
  1911     void *malloc_data;
  1912 
  1913     /*
  1914      * This is internal data, and not for the application to touch.
  1915      */
  1916     void *opaque;
  1917 } MOJOSHADER_astData;
  1918 
  1919 
  1920 /*
  1921  * You almost certainly don't need this function, unless you absolutely know
  1922  *  why you need it without hesitation. This is almost certainly only good for
  1923  *  building code analysis tools on top of.
  1924  *
  1925  * This is intended to parse HLSL source code, turning it into an abstract
  1926  *  syntax tree.
  1927  *
  1928  * (srcprofile) specifies the source language of the shader. You can specify
  1929  *  a shader model with this, too. See MOJOSHADER_SRC_PROFILE_* constants.
  1930  *
  1931  * (filename) is a NULL-terminated UTF-8 filename. It can be NULL. We do not
  1932  *  actually access this file, as we obtain our data from (source). This
  1933  *  string is copied when we need to report errors while processing (source),
  1934  *  as opposed to errors in a file referenced via the #include directive in
  1935  *  (source). If this is NULL, then errors will report the filename as NULL,
  1936  *  too.
  1937  *
  1938  * (source) is an UTF-8 string of valid high-level shader source code.
  1939  *  It does not need to be NULL-terminated.
  1940  *
  1941  * (sourcelen) is the length of the string pointed to by (source), in bytes.
  1942  *
  1943  * (defines) points to (define_count) preprocessor definitions, and can be
  1944  *  NULL. These are treated by the preprocessor as if the source code started
  1945  *  with one #define for each entry you pass in here.
  1946  *
  1947  * (include_open) and (include_close) let the app control the preprocessor's
  1948  *  behaviour for #include statements. Both are optional and can be NULL, but
  1949  *  both must be specified if either is specified.
  1950  *
  1951  * This will return a MOJOSHADER_astData. The data supplied here gives the
  1952  *  application a tree-like structure they can walk to see the layout of
  1953  *  a given program. When you are done with this data, pass it to
  1954  *  MOJOSHADER_freeCompileData() to deallocate resources.
  1955  *
  1956  * This function will never return NULL, even if the system is completely
  1957  *  out of memory upon entry (in which case, this function returns a static
  1958  *  MOJOSHADER_astData object, which is still safe to pass to
  1959  *  MOJOSHADER_freeAstData()).
  1960  *
  1961  * As parsing requires some memory to be allocated, you may provide a
  1962  *  custom allocator to this function, which will be used to allocate/free
  1963  *  memory. They function just like malloc() and free(). We do not use
  1964  *  realloc(). If you don't care, pass NULL in for the allocator functions.
  1965  *  If your allocator needs instance-specific data, you may supply it with the
  1966  *  (d) parameter. This pointer is passed as-is to your (m) and (f) functions.
  1967  *
  1968  * This function is thread safe, so long as the various callback functions
  1969  *  are, too, and that the parameters remains intact for the duration of the
  1970  *  call. This allows you to parse several shaders on separate CPU cores
  1971  *  at the same time.
  1972  */
  1973 DECLSPEC const MOJOSHADER_astData *MOJOSHADER_parseAst(const char *srcprofile,
  1974                                     const char *filename, const char *source,
  1975                                     unsigned int sourcelen,
  1976                                     const MOJOSHADER_preprocessorDefine *defs,
  1977                                     unsigned int define_count,
  1978                                     MOJOSHADER_includeOpen include_open,
  1979                                     MOJOSHADER_includeClose include_close,
  1980                                     MOJOSHADER_malloc m, MOJOSHADER_free f,
  1981                                     void *d);
  1982 
  1983 
  1984 /* !!! FIXME: expose semantic analysis to the public API? */
  1985 
  1986 
  1987 /*
  1988  * Call this to dispose of AST parsing results when you are done with them.
  1989  *  This will call the MOJOSHADER_free function you provided to
  1990  *  MOJOSHADER_parseAst() multiple times, if you provided one.
  1991  *  Passing a NULL here is a safe no-op.
  1992  *
  1993  * This function is thread safe, so long as any allocator you passed into
  1994  *  MOJOSHADER_parseAst() is, too.
  1995  */
  1996 DECLSPEC void MOJOSHADER_freeAstData(const MOJOSHADER_astData *data);
  1997 
  1998 
  1999 /* Intermediate Representation interface... */
  2000 /* !!! FIXME: there is currently no way to access the IR via the public API. */
  2001 typedef enum MOJOSHADER_irNodeType
  2002 {
  2003     MOJOSHADER_IR_START_RANGE_EXPR,
  2004     MOJOSHADER_IR_CONSTANT,
  2005     MOJOSHADER_IR_TEMP,
  2006     MOJOSHADER_IR_BINOP,
  2007     MOJOSHADER_IR_MEMORY,
  2008     MOJOSHADER_IR_CALL,
  2009     MOJOSHADER_IR_ESEQ,
  2010     MOJOSHADER_IR_ARRAY,
  2011     MOJOSHADER_IR_CONVERT,
  2012     MOJOSHADER_IR_SWIZZLE,
  2013     MOJOSHADER_IR_CONSTRUCT,
  2014     MOJOSHADER_IR_END_RANGE_EXPR,
  2015 
  2016     MOJOSHADER_IR_START_RANGE_STMT,
  2017     MOJOSHADER_IR_MOVE,
  2018     MOJOSHADER_IR_EXPR_STMT,
  2019     MOJOSHADER_IR_JUMP,
  2020     MOJOSHADER_IR_CJUMP,
  2021     MOJOSHADER_IR_SEQ,
  2022     MOJOSHADER_IR_LABEL,
  2023     MOJOSHADER_IR_DISCARD,
  2024     MOJOSHADER_IR_END_RANGE_STMT,
  2025 
  2026     MOJOSHADER_IR_START_RANGE_MISC,
  2027     MOJOSHADER_IR_EXPRLIST,
  2028     MOJOSHADER_IR_END_RANGE_MISC,
  2029 
  2030     MOJOSHADER_IR_END_RANGE
  2031 } MOJOSHADER_irNodeType;
  2032 
  2033 typedef struct MOJOSHADER_irNodeInfo
  2034 {
  2035     MOJOSHADER_irNodeType type;
  2036     const char *filename;
  2037     unsigned int line;
  2038 } MOJOSHADER_irNodeInfo;
  2039 
  2040 typedef struct MOJOSHADER_irExprList MOJOSHADER_irExprList;
  2041 
  2042 /*
  2043  * IR nodes are categorized into Expressions, Statements, and Everything Else.
  2044  *  You can cast any of them to MOJOSHADER_irGeneric, but this split is
  2045  *  useful for slightly better type-checking (you can't cleanly assign
  2046  *  something that doesn't return a value to something that wants one, etc).
  2047  * These broader categories are just unions of the simpler types, so the
  2048  *  real definitions are below all the things they contain (but these
  2049  *  predeclarations are because the simpler types refer to the broader
  2050  *  categories).
  2051  */
  2052 typedef union MOJOSHADER_irExpression MOJOSHADER_irExpression;  /* returns a value. */
  2053 typedef union MOJOSHADER_irStatement MOJOSHADER_irStatement;   /* no returned value. */
  2054 typedef union MOJOSHADER_irMisc MOJOSHADER_irMisc;        /* Everything Else. */
  2055 typedef union MOJOSHADER_irNode MOJOSHADER_irNode;        /* Generic uber-wrapper. */
  2056 
  2057 /* You can cast any IR node pointer to this. */
  2058 typedef struct MOJOSHADER_irGeneric
  2059 {
  2060     MOJOSHADER_irNodeInfo ir;
  2061 } MOJOSHADER_irGeneric;
  2062 
  2063 
  2064 /* These are used for MOJOSHADER_irBinOp */
  2065 typedef enum MOJOSHADER_irBinOpType
  2066 {
  2067     MOJOSHADER_IR_BINOP_ADD,
  2068     MOJOSHADER_IR_BINOP_SUBTRACT,
  2069     MOJOSHADER_IR_BINOP_MULTIPLY,
  2070     MOJOSHADER_IR_BINOP_DIVIDE,
  2071     MOJOSHADER_IR_BINOP_MODULO,
  2072     MOJOSHADER_IR_BINOP_AND,
  2073     MOJOSHADER_IR_BINOP_OR,
  2074     MOJOSHADER_IR_BINOP_XOR,
  2075     MOJOSHADER_IR_BINOP_LSHIFT,
  2076     MOJOSHADER_IR_BINOP_RSHIFT,
  2077     MOJOSHADER_IR_BINOP_UNKNOWN
  2078 } MOJOSHADER_irBinOpType;
  2079 
  2080 typedef enum MOJOSHADER_irConditionType
  2081 {
  2082     MOJOSHADER_IR_COND_EQL,
  2083     MOJOSHADER_IR_COND_NEQ,
  2084     MOJOSHADER_IR_COND_LT,
  2085     MOJOSHADER_IR_COND_GT,
  2086     MOJOSHADER_IR_COND_LEQ,
  2087     MOJOSHADER_IR_COND_GEQ,
  2088     MOJOSHADER_IR_COND_UNKNOWN
  2089 } MOJOSHADER_irConditionType;
  2090 
  2091 
  2092 /* MOJOSHADER_irExpression types... */
  2093 
  2094 typedef struct MOJOSHADER_irExprInfo
  2095 {
  2096     MOJOSHADER_irNodeInfo ir;
  2097     MOJOSHADER_astDataTypeType type;
  2098     int elements;
  2099 } MOJOSHADER_irExprInfo;
  2100 
  2101 typedef struct MOJOSHADER_irConstant    /* Constant value */
  2102 {
  2103     MOJOSHADER_irExprInfo info;  /* Always MOJOSHADER_IR_CONSTANT */
  2104     union
  2105     {
  2106         int ival[16];
  2107         float fval[16];
  2108     } value;
  2109 } MOJOSHADER_irConstant;
  2110 
  2111 typedef struct MOJOSHADER_irTemp /* temp value (not necessarily a register). */
  2112 {
  2113     MOJOSHADER_irExprInfo info;  /* Always MOJOSHADER_IR_TEMP */
  2114     int index;
  2115 } MOJOSHADER_irTemp;
  2116 
  2117 typedef struct MOJOSHADER_irBinOp  /* binary operator (+, -, etc) */
  2118 {
  2119     MOJOSHADER_irExprInfo info;  /* Always MOJOSHADER_IR_BINOP */
  2120     MOJOSHADER_irBinOpType op;
  2121     MOJOSHADER_irExpression *left;
  2122     MOJOSHADER_irExpression *right;
  2123 } MOJOSHADER_irBinOp;
  2124 
  2125 typedef struct MOJOSHADER_irMemory
  2126 {
  2127     MOJOSHADER_irExprInfo info;  /* Always MOJOSHADER_IR_MEMORY */
  2128     int index;  /* not final addresses, just a unique identifier. */
  2129 } MOJOSHADER_irMemory;
  2130 
  2131 typedef struct MOJOSHADER_irCall
  2132 {
  2133     MOJOSHADER_irExprInfo info;  /* Always MOJOSHADER_IR_CALL */
  2134     int index;
  2135     MOJOSHADER_irExprList *args;
  2136 } MOJOSHADER_irCall;
  2137 
  2138 typedef struct MOJOSHADER_irESeq  /* statement with result */
  2139 {
  2140     MOJOSHADER_irExprInfo info;  /* Always MOJOSHADER_IR_ESEQ */
  2141     MOJOSHADER_irStatement *stmt;  /* execute this for side-effects, then... */
  2142     MOJOSHADER_irExpression *expr; /* ...use this for the result. */
  2143 } MOJOSHADER_irESeq;
  2144 
  2145 typedef struct MOJOSHADER_irArray  /* Array dereference. */
  2146 {
  2147     MOJOSHADER_irExprInfo info;  /* Always MOJOSHADER_IR_ARRAY */
  2148     MOJOSHADER_irExpression *array;
  2149     MOJOSHADER_irExpression *element;
  2150 } MOJOSHADER_irArray;
  2151 
  2152 typedef struct MOJOSHADER_irConvert  /* casting between datatypes */
  2153 {
  2154     MOJOSHADER_irExprInfo info;  /* Always MOJOSHADER_IR_CONVERT */
  2155     MOJOSHADER_irExpression *expr;
  2156 } MOJOSHADER_irConvert;
  2157 
  2158 typedef struct MOJOSHADER_irSwizzle  /* vector swizzle */
  2159 {
  2160     MOJOSHADER_irExprInfo info;  /* Always MOJOSHADER_IR_SWIZZLE */
  2161     MOJOSHADER_irExpression *expr;
  2162     char channels[4];
  2163 } MOJOSHADER_irSwizzle;
  2164 
  2165 typedef struct MOJOSHADER_irConstruct  /* vector construct from discrete items */
  2166 {
  2167     MOJOSHADER_irExprInfo info;  /* Always MOJOSHADER_IR_CONTSTRUCT */
  2168     MOJOSHADER_irExprList *args;
  2169 } MOJOSHADER_irConstruct;
  2170 
  2171 /* Wrap the whole category in a union for type "safety." */
  2172 union MOJOSHADER_irExpression
  2173 {
  2174     MOJOSHADER_irNodeInfo ir;
  2175     MOJOSHADER_irExprInfo info;
  2176     MOJOSHADER_irConstant constant;
  2177     MOJOSHADER_irTemp temp;
  2178     MOJOSHADER_irBinOp binop;
  2179     MOJOSHADER_irMemory memory;
  2180     MOJOSHADER_irCall call;
  2181     MOJOSHADER_irESeq eseq;
  2182     MOJOSHADER_irArray array;
  2183     MOJOSHADER_irConvert convert;
  2184     MOJOSHADER_irSwizzle swizzle;
  2185     MOJOSHADER_irConstruct construct;
  2186 };
  2187 
  2188 /* MOJOSHADER_irStatement types. */
  2189 
  2190 typedef struct MOJOSHADER_irMove  /* load/store. */
  2191 {
  2192     MOJOSHADER_irNodeInfo ir;  /* Always MOJOSHADER_IR_MOVE */
  2193     MOJOSHADER_irExpression *dst; /* must result in a temp or mem! */
  2194     MOJOSHADER_irExpression *src;
  2195     int writemask;  // for write-masking vector channels.
  2196 } MOJOSHADER_irMove;
  2197 
  2198 typedef struct MOJOSHADER_irExprStmt  /* evaluate expression, throw it away. */
  2199 {
  2200     MOJOSHADER_irNodeInfo ir;  /* Always MOJOSHADER_IR_EXPR_STMT */
  2201     MOJOSHADER_irExpression *expr;
  2202 } MOJOSHADER_irExprStmt;
  2203 
  2204 typedef struct MOJOSHADER_irJump  /* unconditional jump */
  2205 {
  2206     MOJOSHADER_irNodeInfo ir;  /* Always MOJOSHADER_IR_JUMP */
  2207     int label;
  2208     // !!! FIXME: possible label list, for further optimization passes.
  2209 } MOJOSHADER_irJump;
  2210 
  2211 typedef struct MOJOSHADER_irCJump  /* conditional jump */
  2212 {
  2213     MOJOSHADER_irNodeInfo ir;  /* Always MOJOSHADER_IR_CJUMP */
  2214     MOJOSHADER_irConditionType cond;
  2215     MOJOSHADER_irExpression *left;  /* if (left cond right) */
  2216     MOJOSHADER_irExpression *right;
  2217     int iftrue;  /* label id for true case. */
  2218     int iffalse; /* label id for false case. */
  2219 } MOJOSHADER_irCJump;
  2220 
  2221 typedef struct MOJOSHADER_irSeq  /* statement without side effects */
  2222 {
  2223     MOJOSHADER_irNodeInfo ir;  /* Always MOJOSHADER_IR_SEQ */
  2224     MOJOSHADER_irStatement *first;
  2225     MOJOSHADER_irStatement *next;
  2226 } MOJOSHADER_irSeq;
  2227 
  2228 typedef struct MOJOSHADER_irLabel  /* like a label in assembly language. */
  2229 {
  2230     MOJOSHADER_irNodeInfo ir;  /* Always MOJOSHADER_IR_LABEL */
  2231     int index;
  2232 } MOJOSHADER_irLabel;
  2233 
  2234 typedef MOJOSHADER_irGeneric MOJOSHADER_irDiscard;  /* discard statement. */
  2235 
  2236 
  2237 /* Wrap the whole category in a union for type "safety." */
  2238 union MOJOSHADER_irStatement
  2239 {
  2240     MOJOSHADER_irNodeInfo ir;
  2241     MOJOSHADER_irGeneric generic;
  2242     MOJOSHADER_irMove move;
  2243     MOJOSHADER_irExprStmt expr;
  2244     MOJOSHADER_irJump jump;
  2245     MOJOSHADER_irCJump cjump;
  2246     MOJOSHADER_irSeq seq;
  2247     MOJOSHADER_irLabel label;
  2248     MOJOSHADER_irDiscard discard;
  2249 };
  2250 
  2251 /* MOJOSHADER_irMisc types. */
  2252 
  2253 struct MOJOSHADER_irExprList
  2254 {
  2255     MOJOSHADER_irNodeInfo ir;  /* Always MOJOSHADER_IR_EXPRLIST */
  2256     MOJOSHADER_irExpression *expr;
  2257     MOJOSHADER_irExprList *next;
  2258 };
  2259 
  2260 /* Wrap the whole category in a union for type "safety." */
  2261 union MOJOSHADER_irMisc
  2262 {
  2263     MOJOSHADER_irNodeInfo ir;
  2264     MOJOSHADER_irGeneric generic;
  2265     MOJOSHADER_irExprList exprlist;
  2266 };
  2267 
  2268 /* This is a catchall for all your needs. :) */
  2269 union MOJOSHADER_irNode
  2270 {
  2271     MOJOSHADER_irNodeInfo ir;
  2272     MOJOSHADER_irGeneric generic;
  2273     MOJOSHADER_irExpression expr;
  2274     MOJOSHADER_irStatement stmt;
  2275     MOJOSHADER_irMisc misc;
  2276 };
  2277 
  2278 
  2279 /* Compiler interface... */
  2280 
  2281 /*
  2282  * Structure used to return data from parsing of a shader...
  2283  */
  2284 /* !!! FIXME: most of these ints should be unsigned. */
  2285 typedef struct MOJOSHADER_compileData
  2286 {
  2287     /*
  2288      * The number of elements pointed to by (errors).
  2289      */
  2290     int error_count;
  2291 
  2292     /*
  2293      * (error_count) elements of data that specify errors that were generated
  2294      *  by compiling this shader.
  2295      * This can be NULL if there were no errors or if (error_count) is zero.
  2296      */
  2297     MOJOSHADER_error *errors;
  2298 
  2299     /*
  2300      * The number of elements pointed to by (warnings).
  2301      */
  2302     int warning_count;
  2303 
  2304     /*
  2305      * (warning_count) elements of data that specify errors that were
  2306      *  generated by compiling this shader.
  2307      * This can be NULL if there were no errors or if (warning_count) is zero.
  2308      */
  2309     MOJOSHADER_error *warnings;
  2310 
  2311     /*
  2312      * The name of the source profile used to compile the shader. Will be NULL
  2313      *  on error.
  2314      */
  2315     const char *source_profile;
  2316 
  2317     /*
  2318      * Bytes of output from compiling. This will be a null-terminated ASCII
  2319      *  string of D3D assembly source code.
  2320      */
  2321     const char *output;
  2322 
  2323     /*
  2324      * Byte count for output, not counting any null terminator.
  2325      *  Will be 0 on error.
  2326      */
  2327     int output_len;
  2328 
  2329     /*
  2330      * The number of elements pointed to by (symbols).
  2331      */
  2332     int symbol_count;
  2333 
  2334     /*
  2335      * (symbol_count) elements of data that specify high-level symbol data
  2336      *  for the shader. This can be used by MOJOSHADER_assemble() to
  2337      *  generate a CTAB section in bytecode, which is needed by
  2338      *  MOJOSHADER_parseData() to handle some shaders. This can be NULL on
  2339      *  error or if (symbol_count) is zero.
  2340      */
  2341     MOJOSHADER_symbol *symbols;
  2342 
  2343     /*
  2344      * This is the malloc implementation you passed to MOJOSHADER_parse().
  2345      */
  2346     MOJOSHADER_malloc malloc;
  2347 
  2348     /*
  2349      * This is the free implementation you passed to MOJOSHADER_parse().
  2350      */
  2351     MOJOSHADER_free free;
  2352 
  2353     /*
  2354      * This is the pointer you passed as opaque data for your allocator.
  2355      */
  2356     void *malloc_data;
  2357 } MOJOSHADER_compileData;
  2358 
  2359 
  2360 /*
  2361  * This function is optional. Use this to compile high-level shader programs.
  2362  *
  2363  * This is intended to turn HLSL source code into D3D assembly code, which
  2364  *  can then be passed to MOJOSHADER_assemble() to convert it to D3D bytecode
  2365  *  (which can then be used with MOJOSHADER_parseData() to support other
  2366  *  shading targets).
  2367  *
  2368  * (srcprofile) specifies the source language of the shader. You can specify
  2369  *  a shader model with this, too. See MOJOSHADER_SRC_PROFILE_* constants.
  2370  *
  2371  * (filename) is a NULL-terminated UTF-8 filename. It can be NULL. We do not
  2372  *  actually access this file, as we obtain our data from (source). This
  2373  *  string is copied when we need to report errors while processing (source),
  2374  *  as opposed to errors in a file referenced via the #include directive in
  2375  *  (source). If this is NULL, then errors will report the filename as NULL,
  2376  *  too.
  2377  *
  2378  * (source) is an UTF-8 string of valid high-level shader source code.
  2379  *  It does not need to be NULL-terminated.
  2380  *
  2381  * (sourcelen) is the length of the string pointed to by (source), in bytes.
  2382  *
  2383  * (defines) points to (define_count) preprocessor definitions, and can be
  2384  *  NULL. These are treated by the preprocessor as if the source code started
  2385  *  with one #define for each entry you pass in here.
  2386  *
  2387  * (include_open) and (include_close) let the app control the preprocessor's
  2388  *  behaviour for #include statements. Both are optional and can be NULL, but
  2389  *  both must be specified if either is specified.
  2390  *
  2391  * This will return a MOJOSHADER_compileData. The data supplied here is
  2392  *  sufficient to supply to MOJOSHADER_assemble() for further processing.
  2393  *  When you are done with this data, pass it to MOJOSHADER_freeCompileData()
  2394  *  to deallocate resources.
  2395  *
  2396  * This function will never return NULL, even if the system is completely
  2397  *  out of memory upon entry (in which case, this function returns a static
  2398  *  MOJOSHADER_compileData object, which is still safe to pass to
  2399  *  MOJOSHADER_freeCompileData()).
  2400  *
  2401  * As compiling requires some memory to be allocated, you may provide a
  2402  *  custom allocator to this function, which will be used to allocate/free
  2403  *  memory. They function just like malloc() and free(). We do not use
  2404  *  realloc(). If you don't care, pass NULL in for the allocator functions.
  2405  *  If your allocator needs instance-specific data, you may supply it with the
  2406  *  (d) parameter. This pointer is passed as-is to your (m) and (f) functions.
  2407  *
  2408  * This function is thread safe, so long as the various callback functions
  2409  *  are, too, and that the parameters remains intact for the duration of the
  2410  *  call. This allows you to compile several shaders on separate CPU cores
  2411  *  at the same time.
  2412  */
  2413 DECLSPEC const MOJOSHADER_compileData *MOJOSHADER_compile(const char *srcprofile,
  2414                                     const char *filename, const char *source,
  2415                                     unsigned int sourcelen,
  2416                                     const MOJOSHADER_preprocessorDefine *defs,
  2417                                     unsigned int define_count,
  2418                                     MOJOSHADER_includeOpen include_open,
  2419                                     MOJOSHADER_includeClose include_close,
  2420                                     MOJOSHADER_malloc m, MOJOSHADER_free f,
  2421                                     void *d);
  2422 
  2423 
  2424 /*
  2425  * Call this to dispose of compile results when you are done with them.
  2426  *  This will call the MOJOSHADER_free function you provided to
  2427  *  MOJOSHADER_compile() multiple times, if you provided one.
  2428  *  Passing a NULL here is a safe no-op.
  2429  *
  2430  * This function is thread safe, so long as any allocator you passed into
  2431  *  MOJOSHADER_compile() is, too.
  2432  */
  2433 DECLSPEC void MOJOSHADER_freeCompileData(const MOJOSHADER_compileData *data);
  2434 
  2435 
  2436 /* OpenGL interface... */
  2437 
  2438 /*
  2439  * Signature for function lookup callbacks. MojoShader will call a function
  2440  *  you provide to get OpenGL entry points (both standard functions and
  2441  *  extensions). Through this, MojoShader never links directly to OpenGL,
  2442  *  but relies on you to provide the implementation. This means you can
  2443  *  swap in different drivers, or hook functions (log every GL call MojoShader
  2444  *  makes, etc).
  2445  *
  2446  * (fnname) is the function name we want the address for ("glBegin" or
  2447  *  whatever. (data) is a void pointer you provide, if this callback needs
  2448  *  extra information. If you don't need it, you may specify NULL.
  2449  *
  2450  * Return the entry point on success, NULL if it couldn't be found.
  2451  *  Note that this could ask for standard entry points like glEnable(), or
  2452  *  extensions like glProgramLocalParameterI4ivNV(), so you might need
  2453  *  to check two places to find the desired entry point, depending on your
  2454  *  platform (Windows might need to look in OpenGL32.dll and use WGL, etc).
  2455  */
  2456 typedef void *(MOJOSHADERCALL *MOJOSHADER_glGetProcAddress)(const char *fnname, void *data);
  2457 
  2458 
  2459 /*
  2460  * "Contexts" map to OpenGL contexts...you need one per window, or whatever,
  2461  *  and need to inform MojoShader when you make a new one current.
  2462  *
  2463  * "Shaders" refer to individual vertex or pixel programs, and are created
  2464  *  by "compiling" Direct3D shader bytecode. A vertex and pixel shader are
  2465  *  "linked" into a "Program" before you can use them to render.
  2466  *
  2467  * To the calling application, these are all opaque handles.
  2468  */
  2469 typedef struct MOJOSHADER_glContext MOJOSHADER_glContext;
  2470 typedef struct MOJOSHADER_glShader MOJOSHADER_glShader;
  2471 typedef struct MOJOSHADER_glProgram MOJOSHADER_glProgram;
  2472 
  2473 
  2474 /*
  2475  * Get a list of available profiles. This will fill in the array (profs)
  2476  *  with up to (size) pointers of profiles that the current system can handle;
  2477  *  that is, the profiles are built into MojoShader and the OpenGL extensions
  2478  *  required for them exist at runtime. This function returns the number of
  2479  *  available profiles, which may be more, less, or equal to (size).
  2480  *
  2481  * If there are more than (size) profiles, the (profs) buffer will not
  2482  *  overflow. You can check the return value for the total number of
  2483  *  available profiles, allocate more space, and try again if necessary.
  2484  *  Calling this function with (size) == 0 is legal.
  2485  *
  2486  * You can only call this AFTER you have successfully built your GL context
  2487  *  and made it current. This function will lookup the GL functions it needs
  2488  *  through the callback you supply, via (lookup) and (lookup_d). The lookup
  2489  *  function is neither stored nor used by MojoShader after this function
  2490  *  returns, nor are the functions it might look up.
  2491  *
  2492  * As MojoShader requires some memory to be allocated, you may provide a
  2493  *  custom allocator to this function, which will be used to allocate/free
  2494  *  memory. They function just like malloc() and free(). We do not use
  2495  *  realloc(). If you don't care, pass NULL in for the allocator functions.
  2496  *  If your allocator needs instance-specific data, you may supply it with the
  2497  *  (malloc_d) parameter. This pointer is passed as-is to your (m) and (f)
  2498  *  functions.
  2499  *
  2500  * You should not free any strings returned from this function; they are
  2501  *  pointers to internal, probably static, memory.
  2502  *
  2503  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2504  *  safe, you should probably only call this from the same thread that created
  2505  *  the GL context.
  2506  */
  2507 DECLSPEC int MOJOSHADER_glAvailableProfiles(MOJOSHADER_glGetProcAddress lookup,
  2508                                             void *lookup_d,
  2509                                             const char **profs, const int size,
  2510                                             MOJOSHADER_malloc m, MOJOSHADER_free f,
  2511                                             void *malloc_d);
  2512 
  2513 
  2514 /*
  2515  * Determine the best profile to use for the current system.
  2516  *
  2517  * You can only call this AFTER you have successfully built your GL context
  2518  *  and made it current. This function will lookup the GL functions it needs
  2519  *  through the callback you supply via (lookup) and (lookup_d). The lookup
  2520  *  function is neither stored nor used by MojoShader after this function
  2521  *  returns, nor are the functions it might look up.
  2522  *
  2523  * Returns the name of the "best" profile on success, NULL if none of the
  2524  *  available profiles will work on this system. "Best" is a relative term,
  2525  *  but it generally means the best trade off between feature set and
  2526  *  performance. The selection algorithm may be arbitrary and complex.
  2527  *
  2528  * As MojoShader requires some memory to be allocated, you may provide a
  2529  *  custom allocator to this function, which will be used to allocate/free
  2530  *  memory. They function just like malloc() and free(). We do not use
  2531  *  realloc(). If you don't care, pass NULL in for the allocator functions.
  2532  *  If your allocator needs instance-specific data, you may supply it with the
  2533  *  (malloc_d) parameter. This pointer is passed as-is to your (m) and (f)
  2534  *  functions.
  2535  *
  2536  * The returned value is an internal static string, and should not be free()'d
  2537  *  by the caller. If you get a NULL, calling MOJOSHADER_glGetError() might
  2538  *  shed some light on why.
  2539  *
  2540  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2541  *  safe, you should probably only call this from the same thread that created
  2542  *  the GL context.
  2543  */
  2544 DECLSPEC const char *MOJOSHADER_glBestProfile(MOJOSHADER_glGetProcAddress lookup,
  2545                                    void *lookup_d,
  2546                                    MOJOSHADER_malloc m, MOJOSHADER_free f,
  2547                                    void *malloc_d);
  2548 
  2549 /*
  2550  * Prepare MojoShader to manage OpenGL shaders.
  2551  *
  2552  * You do not need to call this if all you want is MOJOSHADER_parse().
  2553  *
  2554  * You must call this once AFTER you have successfully built your GL context
  2555  *  and made it current. This function will lookup the GL functions it needs
  2556  *  through the callback you supply via (lookup) and (lookup_d), after which
  2557  *  it may call them at any time up until you call
  2558  *  MOJOSHADER_glDestroyContext(). The lookup function is neither stored nor
  2559  *  used by MojoShader after this function returns.
  2560  *
  2561  * (profile) is an OpenGL-specific MojoShader profile, which decides how
  2562  *  Direct3D bytecode shaders get turned into OpenGL programs, and how they
  2563  *  are fed to the GL.
  2564  *
  2565  * (lookup) is a callback that is used to load GL entry points. This callback
  2566  *  has to look up base GL functions and extension entry points. The pointer
  2567  *  you supply in (lookup_d) is passed as-is to the callback.
  2568  *
  2569  * As MojoShader requires some memory to be allocated, you may provide a
  2570  *  custom allocator to this function, which will be used to allocate/free
  2571  *  memory. They function just like malloc() and free(). We do not use
  2572  *  realloc(). If you don't care, pass NULL in for the allocator functions.
  2573  *  If your allocator needs instance-specific data, you may supply it with the
  2574  *  (malloc_d) parameter. This pointer is passed as-is to your (m) and (f)
  2575  *  functions.
  2576  *
  2577  * Returns a new context on success, NULL on error. If you get a new context,
  2578  *  you need to make it current before using it with
  2579  *  MOJOSHADER_glMakeContextCurrent().
  2580  *
  2581  * This call is NOT thread safe! It must return success before you may call
  2582  *  any other MOJOSHADER_gl* function. Also, as most OpenGL implementations
  2583  *  are not thread safe, you should probably only call this from the same
  2584  *  thread that created the GL context.
  2585  */
  2586 DECLSPEC MOJOSHADER_glContext *MOJOSHADER_glCreateContext(const char *profile,
  2587                                         MOJOSHADER_glGetProcAddress lookup,
  2588                                         void *lookup_d,
  2589                                         MOJOSHADER_malloc m, MOJOSHADER_free f,
  2590                                         void *malloc_d);
  2591 
  2592 /*
  2593  * You must call this before using the context that you got from
  2594  *  MOJOSHADER_glCreateContext(), and must use it when you switch to a new GL
  2595  *  context.
  2596  *
  2597  * You can only have one MOJOSHADER_glContext per actual GL context, or
  2598  *  undefined behaviour will result.
  2599  *
  2600  * It is legal to call this with a NULL pointer to make no context current,
  2601  *  but you need a valid context to be current to use most of MojoShader.
  2602  */
  2603 DECLSPEC void MOJOSHADER_glMakeContextCurrent(MOJOSHADER_glContext *ctx);
  2604 
  2605 /*
  2606  * Get any error state we might have picked up. MojoShader will NOT call
  2607  *  glGetError() internally, but there are other errors we can pick up,
  2608  *  such as failed shader compilation, etc.
  2609  *
  2610  * Returns a human-readable string. This string is for debugging purposes, and
  2611  *  not guaranteed to be localized, coherent, or user-friendly in any way.
  2612  *  It's for programmers!
  2613  *
  2614  * The latest error may remain between calls. New errors replace any existing
  2615  *  error. Don't check this string for a sign that an error happened, check
  2616  *  return codes instead and use this for explanation when debugging.
  2617  *
  2618  * Do not free the returned string: it's a pointer to a static internal
  2619  *  buffer. Do not keep the pointer around, either, as it's likely to become
  2620  *  invalid as soon as you call into MojoShader again.
  2621  *
  2622  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2623  *  safe, you should probably only call this from the same thread that created
  2624  *  the GL context.
  2625  *
  2626  * This call does NOT require a valid MOJOSHADER_glContext to have been made
  2627  *  current. The error buffer is shared between contexts, so you can get
  2628  *  error results from a failed MOJOSHADER_glCreateContext().
  2629  */
  2630 DECLSPEC const char *MOJOSHADER_glGetError(void);
  2631 
  2632 /*
  2633  * Get the maximum uniforms a shader can support for the current GL context,
  2634  *  MojoShader profile, and shader type. You can use this to make decisions
  2635  *  about what shaders you want to use (for example, a less complicated
  2636  *  shader may be swapped in for lower-end systems).
  2637  *
  2638  * Returns the number, or -1 on error.
  2639  *
  2640  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2641  *  safe, you should probably only call this from the same thread that created
  2642  *  the GL context.
  2643  *
  2644  * This call requires a valid MOJOSHADER_glContext to have been made current,
  2645  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  2646  */
  2647 DECLSPEC int MOJOSHADER_glMaxUniforms(MOJOSHADER_shaderType shader_type);
  2648 
  2649 /*
  2650  * Compile a buffer of Direct3D shader bytecode into an OpenGL shader.
  2651  *  You still need to link the shader before you may render with it.
  2652  *
  2653  *   (tokenbuf) is a buffer of Direct3D shader bytecode.
  2654  *   (bufsize) is the size, in bytes, of the bytecode buffer.
  2655  *   (swiz), (swizcount), (smap), and (smapcount) are passed to
  2656  *   MOJOSHADER_parse() unmolested.
  2657  *
  2658  * Returns NULL on error, or a shader handle on success.
  2659  *
  2660  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2661  *  safe, you should probably only call this from the same thread that created
  2662  *  the GL context.
  2663  *
  2664  * This call requires a valid MOJOSHADER_glContext to have been made current,
  2665  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  2666  *
  2667  * Compiled shaders from this function may not be shared between contexts.
  2668  */
  2669 DECLSPEC MOJOSHADER_glShader *MOJOSHADER_glCompileShader(const unsigned char *tokenbuf,
  2670                                                          const unsigned int bufsize,
  2671                                                          const MOJOSHADER_swizzle *swiz,
  2672                                                          const unsigned int swizcount,
  2673                                                          const MOJOSHADER_samplerMap *smap,
  2674                                                          const unsigned int smapcount);
  2675 
  2676 
  2677 /*
  2678  * Get the MOJOSHADER_parseData structure that was produced from the
  2679  *  call to MOJOSHADER_glCompileShader().
  2680  *
  2681  * This data is read-only, and you should NOT attempt to free it. This
  2682  *  pointer remains valid until the shader is deleted.
  2683  */
  2684 DECLSPEC const MOJOSHADER_parseData *MOJOSHADER_glGetShaderParseData(
  2685                                                 MOJOSHADER_glShader *shader);
  2686 /*
  2687  * Link a vertex and pixel shader into an OpenGL program.
  2688  *  (vshader) or (pshader) can be NULL, to specify that the GL should use the
  2689  *  fixed-function pipeline instead of the programmable pipeline for that
  2690  *  portion of the work. You can reuse shaders in various combinations across
  2691  *  multiple programs, by relinking different pairs.
  2692  *
  2693  * It is illegal to give a vertex shader for (pshader) or a pixel shader
  2694  *  for (vshader).
  2695  *
  2696  * Once you have successfully linked a program, you may render with it.
  2697  *
  2698  * Returns NULL on error, or a program handle on success.
  2699  *
  2700  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2701  *  safe, you should probably only call this from the same thread that created
  2702  *  the GL context.
  2703  *
  2704  * This call requires a valid MOJOSHADER_glContext to have been made current,
  2705  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  2706  *
  2707  * Linked programs from this function may not be shared between contexts.
  2708  */
  2709 DECLSPEC MOJOSHADER_glProgram *MOJOSHADER_glLinkProgram(MOJOSHADER_glShader *vshader,
  2710                                                         MOJOSHADER_glShader *pshader);
  2711 
  2712 /*
  2713  * This binds the program (using, for example, glUseProgramObjectARB()), and
  2714  *  disables all the client-side arrays so we can reset them with new values
  2715  *  if appropriate.
  2716  *
  2717  * Call with NULL to disable the programmable pipeline and all enabled
  2718  *  client-side arrays.
  2719  *
  2720  * After binding a program, you should update any uniforms you care about
  2721  *  with MOJOSHADER_glSetVertexShaderUniformF() (etc), set any vertex arrays
  2722  *  you want to use with MOJOSHADER_glSetVertexAttribute(), and finally call
  2723  *  MOJOSHADER_glProgramReady() to commit everything to the GL. Then you may
  2724  *  begin drawing through standard GL entry points.
  2725  *
  2726  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2727  *  safe, you should probably only call this from the same thread that created
  2728  *  the GL context.
  2729  *
  2730  * This call requires a valid MOJOSHADER_glContext to have been made current,
  2731  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  2732  */
  2733 DECLSPEC void MOJOSHADER_glBindProgram(MOJOSHADER_glProgram *program);
  2734 
  2735 /*
  2736  * This binds individual shaders as if you had linked them with
  2737  *  MOJOSHADER_glLinkProgram(), and used MOJOSHADER_glBindProgram() on the
  2738  *  linked result.
  2739  *
  2740  * MojoShader will handle linking behind the scenes, and keep a cache of
  2741  *  programs linked here. Programs are removed from this cache when one of the
  2742  *  invidual shaders in it is deleted, otherwise they remain cached so future
  2743  *  calls to this function don't need to relink a previously-used shader
  2744  *  grouping.
  2745  *
  2746  * This function is for convenience, as the API is closer to how Direct3D
  2747  *  works, and retrofitting linking into your app can be difficult;
  2748  *  frequently, you just end up building your own cache, anyhow.
  2749  *
  2750  * Calling with all shaders set to NULL is equivalent to calling
  2751  *  MOJOSHADER_glBindProgram(NULL).
  2752  *
  2753  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2754  *  safe, you should probably only call this from the same thread that created
  2755  *  the GL context.
  2756  *
  2757  * This call requires a valid MOJOSHADER_glContext to have been made current,
  2758  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  2759  */
  2760 DECLSPEC void MOJOSHADER_glBindShaders(MOJOSHADER_glShader *vshader,
  2761                                        MOJOSHADER_glShader *pshader);
  2762 
  2763 /*
  2764  * Set a floating-point uniform value (what Direct3D calls a "constant").
  2765  *
  2766  * There is a single array of 4-float "registers" shared by all vertex shaders.
  2767  *  This is the "c" register file in Direct3D (c0, c1, c2, etc...)
  2768  *  MojoShader will take care of synchronizing this internal array with the
  2769  *  appropriate variables in the GL shaders.
  2770  *
  2771  * (idx) is the index into the internal array: 0 is the first four floats,
  2772  *  1 is the next four, etc.
  2773  * (data) is a pointer to (vec4count*4) floats.
  2774  *
  2775  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2776  *  safe, you should probably only call this from the same thread that created
  2777  *  the GL context.
  2778  *
  2779  * This call requires a valid MOJOSHADER_glContext to have been made current,
  2780  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  2781  *
  2782  * Uniforms are not shared between contexts.
  2783  */
  2784 DECLSPEC void MOJOSHADER_glSetVertexShaderUniformF(unsigned int idx, const float *data,
  2785                                                    unsigned int vec4count);
  2786 
  2787 /*
  2788  * Retrieve a floating-point uniform value (what Direct3D calls a "constant").
  2789  *
  2790  * There is a single array of 4-float "registers" shared by all vertex shaders.
  2791  *  This is the "c" register file in Direct3D (c0, c1, c2, etc...)
  2792  *  MojoShader will take care of synchronizing this internal array with the
  2793  *  appropriate variables in the GL shaders.
  2794  *
  2795  * (idx) is the index into the internal array: 0 is the first four floats,
  2796  *  1 is the next four, etc.
  2797  * (data) is a pointer to space for (vec4count*4) floats.
  2798  *  (data) will be filled will current values in the register file. Results
  2799  *  are undefined if you request data past the end of the register file or
  2800  *  previously uninitialized registers.
  2801  *
  2802  * This is a "fast" call; we're just reading from internal memory. We do not
  2803  *  query the GPU or the GL for this information.
  2804  *
  2805  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2806  *  safe, you should probably only call this from the same thread that created
  2807  *  the GL context.
  2808  *
  2809  * This call requires a valid MOJOSHADER_glContext to have been made current,
  2810  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  2811  *
  2812  * Uniforms are not shared between contexts.
  2813  */
  2814 DECLSPEC void MOJOSHADER_glGetVertexShaderUniformF(unsigned int idx, float *data,
  2815                                                    unsigned int vec4count);
  2816 
  2817 
  2818 /*
  2819  * Set an integer uniform value (what Direct3D calls a "constant").
  2820  *
  2821  * There is a single array of 4-int "registers" shared by all vertex shaders.
  2822  *  This is the "i" register file in Direct3D (i0, i1, i2, etc...)
  2823  *  MojoShader will take care of synchronizing this internal array with the
  2824  *  appropriate variables in the GL shaders.
  2825  *
  2826  * (idx) is the index into the internal array: 0 is the first four ints,
  2827  *  1 is the next four, etc.
  2828  * (data) is a pointer to (ivec4count*4) ints.
  2829  *
  2830  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2831  *  safe, you should probably only call this from the same thread that created
  2832  *  the GL context.
  2833  *
  2834  * This call requires a valid MOJOSHADER_glContext to have been made current,
  2835  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  2836  *
  2837  * Uniforms are not shared between contexts.
  2838  */
  2839 DECLSPEC void MOJOSHADER_glSetVertexShaderUniformI(unsigned int idx, const int *data,
  2840                                                    unsigned int ivec4count);
  2841 
  2842 /*
  2843  * Retrieve an integer uniform value (what Direct3D calls a "constant").
  2844  *
  2845  * There is a single array of 4-int "registers" shared by all vertex shaders.
  2846  *  This is the "i" register file in Direct3D (i0, i1, i2, etc...)
  2847  *  MojoShader will take care of synchronizing this internal array with the
  2848  *  appropriate variables in the GL shaders.
  2849  *
  2850  * (idx) is the index into the internal array: 0 is the first four ints,
  2851  *  1 is the next four, etc.
  2852  * (data) is a pointer to space for (ivec4count*4) ints.
  2853  *  (data) will be filled will current values in the register file. Results
  2854  *  are undefined if you request data past the end of the register file or
  2855  *  previously uninitialized registers.
  2856  *
  2857  * This is a "fast" call; we're just reading from internal memory. We do not
  2858  *  query the GPU or the GL for this information.
  2859  *
  2860  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2861  *  safe, you should probably only call this from the same thread that created
  2862  *  the GL context.
  2863  *
  2864  * This call requires a valid MOJOSHADER_glContext to have been made current,
  2865  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  2866  *
  2867  * Uniforms are not shared between contexts.
  2868  */
  2869 DECLSPEC void MOJOSHADER_glGetVertexShaderUniformI(unsigned int idx, int *data,
  2870                                                    unsigned int ivec4count);
  2871 
  2872 /*
  2873  * Set a boolean uniform value (what Direct3D calls a "constant").
  2874  *
  2875  * There is a single array of "registers" shared by all vertex shaders.
  2876  *  This is the "b" register file in Direct3D (b0, b1, b2, etc...)
  2877  *  MojoShader will take care of synchronizing this internal array with the
  2878  *  appropriate variables in the GL shaders.
  2879  *
  2880  * Unlike the float and int counterparts, booleans are single values, not
  2881  *  four-element vectors...so idx==1 is the second boolean in the internal
  2882  *  array, not the fifth.
  2883  *
  2884  * Non-zero values are considered "true" and zero is considered "false".
  2885  *
  2886  * (idx) is the index into the internal array.
  2887  * (data) is a pointer to (bcount) ints.
  2888  *
  2889  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2890  *  safe, you should probably only call this from the same thread that created
  2891  *  the GL context.
  2892  *
  2893  * This call requires a valid MOJOSHADER_glContext to have been made current,
  2894  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  2895  *
  2896  * Uniforms are not shared between contexts.
  2897  */
  2898 DECLSPEC void MOJOSHADER_glSetVertexShaderUniformB(unsigned int idx, const int *data,
  2899                                                    unsigned int bcount);
  2900 
  2901 /*
  2902  * Retrieve a boolean uniform value (what Direct3D calls a "constant").
  2903  *
  2904  * There is a single array of "registers" shared by all vertex shaders.
  2905  *  This is the "b" register file in Direct3D (b0, b1, b2, etc...)
  2906  *  MojoShader will take care of synchronizing this internal array with the
  2907  *  appropriate variables in the GL shaders.
  2908  *
  2909  * Unlike the float and int counterparts, booleans are single values, not
  2910  *  four-element vectors...so idx==1 is the second boolean in the internal
  2911  *  array, not the fifth.
  2912  *
  2913  * Non-zero values are considered "true" and zero is considered "false".
  2914  *  This function will always return true values as 1, regardless of what
  2915  *  non-zero integer you originally used to set the registers.
  2916  *
  2917  * (idx) is the index into the internal array.
  2918  * (data) is a pointer to space for (bcount) ints.
  2919  *  (data) will be filled will current values in the register file. Results
  2920  *  are undefined if you request data past the end of the register file or
  2921  *  previously uninitialized registers.
  2922  *
  2923  * This is a "fast" call; we're just reading from internal memory. We do not
  2924  *  query the GPU or the GL for this information.
  2925  *
  2926  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2927  *  safe, you should probably only call this from the same thread that created
  2928  *  the GL context.
  2929  *
  2930  * This call requires a valid MOJOSHADER_glContext to have been made current,
  2931  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  2932  *
  2933  * Uniforms are not shared between contexts.
  2934  */
  2935 DECLSPEC void MOJOSHADER_glGetVertexShaderUniformB(unsigned int idx, int *data,
  2936                                                    unsigned int bcount);
  2937 
  2938 /*
  2939  * The equivalent of MOJOSHADER_glSetVertexShaderUniformF() for pixel
  2940  *  shaders. Other than using a different internal array that is specific
  2941  *  to pixel shaders, this functions just like its vertex array equivalent.
  2942  *
  2943  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2944  *  safe, you should probably only call this from the same thread that created
  2945  *  the GL context.
  2946  *
  2947  * This call requires a valid MOJOSHADER_glContext to have been made current,
  2948  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  2949  *
  2950  * Uniforms are not shared between contexts.
  2951  */
  2952 DECLSPEC void MOJOSHADER_glSetPixelShaderUniformF(unsigned int idx, const float *data,
  2953                                                   unsigned int vec4count);
  2954 
  2955 
  2956 /*
  2957  * The equivalent of MOJOSHADER_glGetVertexShaderUniformF() for pixel
  2958  *  shaders. Other than using a different internal array that is specific
  2959  *  to pixel shaders, this functions just like its vertex array equivalent.
  2960  *
  2961  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2962  *  safe, you should probably only call this from the same thread that created
  2963  *  the GL context.
  2964  *
  2965  * This call requires a valid MOJOSHADER_glContext to have been made current,
  2966  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  2967  *
  2968  * Uniforms are not shared between contexts.
  2969  */
  2970 DECLSPEC void MOJOSHADER_glGetPixelShaderUniformF(unsigned int idx, float *data,
  2971                                                   unsigned int vec4count);
  2972 
  2973 
  2974 /*
  2975  * The equivalent of MOJOSHADER_glSetVertexShaderUniformI() for pixel
  2976  *  shaders. Other than using a different internal array that is specific
  2977  *  to pixel shaders, this functions just like its vertex array equivalent.
  2978  *
  2979  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2980  *  safe, you should probably only call this from the same thread that created
  2981  *  the GL context.
  2982  *
  2983  * This call requires a valid MOJOSHADER_glContext to have been made current,
  2984  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  2985  *
  2986  * Uniforms are not shared between contexts.
  2987  */
  2988 DECLSPEC void MOJOSHADER_glSetPixelShaderUniformI(unsigned int idx, const int *data,
  2989                                                   unsigned int ivec4count);
  2990 
  2991 
  2992 /*
  2993  * The equivalent of MOJOSHADER_glGetVertexShaderUniformI() for pixel
  2994  *  shaders. Other than using a different internal array that is specific
  2995  *  to pixel shaders, this functions just like its vertex array equivalent.
  2996  *
  2997  * This call is NOT thread safe! As most OpenGL implementations are not thread
  2998  *  safe, you should probably only call this from the same thread that created
  2999  *  the GL context.
  3000  *
  3001  * This call requires a valid MOJOSHADER_glContext to have been made current,
  3002  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  3003  *
  3004  * Uniforms are not shared between contexts.
  3005  */
  3006 DECLSPEC void MOJOSHADER_glGetPixelShaderUniformI(unsigned int idx, int *data,
  3007                                                   unsigned int ivec4count);
  3008 
  3009 /*
  3010  * The equivalent of MOJOSHADER_glSetVertexShaderUniformB() for pixel
  3011  *  shaders. Other than using a different internal array that is specific
  3012  *  to pixel shaders, this functions just like its vertex array equivalent.
  3013  *
  3014  * This call is NOT thread safe! As most OpenGL implementations are not thread
  3015  *  safe, you should probably only call this from the same thread that created
  3016  *  the GL context.
  3017  *
  3018  * This call requires a valid MOJOSHADER_glContext to have been made current,
  3019  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  3020  *
  3021  * Uniforms are not shared between contexts.
  3022  */
  3023 DECLSPEC void MOJOSHADER_glSetPixelShaderUniformB(unsigned int idx, const int *data,
  3024                                                   unsigned int bcount);
  3025 
  3026 /*
  3027  * The equivalent of MOJOSHADER_glGetVertexShaderUniformB() for pixel
  3028  *  shaders. Other than using a different internal array that is specific
  3029  *  to pixel shaders, this functions just like its vertex array equivalent.
  3030  *
  3031  * This call is NOT thread safe! As most OpenGL implementations are not thread
  3032  *  safe, you should probably only call this from the same thread that created
  3033  *  the GL context.
  3034  *
  3035  * This call requires a valid MOJOSHADER_glContext to have been made current,
  3036  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  3037  *
  3038  * Uniforms are not shared between contexts.
  3039  */
  3040 DECLSPEC void MOJOSHADER_glGetPixelShaderUniformB(unsigned int idx, int *data,
  3041                                                   unsigned int bcount);
  3042 
  3043 /*
  3044  * Set up the vector for the TEXBEM opcode. Most apps can ignore this API.
  3045  *
  3046  * Shader Model 1.1 through 1.3 had an instruction for "fake bump mapping"
  3047  *  called TEXBEM. To use it, you had to set some sampler states,
  3048  *  D3DTSS_BUMPENVMATxx, which would be referenced by the opcode.
  3049  *
  3050  * This functionality was removed from Shader Model 1.4 and later, because
  3051  *  it was special-purpose and limited. The functionality could be built on
  3052  *  more general opcodes, and the sampler state could be supplied in a more
  3053  *  general uniform.
  3054  *
  3055  * However, to support this opcode, we supply a way to specify that sampler
  3056  *  state, and the OpenGL glue code does the right thing to pass that
  3057  *  information to the shader.
  3058  *
  3059  * This call maps to IDirect3DDevice::SetTextureStageState() with the
  3060  *  D3DTSS_BUMPENVMAT00, D3DTSS_BUMPENVMAT01, D3DTSS_BUMPENVMAT10,
  3061  *  D3DTSS_BUMPENVMAT11, D3DTSS_BUMPENVLSCALE, and D3DTSS_BUMPENVLOFFSET
  3062  *  targets. This is only useful for Shader Model < 1.4 pixel shaders, if
  3063  *  they use the TEXBEM or TEXBEML opcode. If you aren't sure, you don't need
  3064  *  this function.
  3065  *
  3066  * Like the rest of your uniforms, you must call MOJOSHADER_glProgramReady()
  3067  *  between setting new values and drawing with them.
  3068  *
  3069  * This call is NOT thread safe! As most OpenGL implementations are not thread
  3070  *  safe, you should probably only call this from the same thread that created
  3071  *  the GL context.
  3072  *
  3073  * This call requires a valid MOJOSHADER_glContext to have been made current,
  3074  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  3075  *
  3076  * These values are not shared between contexts.
  3077  */
  3078 DECLSPEC void MOJOSHADER_glSetLegacyBumpMapEnv(unsigned int sampler, float mat00,
  3079                                                float mat01, float mat10, float mat11,
  3080                                                float lscale, float loffset);
  3081 
  3082 /*
  3083  * Return the location of a vertex attribute for the currently-bound program.
  3084  *
  3085  * (usage) and (index) map to Direct3D vertex declaration values: COLOR1 would
  3086  *  be MOJOSHADER_USAGE_COLOR and 1.
  3087  *
  3088  * The return value is the index of the attribute to be sent to
  3089  *  glVertexAttribPointer, or -1 if the stream is not used.
  3090  *
  3091  * This call requires a valid MOJOSHADER_glContext to have been made current,
  3092  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  3093  */
  3094 DECLSPEC int MOJOSHADER_glGetVertexAttribLocation(MOJOSHADER_usage usage, int index);
  3095 
  3096 /*
  3097  * Connect a client-side array to the currently-bound program.
  3098  *
  3099  * (usage) and (index) map to Direct3D vertex declaration values: COLOR1 would
  3100  *  be MOJOSHADER_USAGE_COLOR and 1.
  3101  *
  3102  * The caller should bind VBOs before this call and treat (ptr) as an offset,
  3103  *  if appropriate.
  3104  *
  3105  * MojoShader will figure out where to plug this stream into the
  3106  *  currently-bound program, and enable the appropriate client-side array.
  3107  *
  3108  * (size), (type), (normalized), (stride), and (ptr) correspond to
  3109  *  glVertexAttribPointer()'s parameters (in most cases, these get passed
  3110  *  unmolested to that very entry point during this function).
  3111  *
  3112  * This call is NOT thread safe! As most OpenGL implementations are not thread
  3113  *  safe, you should probably only call this from the same thread that created
  3114  *  the GL context.
  3115  *
  3116  * This call requires a valid MOJOSHADER_glContext to have been made current,
  3117  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  3118  *
  3119  * Vertex attributes are not shared between contexts.
  3120  */
  3121  /* !!! FIXME: this should probably be "input" and not "attribute" */
  3122  /* !!! FIXME: or maybe "vertex array" or something. */
  3123 DECLSPEC void MOJOSHADER_glSetVertexAttribute(MOJOSHADER_usage usage,
  3124                                               int index, unsigned int size,
  3125                                               MOJOSHADER_attributeType type,
  3126                                               int normalized, unsigned int stride,
  3127                                               const void *ptr);
  3128 
  3129 /*
  3130  *  Modify the rate at which this vertex attribute advances during instanced
  3131  *  rendering.
  3132  *
  3133  * This should be called alongside glSetVertexAttribute, as this does not flag
  3134  *  the vertex array as being in use. This just calls glVertexAttribDivisorARB.
  3135  *
  3136  * This call is NOT thread safe! As most OpenGL implementations are not thread
  3137  *  safe, you should probably only call this from the same thread that created
  3138  *  the GL context.
  3139  *
  3140  * This call requires a valid MOJOSHADER_glContext to have been made current,
  3141  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  3142  *
  3143  * Vertex attributes are not shared between contexts.
  3144  */
  3145 DECLSPEC void MOJOSHADER_glSetVertexAttribDivisor(MOJOSHADER_usage usage,
  3146                                                   int index, unsigned int divisor);
  3147 
  3148 /*
  3149  * Inform MojoShader that it should commit any pending state to the GL. This
  3150  *  must be called after you bind a program and update any inputs, right
  3151  *  before you start drawing, so any outstanding changes made to the shared
  3152  *  constants array (etc) can propagate to the shader during this call.
  3153  *
  3154  * This call is NOT thread safe! As most OpenGL implementations are not thread
  3155  *  safe, you should probably only call this from the same thread that created
  3156  *  the GL context.
  3157  *
  3158  * This call requires a valid MOJOSHADER_glContext to have been made current,
  3159  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  3160  */
  3161 DECLSPEC void MOJOSHADER_glProgramReady(void);
  3162 
  3163 #ifdef MOJOSHADER_FLIP_RENDERTARGET
  3164 // !!! FIXME: Document me.
  3165 DECLSPEC void MOJOSHADER_glProgramViewportFlip(int flip);
  3166 #endif
  3167 
  3168 /*
  3169  * Free the resources of a linked program. This will delete the GL object
  3170  *  and free memory.
  3171  *
  3172  * If the program is currently bound by MOJOSHADER_glBindProgram(), it will
  3173  *  be deleted as soon as it becomes unbound.
  3174  *
  3175  * This call is NOT thread safe! As most OpenGL implementations are not thread
  3176  *  safe, you should probably only call this from the same thread that created
  3177  *  the GL context.
  3178  *
  3179  * This call requires a valid MOJOSHADER_glContext to have been made current,
  3180  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  3181  */
  3182 DECLSPEC void MOJOSHADER_glDeleteProgram(MOJOSHADER_glProgram *program);
  3183 
  3184 /*
  3185  * Free the resources of a compiled shader. This will delete the GL object
  3186  *  and free memory.
  3187  *
  3188  * If the shader is currently referenced by a linked program (or is currently
  3189  *  bound with MOJOSHADER_glBindShaders()), it will be deleted as soon as all
  3190  *  referencing programs are deleted and it is no longer bound, too.
  3191  *
  3192  * This call is NOT thread safe! As most OpenGL implementations are not thread
  3193  *  safe, you should probably only call this from the same thread that created
  3194  *  the GL context.
  3195  *
  3196  * This call requires a valid MOJOSHADER_glContext to have been made current,
  3197  *  or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
  3198  */
  3199 DECLSPEC void MOJOSHADER_glDeleteShader(MOJOSHADER_glShader *shader);
  3200 
  3201 /*
  3202  * Deinitialize MojoShader's OpenGL shader management.
  3203  *
  3204  * You must call this once, while your GL context (not MojoShader context) is
  3205  *  still current, if you previously had a successful call to
  3206  *  MOJOSHADER_glCreateContext(). This should be the last MOJOSHADER_gl*
  3207  *  function you call until you've prepared a context again.
  3208  *
  3209  * This will clean up resources previously allocated, and may call into the GL.
  3210  *
  3211  * This will not clean up shaders and programs you created! Please call
  3212  *  MOJOSHADER_glDeleteShader() and MOJOSHADER_glDeleteProgram() to clean
  3213  *  those up before calling this function!
  3214  *
  3215  * This function destroys the MOJOSHADER_glContext you pass it. If it's the
  3216  *  current context, then no context will be current upon return.
  3217  *
  3218  * This call is NOT thread safe! There must not be any other MOJOSHADER_gl*
  3219  *  functions running when this is called. Also, as most OpenGL implementations
  3220  *  are not thread safe, you should probably only call this from the same
  3221  *  thread that created the GL context.
  3222  */
  3223 DECLSPEC void MOJOSHADER_glDestroyContext(MOJOSHADER_glContext *ctx);
  3224 
  3225 #ifdef __cplusplus
  3226 }
  3227 #endif
  3228 
  3229 #endif  /* include-once blocker. */
  3230 
  3231 /* end of mojoshader.h ... */
  3232