dali/public-api/shader-effects/shader-effect.h

   1 #ifndef __DALI_SHADER_EFFECT_H__
   2 #define __DALI_SHADER_EFFECT_H__
   3
   4 /*
   5  * Copyright (c) 2015 Samsung Electronics Co., Ltd.
   6  *
   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
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  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.
  18  *
  19  */
  20
  21 // INTERNAL INCLUDES
  22 #include <dali/public-api/object/handle.h>
  23 #include <dali/public-api/object/property-index-ranges.h>
  24
  25 namespace Dali
  26 {
  27
  28 /**
  29  * @brief DALI_COMPOSE_SHADER macro provides a convenient way to write shader source code.
  30  *
  31  * We normally use double quotation marks to write a string such as "Hello World".
  32  * However many symbols are needed to add multiple lines of string.
  33  * We don't need to write quotation marks using this macro at every line.
  34  *
  35  * [An example of double quotation marks usage]
  36  * const string FRAGMENT_SHADER_SOURCE = \
  37  * "  void main()\n"
  38  * "  {\n"
  39  * "    gl_FragColor = texture2D( sTexture, vTexCoord ) * uColor;\n"
  40  * "  }\n";
  41  *
  42  * [An example of DALI_COMPOSE_SHADER usage]
  43  * const string VERTEX_SHADER_SOURCE = DALI_COMPOSE_SHADER (
  44  *   void main()
  45  *   {
  46  *     gl_Position = uProjection * uModelView * vec4(aPosition, 1.0);
  47  *     vTexCoord = aTexCoord;
  48  *   }
  49  * );
  50  */
  51 #define DALI_COMPOSE_SHADER(STR) #STR
  52
  53 class Image;
  54 struct Vector2;
  55 struct Vector3;
  56 struct Vector4;
  57
  58 namespace Internal DALI_INTERNAL
  59 {
  60 class ShaderEffect;
  61 }
  62
  63 /**
  64  * @brief Shader effects provide a visual effect for image actors.
  65  *
  66  * @deprecated Use classes Dali::Shader, Dali::Material, and Dali::Sampler to implement
  67  * any new programmable shading effects.
  68  *
  69  * For a Custom shader you can provide the vertex and fragment shader code as strings.
  70  * These shader snippets get concatenated with the default attributes and uniforms.
  71  * For a vertex shader this part contains the following code:
  72  * <pre>
  73  * precision highp float;
  74  * attribute vec3  aPosition;
  75  * attribute vec2  aTexCoord;
  76  * uniform   mat4  uMvpMatrix;
  77  * uniform   mat4  uModelMatrix;
  78  * uniform   mat4  uViewMatrix;
  79  * uniform   mat4  uModelView;
  80  * uniform   mat3  uNormalMatrix;
  81  * uniform   mat4  uProjection;
  82  * uniform   vec4  uColor;
  83  * varying   vec2  vTexCoord;
  84  * </pre>
  85  * The custom shader part is expected to output the vertex position and texture coordinate.
  86  * A basic custom vertex shader would contain the following code:
  87  * <pre>
  88  * void main()
  89  * {
  90  *   gl_Position = uProjection * uModelView * vec4(aPosition, 1.0);
  91  *   vTexCoord = aTexCoord;
  92  * }
  93  * </pre>
  94  * For fragment shader the default part for images contains the following code:
  95  * <pre>
  96  * precision mediump float;
  97  * uniform   sampler2D sTexture;
  98  * uniform   sampler2D sEffect;
  99  * uniform   vec4      uColor;
 100  * varying   vec2      vTexCoord;
 101  * </pre>
 102  * <BR>
 103  * <B>
 104  * Note: In order for fade and color animations to work, the fragment shader needs to multiply the fragment color
 105  * with the uniform color "uColor" of the node
 106  * </B>
 107  */
 108 class DALI_IMPORT_API ShaderEffect : public Handle
 109 {
 110 public:
 111
 112   // Default Properties
 113   /**
 114    * @brief An enumeration of properties belonging to the Path class.
 115    * Grid Density defines the spacing of vertex coordinates in world units.
 116    * ie a larger actor will have more grids at the same spacing.
 117    *
 118    *  +---+---+         +---+---+---+
 119    *  |   |   |         |   |   |   |
 120    *  +---+---+         +---+---+---+
 121    *  |   |   |         |   |   |   |
 122    *  +---+---+         +---+---+---+
 123    *                    |   |   |   |
 124    *                    +---+---+---+
 125    */
 126   struct Property
 127   {
 128     enum
 129     {
 130       GRID_DENSITY = DEFAULT_ACTOR_PROPERTY_START_INDEX, ///< name "grid-density",   type float
 131       IMAGE,                                             ///< name "image",          type Map {"filename":"", "load-policy":...}
 132       PROGRAM,                                           ///< name "program",        type Map {"vertex-prefix":"","fragment-prefix":"","vertex":"","fragment":""}
 133       GEOMETRY_HINTS                                     ///< name "geometry-hints", type int (bitfield) values from enum GeometryHints
 134     };
 135   };
 136
 137   static const float DEFAULT_GRID_DENSITY;              ///< The default density is 40 pixels
 138
 139   /**
 140    * @brief Hints for rendering/subdividing geometry.
 141    */
 142   enum GeometryHints
 143   {
 144     HINT_NONE           = 0x00,   ///< no hints
 145     HINT_GRID_X         = 0x01,   ///< Geometry must be subdivided in X
 146     HINT_GRID_Y         = 0x02,   ///< Geometry must be subdivided in Y
 147     HINT_GRID           = (HINT_GRID_X | HINT_GRID_Y),
 148     HINT_DEPTH_BUFFER   = 0x04,   ///< Needs depth buffering turned on
 149     HINT_BLENDING       = 0x08,   ///< Notifies the actor to use blending even if it's fully opaque. Needs actor's blending set to BlendingMode::AUTO
 150     HINT_DOESNT_MODIFY_GEOMETRY = 0x10 ///< Notifies that the vertex shader will not change geometry (enables bounding box culling)
 151   };
 152
 153   /**
 154    * @brief Coordinate type of the shader uniform.
 155    *
 156    * Viewport coordinate types will convert from viewport to view space.
 157    * Use this coordinate type if your are doing a transformation in view space.
 158    * The texture coordinate type converts a value in actor local space to texture coodinates.
 159    * This is useful for pixel shaders and accounts for texture atlas.
 160    */
 161   enum UniformCoordinateType
 162   {
 163     COORDINATE_TYPE_DEFAULT,           ///< Default, No transformation to be applied
 164     COORDINATE_TYPE_VIEWPORT_POSITION, ///< The uniform is a position vector in viewport coordinates that needs to be converted to GL view space coordinates.
 165     COORDINATE_TYPE_VIEWPORT_DIRECTION ///< The uniform is a directional vector in viewport coordinates that needs to be converted to GL view space coordinates.
 166   };
 167
 168   /**
 169    * @brief Create an empty ShaderEffect.
 170    *
 171    * This can be initialised with ShaderEffect::New(...)
 172    */
 173   ShaderEffect();
 174
 175   /**
 176    * @brief Create ShaderEffect.
 177    *
 178    * @param vertexShader code for the effect. If you pass in an empty string, the default version will be used
 179    * @param fragmentShader code for the effect. If you pass in an empty string, the default version will be used
 180    * @param hints GeometryHints to define the geometry of the rendered object
 181    * @return A handle to a shader effect
 182    */
 183   static ShaderEffect New( const std::string& vertexShader,
 184                            const std::string& fragmentShader,
 185                            GeometryHints hints = GeometryHints(HINT_NONE) );
 186
 187   /**
 188    * @brief Create ShaderEffect.
 189    * @param vertexShaderPrefix code for the effect. It will be inserted before the default uniforms (ideal for \#defines)
 190    * @param vertexShader code for the effect. If you pass in an empty string, the default version will be used
 191    * @param fragmentShaderPrefix code for the effect. It will be inserted before the default uniforms (ideal for \#defines)
 192    * @param fragmentShader code for the effect. If you pass in an empty string, the default version will be used
 193    * @param hints GeometryHints to define the geometry of the rendered object
 194    * @return A handle to a shader effect
 195    */
 196   static ShaderEffect NewWithPrefix(const std::string& vertexShaderPrefix,
 197                                     const std::string& vertexShader,
 198                                     const std::string& fragmentShaderPrefix,
 199                                     const std::string& fragmentShader,
 200                                     GeometryHints hints = GeometryHints(HINT_NONE) );
 201
 202   /**
 203    * @brief Downcast an Object handle to ShaderEffect.
 204    *
 205    * If handle points to a ShaderEffect the downcast produces valid
 206    * handle. If not the returned handle is left uninitialized.
 207    *
 208    * @param[in] handle to An object
 209    * @return handle to a ShaderEffect object or an uninitialized handle
 210    */
 211   static ShaderEffect DownCast( BaseHandle handle );
 212
 213   /**
 214    * @brief Destructor
 215    *
 216    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 217    */
 218   ~ShaderEffect();
 219
 220   /**
 221    * @brief Copy constructor
 222    *
 223    * @param object A reference to a ShaderEffect object
 224    */
 225   ShaderEffect(const ShaderEffect& object);
 226
 227   /**
 228    * @brief This assignment operator is required for (smart) pointer semantics.
 229    *
 230    * @param [in] rhs  A reference to the copied handle
 231    * @return A reference to this
 232    */
 233   ShaderEffect& operator=(const ShaderEffect& rhs);
 234
 235   /**
 236    * @brief Sets image for using as effect texture.
 237    *
 238    * This image texture will be bound to the "sEffect" sampler
 239    * so it can be used in fragment shader for effects
 240    *
 241    * @param[in] image to use as effect texture
 242    */
 243   void SetEffectImage( Image image );
 244
 245   /**
 246    * @brief Set a uniform value.
 247    * This will register a property of type Property::FLOAT; see Object::RegisterProperty() for more details.
 248    * If name matches a uniform in the shader source, this value will be uploaded when rendering.
 249    * @pre Either the property name is not in use, or a property exists with the correct name & type.
 250    * @param name The name of the uniform.
 251    * @param value The value to to set.
 252    * @param uniformCoordinateType The coordinate type of the uniform.
 253    */
 254   void SetUniform( const std::string& name,
 255                    float value,
 256                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 257
 258   /**
 259    * @brief Set a uniform value.
 260    *
 261    * This will register a property of type Property::VECTOR2; see Object::RegisterProperty() for more details.
 262    * If name matches a uniform in the shader source, this value will be uploaded when rendering.
 263    * @pre Either the property name is not in use, or a property exists with the correct name & type.
 264    * @param name The name of the uniform.
 265    * @param value The value to to set.
 266    * @param uniformCoordinateType The coordinate type of the uniform.
 267    */
 268   void SetUniform( const std::string& name,
 269                    Vector2 value,
 270                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 271
 272   /**
 273    * @brief Set a uniform value.
 274    *
 275    * This will register a property of type Property::VECTOR3; see Object::RegisterProperty() for more details.
 276    * If name matches a uniform in the shader source, this value will be uploaded when rendering.
 277    * @pre Either the property name is not in use, or a property exists with the correct name & type.
 278    * @param name The name of the uniform.
 279    * @param value The value to to set.
 280    * @param uniformCoordinateType The coordinate type of the uniform.
 281    */
 282   void SetUniform( const std::string& name,
 283                    Vector3 value,
 284                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 285
 286   /**
 287    * @brief Set a uniform value.
 288    *
 289    * This will register a property of type Property::VECTOR4; see Object::RegisterProperty() for more details.
 290    * If name matches a uniform in the shader source, this value will be uploaded when rendering.
 291    * @pre Either the property name is not in use, or a property exists with the correct name & type.
 292    * @param name The name of the uniform.
 293    * @param value The value to to set.
 294    * @param uniformCoordinateType The coordinate type of the uniform.
 295    */
 296   void SetUniform( const std::string& name,
 297                    Vector4 value,
 298                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 299
 300   /**
 301    * @brief Set a uniform value.
 302    *
 303    * This will register a property of type Property::MATRIX; see Object::RegisterProperty() for more details.
 304    * If name matches a uniform in the shader source, this value will be uploaded when rendering.
 305    * @pre Either the property name is not in use, or a property exists with the correct name & type.
 306    * @param name The name of the uniform.
 307    * @param value The value to to set.
 308    * @param uniformCoordinateType The coordinate type of the uniform.
 309    */
 310   void SetUniform( const std::string& name,
 311                    const Matrix& value,
 312                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 313
 314   /**
 315    * @brief Set a uniform value.
 316    *
 317    * This will register a property of type Property::MATRIX3; see Object::RegisterProperty() for more details.
 318    * If name matches a uniform in the shader source, this value will be uploaded when rendering.
 319    * @pre Either the property name is not in use, or a property exists with the correct name & type.
 320    * @param name The name of the uniform.
 321    * @param value The value to to set.
 322    * @param uniformCoordinateType The coordinate type of the uniform.
 323    */
 324   void SetUniform( const std::string& name,
 325                    const Matrix3& value,
 326                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 327
 328 public: // Not intended for application developers
 329
 330   /**
 331    * @brief This constructor is used by Dali New() methods.
 332    * @param [in] effect A pointer to a newly allocated Dali resource.
 333    */
 334   explicit DALI_INTERNAL ShaderEffect(Internal::ShaderEffect* effect);
 335 };
 336
 337 } // namespace Dali
 338
 339 #endif // __DALI_SHADER_EFFECT_H__