6618b70b988ffeaa749f29f141016822e9da0280
[blender.git] / source / blender / python / api2_2x / doc / Render.py
1 # Blender.Scene.Render module and the RenderData PyType object
2
3 """
4 The Blender.Scene.Render submodule.
5
6 Scene
7 =====
8
9 This module provides access to B{Scene Rendering Contexts} in Blender.
10
11 Example::
12   import Blender
13   from Blender import *
14   from Blender.Scene import Render
15   
16   scn = Scene.GetCurrent()
17   context = scn.getRenderingContext()
18   
19   Render.EnableDispWin()
20   context.enableExtensions(1)
21   context.setRenderPath("C:/myRenderdir/")
22   context.sizePreset(Scene.PC)
23   context.setImageType(Render.AVIRAW)
24   context.startFrame(2)
25   context.endFrame(10)
26   context.renderAnim()
27
28   context.setImageType(Render.TARGA)
29   context.framesPerSec(15)
30   context.startFrame(15)
31   context.endFrame(22)
32   context.renderAnim()
33
34   Render.CloseRenderWindow()
35   print context.framesPerSec()
36   print context.currentFrame()
37
38 """
39
40 def CloseRenderWindow():
41   """
42   Closes the rendering window.
43   """
44
45 def EnableDispView():
46   """
47   Render in the 3d View area.
48   """
49
50 def EnableDispWin():
51   """
52   Render in Render window.
53   """
54
55 def SetRenderWinPos(locationList):
56   """
57   Set the position of the Render window on the screen.
58   Possible values are:
59     -  S = south
60     -  N = north
61     -  W = west
62     -  E = east
63     -  C = center
64     -  ne = northeast
65     -  nw = northwest
66     -  se = southeast
67     -  sw = southwest
68   @type locationList: PyList of strings
69   @param locationList: a list of strings that together define
70   the location of the Render window on the screen.
71   """
72
73 def EnableEdgeShift():
74   """
75   Globally with the unified renderer enabled the outlines of the render
76   are shifted a bit.
77   """
78
79 def EnableEdgeAll():
80   """
81   Globally consider transparent faces for edge-rendering with the unified renderer.
82   """
83
84 class RenderData:
85   """
86   The RenderData object
87   =====================
88     This object gives access to Scene rendering contexts in Blender.
89   """
90   
91   def getRenderdir():
92     """
93     @warn: B{Depricated}: use RenderData.getRenderPath()
94     """
95
96   def getBackbufdir():
97     """
98     @warn: B{Depricated}: use RenderData.getBackbufPath()
99     """
100
101   def getChildren():
102     """
103     Get all objects linked to this Scene.
104     @rtype: list of Blender Objects
105     @return: A list with all Blender Objects linked to this Scene.
106     """
107
108   def getCurrentCamera():
109     """
110     Get the currently active Camera for this Scene.
111     @rtype: Blender Camera
112     @return: The currently active Camera.
113     """
114
115   def setCurrentCamera(camera):
116     """
117     Set the currently active Camera in this Scene.
118     @type camera: Blender Camera
119     @param camera: The new active Camera.
120     """
121
122   def render():
123     """
124     Render the scene.
125     """
126
127   def renderAnim():
128     """
129     Render a series of frames to an output directory.
130     """
131
132   def play():
133     """
134     play animation of rendered images/avi (searches Pics: field).
135     """
136
137   def setRenderPath(path):
138     """
139     Set the path to where the renderer will write to.
140     @type path: string
141     @param path: A directory for that the renderer searches for
142     both playback and output from the renderAnim function.
143     """
144
145   def getRenderPath():
146     """
147     Get the path to where the renderer will write to.
148     @rtype: string
149     @return: Returns the directory that is used to playback and store rendered
150     sequences.
151     """
152
153   def setBackbufPath(path):
154     """
155     Set the path to a background image and load it.
156     @type path: string
157     @param path: The path to a background image for loading.
158     """
159
160   def getBackbufPath():
161     """
162     Get the path to the background image.
163     @rtype: string
164     @return: The path to a background image.
165     """
166
167   def enableBackbuf(toggle):
168     """
169     Enable/disable the backbuf image.
170     @type toggle: int
171     @param toggle: pass 1 for on / 0 for off
172     """
173
174   def setFtypePath(path):
175     """
176     Set the path to Ftype file.
177     @type path: string
178     @param path: Path to Ftype Image type.
179     """
180
181   def getFtypePath():
182     """
183     Get the path to the Ftype file
184     @rtype: string
185     @return: Path to FtypeImage type.
186     """
187
188   def enableExtensions(toggle):
189     """
190     Enable/disable windows extensions for output files.
191     @type toggle: int
192     @param toggle: pass 1 for on / 0 for off
193     """
194
195   def enableSequencer(toggle):
196     """
197     Enable/disable Do Sequence.
198     @type toggle: int
199     @param toggle: pass 1 for on / 0 for off
200     """
201
202   def enableRenderDaemon(toggle):
203     """
204     Enable/disable Scene daemon.
205     @type toggle: int
206     @param toggle: pass 1 for on / 0 for off
207     """
208
209   def enableToonShading(toggle):
210     """
211     Enable/disable Edge rendering.
212     @type toggle: int
213     @param toggle: pass 1 for on / 0 for off
214     """
215
216   def edgeIntensity(intensity = None):
217     """
218     Get/set edge intensity for toon shading.
219     @type intensity: int (optional)
220     @param intensity: must be between 0 - 255
221     @rtype: int (if prototype is empty)
222     @return: Current edge intensity for the scene.
223     """
224
225   def setEdgeColor(red, green, blue):
226     """
227     Set the edge color for toon shading.
228     @type red: float
229     @param red: must be between 0 - 1.0
230     @type green: float
231     @param green: must be between 0 - 1.0
232     @type blue: float
233     @param blue: must be between 0 - 1.0
234     """
235
236   def getEdgeColor():
237     """
238     Get the edge color for toon shading.
239     @rtype: string
240     @return: A string representing the edge color.
241     """
242
243   def edgeAntiShift(intensity = None):
244     """
245     With the unified renderer, reduce intensity on boundaries.
246     @type intensity: int (optional)
247     @param intensity: must be between 0 - 255
248     @rtype: int (if prototype is empty)
249     @return: Current edge antishift for the scene.
250     """
251
252   def enableOversampling(toggle):
253     """
254     Enable/disable oversampling (anit-aliasing).
255     @type toggle: int
256     @param toggle: pass 1 for on / 0 for off
257     """
258
259   def setOversamplingLevel(level):
260     """
261     Set the edge color for toon shading.
262     @type level: int
263     @param level: can be either 5, 8, 11, or 16
264     """
265
266   def enableMotionBlur(toggle):
267     """
268     Enable/disable MBlur.
269     @type toggle: int
270     @param toggle: pass 1 for on / 0 for off
271     """
272
273   def motionBlurLevel(level = None):
274     """
275     Get/set the length of shutter time for motion blur.
276     @type level: float (optional)
277     @param level: must be between 0.01 - 5.0
278     @rtype: float (if prototype is empty)
279     @return: Current MBlur for the scene.
280     """
281
282   def partsX(parts = None):
283     """
284     Get/set the number of parts to divide the render in the X direction.
285     @type parts: int (optional)
286     @param parts: must be between 1 - 64
287     @rtype: int (if prototype is empty)
288     @return: Current number of parts in the X for the scene.
289     """
290
291   def partsY(parts = None):
292     """
293     Get/set the number of parts to divide the render in the Y direction.
294     @type parts: int (optional)
295     @param parts: must be between 1 - 64
296     @rtype: int (if prototype is empty)
297     @return: Current number of parts in the Y for the scene.
298     """
299
300   def enableSky():
301     """
302     Enable render background with sky.
303     """
304
305   def enablePremultiply():
306     """
307     Enable premultiply alpha.
308     """
309
310   def enableKey():
311     """
312     Enable alpha and colour values remain unchanged.
313     """
314
315   def enableShadow(toggle):
316     """
317     Enable/disable shadow calculation.
318     @type toggle: int
319     @param toggle: pass 1 for on / 0 for off
320     """
321
322   def enableEnvironmentMap(toggle):
323     """
324     Enable/disable environment map rendering.
325     @type toggle: int
326     @param toggle: pass 1 for on / 0 for off
327     """
328
329   def enableRayTracing(toggle):
330     """
331     Enable/disable ray tracing.
332     @type toggle: int
333     @param toggle: pass 1 for on / 0 for off
334     """
335
336   def enableRadiosityRender(toggle):
337     """
338     Enable/disable radiosity rendering.
339     @type toggle: int
340     @param toggle: pass 1 for on / 0 for off
341     """
342
343   def enablePanorama(toggle):
344     """
345     Enable/disable panorama rendering (output width is multiplied by Xparts).
346     @type toggle: int
347     @param toggle: pass 1 for on / 0 for off
348     """
349
350   def setRenderWinSize(size):
351     """
352     Set the size of the render window.
353     @type size: int
354     @param size: can be 25, 50, 75 or 100 (percent).
355     """
356
357   def enableFieldRendering(toggle):
358     """
359     Enable/disable field rendering
360     @type toggle: int
361     @param toggle: pass 1 for on / 0 for off
362     """
363
364   def enableOddFieldFirst(toggle):
365     """
366     Enable/disable Odd field first rendering (Default: Even field).
367     @type toggle: int
368     @param toggle: pass 1 for on / 0 for off
369     """
370
371   def enableFieldTimeDisable(toggle):
372     """
373     Enable/disable time difference in field calculations.
374     @type toggle: int
375     @param toggle: pass 1 for on / 0 for off
376     """
377
378   def enableGaussFilter(toggle):
379     """
380     Enable/disable Gauss sampling filter for antialiasing.
381     @type toggle: int
382     @param toggle: pass 1 for on / 0 for off
383     """
384
385   def enableBorderRender(toggle):
386     """
387     Enable/disable small cut-out rendering.
388     @type toggle: int
389     @param toggle: pass 1 for on / 0 for off
390     """
391
392   def setBorder(left,bottom,right,top):
393     """
394     Set a border for rendering from cameras in the scene.
395     The left,bottom coordinates and right,top coordinates
396     define the size of the border. (0,0,1,1) will set the border
397     to the whole camera. (0,0) lower left and (1,1) upper right.
398     @type left: float
399     @param left: float between 0 and 1
400     @type right: float
401     @param right: float between 0 and 1
402     @type bottom: float
403     @param bottom: float between 0 and 1
404     @type top: float
405     @param top: float between 0 and 1
406     """
407
408   def enableGammaCorrection(toggle):
409     """
410     Enable/disable gamma correction.
411     @type toggle: int
412     @param toggle: pass 1 for on / 0 for off
413     """
414
415   def gaussFilterSize(size = None):
416     """
417     Get/sets the Gauss filter size.
418     @type size: float (optional)
419     @param size: must be between 0.5 - 1.5
420     @rtype: float (if prototype is empty)
421     @return: Current gauss filter size for the scene.
422     """
423
424   def startFrame(frame = None):
425     """
426     Get/set the starting frame for sequence rendering.
427     @type frame: int (optional)
428     @param frame: must be between 1 - 18000
429     @rtype: int (if prototype is empty)
430     @return: Current starting frame for the scene.
431     """
432
433   def endFrame(frame = None):
434     """
435     Get/set the ending frame for sequence rendering.
436     @type frame: int (optional)
437     @param frame: must be between 1 - 18000
438     @rtype: int (if prototype is empty)
439     @return: Current ending frame for the scene.
440     """
441
442   def imageSizeX(size = None):
443     """
444     Get/set the image width in pixels.
445     @type size: int (optional)
446     @param size: must be between 4 - 10000
447     @rtype: int (if prototype is empty)
448     @return: Current image width for the scene.
449     """
450
451   def imageSizeY(size = None):
452     """
453     Get/set the image height in pixels.
454     @type size: int (optional)
455     @param size: must be between 4 - 10000
456     @rtype: int (if prototype is empty)
457     @return: Current image height for the scene.
458     """
459
460   def aspectRatioX(ratio = None):
461     """
462     Get/set the horizontal aspect ratio.
463     @type ratio: int (optional)
464     @param ratio: must be between 1 - 200
465     @rtype: int (if prototype is empty)
466     @return: Current horizontal aspect ratio for the scene.
467     """
468
469   def aspectRatioY(ratio = None):
470     """
471     Get/set the vertical aspect ratio.
472     @type ratio: int (optional)
473     @param ratio: must be between 1 - 200
474     @rtype: int (if prototype is empty)
475     @return: Current vertical aspect ratio for the scene.
476     """
477
478   def setRenderer(type):
479     """
480     Get/set which renderer to render the output.
481     @type type: enum constant
482     @param type: must be one of 2 constants:
483         - INTERN: Blender's internal renderer
484         - YAFRAY: Yafray renderer
485     """
486
487   def enableCropping(toggle):
488     """
489     Enable/disable exclusion of border rendering from total image.
490     @type toggle: int
491     @param toggle: pass 1 for on / 0 for off
492     """
493
494   def setImageType(type):
495     """
496     Set the type of image to output from the render.
497     @type type: enum constant
498     @param type: must be one of 13 constants:
499         - AVIRAW: Uncompressed AVI files. AVI is a commonly used format on Windows plattforms
500         - AVIJPEG: AVI movie w/ Jpeg images
501         - AVICODEC: AVI using win32 codec
502         - QUICKTIME: Quicktime movie (if enabled)
503         - TARGA: Targa files
504         - RAWTGA: Raw Targa files
505         - PNG: Png files
506         - BMP: Bitmap files
507         - JPEG90: Jpeg files
508         - HAMX: Hamx files
509         - IRIS: Iris files
510         - IRIZ: Iris + z-buffer files
511         - FTYPE: Ftype file
512     """
513
514   def quality(qual = None):
515     """
516     Get/set quality get/setting for JPEG images, AVI Jpeg and SGI movies.
517     @type qual: int (optional)
518     @param qual: must be between 10 - 100
519     @rtype: int (if prototype is empty)
520     @return: Current image quality for the scene.
521     """
522
523   def framesPerSec(qual = None):
524     """
525     Get/set frames per second.
526     @type qual: int (optional)
527     @param qual: must be between 1 - 120
528     @rtype: int (if prototype is empty)
529     @return: Current frames per second for the scene.
530     """
531
532   def enableGrayscale():
533     """
534     Images are saved with BW (grayscale) data.
535     """
536
537   def enableRGBColor():
538     """
539     Images are saved with RGB (color) data.
540     """
541
542   def enableRGBAColor():
543     """
544     Images are saved with RGB and Alpha data (if supported).
545     """
546
547   def sizePreset(type):
548     """
549     Set the renderer to one of a few presets.
550     @type type: enum constant
551     @param type: must be one of 8 constants:
552         - PAL: The European video standard: 720 x 576 pixels, 54 x 51 aspect.
553         - FULL: For large screens: 1280 x 1024 pixels. 
554         - PREVIEW: For preview rendering: 320 x 256 pixels.
555         - PAL169: Wide-screen PAL.
556         - DEFAULT: Like "PAL", but here the render settings are also set.
557         - PANO: Panorama render.
558         - NTSC: For TV playback.
559         - PC: For standard PC graphics: 640 x 480 pixels.
560     """
561
562   def enableUnifiedRenderer(toggle):
563     """
564     Use the unified renderer.
565     @type toggle: int
566     @param toggle: pass 1 for on / 0 for off
567     """
568
569   def setYafrayGIQuality(type):
570     """
571     Set yafray global Illumination quality.
572     @type type: enum constant
573     @param type: must be one of 6 constants:
574         - NONE
575         - LOW
576         - MEDIUM
577         - HIGH
578         - HIGHER
579         - BEST
580     """
581
582   def setYafrayGIMethod(type):
583     """
584     Set yafray global Illumination method.
585     @type type: enum constant
586     @param type: must be one of 3 constants:
587         - NONE: Dont use GI illumination
588         - SKYDOME: Use Skydome method
589         - GIFULL: Use Full method
590     """
591
592   def yafrayGIPower(power = None):
593     """
594     Get/set GI lighting intensity scale.
595     YafrayMethod must be either SKYDOME or GIFULL.
596     @type power: float (optional)
597     @param power: must be between 0.01 - 100.0
598     @rtype: float (if prototype is empty)
599     @return: Current yafray global illumination intensity for the scene.
600     """
601
602   def yafrayGIDepth(depth = None):
603     """
604     Get/set number of bounces of the indirect light.
605     YafrayMethod must be GIFULL.
606     @type depth: int (optional)
607     @param depth: must be between 1 - 8
608     @rtype: int (if prototype is empty)
609     @return: Current yafray global illumination light bounces for the scene.
610     """
611
612   def yafrayGICDepth(depth = None):
613     """
614     Get/set number of bounces inside objects (for caustics).
615     YafrayMethod must be GIFULL.
616     @type depth: int (optional)
617     @param depth: must be between 1 - 8
618     @rtype: int (if prototype is empty)
619     @return: Current yafray global illumination inside light bounces for the scene.
620     """
621
622   def enableYafrayGICache(toggle):
623     """
624     Enable/disable cache irradiance samples (faster).
625     YafrayMethod must be GIFULL.
626     @type toggle: int
627     @param toggle: pass 1 for on / 0 for off
628     """
629
630   def enableYafrayGIPhotons(toggle):
631     """
632     Enable/disable use of global photons to help in GI.
633     YafrayMethod must be GIFULL.
634     @type toggle: int
635     @param toggle: pass 1 for on / 0 for off
636     """
637
638   def yafrayGIPhotonCount(count = None):
639     """
640     Get/set number of photons to shoot.
641     YafrayMethod must be GIFULL and Photons enabled.
642     @type count: int (optional)
643     @param count: must be between 0 - 10000000
644     @rtype: int (if prototype is empty)
645     @return: Current number of photons to shoot for the scene.
646     """
647
648
649   def yafrayGIPhotonRadius(radius = None):
650     """
651     Get/set radius to search for photons to mix (blur).
652     YafrayMethod must be GIFULL and Photons enabled.
653     @type radius: float (optional)
654     @param radius: must be between 0.00001 - 100.0
655     @rtype: float (if prototype is empty)
656     @return: Current photon search radius for the scene.
657     """
658
659
660   def yafrayGIPhotonMixCount(count = None):
661     """
662     Get/set number of photons to keep inside radius.
663     YafrayMethod must be GIFULL and Photons enabled.
664     @type count: int (optional)
665     @param count: must be between 0 - 1000
666     @rtype: int (if prototype is empty)
667     @return: Current number of photons to keep inside radius for the scene.
668     """
669
670   def enableYafrayGITunePhotons(toggle):
671     """
672     Enable/disable show the photonmap directly in the render for tuning.
673     YafrayMethod must be GIFULL and Photons enabled.
674     @type toggle: int
675     @param toggle: pass 1 for on / 0 for off
676     """
677
678   def yafrayGIShadowQuality(qual = None):
679     """
680     Get/set the shadow quality, keep it under 0.95.
681     YafrayMethod must be GIFULL and Cache enabled.
682     @type qual: float (optional)
683     @param qual: must be between 0.01 - 1.0
684     @rtype: float (if prototype is empty)
685     @return: Current shadow quality for the scene.
686     """
687
688   def yafrayGIPixelsPerSample(pixels = None):
689     """
690     Get/set maximum number of pixels without samples, the lower the better and slower.
691     YafrayMethod must be GIFULL and Cache enabled.
692     @type pixels: int (optional)
693     @param pixels: must be between 1 - 50
694     @rtype: int (if prototype is empty)
695     @return: Current number of pixels without samples for the scene.
696     """
697
698   def enableYafrayGIGradient(toggle):
699     """
700     Enable/disable try to smooth lighting using a gradient.
701     YafrayMethod must be GIFULL and Cache enabled.
702     @type toggle: int
703     @param toggle: pass 1 for on / 0 for off
704     """ 
705
706   def yafrayGIRefinement(refine = None):
707     """
708     Get/set threshold to refine shadows EXPERIMENTAL. 1 = no refinement.
709     YafrayMethod must be GIFULL and Cache enabled.
710     @type refine: float (optional)
711     @param refine: must be between 0.001 - 1.0
712     @rtype: float (if prototype is empty)
713     @return: Current threshold to refine shadows for the scene.
714     """
715
716   def yafrayRayBias(bias = None):
717     """
718     Get/set shadow ray bias to avoid self shadowing.
719     @type bias: float (optional)
720     @param bias: must be between 0 - 10.0
721     @rtype: float (if prototype is empty)
722     @return: Current ray bias for the scene.
723     """
724
725   def yafrayRayDepth(depth = None):
726     """
727     Get/set maximum render ray depth from the camera.
728     @type depth: int (optional)
729     @param depth: must be between 1 - 80
730     @rtype: int (if prototype is empty)
731     @return: Current ray depth for the scene.
732     """
733
734   def yafrayGamma(gamma = None):
735     """
736     Get/set gamma correction, 1 is off.
737     @type gamma: float (optional)
738     @param gamma: must be between 0.001 - 5.0
739     @rtype: float (if prototype is empty)
740     @return: Current gamma correction for the scene.
741     """
742
743   def yafrayExposure(expose = None):
744     """
745     Get/set exposure adjustment, 0 is off.
746     @type expose: float (optional)
747     @param expose: must be between 0 - 10.0
748     @rtype: float (if prototype is empty)
749     @return: Current exposure adjustment for the scene.
750     """
751
752   def yafrayProcessorCount(count = None):
753     """
754     Get/set number of processors to use.
755     @type count: int (optional)
756     @param count: must be between 1 - 8
757     @rtype: int (if prototype is empty)
758     @return: Current number of processors for the scene.
759     """
760
761   def enableGameFrameStretch():
762     """
763     Enble stretch or squeeze the viewport to fill the display window.
764     """
765
766   def enableGameFrameExpose():
767     """
768     Enable show the entire viewport in the display window, viewing more 
769     horizontally or vertically.
770     """
771
772   def enableGameFrameBars():
773     """
774     Enable show the entire viewport in the display window, using bar 
775     horizontally or vertically.
776     """
777
778   def setGameFrameColor(red, green, blue):
779     """
780     Set the red, green, blue component of the bars.
781     @type red: float
782     @param red: must be between 0 - 1.0
783     @type green: float
784     @param green: must be between 0 - 1.0
785     @type blue: float
786     @param blue: must be between 0 - 1.0
787     """
788
789   def getGameFrameColor():
790     """
791     Set the red, green, blue component of the bars.
792     @rtype: string
793     @return: A string representing the color component of the bars.
794     """
795
796   def gammaLevel(level = None):
797     """
798     Get/set the gamma value for blending oversampled images (1.0 = no correction).
799     Unified renderer must be enabled.
800     @type level: float (optional)
801     @param level: must be between 0.2 - 5.0
802     @rtype: float (if prototype is empty)
803     @return: Current gamma value for the scene.
804     """
805
806   def postProcessAdd(add = None):
807     """
808     Get/set post processing add.
809     Unified renderer must be enabled.
810     @type add: float (optional)
811     @param add: must be between -1.0 - 1.0
812     @rtype: float (if prototype is empty)
813     @return: Current processing add value for the scene.
814     """
815
816   def postProcessMultiply(mult = None):
817     """
818     Get/set post processing multiply.
819     Unified renderer must be enabled.
820     @type mult: float (optional)
821     @param mult: must be between 0.01 - 4.0
822     @rtype: float (if prototype is empty)
823     @return: Current processing multiply value for the scene.
824     """
825
826   def postProcessGamma(gamma = None):
827     """
828     Get/set post processing gamma.
829     Unified renderer must be enabled.
830     @type gamma: float (optional)
831     @param gamma: must be between 0.2 - 2.0
832     @rtype: float (if prototype is empty)
833     @return: Current processing gamma value for the scene.
834     """
835
836   def SGIMaxsize(size = None):
837     """
838     Get/set maximum size per frame to save in an SGI movie.
839     SGI must be defined on your machine.
840     @type size: int (optional)
841     @param size: must be between 0 - 500
842     @rtype: int (if prototype is empty)
843     @return: Current SGI maximum size per frame for the scene.
844     """
845
846   def enableSGICosmo(toggle):
847     """
848     Enable/disable attempt to save SGI movies using Cosmo hardware
849     SGI must be defined on your machine.
850     @type toggle: int
851     @param toggle: pass 1 for on / 0 for off
852     """
853
854   def oldMapValue(value = None):
855     """
856     Get/set specify old map value in frames.
857     @type value: int (optional)
858     @param value: must be between 1 - 900
859     @rtype: int (if prototype is empty)
860     @return: Current old map value for the scene.
861     """
862
863   def newMapValue(value = None):
864     """
865     Get/set specify new map value in frames.
866     @type value: int (optional)
867     @param value: must be between 1 - 900
868     @rtype: int (if prototype is empty)
869     @return: Current new map value for the scene.
870     """