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  * @DEPRECATED_1_0.47
  34  * @brief DALI_COMPOSE_SHADER macro provides a convenient way to write shader source code.
  35  *
  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.
  39  *
  40  * [An example of double quotation marks usage]
  41  * const string FRAGMENT_SHADER_SOURCE = \
  42  * "  void main()\n"
  43  * "  {\n"
  44  * "    gl_FragColor = texture2D( sTexture, vTexCoord ) * uColor;\n"
  45  * "  }\n";
  46  *
  47  * [An example of DALI_COMPOSE_SHADER usage]
  48  * const string VERTEX_SHADER_SOURCE = DALI_COMPOSE_SHADER (
  49  *   void main()
  50  *   {
  51  *     gl_Position = uMvpMatrix * vec4(aPosition, 1.0);
  52  *     vTexCoord = mix( sTextureRect.xy, sTextureRect.zw, aTexCoord) );
  53  *   }
  54  * );
  55  * @SINCE_1_0.0
  56  * @remarks This is an experimental feature and might not be supported in the next release. We do recommend not to use it.
  57  */
  58 #define DALI_COMPOSE_SHADER(STR) #STR
  59
  60 class Image;
  61 struct Vector2;
  62 struct Vector3;
  63 struct Vector4;
  64
  65 namespace Internal DALI_INTERNAL
  66 {
  67 class ShaderEffect;
  68 }
  69
  70 /**
  71  * @DEPRECATED_1_0.47
  72  *
  73  * @brief Shader effects provide a visual effect for image actors.
  74  *
  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:
  78  * <pre>
  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;
  90  * </pre>
  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:
  93  * <pre>
  94  * void main()
  95  * {
  96  *     gl_Position = uMvpMatrix * vec4(aPosition, 1.0);
  97  *     vTexCoord = mix( sTextureRect.xy, sTextureRect.zw, aTexCoord );
  98  * }
  99  * </pre>
 100  * For fragment shader the default part for images contains the following code:
 101  * <pre>
 102  * precision mediump float;
 103  * uniform   sampler2D sTexture;
 104  * uniform   sampler2D sEffect;
 105  * uniform   vec4      uColor;
 106  * varying   vec2      vTexCoord;
 107  * </pre>
 108  * @SINCE_1_0.0
 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.
 112  */
 113 class DALI_IMPORT_API ShaderEffect : public Handle
 114 {
 115 public:
 116
 117   // Default Properties
 118   /**
 119    * @DEPRECATED_1_0.47
 120    * @brief An enumeration of properties belonging to the ShaderEffect class.
 121    *
 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.
 124    *
 125    *  +---+---+         +---+---+---+
 126    *  |   |   |         |   |   |   |
 127    *  +---+---+         +---+---+---+
 128    *  |   |   |         |   |   |   |
 129    *  +---+---+         +---+---+---+
 130    *                    |   |   |   |
 131    *                    +---+---+---+
 132    * @SINCE_1_0.0
 133    */
 134   struct Property
 135   {
 136     enum
 137     {
 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
 142     };
 143   };
 144
 145   static const float DEFAULT_GRID_DENSITY;              ///< The default density is 40 pixels
 146
 147   /**
 148    * @DEPRECATED_1_0.47
 149    * @brief Hints for rendering/subdividing geometry.
 150    * @SINCE_1_0.0
 151    */
 152   enum GeometryHints
 153   {
 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
 161   };
 162
 163   /**
 164    * @DEPRECATED_1_0.47
 165    * @brief Coordinate type of the shader uniform.
 166    *
 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.
 171    * @SINCE_1_0.0
 172    */
 173   enum UniformCoordinateType
 174   {
 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
 178   };
 179
 180   /**
 181    * @DEPRECATED_1_0.47
 182    * @brief Create an empty ShaderEffect.
 183    *
 184    * This can be initialised with ShaderEffect::New(...)
 185    * @SINCE_1_0.0
 186    */
 187   ShaderEffect();
 188
 189   /**
 190    * @DEPRECATED_1_0.47
 191    * @brief Create ShaderEffect.
 192    *
 193    * @SINCE_1_0.0
 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
 198    */
 199   static ShaderEffect New( const std::string& vertexShader,
 200                            const std::string& fragmentShader,
 201                            GeometryHints hints = GeometryHints(HINT_NONE) );
 202
 203   /**
 204    * @DEPRECATED_1_0.47
 205    * @brief Create ShaderEffect.
 206    * @SINCE_1_0.0
 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
 213    */
 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) );
 219
 220   /**
 221    * @DEPRECATED_1_0.47
 222    * @brief Downcast a handle to ShaderEffect handle.
 223    *
 224    * If handle points to a ShaderEffect the downcast produces valid
 225    * handle. If not the returned handle is left uninitialized.
 226    *
 227    * @SINCE_1_0.0
 228    * @param[in] handle to An object
 229    * @return handle to a ShaderEffect object or an uninitialized handle
 230    */
 231   static ShaderEffect DownCast( BaseHandle handle );
 232
 233   /**
 234    * @DEPRECATED_1_0.47
 235    * @brief Destructor
 236    *
 237    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 238    * @SINCE_1_0.0
 239    */
 240   ~ShaderEffect();
 241
 242   /**
 243    * @DEPRECATED_1_0.47
 244    * @brief Copy constructor
 245    *
 246    * @SINCE_1_0.0
 247    * @param object A reference to a ShaderEffect object
 248    */
 249   ShaderEffect(const ShaderEffect& object);
 250
 251   /**
 252    * @DEPRECATED_1_0.47
 253    * @brief This assignment operator is required for (smart) pointer semantics.
 254    *
 255    * @SINCE_1_0.0
 256    * @param [in] rhs  A reference to the copied handle
 257    * @return A reference to this
 258    */
 259   ShaderEffect& operator=(const ShaderEffect& rhs);
 260
 261   /**
 262    * @DEPRECATED_1_0.47
 263    * @brief Sets image for using as effect texture.
 264    *
 265    * This image texture will be bound to the "sEffect" sampler
 266    * so it can be used in fragment shader for effects
 267    *
 268    * @SINCE_1_0.0
 269    * @param[in] image to use as effect texture
 270    */
 271   void SetEffectImage( Image image );
 272
 273   /**
 274    * @DEPRECATED_1_0.47
 275    * @brief Set a uniform value.
 276    *
 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.
 279    * @SINCE_1_0.0
 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.
 284    */
 285   void SetUniform( const std::string& name,
 286                    float value,
 287                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 288
 289   /**
 290    * @DEPRECATED_1_0.47
 291    * @brief Set a uniform value.
 292    *
 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.
 295    * @SINCE_1_0.0
 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                    Vector2 value,
 303                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 304
 305   /**
 306    * @DEPRECATED_1_0.47
 307    * @brief Set a uniform value.
 308    *
 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.
 311    * @SINCE_1_0.0
 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.
 316    */
 317   void SetUniform( const std::string& name,
 318                    Vector3 value,
 319                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 320
 321   /**
 322    * @DEPRECATED_1_0.47
 323    * @brief Set a uniform value.
 324    *
 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.
 327    * @SINCE_1_0.0
 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.
 332    */
 333   void SetUniform( const std::string& name,
 334                    Vector4 value,
 335                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 336
 337   /**
 338    * @DEPRECATED_1_0.47
 339    * @brief Set a uniform value.
 340    *
 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.
 343    * @SINCE_1_0.0
 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.
 348    */
 349   void SetUniform( const std::string& name,
 350                    const Matrix& value,
 351                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 352
 353   /**
 354    * @DEPRECATED_1_0.47
 355    * @brief Set a uniform value.
 356    *
 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.
 359    * @SINCE_1_0.0
 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.
 364    */
 365   void SetUniform( const std::string& name,
 366                    const Matrix3& value,
 367                    UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) );
 368
 369 public: // Not intended for application developers
 370
 371   /**
 372    * @internal
 373    * @DEPRECATED_1_0.47
 374    * @brief This constructor is used by Dali New() methods.
 375    * @SINCE_1_0.0
 376    * @param [in] effect A pointer to a newly allocated Dali resource.
 377    */
 378   explicit DALI_INTERNAL ShaderEffect(Internal::ShaderEffect* effect);
 379 };
 380
 381 /**
 382  * @}
 383  */
 384 } // namespace Dali
 385
 386 #endif // __DALI_SHADER_EFFECT_H__