mojoshader.h
author Ryan C. Gordon <icculus@icculus.org>
Tue, 24 May 2016 01:05:54 -0400
changeset 1160 24ee60c85ec3
parent 1150 02c0f0afb39a
permissions -rw-r--r--
metal: Group all uniform arrays into one struct with explicit array sizes.

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