Initial revision
[blender.git] / intern / python / modules / Blender / Lamp.py
1 """The Blender Lamp module
2
3 This module provides control over **Lamp** objects in Blender.
4
5 Example::
6
7   from Blender import Lamp
8   l = Lamp.New('Spot')
9   l.setMode('square', 'shadow')
10   ob = Object.New('Lamp')
11   ob.link(l)
12 """
13
14 import _Blender.Lamp as _Lamp
15 import shadow
16
17 _validBufferSizes = [512, 768, 1024, 1536, 2560]        
18
19 def _setBufferSize(self, bufsize):
20         """Set the lamp's buffersize. This function makes sure that a valid
21 bufferSize value is set (unlike setting lamp.bufferSize directly)"""
22         if bufsize not in _validBufferSizes:
23                 print """Buffer size should be one of:
24 %s
25 Setting to default 512""" % _validBufferSizes
26                 bufsize = 512
27         self._object.bufferSize = bufsize
28
29 class Lamp(shadow.hasIPO, shadow.hasModes):
30         """Wrapper for Blender Lamp DataBlock
31         
32   Attributes
33   
34     mode         -- Lamp mode value - see EditButtons. Do not access directly 
35                     See setMode()
36
37     type         -- Lamp type value - see EditButtons. No direct access, please.
38                     See setType()
39
40     col          -- RGB vector (R, G, B) of lamp colour
41
42     energy       -- Intensity (float)
43
44     dist         -- clipping distance of a spot lamp or decay range
45
46     spotSize     -- float angle (in degrees) of spot cone 
47                     (between 0.0 and 180.0)
48
49     spotBlend    -- value defining the blurriness of the spot edge
50
51     haloInt      -- Halo intensity
52
53     clipStart    -- shadow buffer clipping start
54
55     clipStart    -- shadow buffer clipping end
56
57     bias         -- The bias value for the shadowbuffer routine
58
59     softness     -- The filter value for the shadow blurring
60
61     samples      -- Number of samples in shadow calculation - the
62                     larger, the better
63
64     bufferSize   -- Size of the shadow buffer which should be one of:
65                     [512, 768, 1024, 1536, 2560]        
66
67     haloStep     -- Number of steps in halo calculation - the smaller, the
68                     the better (and slower). A value of 0 disables shadow
69                     halo calculation
70         """
71
72         _emulation = {'Energ' : "energy",
73                       'SpoSi' : "spotSize",
74                   'SpoBl' : "SpotBlend",
75                   'HaInt' : "haloInt",
76                   'Dist'  : "dist",
77                   'Quad1' : "quad1",
78                   'Quad2' : "quad2",
79                  } 
80
81         _setters = {'bufferSize' : _setBufferSize}
82
83         t = _Lamp.Types
84
85         Types = {'Lamp'  : t.LOCAL,
86                          'Spot'  : t.SPOT,
87                          'Sun'   : t.SUN,
88                          'Hemi'  : t.HEMI,
89                         } 
90
91         t = _Lamp.Modes
92
93         Modes = {'quad'       : t.QUAD,
94                          'sphere'     : t.SPHERE,
95                          'shadow'     : t.SHAD,
96                          'halo'       : t.HALO,
97                          'layer'      : t.LAYER,
98                          'negative'   : t.NEG,
99                          'onlyShadow' : t.ONLYSHADOW,
100                          'square'     : t.SQUARE,
101                         }
102
103         del t
104
105         def __repr__(self):
106                 return "[Lamp \"%s\"]" % self.name
107
108         def setType(self, name):
109                 """Set the Lamp type of Lamp 'self'. 'name' must be a string of:
110
111 * 'Lamp': A standard point light source
112
113 * 'Spot': A spot light
114
115 * 'Sun' : A unidirectional light source, very far away (like a Sun!)
116
117 * 'Hemi': A diffuse hemispherical light source (daylight without sun)"""
118
119                 try:
120                         self._object.type = self.Types[name]
121                 except:
122                         raise TypeError, "type must be one of %s" % self.Types.keys()
123
124         def getType(self):
125                 """Returns the lamp's type as string. See setType()"""
126                 for k in self.Types.keys():
127                         if self.Types[k] == self.type:
128                                 return k
129
130         def getMode(self):
131                 """Returns the Lamp modes as a list of strings"""
132                 return shadow._getModeBits(self.Modes, self._object.mode)
133
134         def setMode(self, *args):
135                 """Set the Lamp mode of Lamp 'self'. This function takes a variable number
136 of string arguments of the types listed in self.Modes.
137
138   Example::
139
140     l = Lamp.New()
141     l.setMode('quad', 'shadow')
142 """
143                 print args
144                 self._object.mode = shadow._setModeBits(self.Modes, args)
145
146         def getBufferSize(self):
147                 return self.bufferSize
148
149 def New(type = "Lamp", name = "Lamp"):
150         """Returns a new Lamp datablock of type 'type' and optional name 'name'
151 """
152         t = Lamp.Types[type]
153         rawlamp = _Lamp.New()
154         rawlamp.type = t
155         rawlamp.name = name
156         return Lamp(rawlamp)
157         
158
159 def get(name = None):
160         """If 'name' given, the Lamp 'name' is returned if existing, 'None' otherwise.
161 If no name is given, a list of all Lamps is returned"""
162
163         if name:
164                 return Lamp(_Lamp.get(name))
165         else:
166                 return shadow._List(_Lamp.get(), Lamp)
167
168 Types = _Lamp.Types