diff options
author | Willian Padovani Germano <wpgermano@gmail.com> | 2004-10-20 09:51:24 +0400 |
---|---|---|
committer | Willian Padovani Germano <wpgermano@gmail.com> | 2004-10-20 09:51:24 +0400 |
commit | fa9135385a38c9289a2dfa2320c20b68d782c1e4 (patch) | |
tree | f011e964789f9d9c37f18dfc72de661a525ecf3c /source/blender/python/api2_2x/doc | |
parent | f2f004af2df9733761cf9d4888e883a8c5f0d3e9 (diff) |
BPython:
- Blender.Window: added function GetPerspMatrix() (Tom Musgrave's patch, thanks);
- added Chris Want's patch to tell argc, argv to the Python interpreter (thanks, Hos);
- Blender.Image: added image.glFree() to free textures bound by the recently added
image.glLoad() (both suggested by Campbell Barton -- thanks, with these Blender can
be used to load textures for scripts);
- Blender.Sound: removed for now at least a few get/set methods of vars that can't be
accessed via interface;
- renamed Get/makeActive to Get/setCurrent in Blender.World (actually added alias for
now), same in Blender.Sound: renamed makeActive to setCurrent. Stephen Swaney
pointed this some weeks ago, we should stick to one naming convention.
- added documentation for Sound and Window.Theme modules and the other added
functions, made other small updates.
- Blender.Object: made 'worldspace' become the default output of .getMatrix and .mat/.matrix:
after reading a discussion on blender.org's Python forum where eeshlo mentioned the
pre 2.34 default was worldspace, I took a better look at Blender's relevant code,
confirmed, talked to Theeth about this and as he suggested am changing the default
back to 'worldspace'.
Diffstat (limited to 'source/blender/python/api2_2x/doc')
-rw-r--r-- | source/blender/python/api2_2x/doc/API_intro.py | 6 | ||||
-rw-r--r-- | source/blender/python/api2_2x/doc/BGL.py | 3 | ||||
-rw-r--r-- | source/blender/python/api2_2x/doc/Image.py | 29 | ||||
-rw-r--r-- | source/blender/python/api2_2x/doc/Object.py | 19 | ||||
-rw-r--r-- | source/blender/python/api2_2x/doc/Sound.py | 112 | ||||
-rw-r--r-- | source/blender/python/api2_2x/doc/Theme.py | 188 | ||||
-rw-r--r-- | source/blender/python/api2_2x/doc/Window.py | 17 | ||||
-rw-r--r-- | source/blender/python/api2_2x/doc/World.py | 8 |
8 files changed, 362 insertions, 20 deletions
diff --git a/source/blender/python/api2_2x/doc/API_intro.py b/source/blender/python/api2_2x/doc/API_intro.py index 94f583211fc..8f684c79144 100644 --- a/source/blender/python/api2_2x/doc/API_intro.py +++ b/source/blender/python/api2_2x/doc/API_intro.py @@ -34,11 +34,13 @@ The Blender Python API Reference - L{Scene} (*) - L{Radio} - L{Render} + - L{Sound} (new) - L{Text} - L{Texture} - L{Types} - - L{Window} - - L{World} + - L{Window} (*) + - L{Theme} (new) + - L{World} (*) - L{sys<Sys>} (*) - marks updated. diff --git a/source/blender/python/api2_2x/doc/BGL.py b/source/blender/python/api2_2x/doc/BGL.py index cbb8b455b19..6c20e4ec7b4 100644 --- a/source/blender/python/api2_2x/doc/BGL.py +++ b/source/blender/python/api2_2x/doc/BGL.py @@ -74,6 +74,9 @@ Example:: # Draw.Register(show_win, ev, None) # start the main loop +@note: you can use the L{Image} module and L{Image.Image} bpy object to load + and set textures. See L{Image.Image.glLoad} and L{Image.Image.glFree}, + for example. @see: U{www.opengl.org} @see: U{nehe.gamedev.net} """ diff --git a/source/blender/python/api2_2x/doc/Image.py b/source/blender/python/api2_2x/doc/Image.py index f09a5fbcc69..df4b5c6a65c 100644 --- a/source/blender/python/api2_2x/doc/Image.py +++ b/source/blender/python/api2_2x/doc/Image.py @@ -6,7 +6,7 @@ The Blender.Image submodule. Image ===== -B{New}: L{Image.reload}, L{Image.getBindCode}. +B{New}: L{Image.glLoad}, L{Image.glFree}. This module provides access to B{Image} objects in Blender. @@ -110,8 +110,8 @@ class Image: def getBindCode(): """ - Get the Image's bindcode. This is for texture loading using BGL calls, - see for example L{BGL.glBindTexture}. + Get the Image's bindcode. This is for texture loading using BGL calls. + See, for example, L{BGL.glBindTexture} and L{glLoad}. @rtype: int """ @@ -125,6 +125,29 @@ class Image: @returns: None """ + def glLoad(): + """ + Load this image's data into OpenGL texture memory, if it is not already + loaded (image.bindcode is 0 if it is not loaded yet). + @note: Usually you don't need to call this method. It is only necessary + if you want to draw textured objects in the Scripts window and the + image's bind code is zero at that moment, otherwise Blender itself can + take care of binding / unbinding textures. Calling this method for an + image with nonzero bind code simply returns the image's bind code value + (see L{getBindCode}). + @rtype: int + @returns: the texture's bind code. + """ + + def glFree(): + """ + Delete this image's data from OpenGL texture memory, only (the image itself + is not removed from Blender's memory). Internally, glDeleteTextures (see + L{BGL.glDeleteTextures}) is used, but this method also updates Blender's + Image object so that its bind code is set to 0. See also L{Image.glLoad}, + L{Image.getBindCode}. + """ + def setName(name): """ Set the name of this Image object. diff --git a/source/blender/python/api2_2x/doc/Object.py b/source/blender/python/api2_2x/doc/Object.py index 07c674b9dbe..c2d1db093ca 100644 --- a/source/blender/python/api2_2x/doc/Object.py +++ b/source/blender/python/api2_2x/doc/Object.py @@ -3,7 +3,8 @@ """ The Blender.Object submodule -B{New}: 'oldlocal' parameter in L{Object.Object.getMatrix}. +B{New}: 'old_worldspace' parameter in L{Object.Object.getMatrix}, which now +defaults to 'worldspace'. Object ====== @@ -146,7 +147,7 @@ class Object: @cvar data: The data of the object. (Read-only) @cvar ipo: The ipo data associated with the object. (Read-only) @cvar mat: The matrix of the object relative to its parent. (Read-only) - @cvar matrix: The matrix of the object relative to its parent. (Read-only) + @cvar matrix: The matrix of the object in world space. (Read-only) @cvar matrixLocal: The matrix of the object relative to its parent. (Read-only) @cvar matrixWorld: The matrix of the object in world space. (Read-only) @cvar colbits: The Material usage mask. A set bit #n means: the Material @@ -287,17 +288,17 @@ class Object: @return: list of Material Objects assigned to the object. """ - def getMatrix(space = 'localspace'): + def getMatrix(space = 'worldspace'): """ Returns the object matrix. @type space: string @param space: The desired matrix: - - localspace (default): relative to the object's parent; - - worldspace: absolute, taking vertex parents, tracking and ipo's into - account; - - oldlocal: old behavior, prior to Blender 2.34, where eventual changes - made by the script itself were not taken into account until the - script finished executing. + - worldspace (default): absolute, taking vertex parents, tracking and + ipo's into account; + - localspace: relative to the object's parent; + - old_worldspace: old behavior, prior to Blender 2.34, where eventual + changes made by the script itself were not taken into account until + a redraw happened, either called by the script or upon its exit. Returns the object matrix. @rtype: Py_Matrix @return: a python 4x4 matrix object diff --git a/source/blender/python/api2_2x/doc/Sound.py b/source/blender/python/api2_2x/doc/Sound.py new file mode 100644 index 00000000000..6cc72f471cf --- /dev/null +++ b/source/blender/python/api2_2x/doc/Sound.py @@ -0,0 +1,112 @@ +# Blender.Sound module and the Sound PyType object + +""" +The Blender.Sound submodule. + +Sound +===== + +This module provides access to B{Sound} objects in Blender. + +Example:: + import Blender + from Blender import Sound + # + sound = Sound.Load("/path/to/my/sound.wav") # load a sound file + print "Sound from", sound.getFilename(), + print "loaded to obj", sound.getName()) + print "All Sounds available now:", Sound.Get() +""" + +def Load (filename): + """ + Load the sound called 'filename' into a Sound object. + @type filename: string + @param filename: The full path to the sound file. + @rtype: Blender Sound + @return: A Blender Sound object with the data from I{filename}. + """ + +def Get (name = None): + """ + Get the Sound object(s) from Blender. + @type name: string + @param name: The name of the Sound object. + @rtype: Blender Sound or a list of Blender Sounds + @return: It depends on the I{name} parameter: + - (name): The Sound object called I{name}, None if not found; + - (): A list with all Sound objects in the current scene. + """ + + +class Sound: + """ + The Sound object + ================ + This object gives access to Sounds in Blender. + @cvar name: The name of this Sound object. + @cvar filename: The filename (path) to the sound file loaded into this Sound + object. + """ + + def getName(): + """ + Get the name of this Sound object. + @rtype: string + """ + + def getFilename(): + """ + Get the filename of the sound file loaded into this Sound object. + @rtype: string + """ + + def play(): + """ + Play this sound. + """ + + def setCurrent(): + """ + Make this the active sound in the sound buttons window (also redraws). + """ + + def getVolume(): + """ + Get this sound's volume. + rtype: float + """ + + def setVolume(f): + """ + Set this sound's volume. + @type f: float + @param f: the new volume value in the range [0.0, 1.0]. + """ + + def getAttenuation(): + """ + Get this sound's attenuation value. + rtype: float + """ + + def setAttenuation(f): + """ + Set this sound's attenuation. + @type f: float + @param f: the new attenuation value in the range [0.0, 5.0]. + """ + + def getPitch(): + """ + Get this sound's pitch value. + rtype: float + """ + + def setPitch(f): + """ + Set this sound's pitch. + @type f: float + @param f: the new pitch value in the range [-12.0, 12.0]. + """ + diff --git a/source/blender/python/api2_2x/doc/Theme.py b/source/blender/python/api2_2x/doc/Theme.py new file mode 100644 index 00000000000..facfee068c2 --- /dev/null +++ b/source/blender/python/api2_2x/doc/Theme.py @@ -0,0 +1,188 @@ +# Blender.Window.Theme submodule and the Theme PyType object + +""" +The Blender.Window.Theme submodule. + +Theme +===== + +This module provides access to B{Theme} objects in Blender. + +Example:: + # this is a simplified version of the save_theme.py script + # shipped with Blender: + import Blender + from Blender.Window import Theme, FileSelector + + theme = Theme.Get()[0] # get current theme + + def write_theme(filename): + "Write the current theme as a bpython script" + + f = file(filename, "w") + + f.write("import Blender") + f.write("from Blender.Window import Theme") + f.write("theme = Theme.New('%s')" % theme.name) + + for tsp in theme.get(): # write each theme space + command = "\\n%s = theme.get('%s')" % (tsp, tsp) + f.write(command + "\\n") + exec(command) + exec("vars = dir(%s)" % tsp) + vars.remove('theme') + + for var in vars: # write each variable from each theme space + v = "%s.%s" % (tsp, var) + exec("value = %s" % v) + f.write("%s = %s\\n" % (v, value)) + + f.write('\\nBlender.Redraw(-1)') # redraw to update the screen + f.close() + + FileSelector(write_theme, "Save Current Theme", default_fname) +""" + +def New (name = "New Theme", theme = '<default>'): + """ + Create a new Theme object. + @type name: string + @param name: The name of the new theme. + @type theme: Blender Theme + @param theme: a base theme to copy all data from. It defaults to the current + one. + @rtype: Blender Theme + @return: A new Blender Theme object. + """ + +def Get (name = None): + """ + Get the Theme object(s) from Blender. + @type name: string + @param name: The name of the Theme object. + @rtype: Blender Theme or a list of Blender Themes + @return: It depends on the I{name} parameter: + - (name): The Theme object called I{name}, None if not found; + - (): A list with all Theme objects currently in Blender. + """ + + +class Theme: + """ + The Theme object + ================ + This object gives access to Themes in Blender. Each Theme object is + composed of one UI (Use Interface) theme and many Space themes + (3d view, Text Editor, Buttons window, etc). + @cvar name: The name of this Theme object. + """ + + def getName(): + """ + Get the name of this Theme object. + @rtype: string + @return: the name of this Theme object. + """ + + def setName(s): + """ + Rename this theme. + @type s: string + @param s: the new name. + """ + + def get(t = None): + """ + Get a space or the ui (sub)theme from this Theme. + @type t: string, int or None + @param t: the wanted sub-theme as either: + - int: -1 for UI or the types in L{Window.Types} for the others; + - string: use get() to know them (they are case insensitive); + - nothing: as written above, get() returns a list of names. + @rtype: Blender ThemeSpace or ThemeUI or list of sub-theme types as strings. + @return: It depends on the given parameter: + - (): a list with all available types, as strings; + - (type): the chosen sub-theme. + """ + + class ThemeUI: + """ + The User Interface sub-theme + ============================ + This can be accessed with theme.get(t), where t can be 'ui' or -1. + The available variables follow the internal (C coded) ThemeUI struct in + Blender. Most of them represent rgba (red, green, blue, alpha) colors, + with each component in the range [0, 255]. There is more than one way to + access them. + + Examples:: + print outline.R + outline.r = 180 # it's case insensitive + outline[0] = 94 # 0 for red, 1 for green, ... + outline = [200, 200, 200, 255] # setting all components at once + @type theme: string + @cvar theme: the parent Theme for this object. + @cvar outline: theme rgba var. + @cvar neutral: theme rgba var. + @cvar action: theme rgba var. + @cvar setting: theme rgba var. + @cvar setting1: theme rgba var. + @cvar setting2: theme rgba var. + @cvar num: theme rgba var. + @cvar textfield: theme rgba var. + @cvar popup: theme rgba var. + @cvar text: theme rgba var. + @cvar text_hi: theme rgba var. + @cvar menu_back: theme rgba var. + @cvar menu_item: theme rgba var. + @cvar menu_hilite: theme rgba var. + @cvar menu_text: theme rgba var. + @cvar menu_text_hi: theme rgba var. + @type drawType: int + @cvar drawType: the draw type (minimal, rounded, etc) in the range [1, 4]. + """ + + class ThemeSpace: + """ + The Space sub-themes + ==================== + There is a sub-theme for each space in Blender (except for the Scripts + window, but it will be added soon). Please read the information about + L{Theme.ThemeUI}, since it is also relevant here. In Blender, + all theme spaces share the same C structure. For this reason, all of + them here share the same variables, event though some spaces only use + a few of them. This lower-level access is acceptable because generally + users will prefer to use the interface to change single theme options + and only use scripting to save or restore themes. But anyway, checking + the Themes tab in the User Preferences space in Blender and using the + bundled "Save current theme" script (or its simplified version written + on the top of this page) can help you finding out any specific info you + may need. + @type theme: string + @cvar theme: the parent Theme for this object. + @cvar back: theme rgba var. + @cvar text: theme rgba var. + @cvar text_hi: theme rgba var. + @cvar header: theme rgba var. + @cvar panel: theme rgba var. + @cvar shade1: theme rgba var. + @cvar shade2: theme rgba var. + @cvar hilite: theme rgba var. + @cvar grid: theme rgba var. + @cvar wire: theme rgba var. + @cvar select: theme rgba var. + @cvar active: theme rgba var. + @cvar transform: theme rgba var. + @cvar vertex: theme rgba var. + @cvar vertex_select: theme rgba var. + @cvar edge: theme rgba var. + @cvar edge_select: theme rgba var. + @cvar edge_seam: theme rgba var. + @cvar edge_facesel: theme rgba var. + @cvar face: theme rgba var. + @cvar face_select: theme rgba var. + @cvar normal: theme rgba var. + @type vertex_size: int + @cvar vertex_size: size of the vertices dots on screen in the range [1, 10]. + """ + diff --git a/source/blender/python/api2_2x/doc/Window.py b/source/blender/python/api2_2x/doc/Window.py index 9cc17a26a2e..60f1396dbce 100644 --- a/source/blender/python/api2_2x/doc/Window.py +++ b/source/blender/python/api2_2x/doc/Window.py @@ -8,7 +8,7 @@ Window This module provides access to B{Window} functions in Blender. -B{New}: many new functions related to screens and events. +B{New}: L{GetPerspMatrix}. Example: -------- @@ -81,6 +81,12 @@ DrawProgressBar:: - LSHIFT - RSHIFT - SHIFT + +@type MButs: readonly dictionary +@var MButs: Mouse buttons. + - L: left mouse button + - M: middle mouse button + - R: right mouse button """ def Redraw (spacetype = '<Types.VIEW3D>'): @@ -201,6 +207,13 @@ def GetViewMatrix (): @return: the current matrix. """ +def GetPerspMatrix (): + """ + Get the current 3d perspective matrix. + @rtype: 4x4 float matrix + @return: the current matrix. + """ + def EditMode(enable = -1, undo_msg = 'From script'): """ Get and optionally set the current edit mode status: in or out. @@ -358,7 +371,7 @@ def SetMouseCoords (coords): def GetMouseButtons (): """ - Get the current mouse button state (compare with events from L{Draw}). + Get the current mouse button state (see / compare against L{MButs}). @rtype: int @return: an or'ed flag with the currently pressed buttons. """ diff --git a/source/blender/python/api2_2x/doc/World.py b/source/blender/python/api2_2x/doc/World.py index a8d10ce7073..cd2edd922eb 100644 --- a/source/blender/python/api2_2x/doc/World.py +++ b/source/blender/python/api2_2x/doc/World.py @@ -3,7 +3,7 @@ """ The Blender.World submodule -B{New}: scriptLink methods: L{World.getScriptLinks}, ... +B{New}: L{GetCurrent}, L{World.setCurrent}. INTRODUCTION ============ @@ -44,7 +44,7 @@ def New (name): @type name: string @param name: World's name (optionnal). @rtype: Blender World - @return: The created World. If the "name" paraeter has not been provided, it will be automatically be set by blender. + @return: The created World. If the "name" parameter has not been provided, it will be automatically be set by blender. """ def Get (name): @@ -59,7 +59,7 @@ def Get (name): """ -def GetActive (): +def GetCurrent (): """ Get the active world of the scene. @rtype: Blender World or None @@ -315,7 +315,7 @@ class World: @param event: "FrameChanged" or "Redraw". """ - def makeActive (): + def setCurrent (): """ Make this world active in the current scene. @rtype: PyNone |