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