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