Line data Source code
1 0 : /*
2 :
3 : OOShaderMaterial.h
4 :
5 : Managers a combination of a shader program, textures and uniforms.
6 :
7 :
8 : Copyright (C) 2007-2013 Jens Ayton
9 :
10 : Permission is hereby granted, free of charge, to any person obtaining a copy
11 : of this software and associated documentation files (the "Software"), to deal
12 : in the Software without restriction, including without limitation the rights
13 : to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14 : copies of the Software, and to permit persons to whom the Software is
15 : furnished to do so, subject to the following conditions:
16 :
17 : The above copyright notice and this permission notice shall be included in all
18 : copies or substantial portions of the Software.
19 :
20 : THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21 : IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22 : FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23 : AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24 : LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25 : OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26 : SOFTWARE.
27 :
28 : */
29 :
30 : #import "OOBasicMaterial.h"
31 : #import "OOWeakReference.h"
32 : #import "OOMaths.h"
33 :
34 :
35 : #if OO_SHADERS
36 :
37 :
38 : @class OOShaderProgram, OOTexture;
39 :
40 :
41 : enum
42 : {
43 : // Conversion settings for uniform bindings
44 : kOOUniformConvertClamp = 0x0001U,
45 : kOOUniformConvertNormalize = 0x0002U,
46 : kOOUniformConvertToMatrix = 0x0004U,
47 : kOOUniformBindToSuperTarget = 0x0008U,
48 :
49 : kOOUniformConvertDefaults = kOOUniformConvertToMatrix | kOOUniformBindToSuperTarget
50 : };
51 : typedef uint16_t OOUniformConvertOptions;
52 :
53 :
54 : @interface OOShaderMaterial: OOBasicMaterial
55 : {
56 : @private
57 : OOShaderProgram *shaderProgram;
58 : NSMutableDictionary *uniforms;
59 :
60 : uint32_t texCount;
61 : OOTexture **textures;
62 :
63 : OOWeakReference *bindingTarget;
64 : }
65 :
66 : + (BOOL)configurationDictionarySpecifiesShaderMaterial:(NSDictionary *)configuration;
67 :
68 : /* Set up an OOShaderMaterial.
69 :
70 : Configuration should be a dictionary equivalent to an entry in a
71 : shipdata.plist "shaders" dictionary. Specifically, keys OOShaderMaterial
72 : will look for are currently:
73 : textures array of texture file names.
74 : vertex_shader name of vertex shader file.
75 : fragment_shader name of fragment shader file.
76 : uniforms dictionary of uniforms. Values are either reals or
77 : dictionaries containing:
78 : type "int", "texture" or "float"
79 : value number
80 : gloss gloss value of material, float between 0.0 and 1.0, defaults to 0.5
81 :
82 : Macros is a dictionary which is converted to macro definitions and
83 : prepended to shader source code. It should be used to specify the
84 : availability if uniforms you tend to register, and other macros such as
85 : bug fix identifiers. For example, the
86 : dictionary:
87 : { "OO_ENGINE_LEVEL" = 1; }
88 :
89 : will be transformed into:
90 : #define OO_ENGINE_LEVEL 1
91 : */
92 : + (instancetype) shaderMaterialWithName:(NSString *)name
93 : configuration:(NSDictionary *)configuration
94 : macros:(NSDictionary *)macros
95 : bindingTarget:(id<OOWeakReferenceSupport>)target;
96 :
97 : - (id) initWithName:(NSString *)name
98 : configuration:(NSDictionary *)configuration
99 : macros:(NSDictionary *)macros
100 : bindingTarget:(id<OOWeakReferenceSupport>)target;
101 :
102 : /* Bind a uniform to a property of an object.
103 :
104 : SelectorName should specify a method of source which returns the desired
105 : value; it will be called every time -apply is, assuming uniformName is
106 : used in the shader. (If not, OOShaderMaterial will not track the binding.)
107 :
108 : A bound method must not take any parameters, and must return one of the
109 : following types:
110 : * Any integer or float type.
111 : * NSNumber.
112 : * Vector.
113 : * Quaternion.
114 : * OOMatrix.
115 : * OOColor.
116 :
117 : The "convert" flag has different meanings for different types:
118 : * For int, float or NSNumber, it clamps to the range [0..1].
119 : * For Vector, it normalizes.
120 : * For Quaternion, it converts to a rotation matrix (instead of a vector).
121 :
122 : NOTE: this method *does not* check against the whitelist. See
123 : -bindSafeUniform:toObject:propertyNamed:convertOptions: below.
124 : */
125 : - (BOOL) bindUniform:(NSString *)uniformName
126 : toObject:(id<OOWeakReferenceSupport>)target
127 : property:(SEL)selector
128 : convertOptions:(OOUniformConvertOptions)options;
129 :
130 : /* Bind a uniform to a property of an object.
131 :
132 : This is similar to -bindUniform:toObject:property:convertOptions:, except
133 : that it checks against OOUniformBindingPermitted().
134 : */
135 : - (BOOL) bindSafeUniform:(NSString *)uniformName
136 : toObject:(id<OOWeakReferenceSupport>)target
137 : propertyNamed:(NSString *)property
138 : convertOptions:(OOUniformConvertOptions)options;
139 :
140 : /* Set a uniform value.
141 : */
142 : - (void) setUniform:(NSString *)uniformName intValue:(int)value;
143 : - (void) setUniform:(NSString *)uniformName floatValue:(float)value;
144 : - (void) setUniform:(NSString *)uniformName vectorValue:(GLfloat[4])value;
145 : - (void) setUniform:(NSString *)uniformName vectorObjectValue:(id)value; // Array of four numbers, or something that can be OOVectorFromObject()ed.
146 : - (void) setUniform:(NSString *)uniformName quaternionValue:(Quaternion)value asMatrix:(BOOL)asMatrix;
147 :
148 : /* Add constant uniforms. Same format as uniforms dictionary of configuration
149 : parameter to -initWithConfiguration:macros:. The target parameter is used
150 : for bindings.
151 :
152 : Additionally, the target may implement the following method, used to seed
153 : any random bindings:
154 : - (uint32_t) randomSeedForShaders;
155 : */
156 : -(void) addUniformsFromDictionary:(NSDictionary *)uniformDefs withBindingTarget:(id<OOWeakReferenceSupport>)target;
157 :
158 : @end
159 :
160 :
161 : @interface NSObject (ShaderBindingHierarchy)
162 :
163 : /* Informal protocol for objects to "forward" their shader bindings up a
164 : hierarchy (for instance, subentities to parent entities).
165 : */
166 : - (id<OOWeakReferenceSupport>) superShaderBindingTarget;
167 :
168 : @end
169 :
170 :
171 : enum
172 : {
173 : /* ID of vertex attribute used for tangents. A fixed ID is used for
174 : simplicty.
175 : NOTE: on Nvidia hardware, attribute 15 is aliased to
176 : gl_MultiTexCoord7. This is not expected to become a problem.
177 : */
178 : kTangentAttributeIndex = 15
179 : };
180 :
181 :
182 : /* OOUniformBindingPermitted()
183 :
184 : Predicate determining whether a given property may be used as a binding.
185 : Client code is responsible for implementing this.
186 : */
187 : BOOL OOUniformBindingPermitted(NSString *propertyName, id bindingTarget);
188 :
189 :
190 : @interface NSObject (OOShaderMaterialTargetOptional)
191 :
192 : - (uint32_t) randomSeedForShaders;
193 :
194 : @end
195 :
196 :
197 : // Material specifier dictionary keys.
198 : extern NSString * const kOOVertexShaderSourceKey;
199 : extern NSString * const kOOVertexShaderNameKey;
200 : extern NSString * const kOOFragmentShaderSourceKey;
201 : extern NSString * const kOOFragmentShaderNameKey;
202 : extern NSString * const kOOTexturesKey;
203 : extern NSString * const kOOTextureObjectsKey;
204 : extern NSString * const kOOUniformsKey;
205 : extern NSString * const kOOIsSynthesizedMaterialConfigurationKey;
206 : extern NSString * const kOOIsSynthesizedMaterialMacrosKey;
207 :
208 : #endif // OO_SHADERS
|
