dali-toolkit/devel-api/shader-effects/soft-button-effect.h

   1 #ifndef __DALI_TOOLKIT_SHADER_EFFECT_SOFT_BUTTON_H__
   2 #define __DALI_TOOLKIT_SHADER_EFFECT_SOFT_BUTTON_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 soft button shader that works on a per object basis. Using animatable parameters user can create effect of button pushing in / out. Can be applied to ImageActor only.
  33  *
  34  * Usage example:-
  35  *
  36  * // Create shader used for doing soft button\n
  37  * SoftButtonEffect softButtonEffect = SoftButtonEffect::New();
  38  *
  39  * // set image actor shader to the soft button one\n
  40  * ImageActor imageActor = ImageActor::New( ... );\n
  41  * imageActor.SetShaderEffect( softButtonEffect );
  42  *
  43  * // animate a button push, using e.g. AlphaFunction::BOUNCE. With these values the button pushes in and pops out slightly at the end\n
  44  * Animation animation = Animation::New( ... );\n
  45  * animation.AnimateTo( Property(softButtonEffect, softButtonEffect.GetLightingIndentationAmountPropertyName()), 0.25f, AlphaFunction::BOUNCE, ... );\n
  46  * animation.AnimateTo( Property(softButtonEffect, softButtonEffect.GetLightingIndentationAmountPropertyName()), -0.05f, AlphaFunction::BOUNCE, ... );\n
  47  * animation.AnimateTo( Property(softButtonEffect, softButtonEffect.GetTextureDistortionAmountPropertyName()), 0.25f, AlphaFunction::BOUNCE, ... );\n
  48  * animation.AnimateTo( Property(softButtonEffect, softButtonEffect.GetTextureDistortionAmountPropertyName()), -0.05f, AlphaFunction::BOUNCE, ... );\n
  49  * animation.Play();\n
  50  *
  51  */
  52 class DALI_IMPORT_API SoftButtonEffect : public ShaderEffect
  53 {
  54
  55 public:
  56
  57   /**
  58    * Create an uninitialized SoftButtonEffect; this can be initialized with SoftButtonEffect::New()
  59    * Calling member functions with an uninitialized Dali::Object is not allowed.
  60    */
  61   SoftButtonEffect();
  62
  63   /**
  64    * @brief Destructor
  65    *
  66    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  67    */
  68   ~SoftButtonEffect();
  69
  70   typedef enum
  71   {
  72     ELLIPTICAL = 0,   /// Button is elliptical
  73     RECTANGULAR,      /// Button is rectangular
  74     FIXED             /// Button does not indent (move). Useful for matching lighting between areas that do not indent (which can thus use a cheaper shader) and those that do indent.
  75   }Type;
  76
  77   /**
  78    * Create an initialized SoftButtonEffect
  79    * @param type The type of the soft button, can be either ELLIPTICAL, RECTANGULAR, or FIXED.
  80    * @return A handle to a newly allocated Dali resource.
  81    */
  82   static SoftButtonEffect New(Type type);
  83
  84   /**
  85    * Get the name for the lighting indentation amount property (float). Useful for animation.
  86    * This property changes the lighting, to make it look like the button is pushed in. User should animate this in conjunction
  87    * with texture distortion. Allowable values range from [-1..1], higher values give more change in lighting. Default 0.0 (no lighting change).
  88    * See also GetTextureDistortionAmountPropertyName().
  89    * @return A std::string containing the property name
  90    */
  91   const std::string& GetLightingIndentationAmountPropertyName() const;
  92
  93   /**
  94    * Get the name for the texture distortion amount property (float). Useful for animation.
  95    * This property changes the distortion, to make it look like the button is pushed in. User should animate this is conjunction
  96    * with lighting indentation. Allowable values range from [-1..1) - note 1.0 is NOT allowed - higher values give more distortion. Default 0.0 (no distortion).
  97    * See also GetLightingIndentationAmountPropertyName().
  98    * @return A std::string containing the property name
  99    */
 100   const std::string& GetTextureDistortionAmountPropertyName() const;
 101
 102   /**
 103    * Get the name for the ambient lighting amount property (float)
 104    * The ambient light is used in the lighting calculation. Care must be taken to not saturate the image by setting this value too high,
 105    * or the indentation will not look correct. Default 0.15.
 106    * @return A std::string containing the property name
 107    */
 108   const std::string& GetAmbientLightAmountPropertyName() const;
 109
 110   /**
 111    * Get the name for the diffuse light property (Vector3).
 112    * The diffuse light is used in the lighting calculation. Default is (0.0, 0.7070168, 0.7070168), i.e. a light angled at the surface from in front and above. Note that
 113    * you need to Normalize() the Vector3 that you set with this property.
 114    * @return A std::string containing the property name
 115    */
 116   const std::string& GetDiffuseLightPropertyName() const;
 117
 118   /**
 119    * Get the name for the lighting multiplier property (float).
 120    * The ambient and diffuse lighting is multiplied by this factor. Since a diffuse light at an angle will cause the whole image to darken, even outside the soft button
 121    * indentation, 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,
 122    * or the indentation will not look correct. Default 1.2.
 123    * @return A std::string containing the property name
 124    */
 125   const std::string& GetLightingMultiplierPropertyName() const;
 126
 127   /**
 128    * Get the name for the inside shape size scale property (float).
 129    * The SoftButtonEffect consists of two shapes, one inside the other. The outside shape fits exactly to the actor, touching its edges but completely contained. The inside
 130    * shape size is given by a multiplier of the outside shape size. For example a value of 0.5 means that the inside shape is half the size of the outside one. Allowable
 131    * values are in the range (0.0 - 1.0), note that 0.0 and 1.0 themselves are not allowed. Default 0.75.
 132    * See also GetOutsideShapeDepthPropertyName().
 133    * @return A std::string containing the property name
 134    */
 135   const std::string& GetInsideShapeSizeScalePropertyName() const;
 136
 137   /**
 138    * Get the name for the outside shape depth property (float).
 139    * The SoftButtonEffect consists of two shapes, one inside the other. The depth of the indentation at the transition between the inside and outside shapes is controlled by
 140    * this property. The values lies in the range [0.0 - 1.0]. A value of 0.0 means the outside shape has no depth (and is thus invisible), value of 1.0 means the outside shape
 141    * has maximum depth (and the inside shape is thus invisible). Default 0.05.
 142    * See also GetInsideShapeSizeScalePropertyName().
 143    * @return A std::string containing the property name
 144    */
 145   const std::string& GetOutsideShapeDepthPropertyName() const;
 146
 147   /**
 148    * Get the name for the effect pixel area property (Vector4).
 149    * The soft button effect is applied within the supplied rect region of the texture. Default values for this is (0.0, 0.0, 1.0, 1.0) which is the entire image with
 150    * 0,0 being the top left and 1.0, 1.0 being the bottom right. If the image texture is split between multiple ImageActors then the developer should specify the
 151    * pixel area of the texture the effect should be applied with. Example, If the Image is split among two ImageActors side by side, with the left one using left half of the
 152    * texture and right one using the right half of the texture then the pixel area value for the left ImageActor will be (0.0, 0.0, 0.5, 1.0) and the pixel area for the right
 153    * will be (0.5, 0.0, 1.0, 1.0).
 154    * @return A std::string containing the property name
 155    */
 156   const std::string& GetEffectPixelAreaPropertyName() const;
 157
 158   /**
 159    * Get the name for the rectangle size scale property (float). Only applicable having created this SoftButtonEffect via a call to New() with RECTANGULAR as the type.
 160    * This property can be used to set the mix between proportion of rectangle and proportion of ellipse - the result is a rectangle with rounded corners. If the value is 0.0,
 161    * the shape is an ellipse. If the value is close to 1.0, the shape is close to a rectangle. The value lies in the range [0.0 - 1.0). Note that a value of 1.0 is NOT allowed.
 162    * Default 0.5.
 163    * @return A std::string containing the property name
 164    */
 165   const std::string& GetRectangleSizeScalePropertyName() const;
 166
 167
 168 private:
 169   // Not intended for application developers
 170   DALI_INTERNAL SoftButtonEffect(ShaderEffect handle);
 171 };
 172
 173 }
 174
 175 }
 176
 177 #endif //#ifndef __DALI_TOOLKIT_SHADER_EFFECT_SOFT_BUTTON_H__