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