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