/
mojoshader.h
2274 lines (2047 loc) · 83.5 KB
1
/**
2
3
* MojoShader; generate shader programs from bytecode of compiled
* Direct3D shaders.
4
5
6
7
8
9
*
* Please see the file LICENSE.txt in the source's root directory.
*
* This file written by Ryan C. Gordon.
*/
10
11
#ifndef _INCL_MOJOSHADER_H_
#define _INCL_MOJOSHADER_H_
12
13
14
15
16
#ifdef __cplusplus
extern "C" {
#endif
17
18
19
/* You can define this if you aren't generating mojoshader_version.h */
#ifndef MOJOSHADER_NO_VERSION_INCLUDE
#include "mojoshader_version.h"
20
21
22
#endif
#ifndef MOJOSHADER_VERSION
23
#define MOJOSHADER_VERSION -1
24
25
26
#endif
#ifndef MOJOSHADER_CHANGESET
27
28
29
#define MOJOSHADER_CHANGESET "???"
#endif
30
/*
31
32
33
34
35
* For determining the version of MojoShader you are using:
* const int compiled_against = MOJOSHADER_VERSION;
* const int linked_against = MOJOSHADER_version();
*
* The version is a single integer that increments, not a major/minor value.
36
*/
37
int MOJOSHADER_version(void);
38
39
/*
40
* For determining the revision control changeset of MojoShader you are using:
41
42
43
44
45
46
47
48
49
50
51
* const const *compiled_against = MOJOSHADER_CHANGESET;
* const char *linked_against = MOJOSHADER_changeset();
*
* The version is an arbitrary, null-terminated ASCII string. It is probably
* a hash that represents a revision control changeset, and can't be
* compared to any other string to determine chronology.
*
* Do not attempt to free this string; it's statically allocated.
*/
const char *MOJOSHADER_changeset(void);
52
53
/*
* These allocators work just like the C runtime's malloc() and free()
54
55
* (in fact, they probably use malloc() and free() internally if you don't
* specify your own allocator, but don't rely on that behaviour).
56
57
58
* (data) is the pointer you supplied when specifying these allocator
* callbacks, in case you need instance-specific data...it is passed through
* to your allocator unmolested, and can be NULL if you like.
59
*/
60
61
typedef void *(*MOJOSHADER_malloc)(int bytes, void *data);
typedef void (*MOJOSHADER_free)(void *ptr, void *data);
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
/*
* These are enum values, but they also can be used in bitmasks, so we can
* test if an opcode is acceptable: if (op->shader_types & ourtype) {} ...
*/
typedef enum
{
MOJOSHADER_TYPE_UNKNOWN = 0,
MOJOSHADER_TYPE_PIXEL = (1 << 0),
MOJOSHADER_TYPE_VERTEX = (1 << 1),
MOJOSHADER_TYPE_GEOMETRY = (1 << 2), /* (not supported yet.) */
MOJOSHADER_TYPE_ANY = 0xFFFFFFFF /* used for bitmasks */
} MOJOSHADER_shaderType;
77
78
79
80
81
/*
* Data types for vertex attribute streams.
*/
typedef enum
{
82
MOJOSHADER_ATTRIBUTE_UNKNOWN = -1, /* housekeeping; not returned. */
83
84
85
86
87
88
89
MOJOSHADER_ATTRIBUTE_BYTE,
MOJOSHADER_ATTRIBUTE_UBYTE,
MOJOSHADER_ATTRIBUTE_SHORT,
MOJOSHADER_ATTRIBUTE_USHORT,
MOJOSHADER_ATTRIBUTE_INT,
MOJOSHADER_ATTRIBUTE_UINT,
MOJOSHADER_ATTRIBUTE_FLOAT,
90
91
MOJOSHADER_ATTRIBUTE_DOUBLE,
MOJOSHADER_ATTRIBUTE_HALF_FLOAT, /* MAYBE available in your OpenGL! */
92
93
} MOJOSHADER_attributeType;
94
95
96
/*
* Data types for uniforms. See MOJOSHADER_uniform for more information.
*/
97
98
typedef enum
{
99
MOJOSHADER_UNIFORM_UNKNOWN = -1, /* housekeeping value; never returned. */
100
101
102
MOJOSHADER_UNIFORM_FLOAT,
MOJOSHADER_UNIFORM_INT,
MOJOSHADER_UNIFORM_BOOL,
103
} MOJOSHADER_uniformType;
104
105
106
107
108
109
110
111
/*
* These are the uniforms to be set for a shader. "Uniforms" are what Direct3D
* calls "Constants" ... IDirect3DDevice::SetVertexShaderConstantF() would
* need this data, for example. These integers are register indexes. So if
* index==6 and type==MOJOSHADER_UNIFORM_FLOAT, that means we'd expect a
* 4-float vector to be specified for what would be register "c6" in D3D
* assembly language, before drawing with the shader.
112
113
114
115
116
117
118
119
* (array_count) means this is an array of uniforms...this happens in some
* profiles when we see a relative address ("c0[a0.x]", not the usual "c0").
* In those cases, the shader was built to set some range of constant
* registers as an array. You should set this array with (array_count)
* elements from the constant register file, starting at (index) instead of
* just a single uniform. To be extra difficult, you'll need to fill in the
* correct values from the MOJOSHADER_constant data into the appropriate
* parts of the array, overriding the constant register file. Fun!
120
121
122
123
* (constant) says whether this is a constant array; these need to be loaded
* once at creation time, from the constant list and not ever updated from
* the constant register file. This is a workaround for limitations in some
* profiles.
124
125
* (name) is a profile-specific variable name; it may be NULL if it isn't
* applicable to the requested profile.
126
*/
127
typedef struct MOJOSHADER_uniform
128
{
129
MOJOSHADER_uniformType type;
130
int index;
131
int array_count;
132
int constant;
133
const char *name;
134
135
} MOJOSHADER_uniform;
136
137
138
139
140
141
142
143
144
145
146
/*
* These are the constants defined in a shader. These are data values
* hardcoded in a shader (with the DEF, DEFI, DEFB instructions), which
* override your Uniforms. This data is largely for informational purposes,
* since they are compiled in and can't be changed, like Uniforms can be.
* These integers are register indexes. So if index==6 and
* type==MOJOSHADER_UNIFORM_FLOAT, that means we'd expect a 4-float vector
* to be specified for what would be register "c6" in D3D assembly language,
* before drawing with the shader.
* (value) is the value of the constant, unioned by type.
*/
147
typedef struct MOJOSHADER_constant
148
149
150
151
152
153
154
155
156
157
158
{
MOJOSHADER_uniformType type;
int index;
union
{
float f[4]; /* if type==MOJOSHADER_UNIFORM_FLOAT */
int i[4]; /* if type==MOJOSHADER_UNIFORM_INT */
int b; /* if type==MOJOSHADER_UNIFORM_BOOL */
} value;
} MOJOSHADER_constant;
159
160
161
162
163
/*
* Data types for samplers. See MOJOSHADER_sampler for more information.
*/
typedef enum
{
164
MOJOSHADER_SAMPLER_UNKNOWN = -1, /* housekeeping value; never returned. */
165
166
167
168
169
170
171
172
173
174
175
176
MOJOSHADER_SAMPLER_2D,
MOJOSHADER_SAMPLER_CUBE,
MOJOSHADER_SAMPLER_VOLUME,
} MOJOSHADER_samplerType;
/*
* These are the samplers to be set for a shader. ...
* IDirect3DDevice::SetTexture() would need this data, for example.
* These integers are the sampler "stage". So if index==6 and
* type==MOJOSHADER_SAMPLER_2D, that means we'd expect a regular 2D texture
* to be specified for what would be register "s6" in D3D assembly language,
* before drawing with the shader.
177
178
* (name) is a profile-specific variable name; it may be NULL if it isn't
* applicable to the requested profile.
179
*/
180
typedef struct MOJOSHADER_sampler
181
182
183
{
MOJOSHADER_samplerType type;
int index;
184
const char *name;
185
186
} MOJOSHADER_sampler;
187
188
189
190
191
/*
* Data types for attributes. See MOJOSHADER_attribute for more information.
*/
typedef enum
{
192
MOJOSHADER_USAGE_UNKNOWN = -1, /* housekeeping value; never returned. */
193
194
195
196
197
198
199
200
201
202
203
204
205
206
MOJOSHADER_USAGE_POSITION,
MOJOSHADER_USAGE_BLENDWEIGHT,
MOJOSHADER_USAGE_BLENDINDICES,
MOJOSHADER_USAGE_NORMAL,
MOJOSHADER_USAGE_POINTSIZE,
MOJOSHADER_USAGE_TEXCOORD,
MOJOSHADER_USAGE_TANGENT,
MOJOSHADER_USAGE_BINORMAL,
MOJOSHADER_USAGE_TESSFACTOR,
MOJOSHADER_USAGE_POSITIONT,
MOJOSHADER_USAGE_COLOR,
MOJOSHADER_USAGE_FOG,
MOJOSHADER_USAGE_DEPTH,
MOJOSHADER_USAGE_SAMPLE,
207
MOJOSHADER_USAGE_TOTAL, /* housekeeping value; never returned. */
208
209
210
211
212
213
214
215
216
217
} MOJOSHADER_usage;
/*
* These are the attributes to be set for a shader. "Attributes" are what
* Direct3D calls "Vertex Declarations Usages" ...
* IDirect3DDevice::CreateVertexDeclaration() would need this data, for
* example. Each attribute is associated with an array of data that uses one
* element per-vertex. So if usage==MOJOSHADER_USAGE_COLOR and index==1, that
* means we'd expect a secondary color array to be bound to this shader
* before drawing.
218
219
* (name) is a profile-specific variable name; it may be NULL if it isn't
* applicable to the requested profile.
220
*/
221
typedef struct MOJOSHADER_attribute
222
223
224
{
MOJOSHADER_usage usage;
int index;
225
const char *name;
226
} MOJOSHADER_attribute;
227
228
229
230
231
232
233
/*
* Use this if you want to specify newly-parsed code to swizzle incoming
* data. This can be useful if you know, at parse time, that a shader
* will be processing data on COLOR0 that should be RGBA, but you'll
* be passing it a vertex array full of ARGB instead.
*/
234
typedef struct MOJOSHADER_swizzle
235
236
237
238
239
240
241
{
MOJOSHADER_usage usage;
unsigned int index;
unsigned char swizzles[4]; /* {0,1,2,3} == .xyzw, {2,2,2,2} == .zzzz */
} MOJOSHADER_swizzle;
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
/*
* MOJOSHADER_symbol data.
*
* These are used to expose high-level information in shader bytecode.
* They associate HLSL variables with registers. This data is used for both
* debugging and optimization.
*/
typedef enum
{
MOJOSHADER_SYMREGSET_BOOL,
MOJOSHADER_SYMREGSET_INT4,
MOJOSHADER_SYMREGSET_FLOAT4,
MOJOSHADER_SYMREGSET_SAMPLER,
} MOJOSHADER_symbolRegisterSet;
typedef enum
{
MOJOSHADER_SYMCLASS_SCALAR,
MOJOSHADER_SYMCLASS_VECTOR,
MOJOSHADER_SYMCLASS_MATRIX_ROWS,
MOJOSHADER_SYMCLASS_MATRIX_COLUMNS,
MOJOSHADER_SYMCLASS_OBJECT,
MOJOSHADER_SYMCLASS_STRUCT,
} MOJOSHADER_symbolClass;
typedef enum
{
MOJOSHADER_SYMTYPE_VOID,
MOJOSHADER_SYMTYPE_BOOL,
MOJOSHADER_SYMTYPE_INT,
MOJOSHADER_SYMTYPE_FLOAT,
MOJOSHADER_SYMTYPE_STRING,
MOJOSHADER_SYMTYPE_TEXTURE,
MOJOSHADER_SYMTYPE_TEXTURE1D,
MOJOSHADER_SYMTYPE_TEXTURE2D,
MOJOSHADER_SYMTYPE_TEXTURE3D,
MOJOSHADER_SYMTYPE_TEXTURECUBE,
MOJOSHADER_SYMTYPE_SAMPLER,
MOJOSHADER_SYMTYPE_SAMPLER1D,
MOJOSHADER_SYMTYPE_SAMPLER2D,
MOJOSHADER_SYMTYPE_SAMPLER3D,
MOJOSHADER_SYMTYPE_SAMPLERCUBE,
MOJOSHADER_SYMTYPE_PIXELSHADER,
MOJOSHADER_SYMTYPE_VERTEXSHADER,
MOJOSHADER_SYMTYPE_PIXELFRAGMENT,
MOJOSHADER_SYMTYPE_VERTEXFRAGMENT,
MOJOSHADER_SYMTYPE_UNSUPPORTED,
} MOJOSHADER_symbolType;
typedef struct MOJOSHADER_symbolStructMember MOJOSHADER_symbolStructMember;
typedef struct MOJOSHADER_symbolTypeInfo
{
MOJOSHADER_symbolClass parameter_class;
MOJOSHADER_symbolType parameter_type;
unsigned int rows;
unsigned int columns;
unsigned int elements;
unsigned int member_count;
MOJOSHADER_symbolStructMember *members;
} MOJOSHADER_symbolTypeInfo;
struct MOJOSHADER_symbolStructMember
{
const char *name;
MOJOSHADER_symbolTypeInfo info;
};
typedef struct MOJOSHADER_symbol
{
const char *name;
MOJOSHADER_symbolRegisterSet register_set;
unsigned int register_index;
unsigned int register_count;
MOJOSHADER_symbolTypeInfo info;
void *default_value;
} MOJOSHADER_symbol;
322
typedef struct MOJOSHADER_error
323
324
325
326
327
328
329
330
{
/*
* Human-readable error, if there is one. Will be NULL if there was no
* error. The string will be UTF-8 encoded, and English only. Most of
* these shouldn't be shown to the end-user anyhow.
*/
const char *error;
331
/*
332
333
* Filename where error happened. This can be NULL if the information
* isn't available.
334
335
336
*/
const char *filename;
337
338
339
340
/*
* Position of error, if there is one. Will be -3 if there was no
* error, -2 if there was an error before processing started, and
* -1 if there was an error during final processing. If >= 0,
341
342
* MOJOSHADER_parse() sets this to the byte offset (starting at zero) into
* the bytecode you supplied, and MOJOSHADER_assemble() sets this to a
343
* a line number in the source code you supplied (starting at one).
344
345
*/
int error_position;
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
} MOJOSHADER_error;
/*
* Structure used to return data from parsing of a shader...
*/
/* !!! FIXME: most of these ints should be unsigned. */
typedef struct MOJOSHADER_parseData
{
/*
* The number of elements pointed to by (errors).
*/
int error_count;
/*
* (error_count) elements of data that specify errors that were generated
* by parsing this shader.
* This can be NULL if there were no errors or if (error_count) is zero.
*/
MOJOSHADER_error *errors;
365
366
367
368
369
370
/*
* The name of the profile used to parse the shader. Will be NULL on error.
*/
const char *profile;
371
372
373
374
375
376
377
378
379
/*
* Bytes of output from parsing. Most profiles produce a string of source
* code, but profiles that do binary output may not be text at all.
* Will be NULL on error.
*/
const char *output;
/*
* Byte count for output, not counting any null terminator. Most profiles
380
381
382
* produce an ASCII string of source code (which will be null-terminated
* even though that null char isn't included in output_len), but profiles
* that do binary output may not be text at all. Will be 0 on error.
383
384
385
386
*/
int output_len;
/*
387
* Count of Direct3D instruction slots used. This is meaningless in terms
388
389
* of the actual output, as the profile will probably grow or reduce
* the count (or for high-level languages, not have that information at
390
391
392
393
* all). Also, as with Microsoft's own assembler, this value is just a
* rough estimate, as unpredicable real-world factors make the actual
* value vary at least a little from this count. Still, it can give you
* a rough idea of the size of your shader. Will be zero on error.
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
*/
int instruction_count;
/*
* The type of shader we parsed. Will be MOJOSHADER_TYPE_UNKNOWN on error.
*/
MOJOSHADER_shaderType shader_type;
/*
* The shader's major version. If this was a "vs_3_0", this would be 3.
*/
int major_ver;
/*
* The shader's minor version. If this was a "ps_1_4", this would be 4.
* Two notes: for "vs_2_x", this is 1, and for "vs_3_sw", this is 255.
*/
int minor_ver;
413
414
415
416
417
418
/*
* The number of elements pointed to by (uniforms).
*/
int uniform_count;
/*
419
420
* (uniform_count) elements of data that specify Uniforms to be set for
* this shader. See discussion on MOJOSHADER_uniform for details.
421
* This can be NULL on error or if (uniform_count) is zero.
422
423
424
*/
MOJOSHADER_uniform *uniforms;
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
/*
* The number of elements pointed to by (constants).
*/
int constant_count;
/*
* (constant_count) elements of data that specify constants used in
* this shader. See discussion on MOJOSHADER_constant for details.
* This can be NULL on error or if (constant_count) is zero.
* This is largely informational: constants are hardcoded into a shader.
* The constants that you can set like parameters are in the "uniforms"
* list.
*/
MOJOSHADER_constant *constants;
440
441
442
443
444
445
446
447
448
449
450
451
/*
* The number of elements pointed to by (samplers).
*/
int sampler_count;
/*
* (sampler_count) elements of data that specify Samplers to be set for
* this shader. See discussion on MOJOSHADER_sampler for details.
* This can be NULL on error or if (sampler_count) is zero.
*/
MOJOSHADER_sampler *samplers;
452
453
454
455
456
457
458
459
/*
* The number of elements pointed to by (attributes).
*/
int attribute_count;
/*
* (attribute_count) elements of data that specify Attributes to be set
* for this shader. See discussion on MOJOSHADER_attribute for details.
460
* This can be NULL on error or if (attribute_count) is zero.
461
462
463
*/
MOJOSHADER_attribute *attributes;
464
465
466
467
468
469
470
471
472
473
474
475
476
/*
* The number of elements pointed to by (swizzles).
*/
int swizzle_count;
/*
* (swizzle_count) elements of data that specify swizzles the shader will
* apply to incoming attributes. This is a copy of what was passed to
* MOJOSHADER_parseData().
* This can be NULL on error or if (swizzle_count) is zero.
*/
MOJOSHADER_swizzle *swizzles;
477
478
479
480
481
482
483
484
485
486
487
488
489
490
/*
* The number of elements pointed to by (symbols).
*/
int symbol_count;
/*
* (symbol_count) elements of data that specify high-level symbol data
* for the shader. This will be parsed from the CTAB section
* in bytecode, and will be a copy of what you provide to
* MOJOSHADER_assemble(). This data is optional.
* This can be NULL on error or if (symbol_count) is zero.
*/
MOJOSHADER_symbol *symbols;
491
492
493
494
495
496
497
498
499
/*
* This is the malloc implementation you passed to MOJOSHADER_parse().
*/
MOJOSHADER_malloc malloc;
/*
* This is the free implementation you passed to MOJOSHADER_parse().
*/
MOJOSHADER_free free;
500
501
502
503
504
/*
* This is the pointer you passed as opaque data for your allocator.
*/
void *malloc_data;
505
506
507
508
509
510
511
512
} MOJOSHADER_parseData;
/*
* Profile string for Direct3D assembly language output.
*/
#define MOJOSHADER_PROFILE_D3D "d3d"
513
514
515
/*
* Profile string for passthrough of the original bytecode, unchanged.
*/
516
#define MOJOSHADER_PROFILE_BYTECODE "bytecode"
517
518
519
520
521
522
/*
* Profile string for GLSL: OpenGL high-level shader language output.
*/
#define MOJOSHADER_PROFILE_GLSL "glsl"
523
524
525
526
527
/*
* Profile string for GLSL 1.20: minor improvements to base GLSL spec.
*/
#define MOJOSHADER_PROFILE_GLSL120 "glsl120"
528
529
530
531
532
/*
* Profile string for OpenGL ARB 1.0 shaders: GL_ARB_(vertex|fragment)_program.
*/
#define MOJOSHADER_PROFILE_ARB1 "arb1"
533
534
535
536
537
538
539
540
541
542
/*
* Profile string for OpenGL ARB 1.0 shaders with Nvidia 2.0 extensions:
* GL_NV_vertex_program2_option and GL_NV_fragment_program2
*/
#define MOJOSHADER_PROFILE_NV2 "nv2"
/*
* Profile string for OpenGL ARB 1.0 shaders with Nvidia 3.0 extensions:
* GL_NV_vertex_program3 and GL_NV_fragment_program2
*/
543
#define MOJOSHADER_PROFILE_NV3 "nv3"
544
545
546
/*
* Profile string for OpenGL ARB 1.0 shaders with Nvidia 4.0 extensions:
547
* GL_NV_gpu_program4
548
*/
549
#define MOJOSHADER_PROFILE_NV4 "nv4"
550
551
552
553
554
555
/*
* Determine the highest supported Shader Model for a profile.
*/
int MOJOSHADER_maxShaderModel(const char *profile);
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
/*
* Parse a compiled Direct3D shader's bytecode.
*
* This is your primary entry point into MojoShader. You need to pass it
* a compiled D3D shader and tell it which "profile" you want to use to
* convert it into useful data.
*
* The available profiles are the set of MOJOSHADER_PROFILE_* defines.
* Note that MojoShader may be built without support for all listed
* profiles (in which case using one here will return with an error).
*
* As parsing requires some memory to be allocated, you may provide a custom
* allocator to this function, which will be used to allocate/free memory.
* They function just like malloc() and free(). We do not use realloc().
571
572
573
* If you don't care, pass NULL in for the allocator functions. If your
* allocator needs instance-specific data, you may supply it with the
* (d) parameter. This pointer is passed as-is to your (m) and (f) functions.
574
*
575
* This function returns a MOJOSHADER_parseData.
576
577
578
579
580
581
*
* This function will never return NULL, even if the system is completely
* out of memory upon entry (in which case, this function returns a static
* MOJOSHADER_parseData object, which is still safe to pass to
* MOJOSHADER_freeParseData()).
*
582
583
584
585
586
587
* You can tell the generated program to swizzle certain inputs. If you know
* that COLOR0 should be RGBA but you're passing in ARGB, you can specify
* a swizzle of { MOJOSHADER_USAGE_COLOR, 0, {1,2,3,0} } to (swiz). If the
* input register in the code would produce reg.ywzx, that swizzle would
* change it to reg.wzxy ... (swiz) can be NULL.
*
588
* This function is thread safe, so long as (m) and (f) are too, and that
589
590
591
592
593
594
* (tokenbuf) remains intact for the duration of the call. This allows you
* to parse several shaders on separate CPU cores at the same time.
*/
const MOJOSHADER_parseData *MOJOSHADER_parse(const char *profile,
const unsigned char *tokenbuf,
const unsigned int bufsize,
595
596
const MOJOSHADER_swizzle *swiz,
const unsigned int swizcount,
597
MOJOSHADER_malloc m,
598
599
MOJOSHADER_free f,
void *d);
600
601
602
603
604
605
606
607
608
609
610
/*
* Call this to dispose of parsing results when you are done with them.
* This will call the MOJOSHADER_free function you provided to
* MOJOSHADER_parse multiple times, if you provided one.
* Passing a NULL here is a safe no-op.
*
* This function is thread safe, so long as any allocator you passed into
* MOJOSHADER_parse() is, too.
*/
void MOJOSHADER_freeParseData(const MOJOSHADER_parseData *data);
611
612
613
614
615
616
617
/* Preprocessor interface... */
/*
* Structure used to pass predefined macros. Maps to D3DXMACRO.
618
* You can have macro arguments: set identifier to "a(b, c)" or whatever.
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
*/
typedef struct MOJOSHADER_preprocessorDefine
{
const char *identifier;
const char *definition;
} MOJOSHADER_preprocessorDefine;
/*
* Used with the MOJOSHADER_includeOpen callback. Maps to D3DXINCLUDE_TYPE.
*/
typedef enum
{
MOJOSHADER_INCLUDETYPE_LOCAL, /* local header: #include "blah.h" */
MOJOSHADER_INCLUDETYPE_SYSTEM /* system header: #include <blah.h> */
} MOJOSHADER_includeType;
/*
* Structure used to return data from preprocessing of a shader...
*/
/* !!! FIXME: most of these ints should be unsigned. */
typedef struct MOJOSHADER_preprocessData
{
/*
* The number of elements pointed to by (errors).
*/
int error_count;
/*
* (error_count) elements of data that specify errors that were generated
* by parsing this shader.
* This can be NULL if there were no errors or if (error_count) is zero.
*/
MOJOSHADER_error *errors;
/*
655
* Bytes of output from preprocessing. This is a UTF-8 string. We
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
* guarantee it to be NULL-terminated. Will be NULL on error.
*/
const char *output;
/*
* Byte count for output, not counting any null terminator.
* Will be 0 on error.
*/
int output_len;
/*
* This is the malloc implementation you passed to MOJOSHADER_parse().
*/
MOJOSHADER_malloc malloc;
/*
* This is the free implementation you passed to MOJOSHADER_parse().
*/
MOJOSHADER_free free;
/*
* This is the pointer you passed as opaque data for your allocator.
*/
void *malloc_data;
} MOJOSHADER_preprocessData;
/*
* This callback allows an app to handle #include statements for the
* preprocessor. When the preprocessor sees an #include, it will call this
* function to obtain the contents of the requested file. This is optional;
687
* the preprocessor will open files directly if no callback is supplied, but
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
* this allows an app to retrieve data from something other than the
* traditional filesystem (for example, headers packed in a .zip file or
* headers generated on-the-fly).
*
* This function maps to ID3DXInclude::Open()
*
* (inctype) specifies the type of header we wish to include.
* (fname) specifies the name of the file specified on the #include line.
* (parent) is a string of the entire source file containing the include, in
* its original, not-yet-preprocessed state. Note that this is just the
* contents of the specific file, not all source code that the preprocessor
* has seen through other includes, etc.
* (outdata) will be set by the callback to a pointer to the included file's
* contents. The callback is responsible for allocating this however they
* see fit (we provide allocator functions, but you may ignore them). This
* pointer must remain valid until the includeClose callback runs. This
* string does not need to be NULL-terminated.
* (outbytes) will be set by the callback to the number of bytes pointed to
* by (outdata).
* (m),(f), and (d) are the allocator details that the application passed to
* MojoShader. If these were NULL, MojoShader may have replaced them with its
* own internal allocators.
*
* The callback returns zero on error, non-zero on success.
*
* If you supply an includeOpen callback, you must supply includeClose, too.
*/
typedef int (*MOJOSHADER_includeOpen)(MOJOSHADER_includeType inctype,
const char *fname, const char *parent,
const char **outdata, unsigned int *outbytes,
MOJOSHADER_malloc m, MOJOSHADER_free f, void *d);
/*
* This callback allows an app to clean up the results of a previous
* includeOpen callback.
*
* This function maps to ID3DXInclude::Close()
*
* (data) is the data that was returned from a previous call to includeOpen.
* It is now safe to deallocate this data.
* (m),(f), and (d) are the same allocator details that were passed to your
* includeOpen callback.
*
* If you supply an includeClose callback, you must supply includeOpen, too.
*/
typedef void (*MOJOSHADER_includeClose)(const char *data,
MOJOSHADER_malloc m, MOJOSHADER_free f, void *d);
/*
* This function is optional. Even if you are dealing with shader source
* code, you don't need to explicitly use the preprocessor, as the compiler
* and assembler will use it behind the scenes. In fact, you probably never
* need this function unless you are debugging a custom tool (or debugging
* MojoShader itself).
*
* Preprocessing roughly follows the syntax of an ANSI C preprocessor, as
* Microsoft's Direct3D assembler and HLSL compiler use this syntax. Please
* note that we try to match the output you'd get from Direct3D's
* preprocessor, which has some quirks if you're expecting output that matches
* a generic C preprocessor.
*
* This function maps to D3DXPreprocessShader().
*
752
753
754
755
756
757
758
759
* (filename) is a NULL-terminated UTF-8 filename. It can be NULL. We do not
* actually access this file, as we obtain our data from (source). This
* string is copied when we need to report errors while processing (source),
* as opposed to errors in a file referenced via the #include directive in
* (source). If this is NULL, then errors will report the filename as NULL,
* too.
*
* (source) is an string of UTF-8 text to preprocess. It does not need to be
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
* NULL-terminated.
*
* (sourcelen) is the length of the string pointed to by (source), in bytes.
*
* (defines) points to (define_count) preprocessor definitions, and can be
* NULL. These are treated by the preprocessor as if the source code started
* with one #define for each entry you pass in here.
*
* (include_open) and (include_close) let the app control the preprocessor's
* behaviour for #include statements. Both are optional and can be NULL, but
* both must be specified if either is specified.
*
* This will return a MOJOSHADER_preprocessorData. You should pass this
* return value to MOJOSHADER_freePreprocessData() when you are done with
* it.
*
* This function will never return NULL, even if the system is completely
* out of memory upon entry (in which case, this function returns a static
* MOJOSHADER_preprocessData object, which is still safe to pass to
* MOJOSHADER_freePreprocessData()).
*
* As preprocessing requires some memory to be allocated, you may provide a
* custom allocator to this function, which will be used to allocate/free
* memory. They function just like malloc() and free(). We do not use
* realloc(). If you don't care, pass NULL in for the allocator functions.
* If your allocator needs instance-specific data, you may supply it with the
* (d) parameter. This pointer is passed as-is to your (m) and (f) functions.
*
* This function is thread safe, so long as the various callback functions
* are, too, and that the parameters remains intact for the duration of the
* call. This allows you to preprocess several shaders on separate CPU cores
* at the same time.
*/
793
794
const MOJOSHADER_preprocessData *MOJOSHADER_preprocess(const char *filename,
const char *source, unsigned int sourcelen,
795
const MOJOSHADER_preprocessorDefine *defines,
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
unsigned int define_count,
MOJOSHADER_includeOpen include_open,
MOJOSHADER_includeClose include_close,
MOJOSHADER_malloc m, MOJOSHADER_free f, void *d);
/*
* Call this to dispose of preprocessing results when you are done with them.
* This will call the MOJOSHADER_free function you provided to
* MOJOSHADER_preprocess() multiple times, if you provided one.
* Passing a NULL here is a safe no-op.
*
* This function is thread safe, so long as any allocator you passed into
* MOJOSHADER_preprocess() is, too.
*/
void MOJOSHADER_freePreprocessData(const MOJOSHADER_preprocessData *data);
814
815
816
817
818
819
/* Assembler interface... */
/*
* This function is optional. Use this to convert Direct3D shader assembly
* language into bytecode, which can be handled by MOJOSHADER_parse().
*
820
821
822
823
824
825
826
827
* (filename) is a NULL-terminated UTF-8 filename. It can be NULL. We do not
* actually access this file, as we obtain our data from (source). This
* string is copied when we need to report errors while processing (source),
* as opposed to errors in a file referenced via the #include directive in
* (source). If this is NULL, then errors will report the filename as NULL,
* too.
*
* (source) is an UTF-8 string of valid Direct3D shader assembly source code.
828
829
830
* It does not need to be NULL-terminated.
*
* (sourcelen) is the length of the string pointed to by (source), in bytes.
831
*
832
* (comments) points to (comment_count) NULL-terminated UTF-8 strings, and
833
834
835
836
837
838
839
840
841
842
* can be NULL. These strings are inserted as comments in the bytecode.
*
* (symbols) points to (symbol_count) symbol structs, and can be NULL. These
* become a CTAB field in the bytecode. This is optional, but
* MOJOSHADER_parse() needs CTAB data for all arrays used in a program, or
* relative addressing will not be permitted, so you'll want to at least
* provide symbol information for those. The symbol data is 100% trusted
* at this time; it will not be checked to see if it matches what was
* assembled in any way whatsoever.
*
843
844
845
846
847
848
849
850
851
* (defines) points to (define_count) preprocessor definitions, and can be
* NULL. These are treated by the preprocessor as if the source code started
* with one #define for each entry you pass in here.
*
* (include_open) and (include_close) let the app control the preprocessor's
* behaviour for #include statements. Both are optional and can be NULL, but
* both must be specified if either is specified.
*
* This will return a MOJOSHADER_parseData, like MOJOSHADER_parse() would,
852
853
854
855
856
857
858
859
860
* except the profile will be MOJOSHADER_PROFILE_BYTECODE and the output
* will be the assembled bytecode instead of some other language. This output
* can be pushed back through MOJOSHADER_parseData() with a different profile.
*
* This function will never return NULL, even if the system is completely
* out of memory upon entry (in which case, this function returns a static
* MOJOSHADER_parseData object, which is still safe to pass to
* MOJOSHADER_freeParseData()).
*
861
862
863
864
865
866
867
* As assembling requires some memory to be allocated, you may provide a
* custom allocator to this function, which will be used to allocate/free
* memory. They function just like malloc() and free(). We do not use
* realloc(). If you don't care, pass NULL in for the allocator functions.
* If your allocator needs instance-specific data, you may supply it with the
* (d) parameter. This pointer is passed as-is to your (m) and (f) functions.
*
868
869
870
871
* This function is thread safe, so long as the various callback functions
* are, too, and that the parameters remains intact for the duration of the
* call. This allows you to assemble several shaders on separate CPU cores
* at the same time.
872
*/
873
874
const MOJOSHADER_parseData *MOJOSHADER_assemble(const char *filename,
const char *source, unsigned int sourcelen,
875
876
877
const char **comments, unsigned int comment_count,
const MOJOSHADER_symbol *symbols,
unsigned int symbol_count,
878
const MOJOSHADER_preprocessorDefine *defines,
879
880
881
unsigned int define_count,
MOJOSHADER_includeOpen include_open,
MOJOSHADER_includeClose include_close,
882
MOJOSHADER_malloc m, MOJOSHADER_free f, void *d);
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/* High level shading language support... */
/*
* Source profile strings for HLSL: Direct3D High Level Shading Language.
*/
#define MOJOSHADER_SRC_PROFILE_HLSL_VS_1_1 "hlsl_vs_1_1"
#define MOJOSHADER_SRC_PROFILE_HLSL_VS_2_0 "hlsl_vs_2_0"
#define MOJOSHADER_SRC_PROFILE_HLSL_VS_3_0 "hlsl_vs_3_0"
#define MOJOSHADER_SRC_PROFILE_HLSL_PS_1_1 "hlsl_ps_1_1"
#define MOJOSHADER_SRC_PROFILE_HLSL_PS_1_2 "hlsl_ps_1_2"
#define MOJOSHADER_SRC_PROFILE_HLSL_PS_1_3 "hlsl_ps_1_3"
#define MOJOSHADER_SRC_PROFILE_HLSL_PS_1_4 "hlsl_ps_1_4"
#define MOJOSHADER_SRC_PROFILE_HLSL_PS_2_0 "hlsl_ps_2_0"
#define MOJOSHADER_SRC_PROFILE_HLSL_PS_3_0 "hlsl_ps_3_0"
/* Abstract Syntax Tree interface... */
/*
* ATTENTION: This adds a lot of stuff to the API, but almost everyone can
* ignore this section. Seriously, go ahead and skip over anything that has
* "AST" in it, unless you know why you'd want to use it.
*
* ALSO: This API is still evolving! We make no promises at this time to keep
* source or binary compatibility for the AST pieces.
*/
/* Structures that make up the parse tree... */
typedef enum MOJOSHADER_astNodeType
{
MOJOSHADER_AST_OP_START_RANGE, /* expression operators. */
MOJOSHADER_AST_OP_START_RANGE_UNARY, /* unary operators. */
MOJOSHADER_AST_OP_PREINCREMENT,
MOJOSHADER_AST_OP_PREDECREMENT,
MOJOSHADER_AST_OP_NEGATE,
MOJOSHADER_AST_OP_COMPLEMENT,
MOJOSHADER_AST_OP_NOT,
MOJOSHADER_AST_OP_POSTINCREMENT,
MOJOSHADER_AST_OP_POSTDECREMENT,
MOJOSHADER_AST_OP_END_RANGE_UNARY,
MOJOSHADER_AST_OP_START_RANGE_BINARY, /* binary operators. */
MOJOSHADER_AST_OP_COMMA,
MOJOSHADER_AST_OP_MULTIPLY,
MOJOSHADER_AST_OP_DIVIDE,
MOJOSHADER_AST_OP_MODULO,
MOJOSHADER_AST_OP_ADD,
MOJOSHADER_AST_OP_SUBTRACT,
MOJOSHADER_AST_OP_LSHIFT,
MOJOSHADER_AST_OP_RSHIFT,
MOJOSHADER_AST_OP_LESSTHAN,
MOJOSHADER_AST_OP_GREATERTHAN,
MOJOSHADER_AST_OP_LESSTHANOREQUAL,
MOJOSHADER_AST_OP_GREATERTHANOREQUAL,
MOJOSHADER_AST_OP_EQUAL,
MOJOSHADER_AST_OP_NOTEQUAL,
MOJOSHADER_AST_OP_BINARYAND,
MOJOSHADER_AST_OP_BINARYXOR,
MOJOSHADER_AST_OP_BINARYOR,
MOJOSHADER_AST_OP_LOGICALAND,
MOJOSHADER_AST_OP_LOGICALOR,
MOJOSHADER_AST_OP_ASSIGN,
MOJOSHADER_AST_OP_MULASSIGN,
MOJOSHADER_AST_OP_DIVASSIGN,
MOJOSHADER_AST_OP_MODASSIGN,
MOJOSHADER_AST_OP_ADDASSIGN,
MOJOSHADER_AST_OP_SUBASSIGN,
MOJOSHADER_AST_OP_LSHIFTASSIGN,
MOJOSHADER_AST_OP_RSHIFTASSIGN,
MOJOSHADER_AST_OP_ANDASSIGN,
MOJOSHADER_AST_OP_XORASSIGN,
MOJOSHADER_AST_OP_ORASSIGN,
MOJOSHADER_AST_OP_DEREF_ARRAY,
MOJOSHADER_AST_OP_END_RANGE_BINARY,
MOJOSHADER_AST_OP_START_RANGE_TERNARY, /* ternary operators. */
MOJOSHADER_AST_OP_CONDITIONAL,
MOJOSHADER_AST_OP_END_RANGE_TERNARY,
MOJOSHADER_AST_OP_START_RANGE_DATA, /* expression operands. */
MOJOSHADER_AST_OP_IDENTIFIER,
MOJOSHADER_AST_OP_INT_LITERAL,
MOJOSHADER_AST_OP_FLOAT_LITERAL,
MOJOSHADER_AST_OP_STRING_LITERAL,
MOJOSHADER_AST_OP_BOOLEAN_LITERAL,
MOJOSHADER_AST_OP_END_RANGE_DATA,
MOJOSHADER_AST_OP_START_RANGE_MISC, /* other expression things. */
MOJOSHADER_AST_OP_DEREF_STRUCT,
MOJOSHADER_AST_OP_CALLFUNC,
MOJOSHADER_AST_OP_CONSTRUCTOR,
MOJOSHADER_AST_OP_CAST,
MOJOSHADER_AST_OP_END_RANGE_MISC,
MOJOSHADER_AST_OP_END_RANGE,
MOJOSHADER_AST_COMPUNIT_START_RANGE, /* things in global scope. */
MOJOSHADER_AST_COMPUNIT_FUNCTION,
MOJOSHADER_AST_COMPUNIT_TYPEDEF,
MOJOSHADER_AST_COMPUNIT_STRUCT,
MOJOSHADER_AST_COMPUNIT_VARIABLE,
MOJOSHADER_AST_COMPUNIT_END_RANGE,
MOJOSHADER_AST_STATEMENT_START_RANGE, /* statements in function scope. */
MOJOSHADER_AST_STATEMENT_EMPTY,
MOJOSHADER_AST_STATEMENT_BREAK,
MOJOSHADER_AST_STATEMENT_CONTINUE,
MOJOSHADER_AST_STATEMENT_DISCARD,
MOJOSHADER_AST_STATEMENT_BLOCK,
MOJOSHADER_AST_STATEMENT_EXPRESSION,
MOJOSHADER_AST_STATEMENT_IF,
MOJOSHADER_AST_STATEMENT_SWITCH,
MOJOSHADER_AST_STATEMENT_FOR,
MOJOSHADER_AST_STATEMENT_DO,
MOJOSHADER_AST_STATEMENT_WHILE,