diff options
author | Luca Bonavita <mindrones@gmail.com> | 2010-10-13 18:44:22 +0400 |
---|---|---|
committer | Luca Bonavita <mindrones@gmail.com> | 2010-10-13 18:44:22 +0400 |
commit | 9f05cc59fab2cd3e82be759e46bf4dacd2dbad05 (patch) | |
tree | 416b4c46535acc804fb80ce9d953bc94bf04aecc /doc/guides | |
parent | a81be2075f6304c18838fa2d26380342ba2f7894 (diff) |
== docs ==
- moved files in proper directories and adapted paths where needed
- deleted doc/oldbugs.txt (asked confirmation to jesterking a week ago in irc)
- still working on doxygen files, for now I'll leave them in doc/
- NOTE: while checking if other files were referring to these files, I noted that
"GPL-license.txt" is also used in the files below:
- release/windows/installer/00.sconsblender.nsi
- release/windows/specific.sh
but these files should't be affected by this commit, but please check :)
Diffstat (limited to 'doc/guides')
-rw-r--r-- | doc/guides/blender-guardedalloc.txt | 57 | ||||
-rw-r--r-- | doc/guides/interface_API.txt | 515 | ||||
-rw-r--r-- | doc/guides/python-dev-guide.txt | 170 |
3 files changed, 742 insertions, 0 deletions
diff --git a/doc/guides/blender-guardedalloc.txt b/doc/guides/blender-guardedalloc.txt new file mode 100644 index 00000000000..44a9722a4e4 --- /dev/null +++ b/doc/guides/blender-guardedalloc.txt @@ -0,0 +1,57 @@ +MEMORY MANAGEMENT IN BLENDER (guardedalloc) +------------------------------------------- + +NOTE: This file does not cover memutil and smart pointers and rerefence counted + garbage collection, which are contained in the memutil module. + +Blender takes care of dynamic memory allocation using a set of own functions +which are recognizeable through their MEM_ prefix. All memory allocation and +deallocation in blender is done through these functions. + +The following functions are available through MEM_guardedalloc.h: + +For normal operation: +--------------------- + +void *MEM_[mc]allocN(unsigned int len, char * str); + +- nearest ANSI counterpart: malloc() +- str must be a static string describing the memory block (used for debugging +memory management problems) +- returns a memory block of length len +- MEM_callocN clears the memory block to 0 + +void *MEM_dupallocN(void *vmemh); + +- nearest ANSI counterpart: combination malloc() and memcpy() +- returns a pointer to a copy of the given memory area + +short MEM_freeN(void *vmemh); + +- nearest ANSI counterpart: free() +- frees the memory area given by the pointer +- returns 0 on success and !=0 on error + +int MEM_allocN_len(void *vmemh); + +- nearest ANSI counterpart: none known +- returns the length of the given memory area + +For debugging: +-------------- + +void MEM_set_error_stream(FILE*); + +- this sets the file the memory manager should use to output debugging messages +- if the parameter is NULL the messages are suppressed +- default is that messages are suppressed + +void MEM_printmemlist(void); + +- if err_stream is set by MEM_set_error_stream() this function dumps a list of all +currently allocated memory blocks with length and name to the stream + +int MEM_check_memory_integrity(void); + +- this function tests if the internal structures of the memory manager are intact +- returns 0 on success and !=0 on error diff --git a/doc/guides/interface_API.txt b/doc/guides/interface_API.txt new file mode 100644 index 00000000000..c98794444e6 --- /dev/null +++ b/doc/guides/interface_API.txt @@ -0,0 +1,515 @@ +--------------------------------------------------- +Blender interface.c API toolkit notes +(july 2003, Ton Roosendaal) +--------------------------------------------------- + +Contents + +1 General notes +1.1 C and H files + +2. Windows & Blocks +2.1 Memory allocation +2.2 And how it works internally + +3. API for uiBlock +3.1 uiBlock Controlling functions +3.2 Internal function to know + +4. API for uiButton +4.1 UiDefBut + 1. BUT + 2. TOG or TOGN or TOGR + TOG|BIT|<nr> + 3. TOG3|BIT|<nr> + 4. ROW + 5. SLI or NUMSLI or HSVSLI + 6. NUM + 7. TEX + 8. LABEL + 9 SEPR + 10. MENU + 11. COL +4.2 Icon buttons + 12. ICONROW + 13. ICONTEXTROW +4.3 pulldown menus / block buttons + 14. BLOCK +4.4 specials + 15. KEYEVT + 16. LINK and INLINK + 17. IDPOIN +4.5 uiButton control fuctions + + +----------------1. General notes + +- The API is built with Blender in mind, with some buttons acting on lists of Blender data. + It was not meant to be available as a separate SDK, nor to be used for other applications. + +- It works with only OpenGL calls, for the full 100%. This means that it has some quirks + built-in to work with all OS's and OpenGL versions. Especially frontbuffer drawing is + a continuous point of attention. Buttons can be drawn with any window matrix. However, + errors can still occor when buttons are created in windows with non-standard glViewports. + +- The code was written to replace the old 1.8 button system, but under high pressure. Quite + some button methods from the old system were copied for that reason. + +- I tried to design a unified GUI system, which equally works for pulldown menus, pop up menus, + and normal button layouts. Although it gives nice features and freedom in design, the code + looks quite hard to understand for that reason. Not all 'normal' pulldown menu features + could be hacked in easily, they just differ too much from other UI elements. Could be + looked at once... + +- During the past period of NaN (beginning of 2002) someone tried to make a more 'high' level + API for it, with less low level defines and structure info needed in calling code. I am not + really sure if this was done well... or even finished. In the bottom of interface.c you can + see the 'new' API which is now used in Blender code. It used to be so much more simple! + Nevertheless, I will use that convention in this doc. + +- Unfinished stuff: the code was scheduled to be expanded with 'floating blocks' which can + serve as permanent little button-fields in Blender windows. Think for example of having + an (optional) extra field in the 3d window displaying object loc/rot/size. + After that, the existing button windows can be reorganized in such blocks as well, allowing + a user to configure the genereal buttons layout (make vertical for example). + + +--------------1.1 C and H files + +blender/source/blender/src/interface.c /* almost all code */ +blender/source/blender/include/interface.h /* internals for previous code */ +blender/source/blender/include/BIF_interface.h /* externals for previous code */ + +(the previous 2 include files have not been separated fully yet) + +Color and icons stuff has been put in: (unfinished code, under development) +blender/source/blender/src/resources.c +blender/source/blender/include/BIF_resources.h + +Related code: +blender/source/blender/src/toolbox.c (extra GUI elements built on top of this API) + + +--------------2. Windows & Blocks + +All GUI elements are collected in uiBlocks, which in turn are linked together in a list that's +part of a Blender Area-window. + + uiBlock *block= uiNewBlock(&curarea->uiblocks, "stuff", UI_EMBOSSX, UI_HELV, curarea->win); + +The next code example makes a new block, and puts it in the list of blocks of the current active +Area: + + uiDoBlocks(&curarea->uiblocks, event); + +This code is usually available in each area-window event queue handler. You give uiDoBlocks +an event code, and the uiDoBlocks handles whatever is to be handled. Blocks can be +standard buttons or pull down menus. Can return immediately, or jump to an internal handling +loop. + +2.1 Memory allocation + +Important to know is that for this toolkit there's no difference in "creating blocks" or +"drawing blocks". In fact, for each window redraw all blocks are created again. Constructing +button interfaces in Blender always happens in the main drawing function itself. + +Memory allocation is handled as follows: +- if in this window a uiBlock with the same name existed, it is freed +- when you close a window (or blender) the uiBlocks get freed. +- when you duplicate (split) a window, the uiBlocks get copied + +2.2 And how it works internally + +With a call to uiDoblocks, all blocks in the current active window are evaluated. +It walks through the lists in a rather complex manner: + +- while(looping) + + /* the normal buttons handling */ + - for each block + - call uiDoBlock (handles buttons for single block) + - (end for) + + /* at this moment, a new block can be created, for a menu */ + /* so we create a 2nd loop for it */ + - while first block is a menu + - if block is a menu and not initialized: + - initalize 'saveunder' + - draw it + - get event from queue + - call uiDoBlock (handles buttons for single block) + /* here, a new block again can be created, for a sub menu */ + - if return "end" from uiDoBlock + restore 'saveunder's + free all menu blocks + exit from loop + - do tooltip if nothing has happened + - (end while) + + - if there was menu, it does this loop once more + (when you click outside a menu, at another button) + +- (end while) + +- do tooltip if nothing has happened + + + +-------------3. API for uiBlock + +Create a new buttons block, and link it to the window: + +uiBlock *uiNewBlock(ListBase *lb, char *name, short dt, short font, short win) + ListBase *lb pointer to list basis, where the block will be appended to (blenlib) + char *name unique name to identify the block. When the name exists in the list, + the old uiBlock gets freed. + short dt drawtype. See below + short font font id number + short win blender area-window id + +drawtype: + UI_EMBOSSX 0 /* Rounded embossed button (standard in Blender) */ + UI_EMBOSSW 1 /* Simpler embossed button */ + UI_EMBOSSN 2 /* Button with no border */ + UI_EMBOSSF 3 /* Square embossed button (file select) */ + UI_EMBOSSM 4 /* Colored, for pulldown menus */ + UI_EMBOSSP 5 /* Simple borderless coloured button (like blender sensors) */ + +font: + UI_HELV 0 /* normal font */ + UI_HELVB 1 /* bold font */ +With the new truetype option in Blender, this is used for all font families + +When a uiBlock is created, each uiButton that is defined gets the uiBlock properties. +Changing Block properties inbetween will affact uiButtons defined thereafter. + + + +----------3.1 uiBlock Controlling functions: + +void uiDrawBlock(block) + draws the block + +void uiBlockSetCol(uiBlock *block, int col) + +col: + BUTGREY, + BUTGREEN, + BUTBLUE, + BUTSALMON, + MIDGREY, + BUTPURPLE, + +void uiBlockSetEmboss(uiBlock *block, int emboss) + changes drawtype + +void uiBlockSetDirection(uiBlock *block, int direction) + for pop-up and pulldown menus: + +direction: + UI_TOP + UI_DOWN + UI_LEFT + UI_RIGHT + +void uiBlockSetXOfs(uiBlock *block, int xofs) + for menus, offset from parent + +void uiBlockSetButmFunc(uiBlock *block, void (*menufunc)(void *arg, int event), void *arg) + sets function to be handled when a menu-block is marked "OK" + +void uiAutoBlock(uiBlock *block, float minx, float miny, float sizex, float sizey, UI_BLOCK_ROWS) + + Sets the buttons in this block to automatically align, and fit within boundaries. + Internally it allows multiple collums or rows as well. Only 'row order' has been implemented. + The uiDefBut definitions don't need coordinates as input here, but instead: + - first value (x1) to indicate row number + - width and height values (if filled in) will be used to define a relative width/height. + A call to uiDrawBlock will invoke the calculus to fit in all buttons. + + + +---------- 3.2 Internal function to know: + +These flags used to be accessible from outside of interface.c. Currently it is only +used elsewhere by toolbox.c, so it can be considered 'internal' somewhat. + +void uiBlockSetFlag(uiBlock *block, int flag) /* block types, can be 'OR'ed */ + UI_BLOCK_LOOP 1 a sublooping block, drawn in frontbuffer, i.e. menus + UI_BLOCK_REDRAW 2 block needs a redraw + UI_BLOCK_RET_1 4 block is closed when an event happens with value '1' (press key, not for mouse) + UI_BLOCK_BUSY 8 internal + UI_BLOCK_NUMSELECT 16 keys 1-2-...-9-0 can be used to select items + UI_BLOCK_ENTER_OK 32 enter key closes block with "OK" + +(these values are being set within the interface.c and toolbox.c code.) + + +-------------4. API for uiButton + +In Blender a button can do four things: + +- directly visualize data, and write to it. +- put event codes (shorts) back in the queue, to be handled +- call a user-defined function pointer (while being pressed, etc) +- create and call another block (i.e. menu) + +Internally, each button or menu item is a 'uiButton', with a generic API and handling: +ui_def_but(block, type, retval, str, x1, y1, x2, y2, poin, min, max, a1, a2, tip); + +Beacause a lot of obscure generic (re-use) happens here, translation calls have been made +for each most button types individually. + + +-----------4.1 UiDefBut + +uiBut *UiDefBut[CSIF]( uiBlock *block, int type, int retval, char *str, + short x1, short y1, short x2, short y2, xxxx *poin, + float min, float max, float a1, float a2, char *tip) + +UiDefButC operatates on char +UiDefButS operatates on short +UiDefButI operatates on int +UiDefButF operatates on float + +*block: current uiBlock pointer +type: see below +retval: return value, which is put back in queue +*str: button name +x1, y1: coordinates of left-lower corner +x2, y2: width, height +*poin: pointer to char, short, int, float +min, max used for slider buttons +a1, a2 extra info for some buttons +*tip: tooltip string + +type: + +1. BUT + Activation button. (like "Render") + Passing on a pointer is not needed + +2. TOG or TOGN or TOGR + Toggle button (like "Lock") + The pointer value is set either at 0 or 1 + If pressed, it calls the optional function with arguments provided. + Type TOGN: works negative, when pressed it sets at 0 + Type TOGR: is part of a row, redraws automatically all buttons with same *poin + + "|BIT|<nr>" + When added to type, it works on a single bit <nr> (lowest order bit: nr = '0') + +3. TOG3|BIT|<nr> + A toggle with 3 values! + Can be only used for short *poin. + In the third toggle setting, the bit <nr> of *( poin+1) is set. + +4. ROW + Button that's part of a row. + in "min" you set a row-id number, in "max" the value you want *poin to be + assigned when you press the button. Always pass on these values as floats. + When this button is pressed, it sets the "max" value to *poin, and redraws + all buttons with the same row-id number. + +5. SLI or NUMSLI or HSVSLI + Slider, number-slider or hsv-slider button. + "min" and "max" are to clamp the value to. + If you want a button type "Col" to be updated, make 'a1' equal to 'retval' + from the COL button. + +6. NUM + Number button + Set the clamping values 'min' and 'max' always as float. + For UiDefButF, set a 'step' in 'a1', in 1/100's. The step value is the increment or + decrement when you click once on the right or left side of a button. + The optional button function is additionally called for each change of the *poin value. + +7. TEX + Text string button. + Pointertype is standard a char. Value 'max' is length of string (pass as float). + When button is left with ESC, it doesn't put the 'retval' at the queue. + +8. LABEL + Label button. + Only displays text. + If 'min' is set at 1.0, the text is printed in white. + +9 SEPR + A separator line, typically used within pulldown menus. + +10. MENU + Menu button. + The syntax of the string in *name defines the menu items: + - %t means the previous text becomes the title + - item separator is '|' + - return values are indicated with %x[nr] (i.e: %x12). + without returnvalues, the first item gets value 0 (incl. title!) + Example: "Do something %t| turn left %2| turn right %1| nothing %0" + +11. COL + A special button that only visualizes a RGB value + In 'retval' you can put a code, which is used to identify for sliders if it needs + redraws while using the sliders. Check button '5'. + As *poin you input the pointer to the 'r' value, 'g' and 'b' are supposed to be + next to that. + + +------------4.2 Icon buttons + +Instead of a 'name', all buttons as described for uiDefBut also can have an icon: + +uiBut *uiDefIconBut(uiBlock *block, int type, int retval, int icon, + short x1, short y1, short x2, short y2, void *poin, + float min, float max, float a1, float a2, char *tip) + + Same syntax and types available as previous uiDefBut, but now with an icon code + instead of a name. THe icons are numbered in resources.c + +uiBut *uiDefIconTextButF(uiBlock *block, int type, int retval, int icon, char *str, + short x1, short y1, short x2, short y2, float *poin, + float min, float max, float a1, float a2, char *tip) + + Same again, but now with an icon and string as button name. + +Two special icon buttons are available in Blender: + +12. ICONROW + (uiDefIconBut) + This button pops up a vertical menu with a row of icons to choose from. + 'max' = amount of icons. The icons are supposed to be ordered in a sequence + It writes in *poin which item in the menu was choosen (starting with 0). + +13. ICONTEXTROW + (uiDefIconTextBut) + Same as previous, but with the texts next to it. + + + +-----------4.3 pulldown menus / block buttons + +14. BLOCK +void uiDefBlockBut(uiBlock *block, uiBlockFuncFP func, void *arg, char *str, + short x1, short y1, short x2, short y2, char *tip) + + This button creates a new block when pressed. The function argument 'func' is called + to take care of this. An example func: + + static uiBlock *info_file_importmenu(void *arg_unused) + { + uiBlock *block; + short yco= 0, xco = 20; + + block= uiNewBlock(&curarea->uiblocks, "importmenu", UI_EMBOSSW, UI_HELV, G.curscreen->mainwin); + uiBlockSetXOfs(block, -40); // offset to parent button + + /* flags are defines */ + uiDefBut(block, LABEL, 0, "VRML 2.0 options", xco, yco, 125, 19, NULL, 0.0, 0.0, 0, 0, ""); + uiDefButS(block, TOG|BIT|0, 0, "SepLayers", xco, yco-=20, 75, 19, &U.vrmlflag, 0.0, 0.0, 0, 0, ""); + uiDefButS(block, TOG|BIT|1, 0, "Scale 1/100", xco, yco-=20, 75, 19, &U.vrmlflag, 0.0, 0.0, 0, 0, ""); + uiDefButS(block, TOG|BIT|2, 0, "Two Sided", xco, yco-=20, 75, 19, &U.vrmlflag, 0.0, 0.0, 0, 0, ""); + + uiBlockSetDirection(block, UI_RIGHT); + uiTextBoundsBlock(block, 50); // checks for fontsize + + return block; + } + + The uiDef coordinates here are only relative. When this function is called, the interface + code automatically makes sure the buttons fit in the menu nicely. + + Inside a menu uiBlock, other uiBlocks can be invoked to make a hierarchical menu. + + + +-----------4.4 specials + +15. KEYEVT + +void uiDefKeyevtButS(uiBlock *block, int retval, char *str, + short x1, short y1, short x2, short y2, short *spoin, char *tip) + + A special button, which stores a keyvalue in *spoin. When the button is pressed, + it displays the text 'Press any Key'. A keypress then stores the value. + +16. LINK and INLINK + + These button present a method of linking data in Blender, by drawing a line from one + icon to another. It consists of two button types: + + LINK, the 'linking from' part, can be: + - a single pointer to data (only one line allowed) + - an array of pointers to data. The LINK buttons system keeps track of allocating + space for the array, and set the correct pointers in it. + + INLINK, the 'linking to' part activates creating a link, when a user releases the mouse + cursor over it, while dragging a line from the LINK button. + + These buttons are defined as follows: + + +uiBut but= uiDefIconBut(block, LINK, 0, ICON_LINK, x1, y1, w, h, NULL, 0, 0, 0, 0, ""); + /* create the LINK icon */ + +uiSetButLink(but, void **pt, void ***ppt, short *totlink, short fromcode, short tocode); + **pt: pointer to pointer (only one link allowed) + ***ppt: pointer to pointerpointer (an array of pointers) + (Either one of these values should be NULL) + + fromcode: (currently unused) + tocode: a short indicating which blocks it can link to. + + +uiDefIconBut(block, INLINK, 0, ICON_INLINK, x1, y1, w, h, void *poin, short fromcode, 0, 0, 0, ""); + poin: the pointer of the datablock you want to create links to + fromcode: a short identifying which LINK buttons can connect to it + + + +17. IDPOIN +void uiDefIDPoinBut(uiBlock *block, uiIDPoinFuncFP func, int retval, char *str, + short x1, short y1, short x2, short y2, void *idpp, char *tip) + + The ID struct is a generic part in structs like Object, Material, Mesh, etc. + Most linking options in Blender happens using ID's. (Mesh -> Material). + + This special button in Blender visualizes an ID pointer with its name. Typing in + a new name, changes the pointer. For most ID types in Blender functions have been + written already, needed by this button, to check validity of names, and assign the pointer. + + (BTW: the 'void *idpp' has to be a pointer to the ID pointer!) + + Example function that can be put in 'func': + + void test_scriptpoin_but(char *name, ID **idpp) + { + ID *id; + + id= G.main->text.first; + while(id) { + if( strcmp(name, id->name+2)==0 ) { + *idpp= id; + return; + } + id= id->next; + } + *idpp= 0; + } + + +------------- 4.5 uiButton control fuctions + + +void uiButSetFunc(uiBut *but, void (*func)(void *arg1, void *arg2), void *arg1, void *arg2) + When the button is pressed and released, it calls this function, with the 2 arguments. + +void uiButSetFlag(uiBut *but, int flag) + set a flag for further control of button behaviour: + flag: + UI_TEXT_LEFT + +int uiButGetRetVal(uiBut *but) + gives return value + + +</body> +<br><br><br> diff --git a/doc/guides/python-dev-guide.txt b/doc/guides/python-dev-guide.txt new file mode 100644 index 00000000000..75c9ccb57e5 --- /dev/null +++ b/doc/guides/python-dev-guide.txt @@ -0,0 +1,170 @@ +Simple Blender Python Developer's Guide +--------------------------------------- + +This is an outline for a future guide yet to be written. It is meant for +programmers wanting to understand and maybe help with the embedding of Python +inside Blender. + +I - Introduction + +We could praise Python here for its many qualities, but it's probably better +to just give some links: + +The main site is at www.python.org , with documentation at www.python.org/doc/ + +Also worth of mention: it's an interpreted language and is available for +many different systems. The download includes the interpreter, many modules +(think libs), good documentation and some programs / examples. If you use +linux, there's a high chance you already have Python installed, just try +"man python". + +The reason for embedding a language environment inside Blender is to give +users the ability to access the program's internal data and functionality. +This can be used to import / export (from / to other 2d / 3d formats) or +change the data (to create new objects procedurally, among many other +interesting possibilities). Script writers (Blender Python programmers) can +also expand Blender in new ways, adding new features on-the-fly, without having +to recompile it. It is usually much easier and faster to write scripts in +Python than to code the equivalent in C. + +II - Reference material: + +There are two important texts for us in the documentation that comes +with Python ( docs also available online at www.python.org ): + +- Extending and Embedding (tutorial for C/C++ programmers) + +and specially + +- Python/C API. + +You can read the first one to get a feel for how things are done +(reference counting is probably the most important part), but the second +doc is a must. Specially useful as a fast reference is its Index, at letter +P, where all commands are. + +Specially useful commands are Py_BuildValue and the family of parsing +functions, PyArg_Parse* (PyArg_Parse(), PyArg_ParseTuple(), +PyArg_ParseTupleAndKeywords()). Py_BuildValue is usually the best way to make +Python Objects (the 'variables' that the Python Interpreter understands) +out of C ones. The PyArg_Parse* functions do the opposite, they parse +Python Objects to C variables. + +So, understand PyArg_Parse* functions, Py_BuildValue and reference +counting. The first doc has a good discussion about them. + +- C knowledge is also necessary, of course, use your favorite resource. + +- The Blender 2.25 API documentation ( www.blender.org ) is, along with +the source, our basic API ref. + +III - Directories + +The previous Blender Python API's are spread in blender/intern/python +and the C part of the current one, bpython, is at +blender/source/blender/bpython/, specially in intern/. The current +solution is a Python wrapper on top of this bpython one, at +blender/intern/python/modules/Blender/ + +Note: since it's in Python, they needed the freeze Python utility, a +process/program that creates stand-alone executables out of Python +source files -- that is, it packs together an interpreter, the needed +modules and the source of a Python program so that users of this program +don't need to have the Python interpreter already installed in their +machines to run the program -- Blender, in this case. + +The new implementation is pure C, so we won't need to "freeze" it. + +Another important dir for starters is blender/source/blender/makesdna, +where the headers with Blender structs lie. + +IV - Experimental Python + +The new implementation, currently referred to as experimental python - +exppython - was started by Michel Selten. He chose to solve the mess in +Blender Python by starting over from scratch, in C, but keeping API +compatibility with the current 2.25 API used by Blender. + +It is in blender/source/blender/python , more specifically inside +api2_2x/ + +To make it clear, exppython is the new implementation being worked on. It +will possibly become the de-facto implementation in Blender 2.28, the next +Blender version. Currently, Blender still comes with the same implementation +found in the 2.25 version of the program. So we call that the 2.25 +implementation, or bpython. + +BPython had plenty of "macro magic", lot's of complicate #define's, etc., +since a lot of the embedding work is quite repetitive. But that makes it +much harder for newbies to jump in and learn, so the new files in exppython +avoid that. + +This means: Blender, Object, Camera, Lamp, Image, Text, Window modules +(the files have the same names, ending obviously with .c and .h) + +To speed things up, some independent parts of bpython are being +integrated directly into exppython. That already happened with Draw and +BGL, both taken from opy_draw.c in the bpython/intern dir. The same is +happening with NMesh (Mesh is written in Python and imports NMesh to +extend / change its functionality). + +For a good example of dexterity with macros (cheers to the NaN +programmer(s)!), look at BGL.[ch], the OpenGL API wrapper. The defines +are in the header. + +Besides keeping compatibility with the 2.25 API, there are already some +additions to exppython: + +- some modules have access to more variables than 2.25 had; +- there are more method functions and the access is safer; +- the file selector (or file browser, if you prefer) is back: + It's now in the Window module, along with an image selector, too. +- there are totally new modules, unavailable in 2.25: + Fellow new developers joining our team are contributing new modules + that have been requested by the community for a long time. + + +V - Coding + +The Camera module is a good reference, since it is like most others, in +terms of programming, but is smaller and simple. It's in Camera.c and +Camera.h . To have it working, it was also necessary to include a line to +the end of Blender.c (registering it as a Blender submodule) and another to +modules.h (declaring its init and CreateObject method) + +Currently, one of our conventions is to prepend M_ to module functions, +doc strings, etc. and C_ to the new types we had to create for Python, +like C_Camera, C_Lamp, etc. + +If you look at Camera.[ch], you'll find code for creating the Camera +module and the Camera "type", with all its methods and access policies. +It's really a new type defined in Python, like PyInt or PyFloat, +PyString, etc. In practice, it's a "thin" (because it doesn't make +copies of the variables) wrapper for the Blender Camera Data Object. + +A note about Blender: objects in Blender share a common base, the +Object, whose attributes are things like the matrix, the location, the +rotation, the size, etc. A Camera is actually an Object of type Camera +(which means that its "data" field points to a Camera Data obj) and a +Camera Data object, which is the specific camera part of the object +(attributes like lens, clip start, etc.). Same for other objects, like +Lamp, Mesh, etc. + +That's why C_Camera is a wrapper for the Blender Camera **Data** +object. The full wrapper is Object("Camera") linked with +Camera("camera_name"). + +How to write a new module for a simple object? Use Camera.[ch] as +templates, check the specifics of your object in the makesdna dir +(for example, the camera one is DNA_camera_types.h) and make the +necessary changes. + +If you want to help exppython and in the process possibly learn more about +embedding, the Python/C API and Blender internals, there's this mailing list: + +Bf-python mailing list +Bf-python@blender.org +http://www.blender.org/mailman/listinfo/bf-python + +There you can ask what hasn't been done yet, get help, make suggestions for +new features we should consider, send bug reports, etc. |