1 #ifndef __DALI_SHADER_EFFECT_H__
2 #define __DALI_SHADER_EFFECT_H__
5 * Copyright (c) 2015 Samsung Electronics Co., Ltd.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
22 #include <dali/public-api/object/handle.h>
23 #include <dali/public-api/object/property-index-ranges.h>
28 * @addtogroup dali_core_rendering_effects
34 * @brief DALI_COMPOSE_SHADER macro provides a convenient way to write shader source code.
36 * We normally use double quotation marks to write a string such as "Hello World".
37 * However many symbols are needed to add multiple lines of string.
38 * We don't need to write quotation marks using this macro at every line.
40 * [An example of double quotation marks usage]
41 * const string FRAGMENT_SHADER_SOURCE = \
44 * " gl_FragColor = texture2D( sTexture, vTexCoord ) * uColor;\n"
47 * [An example of DALI_COMPOSE_SHADER usage]
48 * const string VERTEX_SHADER_SOURCE = DALI_COMPOSE_SHADER (
51 * gl_Position = uMvpMatrix * vec4(aPosition, 1.0);
52 * vTexCoord = mix( sTextureRect.xy, sTextureRect.zw, aTexCoord) );
56 * @remarks This is an experimental feature and might not be supported in the next release. We do recommend not to use it.
58 #define DALI_COMPOSE_SHADER(STR) #STR
65 namespace Internal DALI_INTERNAL
73 * @brief Shader effects provide a visual effect for image actors.
75 * For a Custom shader you can provide the vertex and fragment shader code as strings.
76 * These shader snippets get concatenated with the default attributes and uniforms.
77 * For a vertex shader this part contains the following code:
79 * precision highp float;
80 * attribute vec3 aPosition;
81 * attribute vec2 aTexCoord;
82 * uniform mat4 uMvpMatrix;
83 * uniform mat4 uModelMatrix;
84 * uniform mat4 uViewMatrix;
85 * uniform mat4 uModelView;
86 * uniform mat3 uNormalMatrix;
87 * uniform mat4 uProjection;
88 * uniform vec4 uColor;
89 * varying vec2 vTexCoord;
91 * The custom shader part is expected to output the vertex position and texture coordinate.
92 * A basic custom vertex shader would contain the following code:
96 * gl_Position = uMvpMatrix * vec4(aPosition, 1.0);
97 * vTexCoord = mix( sTextureRect.xy, sTextureRect.zw, aTexCoord );
100 * For fragment shader the default part for images contains the following code:
102 * precision mediump float;
103 * uniform sampler2D sTexture;
104 * uniform sampler2D sEffect;
105 * uniform vec4 uColor;
106 * varying vec2 vTexCoord;
109 * @remarks This is an experimental feature and might not be supported in the next release. We do recommend not to use it.
110 * @note In order for fade and color animations to work, the fragment shader needs to multiply the fragment color
111 * with the uniform color "uColor" of the node.
113 class DALI_IMPORT_API ShaderEffect : public Handle
117 // Default Properties
120 * @brief An enumeration of properties belonging to the ShaderEffect class.
122 * Grid Density defines the spacing of vertex coordinates in world units.
123 * ie a larger actor will have more grids at the same spacing.
125 * +---+---+ +---+---+---+
127 * +---+---+ +---+---+---+
129 * +---+---+ +---+---+---+
138 GRID_DENSITY = DEFAULT_ACTOR_PROPERTY_START_INDEX, ///< @DEPRECATED_1_0.47 @brief name "gridDensity", type float @SINCE_1_0.0
139 IMAGE, ///< @DEPRECATED_1_0.47 @brief name "image", type Map {"filename":"", "loadPolicy":...} @SINCE_1_0.0
140 PROGRAM, ///< @DEPRECATED_1_0.47 @brief name "program", type Map {"vertexPrefix":"","fragmentPrefix":"","vertex":"","fragment":""} @SINCE_1_0.0
141 GEOMETRY_HINTS ///< @DEPRECATED_1_0.47 @brief name "geometryHints", type int (bitfield) values from enum GeometryHints @SINCE_1_0.0
145 static const float DEFAULT_GRID_DENSITY; ///< The default density is 40 pixels
149 * @brief Hints for rendering/subdividing geometry.
154 HINT_NONE = 0x00, ///< @DEPRECATED_1_0.47 @brief no hints @SINCE_1_0.0
155 HINT_GRID_X = 0x01, ///< @DEPRECATED_1_0.47 @brief Geometry must be subdivided in X @SINCE_1_0.0
156 HINT_GRID_Y = 0x02, ///< @DEPRECATED_1_0.47 @brief Geometry must be subdivided in Y @SINCE_1_0.0
157 HINT_GRID = (HINT_GRID_X | HINT_GRID_Y), ///< @DEPRECATED_1_0.47 @brief HINT_GRID_X | HINT_GRID_Y @SINCE_1_0.0
158 HINT_DEPTH_BUFFER = 0x04, ///< @DEPRECATED_1_0.47 @brief Needs depth buffering turned on @SINCE_1_0.0
159 HINT_BLENDING = 0x08, ///< @DEPRECATED_1_0.47 @brief Notifies the actor to use blending even if it's fully opaque. Needs actor's blending set to BlendingMode::AUTO @SINCE_1_0.0
160 HINT_DOESNT_MODIFY_GEOMETRY = 0x10 ///< @DEPRECATED_1_0.47 @brief Notifies that the vertex shader will not change geometry (enables bounding box culling) @SINCE_1_0.0
165 * @brief Coordinate type of the shader uniform.
167 * Viewport coordinate types will convert from viewport to view space.
168 * Use this coordinate type if your are doing a transformation in view space.
169 * The texture coordinate type converts a value in actor local space to texture coodinates.
170 * This is useful for pixel shaders and accounts for texture atlas.
173 enum UniformCoordinateType
175 COORDINATE_TYPE_DEFAULT, ///< @DEPRECATED_1_0.47 @brief Default, No transformation to be applied @SINCE_1_0.0
176 COORDINATE_TYPE_VIEWPORT_POSITION, ///< @DEPRECATED_1_0.47 @brief The uniform is a position vector in viewport coordinates that needs to be converted to GL view space coordinates. @SINCE_1_0.0
177 COORDINATE_TYPE_VIEWPORT_DIRECTION ///< @DEPRECATED_1_0.47 @brief The uniform is a directional vector in viewport coordinates that needs to be converted to GL view space coordinates. @SINCE_1_0.0
182 * @brief Create an empty ShaderEffect.
184 * This can be initialised with ShaderEffect::New(...)
191 * @brief Create ShaderEffect.
194 * @param vertexShader code for the effect. If you pass in an empty string, the default version will be used
195 * @param fragmentShader code for the effect. If you pass in an empty string, the default version will be used
196 * @param hints GeometryHints to define the geometry of the rendered object
197 * @return A handle to a shader effect
199 static ShaderEffect New( const std::string& vertexShader,
200 const std::string& fragmentShader,
201 GeometryHints hints = GeometryHints(HINT_NONE) );
205 * @brief Create ShaderEffect.
207 * @param vertexShaderPrefix code for the effect. It will be inserted before the default uniforms (ideal for \#defines)
208 * @param vertexShader code for the effect. If you pass in an empty string, the default version will be used
209 * @param fragmentShaderPrefix code for the effect. It will be inserted before the default uniforms (ideal for \#defines)
210 * @param fragmentShader code for the effect. If you pass in an empty string, the default version will be used
211 * @param hints GeometryHints to define the geometry of the rendered object
212 * @return A handle to a shader effect
214 static ShaderEffect NewWithPrefix(const std::string& vertexShaderPrefix,
215 const std::string& vertexShader,
216 const std::string& fragmentShaderPrefix,
217 const std::string& fragmentShader,
218 GeometryHints hints = GeometryHints(HINT_NONE) );
222 * @brief Downcast a handle to ShaderEffect handle.
224 * If handle points to a ShaderEffect the downcast produces valid
225 * handle. If not the returned handle is left uninitialized.
228 * @param[in] handle to An object
229 * @return handle to a ShaderEffect object or an uninitialized handle
231 static ShaderEffect DownCast( BaseHandle handle );
237 * This is non-virtual since derived Handle types must not contain data or virtual methods.
244 * @brief Copy constructor
247 * @param object A reference to a ShaderEffect object
249 ShaderEffect(const ShaderEffect& object);
253 * @brief This assignment operator is required for (smart) pointer semantics.
256 * @param [in] rhs A reference to the copied handle
257 * @return A reference to this
259 ShaderEffect& operator=(const ShaderEffect& rhs);
263 * @brief Sets image for using as effect texture.
265 * This image texture will be bound to the "sEffect" sampler
266 * so it can be used in fragment shader for effects
269 * @param[in] image to use as effect texture
271 void SetEffectImage( Image image );
275 * @brief Set a uniform value.
277 * This will register a property of type Property::FLOAT; see Object::RegisterProperty() for more details.
278 * If name matches a uniform in the shader source, this value will be uploaded when rendering.
280 * @param name The name of the uniform.
281 * @param value The value to to set.
282 * @param uniformCoordinateType The coordinate type of the uniform.
283 * @pre Either the property name is not in use, or a property exists with the correct name & type.
285 void SetUniform( const std::string& name,
287 UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
291 * @brief Set a uniform value.
293 * This will register a property of type Property::VECTOR2; see Object::RegisterProperty() for more details.
294 * If name matches a uniform in the shader source, this value will be uploaded when rendering.
296 * @param name The name of the uniform.
297 * @param value The value to to set.
298 * @param uniformCoordinateType The coordinate type of the uniform.
299 * @pre Either the property name is not in use, or a property exists with the correct name & type.
301 void SetUniform( const std::string& name,
303 UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
307 * @brief Set a uniform value.
309 * This will register a property of type Property::VECTOR3; see Object::RegisterProperty() for more details.
310 * If name matches a uniform in the shader source, this value will be uploaded when rendering.
312 * @param name The name of the uniform.
313 * @param value The value to to set.
314 * @param uniformCoordinateType The coordinate type of the uniform.
315 * @pre Either the property name is not in use, or a property exists with the correct name & type.
317 void SetUniform( const std::string& name,
319 UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
323 * @brief Set a uniform value.
325 * This will register a property of type Property::VECTOR4; see Object::RegisterProperty() for more details.
326 * If name matches a uniform in the shader source, this value will be uploaded when rendering.
328 * @param name The name of the uniform.
329 * @param value The value to to set.
330 * @param uniformCoordinateType The coordinate type of the uniform.
331 * @pre Either the property name is not in use, or a property exists with the correct name & type.
333 void SetUniform( const std::string& name,
335 UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
339 * @brief Set a uniform value.
341 * This will register a property of type Property::MATRIX; see Object::RegisterProperty() for more details.
342 * If name matches a uniform in the shader source, this value will be uploaded when rendering.
344 * @param name The name of the uniform.
345 * @param value The value to to set.
346 * @param uniformCoordinateType The coordinate type of the uniform.
347 * @pre Either the property name is not in use, or a property exists with the correct name & type.
349 void SetUniform( const std::string& name,
351 UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
355 * @brief Set a uniform value.
357 * This will register a property of type Property::MATRIX3; see Object::RegisterProperty() for more details.
358 * If name matches a uniform in the shader source, this value will be uploaded when rendering.
360 * @param name The name of the uniform.
361 * @param value The value to to set.
362 * @param uniformCoordinateType The coordinate type of the uniform.
363 * @pre Either the property name is not in use, or a property exists with the correct name & type.
365 void SetUniform( const std::string& name,
366 const Matrix3& value,
367 UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
369 public: // Not intended for application developers
373 * @brief This constructor is used by Dali New() methods.
375 * @param [in] effect A pointer to a newly allocated Dali resource.
377 explicit DALI_INTERNAL ShaderEffect(Internal::ShaderEffect* effect);
385 #endif // __DALI_SHADER_EFFECT_H__