Dev:2.4/Source/Extensions/BLU

BLU

What?

BLU is Blender LUa

NB:

• Currently the code is quite much "from-the-hip" coding, don't do this at home, since it is not good practice ;) (I have started a Use Case document in an attempt to formalise the design process. I'm also looking for a web-based requirement management system to use for the design process)

• Feel free to peek at the code, but it'll be ugly as hell until I get myself together to do it nicer, although I think that the not-so-feeble-of-mind should be able to jump right in and get the hang of it.

• I've been playing with #defines, so you'll see some heavy macro usage.

• After reading http://lists.blender.org/pipermail/bf-python/2005-September/003080.html I'll be compiling Lua with float as internal number type. Will report on it soonish. I compile now using float as the internal number format. I haven't spotted any drawbacks from it yet.

Where?

See my personal page for a crude startup (patch) of embedding Lua with Blender. Currently I do it so that Python is cut out. This also means no Game engine etc. For Lua a few (semi-) working modules are now available: Camera, Object, Lamp and Scene.

Why BLU?

Two reasons:

• I need to keep in touch with the codebase

• On the ML the trouble with different Python versions made me think of Lua as a good candidate for Python functionality without having compiling trouble on all the different platforms. The included Lua source in the zip on my personal page should compile on any system with a more or less sane ANSI C compiler. It is self-contained and should have no extra dependencies. In the source/blender/lua/libs directory I have included some external libs I like to see included as 'built-ins' for BLU.

todo/roadmap?

• design interfacing with Blender datatypes
• define naming conventions
  • filenaming
    • blu_[modulename].[c, blu_[modulename]_helper.[c
  • functions
    • blu_[modulename]_get_[member] - this can be handled by copying the macros used in lamp, scene and object
• design internal data representation and access
  • enums
    • use BLU_ENUM macro
  • dictionaries, constants. How should these be represented? Currently I use strings, ie. "Shadows", "Layer" (for Lamp modes). These strings are 'globally' available. I still need to determine if that is the wisest thing to do. 'Normal' constants would be more intuitive for scripters to work with, but that might create potential danger situations, where a scripter chooses a variable name that is already in use as a constant. This could be solved by using module scoping, but is that desirable?
  • bitmasks
• documentation
• example scripts
  • showing features
  • conversion of existing python scripts as proof
• make sure correct handling of license is done (inclusion of proper text, crediting authors of extra libs: lv3, lrandom, lbitlib...)

Apart from BLU itself the actual integration into the rest of Blender needs to be investigated: can BPy and BLU coexist? Is there any reason for them to coexist? Why? Why not?

Features

Blender data is accessible through modules. Follow a few 'features' of how Blender scripting is done with Lua. The list is more of a requirement list. Every entry will tell if it is implemented or not.

See also preliminary scripter documentation: API

Creating a new object

Create a new object (not Blender Object, but data object). Creating a new object means either creating entirely new data into Blender and having it usable in Lua scripting, or retreiving data from Blenders database in Lua usable form.

ob = Object.new(type, "name")

Create an entirely new Blender object of type type

• type, constant, one of Object.Lamp, Object.Camera, Object.Scene, Object.Ipo, Object.Curve (required) (TODO: determine all needed objects)

• name, string (optional)

ob = Object.get("name")

Retrieve a Blender object with name "name"

• name, string (required)

Methods

Perform operations on and with Blender data. Method calls are easily spotted by the colon

loc = ob:get_location()

Bitflags and constants/enums

Manipulate bitflags. This is still open. There are a few potential ways

in string

la = Lamp.new("Spot", "LuaLamp")
la:set_mode("Shadows|Layer")

multiple string

la = Lamp.new("Spot", "LuaLamp")
la:set_mode("Shadows", "Layer")

constants

la = Lamp.new("Spot", "LuaLamp")
la:set_mode(Shadows|Layer)

Constants (and enums) are accessible from their module, ie. Lamp.Spot or Camera.Persp

-- create an new lamp of type Sun
la = Lamp.new(Lamp.Sun, "LuaLamp")
-- set both Shadows and Layer bitflags
la:set_mode(Lamp.Shadows|Lamp.Layer)

Extra datatypes, modules

vector3

-- create vectors for either integers or floats with the same constructor
v = vector3(1,1,1)
v = vector3(1.0,1.0,1.0)
-- the same vector can be accessed in 3 different ways, even those can be mixed
print(v.x, v.y, v.z)
print(v.r, v.g, v.b)
print(v.1, v.2, v.3)
print(v.x, v.g, v.3)

vector3 is by Luiz Henrique de Figueiredo (03 Dec 2004 11:29:50, public domain)

bit (bitlib)

bittest = 8
print(bittest)
bittest = bit.lshift(bittest, 2)
print(bittest)
bittest = bit.rshift(bittest, 1)
print(bittest)
bittest = bit.bnot(bittest)
print(bittest)
bittest = bit.mod(bittest, 3)
print(bittest)

bitlib is by Reuben Thomas (nov00-09jan04)

What Lua version?

Current implementation is based on lua-5.1-alpha, which is included in the patch. Lua 5.1 final is expected to be released in a few months. When that happens I'll update this, too.

Changelog

20050916

• new function for helping in determining userdata type: blu_checkudata (blu_tools)

• start of Camera module

• linking of Camera data to Object

Test script

See test.lua

-- Nathan Letwory