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