/
mojoshader.h
977 lines (889 loc) · 37.4 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
41
42
43
44
45
46
47
48
49
50
51
/*
* For determining the revision control changeste of MojoShader you are using:
* 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
/*
* Structure used to return data from parsing of a shader...
*/
245
typedef struct MOJOSHADER_parseData
246
247
248
249
250
251
252
253
{
/*
* 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;
254
255
256
257
258
/*
* The name of the profile used to parse the shader. Will be NULL on error.
*/
const char *profile;
259
260
261
262
263
264
265
266
267
/*
* 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
268
269
270
* 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.
271
272
273
274
*/
int output_len;
/*
275
* Count of Direct3D instruction slots used. This is meaningless in terms
276
277
* of the actual output, as the profile will probably grow or reduce
* the count (or for high-level languages, not have that information at
278
279
280
281
* 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.
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
*/
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;
301
302
303
304
305
306
/*
* The number of elements pointed to by (uniforms).
*/
int uniform_count;
/*
307
308
* (uniform_count) elements of data that specify Uniforms to be set for
* this shader. See discussion on MOJOSHADER_uniform for details.
309
* This can be NULL on error or if (uniform_count) is zero.
310
311
312
*/
MOJOSHADER_uniform *uniforms;
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
/*
* 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;
328
329
330
331
332
333
334
335
336
337
338
339
/*
* 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;
340
341
342
343
344
345
346
347
/*
* 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.
348
* This can be NULL on error or if (attribute_count) is zero.
349
350
351
*/
MOJOSHADER_attribute *attributes;
352
353
354
355
356
357
358
359
360
361
362
363
364
/*
* 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;
365
366
367
368
369
370
371
372
373
/*
* 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;
374
375
376
377
378
/*
* This is the pointer you passed as opaque data for your allocator.
*/
void *malloc_data;
379
380
381
382
383
384
385
386
} MOJOSHADER_parseData;
/*
* Profile string for Direct3D assembly language output.
*/
#define MOJOSHADER_PROFILE_D3D "d3d"
387
388
389
390
391
/*
* Profile string for passthrough of the original bytecode, unchanged.
*/
#define MOJOSHADER_PROFILE_PASSTHROUGH "passthrough"
392
393
394
395
396
/*
* Profile string for GLSL: OpenGL high-level shader language output.
*/
#define MOJOSHADER_PROFILE_GLSL "glsl"
397
398
399
400
401
/*
* Profile string for GLSL 1.20: minor improvements to base GLSL spec.
*/
#define MOJOSHADER_PROFILE_GLSL120 "glsl120"
402
403
404
405
406
/*
* Profile string for OpenGL ARB 1.0 shaders: GL_ARB_(vertex|fragment)_program.
*/
#define MOJOSHADER_PROFILE_ARB1 "arb1"
407
408
409
410
411
412
413
414
415
416
/*
* 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
*/
417
#define MOJOSHADER_PROFILE_NV3 "nv3"
418
419
420
/*
* Profile string for OpenGL ARB 1.0 shaders with Nvidia 4.0 extensions:
421
* GL_NV_gpu_program4
422
*/
423
#define MOJOSHADER_PROFILE_NV4 "nv4"
424
425
426
427
428
429
/*
* Determine the highest supported Shader Model for a profile.
*/
int MOJOSHADER_maxShaderModel(const char *profile);
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
/*
* 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().
445
446
447
* 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.
448
*
449
* This function returns a MOJOSHADER_parseData.
450
451
452
453
454
455
*
* 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()).
*
456
457
458
459
460
461
* 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.
*
462
* This function is thread safe, so long as (m) and (f) are too, and that
463
464
465
466
467
468
* (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,
469
470
const MOJOSHADER_swizzle *swiz,
const unsigned int swizcount,
471
MOJOSHADER_malloc m,
472
473
MOJOSHADER_free f,
void *d);
474
475
476
477
478
479
480
481
482
483
484
/*
* 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);
485
486
487
488
489
490
/* OpenGL interface... */
491
492
493
494
495
496
497
498
499
500
501
502
503
504
/*
* "Contexts" map to OpenGL contexts...you need one per window, or whatever,
* and need to inform MojoShader when you make a new one current.
*
* "Shaders" refer to individual vertex or pixel programs, and are created
* by "compiling" Direct3D shader bytecode. A vertex and pixel shader are
* "linked" into a "Program" before you can use them to render.
*
* To the calling application, these are all opaque handles.
*/
typedef struct MOJOSHADER_glContext MOJOSHADER_glContext;
typedef struct MOJOSHADER_glShader MOJOSHADER_glShader;
typedef struct MOJOSHADER_glProgram MOJOSHADER_glProgram;
505
506
/*
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
* Get a list of available profiles. This will fill in the array (profs)
* with up to (size) pointers of profiles that the current system can handle;
* that is, the profiles are built into MojoShader and the OpenGL extensions
* required for them exist at runtime. This function returns the number of
* available profiles, which may be more, less, or equal to (size).
*
* If there are more than (size) profiles, the (profs) buffer will not
* overflow. You can check the return value for the total number of
* available profiles, allocate more space, and try again if necessary.
* Calling this function with (size) == 0 is legal.
*
* You can only call this AFTER you have successfully built your GL context
* and made it current. This function will lookup the GL functions it needs
* through the callback you supply. The lookup function is neither stored nor
* used by MojoShader after this function returns, nor are the functions it
* might look up.
*
* You should not free any strings returned from this function; they are
* pointers to internal, probably static, memory.
526
*
527
528
529
530
531
532
533
534
535
536
* This call is NOT thread safe! As most OpenGL implementations are not thread
* safe, you should probably only call this from the same thread that created
* the GL context.
*/
int MOJOSHADER_glAvailableProfiles(void *(*lookup)(const char *fnname),
const char **profs, const int size);
/*
* Determine the best profile to use for the current system.
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
*
* You can only call this AFTER you have successfully built your GL context
* and made it current. This function will lookup the GL functions it needs
* through the callback you supply. The lookup function is neither stored nor
* used by MojoShader after this function returns, nor are the functions it
* might look up.
*
* Returns the name of the "best" profile on success, NULL if none of the
* available profiles will work on this system. "Best" is a relative term,
* but it generally means the best trade off between feature set and
* performance. The selection algorithm may be arbitrary and complex.
*
* The returned value is an internal static string, and should not be free()'d
* by the caller. If you get a NULL, calling MOJOSHADER_glGetError() might
* shed some light on why.
*
* This call is NOT thread safe! As most OpenGL implementations are not thread
* safe, you should probably only call this from the same thread that created
* the GL context.
*/
const char *MOJOSHADER_glBestProfile(void *(*lookup)(const char *fnname));
560
561
562
563
564
565
566
567
/*
* Prepare MojoShader to manage OpenGL shaders.
*
* You do not need to call this if all you want is MOJOSHADER_parse().
*
* You must call this once AFTER you have successfully built your GL context
* and made it current. This function will lookup the GL functions it needs
* through the callback you supply, after which it may call them at any time
568
569
* up until you call MOJOSHADER_glDestroyContext(). The lookup function is
* neither stored nor used by MojoShader after this function returns.
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
*
* (profile) is an OpenGL-specific MojoShader profile, which decides how
* Direct3D bytecode shaders get turned into OpenGL programs, and how they
* are fed to the GL.
*
* (lookup) is a callback that is used to load GL entry points. This callback
* has to look up base GL functions and extension entry points.
*
* As MojoShader 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.
*
585
586
587
* Returns a new context on success, NULL on error. If you get a new context,
* you need to make it current before using it with
* MOJOSHADER_glMakeContextCurrent().
588
589
590
591
592
593
*
* This call is NOT thread safe! It must return success before you may call
* any other MOJOSHADER_gl* function. Also, as most OpenGL implementations
* are not thread safe, you should probably only call this from the same
* thread that created the GL context.
*/
594
MOJOSHADER_glContext *MOJOSHADER_glCreateContext(const char *profile,
595
596
597
598
599
600
void *(*lookup)(const char *fnname),
MOJOSHADER_malloc m, MOJOSHADER_free f,
void *d);
/*
* You must call this before using the context that you got from
601
602
* MOJOSHADER_glCreateContext(), and must use it when you switch to a new GL
* context.
603
604
605
606
607
608
609
610
*
* You can only have one MOJOSHADER_glContext per actual GL context, or
* undefined behaviour will result.
*
* It is legal to call this with a NULL pointer to make no context current,
* but you need a valid context to be current to use most of MojoShader.
*/
void MOJOSHADER_glMakeContextCurrent(MOJOSHADER_glContext *ctx);
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
/*
* Get any error state we might have picked up. MojoShader will NOT call
* glGetError() internally, but there are other errors we can pick up,
* such as failed shader compilation, etc.
*
* Returns a human-readable string. This string is for debugging purposes, and
* not guaranteed to be localized, coherent, or user-friendly in any way.
* It's for programmers!
*
* The latest error may remain between calls. New errors replace any existing
* error. Don't check this string for a sign that an error happened, check
* return codes instead and use this for explanation when debugging.
*
* Do not free the returned string: it's a pointer to a static internal
* buffer. Do not keep the pointer around, either, as it's likely to become
* invalid as soon as you call into MojoShader again.
*
* This call is NOT thread safe! As most OpenGL implementations are not thread
* safe, you should probably only call this from the same thread that created
* the GL context.
632
*
633
634
* This call does NOT require a valid MOJOSHADER_glContext to have been made
* current. The error buffer is shared between contexts, so you can get
635
* error results from a failed MOJOSHADER_glCreateContext().
636
*/
637
const char *MOJOSHADER_glGetError(void);
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
/*
* Get the maximum uniforms a shader can support for the current GL context,
* MojoShader profile, and shader type. You can use this to make decisions
* about what shaders you want to use (for example, a less complicated
* shader may be swapped in for lower-end systems).
*
* Returns the number, or -1 on error.
*
* This call is NOT thread safe! As most OpenGL implementations are not thread
* safe, you should probably only call this from the same thread that created
* the GL context.
*
* This call requires a valid MOJOSHADER_glContext to have been made current,
* or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
*/
int MOJOSHADER_glMaxUniforms(MOJOSHADER_shaderType shader_type);
656
657
658
659
660
661
/*
* Compile a buffer of Direct3D shader bytecode into an OpenGL shader.
* You still need to link the shader before you may render with it.
*
* (tokenbuf) is a buffer of Direct3D shader bytecode.
* (bufsize) is the size, in bytes, of the bytecode buffer.
662
* (swiz) and (swizcount) are passed to MOJOSHADER_parse() unmolested.
663
664
*
* Returns NULL on error, or a shader handle on success.
665
666
667
668
*
* This call is NOT thread safe! As most OpenGL implementations are not thread
* safe, you should probably only call this from the same thread that created
* the GL context.
669
670
671
672
673
*
* This call requires a valid MOJOSHADER_glContext to have been made current,
* or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
*
* Compiled shaders from this function may not be shared between contexts.
674
*/
675
MOJOSHADER_glShader *MOJOSHADER_glCompileShader(const unsigned char *tokenbuf,
676
677
678
const unsigned int bufsize,
const MOJOSHADER_swizzle *swiz,
const unsigned int swizcount);
679
680
681
682
683
684
685
686
687
688
689
/*
* Get the MOJOSHADER_parseData structure that was produced from the
* call to MOJOSHADER_glCompileShader().
*
* This data is read-only, and you should NOT attempt to free it. This
* pointer remains valid until the shader is deleted.
*/
const MOJOSHADER_parseData *MOJOSHADER_glGetShaderParseData(
MOJOSHADER_glShader *shader);
690
/*
691
692
693
694
695
* Link a vertex and pixel shader into an OpenGL program.
* (vshader) or (pshader) can be NULL, to specify that the GL should use the
* fixed-function pipeline instead of the programmable pipeline for that
* portion of the work. You can reuse shaders in various combinations across
* multiple programs, by relinking different pairs.
696
*
697
698
* It is illegal to give a vertex shader for (pshader) or a pixel shader
* for (vshader).
699
700
701
702
*
* Once you have successfully linked a program, you may render with it.
*
* Returns NULL on error, or a program handle on success.
703
704
705
706
*
* This call is NOT thread safe! As most OpenGL implementations are not thread
* safe, you should probably only call this from the same thread that created
* the GL context.
707
708
709
710
711
*
* This call requires a valid MOJOSHADER_glContext to have been made current,
* or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
*
* Linked programs from this function may not be shared between contexts.
712
*/
713
714
MOJOSHADER_glProgram *MOJOSHADER_glLinkProgram(MOJOSHADER_glShader *vshader,
MOJOSHADER_glShader *pshader);
715
716
717
718
719
720
721
722
723
724
725
726
727
728
/*
* This binds the program (using, for example, glUseProgramObjectARB()), and
* disables all the client-side arrays so we can reset them with new values
* if appropriate.
*
* Call with NULL to disable the programmable pipeline and all enabled
* client-side arrays.
*
* After binding a program, you should update any uniforms you care about
* with MOJOSHADER_glSetVertexShaderUniformF() (etc), set any vertex arrays
* you want to use with MOJOSHADER_glSetVertexAttribute(), and finally call
* MOJOSHADER_glProgramReady() to commit everything to the GL. Then you may
* begin drawing through standard GL entry points.
729
730
731
732
*
* This call is NOT thread safe! As most OpenGL implementations are not thread
* safe, you should probably only call this from the same thread that created
* the GL context.
733
734
735
*
* This call requires a valid MOJOSHADER_glContext to have been made current,
* or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
*/
void MOJOSHADER_glBindProgram(MOJOSHADER_glProgram *program);
/*
* Set a floating-point uniform value (what Direct3D calls a "constant").
*
* There is a single array of 4-float "registers" shared by all vertex shaders.
* This is the "c" register file in Direct3D (c0, c1, c2, etc...)
* MojoShader will take care of synchronizing this internal array with the
* appropriate variables in the GL shaders.
*
* (idx) is the index into the internal array: 0 is the first four floats,
* 1 is the next four, etc.
* (data) is a pointer to (vec4count*4) floats.
751
752
753
754
*
* This call is NOT thread safe! As most OpenGL implementations are not thread
* safe, you should probably only call this from the same thread that created
* the GL context.
755
756
757
*
* This call requires a valid MOJOSHADER_glContext to have been made current,
* or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
758
759
*
* Uniforms are not shared between contexts.
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
*/
void MOJOSHADER_glSetVertexShaderUniformF(unsigned int idx, const float *data,
unsigned int vec4count);
/*
* Set an integer uniform value (what Direct3D calls a "constant").
*
* There is a single array of 4-int "registers" shared by all vertex shaders.
* This is the "i" register file in Direct3D (i0, i1, i2, etc...)
* MojoShader will take care of synchronizing this internal array with the
* appropriate variables in the GL shaders.
*
* (idx) is the index into the internal array: 0 is the first four ints,
* 1 is the next four, etc.
* (data) is a pointer to (ivec4count*4) ints.
775
776
777
778
*
* This call is NOT thread safe! As most OpenGL implementations are not thread
* safe, you should probably only call this from the same thread that created
* the GL context.
779
780
781
*
* This call requires a valid MOJOSHADER_glContext to have been made current,
* or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
782
783
*
* Uniforms are not shared between contexts.
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
*/
void MOJOSHADER_glSetVertexShaderUniformI(unsigned int idx, const int *data,
unsigned int ivec4count);
/*
* Set a boolean uniform value (what Direct3D calls a "constant").
*
* There is a single array of "registers" shared by all vertex shaders.
* This is the "b" register file in Direct3D (b0, b1, b2, etc...)
* MojoShader will take care of synchronizing this internal array with the
* appropriate variables in the GL shaders.
*
* Unlike the float and int counterparts, booleans are single values, not
* four-element vectors...so idx==1 is the second boolean in the internal
* array, not the fifth.
*
* Non-zero values are considered "true" and zero is considered "false".
*
* (idx) is the index into the internal array.
* (data) is a pointer to (bcount) ints.
804
805
806
807
*
* This call is NOT thread safe! As most OpenGL implementations are not thread
* safe, you should probably only call this from the same thread that created
* the GL context.
808
809
810
*
* This call requires a valid MOJOSHADER_glContext to have been made current,
* or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
811
812
*
* Uniforms are not shared between contexts.
813
814
815
816
*/
void MOJOSHADER_glSetVertexShaderUniformB(unsigned int idx, const int *data,
unsigned int bcount);
817
818
819
820
/*
* The equivalent of MOJOSHADER_glSetVertexShaderUniformF() for pixel
* shaders. Other than using a different internal array that is specific
* to pixel shaders, this functions just like its vertex array equivalent.
821
822
823
824
*
* This call is NOT thread safe! As most OpenGL implementations are not thread
* safe, you should probably only call this from the same thread that created
* the GL context.
825
826
827
*
* This call requires a valid MOJOSHADER_glContext to have been made current,
* or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
828
829
*
* Uniforms are not shared between contexts.
830
831
832
833
834
835
836
837
*/
void MOJOSHADER_glSetPixelShaderUniformF(unsigned int idx, const float *data,
unsigned int vec4count);
/*
* The equivalent of MOJOSHADER_glSetVertexShaderUniformI() for pixel
* shaders. Other than using a different internal array that is specific
* to pixel shaders, this functions just like its vertex array equivalent.
838
839
840
841
*
* This call is NOT thread safe! As most OpenGL implementations are not thread
* safe, you should probably only call this from the same thread that created
* the GL context.
842
843
844
*
* This call requires a valid MOJOSHADER_glContext to have been made current,
* or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
845
846
*
* Uniforms are not shared between contexts.
847
848
849
850
851
852
853
854
*/
void MOJOSHADER_glSetPixelShaderUniformI(unsigned int idx, const int *data,
unsigned int ivec4count);
/*
* The equivalent of MOJOSHADER_glSetVertexShaderUniformB() for pixel
* shaders. Other than using a different internal array that is specific
* to pixel shaders, this functions just like its vertex array equivalent.
855
856
857
858
*
* This call is NOT thread safe! As most OpenGL implementations are not thread
* safe, you should probably only call this from the same thread that created
* the GL context.
859
860
861
*
* This call requires a valid MOJOSHADER_glContext to have been made current,
* or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
862
863
*
* Uniforms are not shared between contexts.
864
865
866
*/
void MOJOSHADER_glSetPixelShaderUniformB(unsigned int idx, const int *data,
unsigned int bcount);
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
/*
* Connect a client-side array to the currently-bound program.
*
* (usage) and (index) map to Direct3D vertex declaration values: COLOR1 would
* be MOJOSHADER_USAGE_COLOR and 1.
*
* The caller should bind VBOs before this call and treat (ptr) as an offset,
* if appropriate.
*
* MojoShader will figure out where to plug this stream into the
* currently-bound program, and enable the appropriate client-side array.
*
* (size), (type), (normalized), (stride), and (ptr) correspond to
* glVertexAttribPointer()'s parameters (in most cases, these get passed
* unmolested to that very entry point during this function).
883
884
885
886
*
* This call is NOT thread safe! As most OpenGL implementations are not thread
* safe, you should probably only call this from the same thread that created
* the GL context.
887
888
889
890
891
*
* This call requires a valid MOJOSHADER_glContext to have been made current,
* or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
*
* Vertex attributes are not shared between contexts.
892
893
894
895
896
897
898
899
900
901
902
903
*/
void MOJOSHADER_glSetVertexAttribute(MOJOSHADER_usage usage,
int index, unsigned int size,
MOJOSHADER_attributeType type,
int normalized, unsigned int stride,
const void *ptr);
/*
* Inform MojoShader that it should commit any pending state to the GL. This
* must be called after you bind a program and update any inputs, right
* before you start drawing, so any outstanding changes made to the shared
* constants array (etc) can propagate to the shader during this call.
904
905
906
907
*
* This call is NOT thread safe! As most OpenGL implementations are not thread
* safe, you should probably only call this from the same thread that created
* the GL context.
908
909
910
*
* This call requires a valid MOJOSHADER_glContext to have been made current,
* or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
911
912
913
914
915
916
917
*/
void MOJOSHADER_glProgramReady(void);
/*
* Free the resources of a linked program. This will delete the GL object
* and free memory.
*
918
919
* If the program is currently bound by MOJOSHADER_glBindProgram(), it will
* be deleted as soon as it becomes unbound.
920
921
922
923
*
* This call is NOT thread safe! As most OpenGL implementations are not thread
* safe, you should probably only call this from the same thread that created
* the GL context.
924
925
926
*
* This call requires a valid MOJOSHADER_glContext to have been made current,
* or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
927
*/
928
void MOJOSHADER_glDeleteProgram(MOJOSHADER_glProgram *program);
929
930
931
932
933
/*
* Free the resources of a compiled shader. This will delete the GL object
* and free memory.
*
934
935
* If the shader is currently referenced by a linked program, it will
* be deleted as soon as all referencing programs are deleted, too.
936
937
938
939
*
* This call is NOT thread safe! As most OpenGL implementations are not thread
* safe, you should probably only call this from the same thread that created
* the GL context.
940
941
942
*
* This call requires a valid MOJOSHADER_glContext to have been made current,
* or it will crash your program. See MOJOSHADER_glMakeContextCurrent().
943
*/
944
void MOJOSHADER_glDeleteShader(MOJOSHADER_glShader *shader);
945
946
947
948
/*
* Deinitialize MojoShader's OpenGL shader management.
*
949
950
951
952
* You must call this once, while your GL context (not MojoShader context) is
* still current, if you previously had a successful call to
* MOJOSHADER_glCreateContext(). This should be the last MOJOSHADER_gl*
* function you call until you've prepared a context again.
953
954
955
956
957
958
959
*
* This will clean up resources previously allocated, and may call into the GL.
*
* This will not clean up shaders and programs you created! Please call
* MOJOSHADER_glDeleteShader() and MOJOSHADER_glDeleteProgram() to clean
* those up before calling this function!
*
960
961
962
* This function destroys the MOJOSHADER_glContext you pass it. If it's the
* current context, then no context will be current upon return.
*
963
964
965
966
967
* This call is NOT thread safe! There must not be any other MOJOSHADER_gl*
* functions running when this is called. Also, as most OpenGL implementations
* are not thread safe, you should probably only call this from the same
* thread that created the GL context.
*/
968
void MOJOSHADER_glDestroyContext(MOJOSHADER_glContext *ctx);
969
970
971
972
973
974
975
#ifdef __cplusplus
}
#endif
#endif /* include-once blocker. */
976
/* end of mojoshader.h ... */