/
mojoshader.h
3235 lines (2919 loc) · 120 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
36
37
38
39
40
41
42
43
44
45
#ifndef DECLSPEC
#ifdef _WIN32
#define DECLSPEC __declspec(dllexport)
#else
#define DECLSPEC
#endif
#endif
#ifndef MOJOSHADERCALL
#ifdef _WIN32
#define MOJOSHADERCALL __stdcall
#else
#define MOJOSHADERCALL
#endif
#endif
46
/*
47
48
49
50
51
* 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.
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
59
60
61
62
63
64
65
* 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.
*/
66
DECLSPEC const char *MOJOSHADER_changeset(void);
67
68
69
/*
* These allocators work just like the C runtime's malloc() and free()
70
71
* (in fact, they probably use malloc() and free() internally if you don't
* specify your own allocator, but don't rely on that behaviour).
72
73
74
* (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.
75
*/
76
77
typedef void *(MOJOSHADERCALL *MOJOSHADER_malloc)(int bytes, void *data);
typedef void (MOJOSHADERCALL *MOJOSHADER_free)(void *ptr, void *data);
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
/*
* 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;
93
94
95
96
97
/*
* Data types for vertex attribute streams.
*/
typedef enum
{
98
MOJOSHADER_ATTRIBUTE_UNKNOWN = -1, /* housekeeping; not returned. */
99
100
101
102
103
104
105
MOJOSHADER_ATTRIBUTE_BYTE,
MOJOSHADER_ATTRIBUTE_UBYTE,
MOJOSHADER_ATTRIBUTE_SHORT,
MOJOSHADER_ATTRIBUTE_USHORT,
MOJOSHADER_ATTRIBUTE_INT,
MOJOSHADER_ATTRIBUTE_UINT,
MOJOSHADER_ATTRIBUTE_FLOAT,
106
107
MOJOSHADER_ATTRIBUTE_DOUBLE,
MOJOSHADER_ATTRIBUTE_HALF_FLOAT, /* MAYBE available in your OpenGL! */
108
109
} MOJOSHADER_attributeType;
110
111
112
/*
* Data types for uniforms. See MOJOSHADER_uniform for more information.
*/
113
114
typedef enum
{
115
MOJOSHADER_UNIFORM_UNKNOWN = -1, /* housekeeping value; never returned. */
116
117
118
MOJOSHADER_UNIFORM_FLOAT,
MOJOSHADER_UNIFORM_INT,
MOJOSHADER_UNIFORM_BOOL,
119
} MOJOSHADER_uniformType;
120
121
122
123
124
125
126
127
/*
* 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.
128
129
130
131
132
133
134
135
* (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!
136
137
138
139
* (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.
140
141
* (name) is a profile-specific variable name; it may be NULL if it isn't
* 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
151
} MOJOSHADER_uniform;
152
153
154
155
156
157
158
159
160
161
162
/*
* 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.
*/
163
typedef struct MOJOSHADER_constant
164
165
166
167
168
169
170
171
172
173
174
{
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;
175
176
177
178
179
/*
* Data types for samplers. See MOJOSHADER_sampler for more information.
*/
typedef enum
{
180
MOJOSHADER_SAMPLER_UNKNOWN = -1, /* housekeeping value; never returned. */
181
182
183
184
185
186
187
188
189
190
191
192
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.
193
194
* (name) is a profile-specific variable name; it may be NULL if it isn't
* applicable to the requested profile.
195
196
197
198
199
* (texbem) will be non-zero if a TEXBEM opcode references this sampler. This
* is only used in legacy shaders (ps_1_1 through ps_1_3), but it needs some
* special support to work, as we have to load a magic uniform behind the
* scenes to support it. Most code can ignore this field in general, and no
* one has to touch it unless they really know what they're doing.
200
*/
201
typedef struct MOJOSHADER_sampler
202
203
204
{
MOJOSHADER_samplerType type;
int index;
205
const char *name;
206
int texbem;
207
208
} MOJOSHADER_sampler;
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
/*
* This struct is used if you have to force a sampler to a specific type.
* Generally, you can ignore this, but if you have, say, a ps_1_1
* shader, you might need to specify what the samplers are meant to be
* to get correct results, as Shader Model 1 samples textures according
* to what is bound to a sampler at the moment instead of what the shader
* is hardcoded to expect.
*/
typedef struct MOJOSHADER_samplerMap
{
int index;
MOJOSHADER_samplerType type;
} MOJOSHADER_samplerMap;
224
225
226
227
228
/*
* Data types for attributes. See MOJOSHADER_attribute for more information.
*/
typedef enum
{
229
MOJOSHADER_USAGE_UNKNOWN = -1, /* housekeeping value; never returned. */
230
231
232
233
234
235
236
237
238
239
240
241
242
243
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,
244
MOJOSHADER_USAGE_TOTAL /* housekeeping value; never returned. */
245
246
247
248
249
250
251
252
253
254
} 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.
255
256
* (name) is a profile-specific variable name; it may be NULL if it isn't
* applicable to the requested profile.
257
*/
258
typedef struct MOJOSHADER_attribute
259
260
261
{
MOJOSHADER_usage usage;
int index;
262
const char *name;
263
} MOJOSHADER_attribute;
264
265
266
267
268
269
270
/*
* 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.
*/
271
typedef struct MOJOSHADER_swizzle
272
273
274
275
276
277
278
{
MOJOSHADER_usage usage;
unsigned int index;
unsigned char swizzles[4]; /* {0,1,2,3} == .xyzw, {2,2,2,2} == .zzzz */
} MOJOSHADER_swizzle;
279
280
281
282
283
284
285
286
287
288
/*
* 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
{
289
MOJOSHADER_SYMREGSET_BOOL=0,
290
291
292
MOJOSHADER_SYMREGSET_INT4,
MOJOSHADER_SYMREGSET_FLOAT4,
MOJOSHADER_SYMREGSET_SAMPLER,
293
MOJOSHADER_SYMREGSET_TOTAL /* housekeeping value; never returned. */
294
295
296
297
} MOJOSHADER_symbolRegisterSet;
typedef enum
{
298
MOJOSHADER_SYMCLASS_SCALAR=0,
299
300
301
302
303
MOJOSHADER_SYMCLASS_VECTOR,
MOJOSHADER_SYMCLASS_MATRIX_ROWS,
MOJOSHADER_SYMCLASS_MATRIX_COLUMNS,
MOJOSHADER_SYMCLASS_OBJECT,
MOJOSHADER_SYMCLASS_STRUCT,
304
MOJOSHADER_SYMCLASS_TOTAL /* housekeeping value; never returned. */
305
306
307
308
} MOJOSHADER_symbolClass;
typedef enum
{
309
MOJOSHADER_SYMTYPE_VOID=0,
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
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,
329
MOJOSHADER_SYMTYPE_TOTAL /* housekeeping value; never returned. */
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
} 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;
} MOJOSHADER_symbol;
361
362
363
364
365
366
367
/*
* These are used with MOJOSHADER_error as special case positions.
*/
#define MOJOSHADER_POSITION_NONE (-3)
#define MOJOSHADER_POSITION_BEFORE (-2)
#define MOJOSHADER_POSITION_AFTER (-1)
368
typedef struct MOJOSHADER_error
369
370
371
372
373
374
375
376
{
/*
* 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;
377
/*
378
379
* Filename where error happened. This can be NULL if the information
* isn't available.
380
381
382
*/
const char *filename;
383
/*
384
385
386
387
388
389
390
391
* Position of error, if there is one. Will be MOJOSHADER_POSITION_NONE if
* there was no error, MOJOSHADER_POSITION_BEFORE if there was an error
* before processing started, and MOJOSHADER_POSITION_AFTER if there was
* an error during final processing. If >= 0, MOJOSHADER_parse() sets
* this to the byte offset (starting at zero) into the bytecode you
* supplied, and MOJOSHADER_assemble(), MOJOSHADER_parseAst(), and
* MOJOSHADER_compile() sets this to a a line number in the source code
* you supplied (starting at one).
392
393
*/
int error_position;
394
395
} MOJOSHADER_error;
396
397
398
399
400
401
402
403
404
405
406
407
408
409
/* !!! FIXME: document me. */
typedef enum MOJOSHADER_preshaderOpcode
{
MOJOSHADER_PRESHADEROP_NOP,
MOJOSHADER_PRESHADEROP_MOV,
MOJOSHADER_PRESHADEROP_NEG,
MOJOSHADER_PRESHADEROP_RCP,
MOJOSHADER_PRESHADEROP_FRC,
MOJOSHADER_PRESHADEROP_EXP,
MOJOSHADER_PRESHADEROP_LOG,
MOJOSHADER_PRESHADEROP_RSQ,
MOJOSHADER_PRESHADEROP_SIN,
MOJOSHADER_PRESHADEROP_COS,
410
411
412
413
414
MOJOSHADER_PRESHADEROP_ASIN,
MOJOSHADER_PRESHADEROP_ACOS,
MOJOSHADER_PRESHADEROP_ATAN,
MOJOSHADER_PRESHADEROP_MIN,
MOJOSHADER_PRESHADEROP_MAX,
415
416
MOJOSHADER_PRESHADEROP_LT,
MOJOSHADER_PRESHADEROP_GE,
417
418
419
MOJOSHADER_PRESHADEROP_ADD,
MOJOSHADER_PRESHADEROP_MUL,
MOJOSHADER_PRESHADEROP_ATAN2,
420
MOJOSHADER_PRESHADEROP_DIV,
421
MOJOSHADER_PRESHADEROP_CMP,
422
MOJOSHADER_PRESHADEROP_MOVC,
423
MOJOSHADER_PRESHADEROP_DOT,
424
MOJOSHADER_PRESHADEROP_NOISE,
425
426
427
MOJOSHADER_PRESHADEROP_SCALAR_OPS,
MOJOSHADER_PRESHADEROP_MIN_SCALAR = MOJOSHADER_PRESHADEROP_SCALAR_OPS,
MOJOSHADER_PRESHADEROP_MAX_SCALAR,
428
429
MOJOSHADER_PRESHADEROP_LT_SCALAR,
MOJOSHADER_PRESHADEROP_GE_SCALAR,
430
431
432
MOJOSHADER_PRESHADEROP_ADD_SCALAR,
MOJOSHADER_PRESHADEROP_MUL_SCALAR,
MOJOSHADER_PRESHADEROP_ATAN2_SCALAR,
433
MOJOSHADER_PRESHADEROP_DIV_SCALAR,
434
MOJOSHADER_PRESHADEROP_DOT_SCALAR,
435
MOJOSHADER_PRESHADEROP_NOISE_SCALAR,
436
437
438
439
440
441
442
443
444
445
446
447
448
449
} MOJOSHADER_preshaderOpcode;
typedef enum MOJOSHADER_preshaderOperandType
{
MOJOSHADER_PRESHADEROPERAND_INPUT,
MOJOSHADER_PRESHADEROPERAND_OUTPUT,
MOJOSHADER_PRESHADEROPERAND_LITERAL,
MOJOSHADER_PRESHADEROPERAND_TEMP,
} MOJOSHADER_preshaderOperandType;
typedef struct MOJOSHADER_preshaderOperand
{
MOJOSHADER_preshaderOperandType type;
unsigned int index;
450
451
unsigned int array_register_count;
unsigned int *array_registers;
452
453
454
455
456
457
458
} MOJOSHADER_preshaderOperand;
typedef struct MOJOSHADER_preshaderInstruction
{
MOJOSHADER_preshaderOpcode opcode;
unsigned int element_count;
unsigned int operand_count;
459
MOJOSHADER_preshaderOperand operands[4];
460
461
462
463
464
465
466
} MOJOSHADER_preshaderInstruction;
typedef struct MOJOSHADER_preshader
{
unsigned int literal_count;
double *literals;
unsigned int temp_count; /* scalar, not vector! */
467
468
unsigned int symbol_count;
MOJOSHADER_symbol *symbols;
469
470
unsigned int instruction_count;
MOJOSHADER_preshaderInstruction *instructions;
471
472
unsigned int register_count;
float *registers;
473
474
475
MOJOSHADER_malloc malloc;
MOJOSHADER_free free;
void *malloc_data;
476
477
} MOJOSHADER_preshader;
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
/*
* 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;
495
496
497
498
499
500
/*
* The name of the profile used to parse the shader. Will be NULL on error.
*/
const char *profile;
501
502
503
504
505
506
507
508
509
/*
* 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
510
511
512
* 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.
513
514
515
516
*/
int output_len;
/*
517
* Count of Direct3D instruction slots used. This is meaningless in terms
518
519
* of the actual output, as the profile will probably grow or reduce
* the count (or for high-level languages, not have that information at
520
521
522
523
* 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.
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
*/
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;
543
/*
544
545
546
547
548
* This is the main function name of the shader. This will be the
* caller-supplied string even if a given profile ignores it (GLSL,
* for example, always uses "main" in the shader output out of necessity,
* and Direct3D assembly has no concept of a "main function", etc).
* Otherwise, it'll be a default name chosen by the profile ("main") or
549
550
551
552
* whatnot.
*/
const char *mainfn;
553
554
555
556
557
558
/*
* The number of elements pointed to by (uniforms).
*/
int uniform_count;
/*
559
560
* (uniform_count) elements of data that specify Uniforms to be set for
* this shader. See discussion on MOJOSHADER_uniform for details.
561
* This can be NULL on error or if (uniform_count) is zero.
562
563
564
*/
MOJOSHADER_uniform *uniforms;
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
/*
* 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;
580
581
582
583
584
585
586
587
588
589
590
591
/*
* 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;
592
/* !!! FIXME: this should probably be "input" and not "attribute" */
593
594
595
596
597
/*
* The number of elements pointed to by (attributes).
*/
int attribute_count;
598
/* !!! FIXME: this should probably be "input" and not "attribute" */
599
600
601
/*
* (attribute_count) elements of data that specify Attributes to be set
* for this shader. See discussion on MOJOSHADER_attribute for details.
602
* This can be NULL on error or if (attribute_count) is zero.
603
604
605
*/
MOJOSHADER_attribute *attributes;
606
607
608
609
610
611
612
613
614
615
616
617
/*
* The number of elements pointed to by (outputs).
*/
int output_count;
/*
* (output_count) elements of data that specify outputs this shader
* writes to. See discussion on MOJOSHADER_attribute for details.
* This can be NULL on error or if (output_count) is zero.
*/
MOJOSHADER_attribute *outputs;
618
619
620
621
622
/*
* The number of elements pointed to by (swizzles).
*/
int swizzle_count;
623
/* !!! FIXME: this should probably be "input" and not "attribute" */
624
625
626
627
628
629
630
631
/*
* (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;
632
633
634
635
636
637
638
639
640
641
642
643
644
645
/*
* 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;
646
647
648
649
650
651
/*
* !!! FIXME: document me.
* This can be NULL on error or if no preshader was available.
*/
MOJOSHADER_preshader *preshader;
652
653
654
655
656
657
658
659
660
/*
* 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;
661
662
663
664
665
/*
* This is the pointer you passed as opaque data for your allocator.
*/
void *malloc_data;
666
667
668
669
670
671
672
673
} MOJOSHADER_parseData;
/*
* Profile string for Direct3D assembly language output.
*/
#define MOJOSHADER_PROFILE_D3D "d3d"
674
675
676
/*
* Profile string for passthrough of the original bytecode, unchanged.
*/
677
#define MOJOSHADER_PROFILE_BYTECODE "bytecode"
678
679
680
681
682
683
/*
* Profile string for GLSL: OpenGL high-level shader language output.
*/
#define MOJOSHADER_PROFILE_GLSL "glsl"
684
685
686
687
688
/*
* Profile string for GLSL 1.20: minor improvements to base GLSL spec.
*/
#define MOJOSHADER_PROFILE_GLSL120 "glsl120"
689
690
691
692
693
/*
* Profile string for GLSL ES: minor changes to GLSL output for ES compliance.
*/
#define MOJOSHADER_PROFILE_GLSLES "glsles"
694
695
696
697
698
/*
* Profile string for OpenGL ARB 1.0 shaders: GL_ARB_(vertex|fragment)_program.
*/
#define MOJOSHADER_PROFILE_ARB1 "arb1"
699
700
701
702
703
704
705
706
707
708
/*
* 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
*/
709
#define MOJOSHADER_PROFILE_NV3 "nv3"
710
711
712
/*
* Profile string for OpenGL ARB 1.0 shaders with Nvidia 4.0 extensions:
713
* GL_NV_gpu_program4
714
*/
715
#define MOJOSHADER_PROFILE_NV4 "nv4"
716
717
718
719
720
721
/*
* Profile string for Metal: Apple's lowlevel API's high-level shader language.
*/
#define MOJOSHADER_PROFILE_METAL "metal"
722
723
724
/*
* Determine the highest supported Shader Model for a profile.
*/
725
DECLSPEC int MOJOSHADER_maxShaderModel(const char *profile);
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
/*
* 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().
742
743
744
* 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.
745
*
746
* This function returns a MOJOSHADER_parseData.
747
748
749
750
751
752
*
* 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()).
*
753
754
755
756
757
758
* 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.
*
759
760
761
762
763
* You can force the shader to expect samplers of certain types. Generally
* you don't need this, as Shader Model 2 and later always specify what they
* expect samplers to be (2D, cubemap, etc). Shader Model 1, however, just
* uses whatever is bound to a given sampler at draw time, but this doesn't
* work in OpenGL, etc. In these cases, MojoShader will default to
764
765
766
767
768
769
770
* 2D texture sampling (or cubemap sampling, in cases where it makes sense,
* like the TEXM3X3TEX opcode), which works 75% of the time, but if you
* really needed something else, you'll need to specify it here. This can
* also be used, at your own risk, to override DCL opcodes in shaders: if
* the shader explicit says 2D, but you want Cubemap, for example, you can
* use this to override. If you aren't sure about any of this stuff, you can
* (and should) almost certainly ignore it: (smap) can be NULL.
771
*
772
773
774
775
776
* (bufsize) is the size in bytes of (tokenbuf). If (bufsize) is zero,
* MojoShader will attempt to figure out the size of the buffer, but you
* risk a buffer overflow if you have corrupt data, etc. Supply the value
* if you can.
*
777
778
779
780
781
782
* You should pass a name for your shader's main function in here, via the
* (mainfn) param. Some profiles need this name to be unique. Passing a NULL
* here will pick a reasonable default, and most profiles will ignore it
* anyhow. As the name of the shader's main function, etc, so make it a
* simple name that would match C's identifier rules. Keep it simple!
*
783
* This function is thread safe, so long as (m) and (f) are too, and that
784
785
786
* (tokenbuf) remains intact for the duration of the call. This allows you
* to parse several shaders on separate CPU cores at the same time.
*/
787
DECLSPEC const MOJOSHADER_parseData *MOJOSHADER_parse(const char *profile,
788
const char *mainfn,
789
790
791
792
793
794
795
796
797
798
const unsigned char *tokenbuf,
const unsigned int bufsize,
const MOJOSHADER_swizzle *swiz,
const unsigned int swizcount,
const MOJOSHADER_samplerMap *smap,
const unsigned int smapcount,
MOJOSHADER_malloc m,
MOJOSHADER_free f,
void *d);
799
800
801
802
803
804
805
806
807
808
/*
* 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.
*/
809
DECLSPEC void MOJOSHADER_freeParseData(const MOJOSHADER_parseData *data);
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
/*
* You almost certainly don't need this function, unless you absolutely know
* why you need it without hesitation. This is useful if you're doing
* extremely low-level shader work or building specialized tools.
*
* Parse a preshader structure. This expects a buffer of bytes that represents
* the preshader data starting with its magic number token and ending at
* the end of the comment tokens that contain this preshader. Note that it
* does _not_ start at the beginning of the comment tokens.
*
* On success, this will return a MOJOSHADER_preshader. This can be
* deallocated later by calling MOJOSHADER_freePreshader(). On failure,
* this will return NULL. Unlike other MojoShader APIs, this assumes you
* either have a complete and valid buffer of preshader tokens or you have
* incomplete/corrupted data, so there is no explicit error reporting. Please
* note that if the system runs out of memory, this function will also return
* NULL without distinction.
*
* This function is thread safe, so long as any allocator you passed into
* MOJOSHADER_parsePreshader() is, too.
*/
833
834
835
836
837
DECLSPEC const MOJOSHADER_preshader *MOJOSHADER_parsePreshader(const unsigned char *buf,
const unsigned int len,
MOJOSHADER_malloc m,
MOJOSHADER_free f,
void *d);
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
/*
* You almost certainly don't need this function, unless you absolutely know
* why you need it without hesitation. This is useful if you're doing
* extremely low-level shader work or building specialized tools.
*
* Call this to dispose of preshader parsing results when you are done with
* them. This will call the MOJOSHADER_free function you provided to
* MOJOSHADER_parsePreshader() multiple times, if you provided one.
* Passing a NULL here is a safe no-op.
*
* You only need to call this function for results from a call to
* MOJOSHADER_parsePreshader(). Other MojoShader structures with a preshader
* field, such as MOJOSHADER_parseData(), should not use this function, as
* the preshader will be deallocated with everything else in
* MOJOSHADER_freeParseData(), etc.
*
* This function is thread safe, so long as any allocator you passed into
* MOJOSHADER_parsePreshader() is, too.
*/
DECLSPEC void MOJOSHADER_freePreshader(const MOJOSHADER_preshader *preshader);
860
861
862
863
/* Effects interface... */
#include "mojoshader_effects.h"
864
865
866
867
868
869
/* Preprocessor interface... */
/*
* Structure used to pass predefined macros. Maps to D3DXMACRO.
870
* You can have macro arguments: set identifier to "a(b, c)" or whatever.
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
*/
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;
/*
907
* Bytes of output from preprocessing. This is a UTF-8 string. We
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
* 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;
939
* the preprocessor will open files directly if no callback is supplied, but
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
* 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.
*/
967
typedef int (MOJOSHADERCALL *MOJOSHADER_includeOpen)(MOJOSHADER_includeType inctype,
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
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.
*/
985
typedef void (MOJOSHADERCALL *MOJOSHADER_includeClose)(const char *data,
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
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.