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