mojoshader.h
author Ryan C. Gordon <icculus@icculus.org>
Thu, 02 Oct 2014 15:54:31 -0400
changeset 1142 7b554e065321
parent 1112 ef76d5efedcc
permissions -rw-r--r--
Allow multiline comments before preprocessor directives.

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