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