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) 2014 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/animation/active-constraint-declarations.h>
  23 #include <dali/public-api/object/constrainable.h>
  24
  25 namespace Dali DALI_IMPORT_API
  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 Constraint;
  54 class Image;
  55 struct Vector2;
  56 struct Vector3;
  57 struct Vector4;
  58
  59 namespace Internal DALI_INTERNAL
  60 {
  61 class ShaderEffect;
  62 }
  63
  64 /**
  65  * @brief GeometryType determines how geometry is shaped.
  66  */
  67 enum GeometryType
  68 {
  69   GEOMETRY_TYPE_IMAGE = 0x01,         ///< image, with flat color or texture
  70   GEOMETRY_TYPE_TEXT = 0x02,          ///< text, with flat color or texture
  71   GEOMETRY_TYPE_MESH = 0x04,          ///< Complex meshes, with flat color
  72   GEOMETRY_TYPE_TEXTURED_MESH = 0x08, ///< Complex meshes, with texture
  73   GEOMETRY_TYPE_LAST = 0x10
  74 };
  75
  76 /**
  77  * @brief Shader effects provide a visual effect for actors.
  78  *
  79  * For a Custom shader you can provide the vertex and fragment shader code as strings.
  80  * These shader snippets get concatenated with the default attributes and uniforms.
  81  * For a vertex shader this part contains the following code:
  82  * <pre>
  83  * precision highp float;
  84  * attribute vec3  aPosition;
  85  * attribute vec2  aTexCoord;
  86  * uniform   mat4  uMvpMatrix;
  87  * uniform   mat4  uModelMatrix;
  88  * uniform   mat4  uViewMatrix;
  89  * uniform   mat4  uModelView;
  90  * uniform   mat3  uNormalMatrix;
  91  * uniform   mat4  uProjection;
  92  * uniform   vec4  uColor;
  93  * varying   vec2  vTexCoord;
  94  * </pre>
  95  * The custom shader part is expected to output the vertex position and texture coordinate.
  96  * A basic custom vertex shader would contain the following code:
  97  * <pre>
  98  * void main()
  99  * {
 100  *   gl_Position = uProjection * uModelView * vec4(aPosition, 1.0);
 101  *   vTexCoord = aTexCoord;
 102  * }
 103  * </pre>
 104  * For fragment shader the default part for images contains the following code:
 105  * <pre>
 106  * precision mediump float;
 107  * uniform   sampler2D sTexture;
 108  * uniform   sampler2D sEffect;
 109  * uniform   vec4      uColor;
 110  * varying   vec2      vTexCoord;
 111  * </pre>
 112  * and for text:
 113  * <pre>
 114  * \#extension GL_OES_standard_derivatives : enable
 115  * uniform   mediump sampler2D sTexture;
 116  * uniform   lowp    vec4      uColor;
 117  * uniform   lowp    vec4      uTextColor;
 118  * uniform   mediump float     uSmoothing;
 119  * varying   mediump vec2      vTexCoord;
 120  * </pre>
 121  * and the custom shader is expected to output the fragment color.
 122  * The basic fragment shader for images would contain:
 123  * <pre>
 124  * void main()
 125  * {
 126  *   gl_FragColor = texture2D( sTexture, vTexCoord ) * uColor;
 127  * }
 128  * </pre>
 129  * and for text::
 130  * <pre>
 131  *  void main()
 132  *  {
 133  *    // sample distance field
 134  *    mediump float distance = texture2D(sTexture, vTexCoord).a;
 135  *    mediump float smoothWidth = fwidth(distance);
 136  *    // set fragment color
 137  *    lowp vec4 color = uTextColor;
 138  *    // adjust alpha by sampled distance
 139  *    color.a *= smoothstep(uSmoothing - smoothWidth, uSmoothing + smoothWidth, distance);
 140  *    // fragment color multiplied with uColor.
 141  *    glFragColor = color * uColor;
 142  *  }
 143  * </pre>
 144  * <BR>
 145  * <B>
 146  * Note: In order for fade and color animations to work, the fragment shader needs to multiply the fragment color
 147  * with the uniform color "uColor" of the node
 148  * </B>
 149  */
 150 class ShaderEffect : public Constrainable
 151 {
 152 public:
 153   /**
 154    * @brief The Extension class is a base class for objects that can be attached to the
 155    * ShaderEffects as extensions.
 156    *
 157    * Extensions are useful to create pimpled implementations of custom shaders.
 158    * The shader effect will hold an intrusive pointer to the extension.
 159    */
 160   class Extension : public RefObject
 161   {
 162   protected:
 163     /**
 164      * @brief Disable default constructor. This a base class is not meant to be initialised on its own.
 165      */
 166     Extension();
 167
 168     /**
 169      * @brief Virtual destructor.
 170      */
 171     virtual ~Extension();
 172   };
 173
 174   // Default Properties
 175   /* Grid Density defines the spacing of vertex coordinates in world units.
 176    * ie a larger actor will have more grids at the same spacing.
 177    *
 178    *  +---+---+         +---+---+---+
 179    *  |   |   |         |   |   |   |
 180    *  +---+---+         +---+---+---+
 181    *  |   |   |         |   |   |   |
 182    *  +---+---+         +---+---+---+
 183    *                    |   |   |   |
 184    *                    +---+---+---+
 185    */
 186   static const Property::Index GRID_DENSITY;       ///< name "grid-density",   type FLOAT
 187   static const Property::Index IMAGE;              ///< name "image",          type MAP; {"filename":"", "load-policy":...}
 188   static const Property::Index PROGRAM;            ///< name "program",        type MAP; {"vertex-filename":"",...}
 189   static const Property::Index GEOMETRY_HINTS;     ///< name "geometry-hints", type INT (bitfield)
 190
 191   static const float DEFAULT_GRID_DENSITY;         ///< The default density is 40 pixels
 192
 193   /**
 194    * @brief Hints for rendering/subdividing geometry.
 195    */
 196   enum GeometryHints
 197   {
 198     HINT_NONE           = 0x00,   ///< no hints
 199     HINT_GRID_X         = 0x01,   ///< Geometry must be subdivided in X
 200     HINT_GRID_Y         = 0x02,   ///< Geometry must be subdivided in Y
 201     HINT_GRID           = (HINT_GRID_X | HINT_GRID_Y),
 202     HINT_DEPTH_BUFFER   = 0x04,   ///< Needs depth buffering turned on
 203     HINT_BLENDING       = 0x08,   ///< Notifies the actor to use blending even if it's fully opaque. Needs actor's blending set to BlendingMode::AUTO
 204     HINT_DOESNT_MODIFY_GEOMETRY = 0x10 ///< Notifies that the vertex shader will not change geometry (enables bounding box culling)
 205   };
 206
 207   /**
 208    * @brief Coordinate type of the shader uniform.
 209    *
 210    * Viewport coordinate types will convert from viewport to view space.
 211    * Use this coordinate type if your are doing a transformation in view space.
 212    * The texture coordinate type converts a value in actor local space to texture coodinates.
 213    * This is useful for pixel shaders and accounts for texture atlas.
 214    */
 215   enum UniformCoordinateType
 216   {
 217     COORDINATE_TYPE_DEFAULT,            ///< Default, No transformation to be applied
 218     COORDINATE_TYPE_VIEWPORT_POSITION,  ///< The uniform is a position vector in viewport coordinates that needs to be converted to GL view space coordinates.
 219     COORDINATE_TYPE_VIEWPORT_DIRECTION, ///< The uniform is a directional vector in viewport coordinates that needs to be converted to GL view space coordinates.
 220     COORDINATE_TYPE_TEXTURE_POSITION    ///< The uniform is a position in texture coordinates.
 221   };
 222
 223   /**
 224    * @brief Create an empty ShaderEffect.
 225    *
 226    * This can be initialised with ShaderEffect::New(...)
 227    */
 228   ShaderEffect();
 229
 230   /**
 231    * @brief Create ShaderEffect.
 232    *
 233    * @param vertexShader code for the effect. If you pass in an empty string, the default version will be used
 234    * @param fragmentShader code for the effect. If you pass in an empty string, the default version will be used
 235    * @param type GeometryType to define the shape of the geometry
 236    * @param hints GeometryHints to define the geometry of the rendered object
 237    * @return A handle to a shader effect
 238    */
 239   static ShaderEffect New( const std::string& vertexShader,
 240                            const std::string& fragmentShader,
 241                            GeometryType type = GeometryType(GEOMETRY_TYPE_IMAGE),
 242                            GeometryHints hints = GeometryHints(HINT_NONE) );
 243
 244   /**
 245    * @brief Create ShaderEffect.
 246    * @param vertexShaderPrefix code for the effect. It will be inserted before the default uniforms (ideal for \#defines)
 247    * @param vertexShader code for the effect. If you pass in an empty string, the default version will be used
 248    * @param fragmentShaderPrefix code for the effect. It will be inserted before the default uniforms (ideal for \#defines)
 249    * @param fragmentShader code for the effect. If you pass in an empty string, the default version will be used
 250    * @param type GeometryType to define the shape of the geometry
 251    * @param hints GeometryHints to define the geometry of the rendered object
 252    * @return A handle to a shader effect
 253    */
 254   static ShaderEffect NewWithPrefix(const std::string& vertexShaderPrefix,
 255                                     const std::string& vertexShader,
 256                                     const std::string& fragmentShaderPrefix,
 257                                     const std::string& fragmentShader,
 258                                     GeometryType type = GeometryType(GEOMETRY_TYPE_IMAGE),
 259                                     GeometryHints hints = GeometryHints(HINT_NONE) );
 260
 261   /**
 262    * @brief Create ShaderEffect.
 263    * @param imageVertexShader code for the effect. If you pass in an empty string, the default version will be used
 264    * @param imageFragmentShader code for the effect. If you pass in an empty string, the default version will be used
 265    * @param textVertexShader code for the effect. If you pass in an empty string, the default version will be used
 266    * @param textFragmentShader code for the effect. If you pass in an empty string, the default version will be used
 267    * @param hints GeometryHints to define the geometry of the rendered object
 268    * @return A handle to a shader effect
 269    */
 270   static ShaderEffect New( const std::string& imageVertexShader,
 271                            const std::string& imageFragmentShader,
 272                            const std::string& textVertexShader,
 273                            const std::string& textFragmentShader,
 274                            GeometryHints hints = GeometryHints(HINT_NONE) );
 275
 276   /**
 277    * @brief Create ShaderEffect.
 278    * @param imageVertexShader code for the effect. If you pass in an empty string, the default version will be used
 279    * @param imageFragmentShader code for the effect. If you pass in an empty string, the default version will be used
 280    * @param textVertexShader code for the effect. If you pass in an empty string, the default version will be used
 281    * @param textFragmentShader code for the effect. If you pass in an empty string, the default version will be used
 282    * @param texturedMeshVertexShader code for the effect. If you pass in an empty string, the default version will be used
 283    * @param texturedMeshFragmentShader code for the effect. If you pass in an empty string, the default version will be used
 284    * @param meshVertexShader code for the effect. If you pass in an empty string, the default version will be used
 285    * @param meshFragmentShader code for the effect. If you pass in an empty string, the default version will be used
 286    * @param hints GeometryHints to define the geometry of the rendered object
 287    * @return A handle to a shader effect
 288    */
 289   static ShaderEffect New( const std::string& imageVertexShader,
 290                            const std::string& imageFragmentShader,
 291                            const std::string& textVertexShader,
 292                            const std::string& textFragmentShader,
 293                            const std::string& texturedMeshVertexShader,
 294                            const std::string& texturedMeshFragmentShader,
 295                            const std::string& meshVertexShader,
 296                            const std::string& meshFragmentShader,
 297                            GeometryHints hints = GeometryHints(HINT_NONE) );
 298
 299   /**
 300    * @brief Downcast an Object handle to ShaderEffect.
 301    *
 302    * If handle points to a ShaderEffect the downcast produces valid
 303    * handle. If not the returned handle is left uninitialized.
 304    *
 305    * @param[in] handle to An object
 306    * @return handle to a ShaderEffect object or an uninitialized handle
 307    */
 308   static ShaderEffect DownCast( BaseHandle handle );
 309
 310   /**
 311    * @brief Destructor
 312    *
 313    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 314    */
 315   ~ShaderEffect();
 316
 317   /**
 318    * @brief Copy constructor
 319    *
 320    * @param object A reference to a ShaderEffect object
 321    */
 322   ShaderEffect(const ShaderEffect& object);
 323
 324   /**
 325    * @brief This assignment operator is required for (smart) pointer semantics.
 326    *
 327    * @param [in] rhs  A reference to the copied handle
 328    * @return A reference to this
 329    */
 330   ShaderEffect& operator=(const ShaderEffect& rhs);
 331
 332   /**
 333    * @brief This method is defined to allow assignment of the NULL value,
 334    * and will throw an exception if passed any other value.
 335    *
 336    * Assigning to NULL is an alias for Reset().
 337    * @param [in] rhs  A NULL pointer
 338    * @return A reference to this handle
 339    */
 340   ShaderEffect& operator=(BaseHandle::NullType* rhs);
 341
 342   /**
 343    * @brief Sets image for using as effect texture.
 344    *
 345    * This image texture will be bound to the "sEffect" sampler
 346    * so it can be used in fragment shader for effects
 347    *
 348    * @param[in] image to use as effect texture
 349    */
 350   void SetEffectImage( Image image );
 351
 352   /**
 353    * @brief Set a uniform value.
 354    * This will register a property of type Property::FLOAT; see Object::RegisterProperty() for more details.
 355    * If name matches a uniform in the shader source, this value will be uploaded when rendering.
 356    * @pre Either the property name is not in use, or a property exists with the correct name & type.
 357    * @param name The name of the uniform.
 358    * @param value The value to to set.
 359    * @param uniformCoordinateType The coordinate type of the uniform.
 360    */
 361   void SetUniform( const std::string& name,
 362                    float value,
 363                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 364
 365   /**
 366    * @brief Set a uniform value.
 367    *
 368    * This will register a property of type Property::VECTOR2; see Object::RegisterProperty() for more details.
 369    * If name matches a uniform in the shader source, this value will be uploaded when rendering.
 370    * @pre Either the property name is not in use, or a property exists with the correct name & type.
 371    * @param name The name of the uniform.
 372    * @param value The value to to set.
 373    * @param uniformCoordinateType The coordinate type of the uniform.
 374    */
 375   void SetUniform( const std::string& name,
 376                    Vector2 value,
 377                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 378
 379   /**
 380    * @brief Set a uniform value.
 381    *
 382    * This will register a property of type Property::VECTOR3; see Object::RegisterProperty() for more details.
 383    * If name matches a uniform in the shader source, this value will be uploaded when rendering.
 384    * @pre Either the property name is not in use, or a property exists with the correct name & type.
 385    * @param name The name of the uniform.
 386    * @param value The value to to set.
 387    * @param uniformCoordinateType The coordinate type of the uniform.
 388    */
 389   void SetUniform( const std::string& name,
 390                    Vector3 value,
 391                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 392
 393   /**
 394    * @brief Set a uniform value.
 395    *
 396    * This will register a property of type Property::VECTOR4; see Object::RegisterProperty() for more details.
 397    * If name matches a uniform in the shader source, this value will be uploaded when rendering.
 398    * @pre Either the property name is not in use, or a property exists with the correct name & type.
 399    * @param name The name of the uniform.
 400    * @param value The value to to set.
 401    * @param uniformCoordinateType The coordinate type of the uniform.
 402    */
 403   void SetUniform( const std::string& name,
 404                    Vector4 value,
 405                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 406
 407   /**
 408    * @brief Set a uniform value.
 409    *
 410    * This will register a property of type Property::MATRIX; see Object::RegisterProperty() for more details.
 411    * If name matches a uniform in the shader source, this value will be uploaded when rendering.
 412    * @pre Either the property name is not in use, or a property exists with the correct name & type.
 413    * @param name The name of the uniform.
 414    * @param value The value to to set.
 415    * @param uniformCoordinateType The coordinate type of the uniform.
 416    */
 417   void SetUniform( const std::string& name,
 418                    const Matrix& value,
 419                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 420
 421   /**
 422    * @brief Set a uniform value.
 423    *
 424    * This will register a property of type Property::MATRIX3; see Object::RegisterProperty() for more details.
 425    * If name matches a uniform in the shader source, this value will be uploaded when rendering.
 426    * @pre Either the property name is not in use, or a property exists with the correct name & type.
 427    * @param name The name of the uniform.
 428    * @param value The value to to set.
 429    * @param uniformCoordinateType The coordinate type of the uniform.
 430    */
 431   void SetUniform( const std::string& name,
 432                    const Matrix3& value,
 433                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 434
 435   /**
 436    * @brief Attach an extension object.
 437    *
 438    * This object is reference counted and will be automatically deleted.
 439    * This object can be retrieved back with the GetExtension function.
 440    * @param object Pointer to a Extension.
 441    * @pre extension is not NULL
 442    */
 443   void AttachExtension( Extension *object );
 444
 445   /**
 446    * @brief Retrieve the attached extension object.
 447    *
 448    * This object can be set with the AttachExtension function.
 449    * @return implementation Pointer to a Extension.
 450    * @pre An extension needs to be attached previously.
 451    */
 452   Extension& GetExtension();
 453
 454   /**
 455    * @brief Retrieve the attached extension object.
 456    *
 457    * This object can be set with the AttachExtension function.
 458    * @return implementation Pointer to a Extension.
 459    * @pre An extension needs to be attached previously.
 460    */
 461   const Extension& GetExtension() const;
 462
 463
 464 public: // Not intended for application developers
 465
 466   /**
 467    * @brief This constructor is used by Dali New() methods.
 468    * @param [in] effect A pointer to a newly allocated Dali resource.
 469    */
 470   explicit DALI_INTERNAL ShaderEffect(Internal::ShaderEffect* effect);
 471 };
 472
 473 } // namespace Dali
 474
 475 #endif // __DALI_SHADER_EFFECT_H__