dali/public-api/common/light.h

   1 #ifndef __DALI_LIGHT_H__
   2 #define __DALI_LIGHT_H__
   3
   4 /*
   5  * Copyright (c) 2014 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 <string>
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/public-api/object/base-handle.h>
  26
  27
  28 /**
  29  * The top level DALi namespace
  30  */
  31 namespace Dali DALI_IMPORT_API
  32 {
  33
  34 namespace Internal DALI_INTERNAL
  35 {
  36 class Light;
  37 }
  38
  39 class Light;
  40
  41 /**
  42  * @brief Light source types.
  43  */
  44 enum LightType
  45 {
  46   AMBIENT,        ///< Lights everything evenly
  47   DIRECTIONAL,    ///< Casts light evenly in a specific direction.
  48   SPOT,           ///< Casts light from a single point in the shape of a cone. Objects outside the cone are unlit. (EG: a search light)
  49   POINT           ///< Casts light outward from a single point in all directions. (EG: a light bulb)
  50 };
  51
  52 /**
  53  * @brief Encapsulates the data describing a light source.
  54  */
  55 class Light : public BaseHandle
  56 {
  57 public:
  58   /**
  59    * @brief Create an initialized Light.
  60    *
  61    * @param[in] name The light's name
  62    * @return A handle to a newly allocated Dali resource.
  63    */
  64   static Light New(const std::string& name);
  65
  66   /**
  67    * @brief Downcast an Object handle to Light handle.
  68    *
  69    * If handle points to a Light object the downcast produces valid
  70    * handle. If not the returned handle is left uninitialized.
  71    * @param[in] handle to An object
  72    * @return handle to a Light object or an uninitialized handle
  73    */
  74   static Light DownCast( BaseHandle handle );
  75
  76   /**
  77    * @brief Create an uninitialized light; this can be initialized with Light::New().
  78    *
  79    * Calling member functions with an uninitialized Dali::Object is not allowed.
  80    */
  81   Light()
  82   {
  83   }
  84
  85   /**
  86    * @brief Destructor
  87    *
  88    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  89    */
  90   ~Light();
  91
  92   /**
  93    * @brief This copy constructor is required for (smart) pointer semantics.
  94    *
  95    * @param [in] handle A reference to the copied handle
  96    */
  97   Light(const Light& handle);
  98
  99   /**
 100    * @brief This assignment operator is required for (smart) pointer semantics.
 101    *
 102    * @param [in] rhs  A reference to the copied handle
 103    * @return A reference to this
 104    */
 105   Light& operator=(const Light& rhs);
 106
 107   /**
 108    * @brief This method is defined to allow assignment of the NULL value,
 109    * and will throw an exception if passed any other value.
 110    *
 111    * Assigning to NULL is an alias for Reset().
 112    * @param [in] rhs  A NULL pointer
 113    * @return A reference to this handle
 114    */
 115   Light& operator=(BaseHandle::NullType* rhs);
 116
 117   /**
 118    * @brief Set the light's name.
 119    *
 120    * @param[in] name The light's name
 121    */
 122   void SetName(const std::string& name);
 123
 124   /**
 125    * @brief Get the light's name.
 126    *
 127    * @return The light's name
 128    */
 129   const std::string& GetName() const;
 130
 131   /**
 132    * @brief Set the light's type.
 133    *
 134    * @param[in] type The type of light
 135    */
 136   void SetType(LightType type);
 137
 138   /**
 139    * @brief Get the lights type.
 140    *
 141    * @return The light's type
 142    */
 143   LightType GetType() const;
 144
 145   /**
 146    * @brief Set the distances at which the light's intensity starts to fall off and reaches zero.
 147    *
 148    * @param[in] fallOff The fall off start and end. The start is in the x component and end is in the y component.
 149    */
 150   void SetFallOff(const Vector2& fallOff);
 151
 152   /**
 153    * @brief Get the distances at which the light's intensity starts to fall off and reaches zero.
 154    *
 155    * @return The distances at which the light's intensity starts to fall off, and reaches zero.
 156    * See @ref SetFallOff
 157    */
 158   const Vector2& GetFallOff() const;
 159
 160   /**
 161    * @brief Set the spotlight's inner and outer cone angles.
 162    *
 163    * @param[in] angle The spotlight's inner and outer cone angles.
 164    *                  The inner is in the x component and outer is in the y component.
 165    */
 166   void SetSpotAngle(const Vector2& angle);
 167
 168   /**
 169    * @brief Get the spotlight's inner and outer cone angles.
 170    *
 171    * @return The spotlight's inner and outer cone angles
 172    */
 173   const Vector2& GetSpotAngle() const;
 174
 175   /**
 176    * @brief Set the ambient color for the light.
 177    *
 178    * The color is composed of rgb
 179    * @param[in] color The color to set.
 180    */
 181   void SetAmbientColor(const Vector3& color);
 182
 183   /**
 184    * @brief Get the light's ambient color.
 185    *
 186    * @return the light's color as rgb
 187    */
 188   const Vector3& GetAmbientColor() const;
 189
 190   /**
 191    * @brief Set the diffuse color for the light.
 192    *
 193    * The color is composed of rgb
 194    * @param[in] color The color to set.
 195    */
 196   void SetDiffuseColor(const Vector3& color);
 197
 198   /**
 199    * @brief Get the light's ambient color.
 200    *
 201    * @return the light's color as rgb
 202    */
 203   const Vector3& GetDiffuseColor() const;
 204
 205   /**
 206    * @brief Set the specular color for the light.
 207    *
 208    * The color is composed of rgb
 209    * @param[in] color The color to set.
 210    */
 211   void SetSpecularColor(const Vector3& color);
 212
 213   /**
 214    * @brief Get the light's specular color.
 215    *
 216    * @return the light's specular color as rgb
 217    */
 218   const Vector3& GetSpecularColor() const;
 219
 220   /**
 221    * @brief Set the direction in which the light's rays are cast.
 222    *
 223    * Valid when the light's type is DIRECTIONAL (see @ref Dali::LightType).
 224    * @param [in] direction The direction in which the light's rays are cast.
 225    */
 226   void SetDirection(const Vector3& direction);
 227
 228   /**
 229    * @brief Get the direction in which the light's rays are cast.
 230    *
 231    * Valid when the light's type is DIRECTIONAL (see @ref LightType).
 232    * @return The direction in which the light's rays are cast.
 233    */
 234   const Vector3& GetDirection() const;
 235
 236 public: // Not intended for application developers
 237
 238   /**
 239    * @brief This constructor is used by Dali New() methods.
 240    *
 241    * @param [in] light A pointer to a newly allocated Dali resource
 242    */
 243   explicit DALI_INTERNAL Light(Internal::Light* light);
 244 };
 245
 246 } // namespace Dali
 247
 248 #endif // __DALI_LIGHT_H__