dali-toolkit/devel-api/shader-effects/displacement-effect.h

   1 #ifndef __DALI_TOOLKIT_SHADER_EFFECT_DISPLACEMENT_H__
   2 #define __DALI_TOOLKIT_SHADER_EFFECT_DISPLACEMENT_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 // EXTERNAL INCLUDES
  22 #include <dali/public-api/shader-effects/shader-effect.h>
  23
  24 namespace Dali
  25 {
  26
  27 namespace Toolkit
  28 {
  29
  30 /**
  31  *
  32  * Class for two state displacement effect shader that works on a per object basis. By passing a height-normal map as an effect image, the user can create
  33  * various styles of buttons on an image actor. The shader requires two height-normal maps in one image, one for each state.
  34  *
  35  *    The normals and height information for the two states of the button should be strictly specified in this format:
  36  *     ______________
  37  *    |   State 0    |
  38  *    |              |
  39  *    |              | --> Unpressed button normals in rgb and height in a
  40  *    |     Map      |
  41  *    |______________|
  42  *    |   State 1    |
  43  *    |              |
  44  *    |              | --> Pressed button normals in rgb and height in a
  45  *    |     Map      |
  46  *    |______________|
  47  *
  48  *    The RGB values should contain the surface normals and the alpha should contian the height map. For a better effect keep the highest point (alpha value) in
  49  *    the combined map as 1.0 and the lowest posint as 0.0 and 0.5 for any region which doesn't need displacement.
  50  *
  51  *    For the supplied Normal map the Y-Axis should be down, Meaning (0,0) is in the top left. As the shader inverts the Y axis for lighting calculation.
  52  *
  53  *    Limitations: Can be applied to ImageActor only, And doesn't provide support for specular color.
  54  *
  55  * Usage example:-
  56  *
  57  * // Create shader used for doing soft button\n
  58  * DisplacementEffect buttonEffect = DisplacementEffect::New();
  59  * buttonEffect.SetEffectImage(Image::New( FANCY_BUTTON_HEIGHT_MAP_IMAGE_PATH ););
  60  *
  61  * // set shader to the soft button\n
  62  * ImageActor fancyButton = ImageActor::New( ... );\n
  63  * fancyButton.SetShaderEffect( buttonEffect );
  64  *
  65  * // animate a button push, using e.g. AlphaFunction::BOUNCE. With these values the button pushes in and out (animates to and fro between the two states)
  66  *
  67  *
  68  * Animation animation = Animation::New( ... );\n
  69  * animation.AnimateTo( Property(buttonEffect, buttonEffect.GetStatePropertyName()), 1.0f, AlphaFunction::BOUNCE, ... );\n
  70  * animation.Play();\n
  71  *
  72  */
  73 class DALI_IMPORT_API DisplacementEffect : public ShaderEffect
  74 {
  75
  76 public:
  77
  78   typedef enum
  79   {
  80     DISPLACED = 0,    /// Image gets displaced
  81     FIXED             /// Image does not displace. Useful for matching lighting between areas that do not displace and those that do, e.g for backgrounds which are visible between buttons.
  82   }Type;
  83
  84   /**
  85    * Create an uninitialized DisplacementEffect; this can be initialized with DisplacementEffect::New()
  86    * Calling member functions with an uninitialized Dali::Object is not allowed.
  87    */
  88   DisplacementEffect();
  89
  90   /**
  91    * @brief Destructor
  92    *
  93    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  94    */
  95   ~DisplacementEffect();
  96
  97   /**
  98    * Create an initialized DisplacementEffect
  99    * @param type The type of the effect, can be either DISPLACED, or FIXED.
 100    * @return A handle to a newly allocated Dali resource.
 101    */
 102   static DisplacementEffect New(Type type);
 103
 104   /**
 105    * Get the name for the light direction property (Vector3)
 106    * The light direction is used in the lighting calculation. The angle of incidence directly affects the amount of light reflected.
 107    * Default (0.0f, 0.7070168f, 0.7071068f), i.e angled at the surface from in front and above.
 108    * @return A std::string containing the property name
 109    */
 110   const std::string& GetLightDirectionPropertyName() const;
 111
 112   /**
 113    * Get the name for the ambient lighting color property (Vector3)
 114    * The ambient light is used in the lighting calculation. Care must be taken to not saturate the image by setting this value too high,
 115    * or the indentation will not look correct. Default 0.15.
 116    * @return A std::string containing the property name
 117    */
 118   const std::string& GetAmbientLightColorPropertyName() const;
 119
 120   /**
 121    * Get the name for the diffuse light color property (Vector3).
 122    * The diffuse light is used in the lighting calculation. Default is (1.0f, 1.0f, 1.0f).
 123    * @return A std::string containing the property name
 124    */
 125   const std::string& GetDiffuseLightColorPropertyName() const;
 126
 127   /**
 128    * Get the name for the lighting multiplier property (float).
 129    * The ambient and diffuse lighting is multiplied by this factor. Since a diffuse light at an angle will cause the whole image to darken,
 130    * this property can be used to scale the image back up closer to the pixel values of the original diffuse texture. Care must be taken to not saturate the image,
 131    * or the indentation will not look correct. Default 1.0
 132    * @return A std::string containing the property name
 133    */
 134   const std::string& GetLightingMultiplierPropertyName() const;
 135
 136   /**
 137    * Get the name for the state property (float).
 138    * The shader can have a maximum of two end states 0 or 1, Animate between these two values to do the transitions between states.
 139    * Default 0.0
 140    * @return A std::string containing the property name.
 141    */
 142   const std::string& GetStatePropertyName() const;
 143
 144   /**
 145    * Get the name for the height scale property (float).
 146    * The height displacement is multiplied by this factor. Tweak this to get the required level of depth.
 147    * Default 0.1
 148    * @return A std::string containing the property name.
 149    */
 150   const std::string& GetHeightScalePropertyName() const;
 151
 152   /**
 153    * Get the name for the fixed normal property (Vector3).
 154    * Only applicable for the FIXED type shader and not for DISPLACEMENT type.
 155    * The Fixed normal will be used for the light calculation. Tweak this to get the required level of light.
 156    * Default (0.0f, 0.0f, 1.0f)
 157    * @return A std::string containing the property name.
 158    */
 159   const std::string& GetFixedNormalPropertyName() const;
 160
 161   /**
 162    * Set the light direction property
 163    * The light direction is used in the lighting calculation. The angle of incidence directly affects the amount of light reflected.
 164    * Default (0.0f, 0.7070168f, 0.7071068f), i.e angled at the surface from in front and above.
 165    * @param [in] lightDirection The new light direction.
 166    */
 167   void SetLightDirection(Vector3 lightDirection);
 168
 169   /**
 170    * Set the ambient light color property
 171    * The ambient light is used in the lighting calculation. Care must be taken to not saturate the image by setting this value too high,
 172    * or the indentation will not look correct. Default (0.15f, 0.15f, 0.15f).
 173    * @param [in] ambientLight The new ambient light value.
 174    */
 175   void SetAmbientLightColorProperty(Vector3 ambientLight);
 176
 177   /**
 178    * Set the diffuse light color property.
 179    * The diffuse light is used in the lighting calculation. Default is (1.0f, 1.0f, 1.0f), i.e. a white light so the natural image color is shown.
 180    * @param [in] diffuseLight The new diffuse light value.
 181    */
 182   void SetDiffuseLightColorProperty(Vector3 diffuseLight);
 183
 184   /**
 185    * Get the name for the lighting multiplier property.
 186    * The ambient and diffuse lighting is multiplied by this factor. Since a diffuse light at an angle will cause the whole image to darken,
 187    * this property can be used to scale the image back up closer to the pixel values of the original diffuse texture. Care must be taken to not saturate the image,
 188    * or the indentation will not look correct. Default 1.0
 189    * @param [in] lightMultiplier The new light multiplier value.
 190    */
 191   void SetLightingMultiplierProperty(float lightMultiplier);
 192
 193   /**
 194    * Get the name for the state property.
 195    * The shader can only be in or in between two states 0 or 1, Animate between these two values to do the transitions between states.
 196    * @param [in] state The new state value.
 197    */
 198   void SetStateProperty(float state);
 199
 200   /**
 201    * Set the name for the height scale property.
 202    * The height displacement is multiplied by this factor. Tweak this to get the required level of depth. Default 0.1
 203    * @param [in] heightScale The new height scale.
 204    */
 205   void SetHeightScaleProperty(float heightScale);
 206
 207   /**
 208    * Set the name for fixed normal property, Only applicable for the FIXED type shader and not for DISPLACEMENT type.
 209    * The Fixed normal will be used for the light calculation. Tweak this to get the required level of light.
 210    * @param [in] fixedNormal The new normal for the fixed type shader effect.
 211    */
 212   void SetFixedNormalProperty(Vector3 fixedNormal);
 213
 214 private:
 215   // Not intended for application developers
 216   DALI_INTERNAL DisplacementEffect(ShaderEffect handle);
 217 };
 218
 219 }
 220
 221 }
 222
 223 #endif //#ifndef __DALI_TOOLKIT_SHADER_EFFECT_DISPLACEMENT_H__