← Back to branch summary

~siretart/ubuntu/utopic/blender/libav10

« back to all changes in this revision

Viewing changes to doc/guides/interface_API.txt

  • Committer: Package Import Robot
  • Author(s): Matteo F. Vescovi
  • Date: 2012-07-23 08:54:18 UTC
  • mfrom: (14.2.16 sid)
  • mto: (14.2.19 sid)
  • mto: This revision was merged to the branch mainline in revision 42.
  • Revision ID: package-import@ubuntu.com-20120723085418-9foz30v6afaf5ffs
Tags: 2.63a-2
http://bugs.debian.org/658075
* debian/: Cycles support added (Closes: #658075)
  For now, this top feature has been enabled only
  on [any-amd64 any-i386] architectures because
  of OpenImageIO failing on all others
* debian/: scripts installation path changed
  from /usr/lib to /usr/share:
  + debian/patches/: patchset re-worked for path changing
  + debian/control: "Breaks" field added on yafaray-exporter

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/guides/interface_API.txt
 
1
---------------------------------------------------
 
2
Blender interface.c API toolkit notes
 
3
(july 2003, Ton Roosendaal)
 
4
---------------------------------------------------
 
5
 
 
6
Contents
 
7
 
 
8
1 General notes
 
9
1.1 C and H files
 
10
 
 
11
2. Windows & Blocks 
 
12
2.1 Memory allocation
 
13
2.2 And how it works internally
 
14
 
 
15
3. API for uiBlock
 
16
3.1 uiBlock Controlling functions
 
17
3.2 Internal function to know
 
18
 
 
19
4. API for uiButton 
 
20
4.1 UiDefBut
 
21
        1. BUT
 
22
        2. TOG or TOGN or TOGR
 
23
           TOG|BIT|<nr>
 
24
        3. TOG3|BIT|<nr>
 
25
        4. ROW
 
26
        5. SLI or NUMSLI or HSVSLI
 
27
        6. NUM
 
28
        7. TEX
 
29
        8. LABEL
 
30
        9  SEPR
 
31
        10. MENU
 
32
        11.     COL
 
33
4.2 Icon buttons
 
34
        12. ICONROW
 
35
        13. ICONTEXTROW
 
36
4.3 pulldown menus / block buttons
 
37
        14. BLOCK
 
38
4.4 specials
 
39
        15. KEYEVT
 
40
        16. LINK and INLINK
 
41
        17. IDPOIN
 
42
4.5 uiButton control fuctions
 
43
 
 
44
 
 
45
----------------1. General notes
 
46
 
 
47
- The API is built with Blender in mind, with some buttons acting on lists of Blender data.
 
48
  It was not meant to be available as a separate SDK, nor to be used for other applications.
 
49
  
 
50
- It works with only OpenGL calls, for the full 100%. This means that it has some quirks
 
51
  built-in to work with all OS's and OpenGL versions. Especially frontbuffer drawing is 
 
52
  a continuous point of attention. Buttons can be drawn with any window matrix. However,
 
53
  errors can still occor when buttons are created in windows with non-standard glViewports.
 
54
  
 
55
- The code was written to replace the old 1.8 button system, but under high pressure. Quite
 
56
  some button methods from the old system were copied for that reason.
 
57
  
 
58
- I tried to design a unified GUI system, which equally works for pulldown menus, pop up menus,
 
59
  and normal button layouts. Although it gives nice features and freedom in design, the code 
 
60
  looks quite hard to understand for that reason. Not all 'normal' pulldown menu features 
 
61
  could be hacked in easily, they just differ too much from other UI elements. Could be 
 
62
  looked at once...
 
63
  
 
64
- During the past period of NaN (beginning of 2002) someone tried to make a more 'high' level
 
65
  API for it, with less low level defines and structure info needed in calling code. I am not 
 
66
  really sure if this was done well... or even finished. In the bottom of interface.c you can
 
67
  see the 'new' API which is now used in Blender code. It used to be so much more simple!
 
68
  Nevertheless, I will use that convention in this doc.
 
69
 
 
70
- Unfinished stuff: the code was scheduled to be expanded with 'floating blocks' which can
 
71
  serve as permanent little button-fields in Blender windows. Think for example of having
 
72
  an (optional) extra field in the 3d window displaying object loc/rot/size.
 
73
  After that, the existing button windows can be reorganized in such blocks as well, allowing
 
74
  a user to configure the genereal buttons layout (make vertical for example).
 
75
  
 
76
 
 
77
--------------1.1 C and H files
 
78
 
 
79
blender/source/blender/src/interface.c  /* almost all code */
 
80
blender/source/blender/include/interface.h      /* internals for previous code */
 
81
blender/source/blender/include/BIF_interface.h  /* externals for previous code */
 
82
 
 
83
(the previous 2 include files have not been separated fully yet)
 
84
 
 
85
Color and icons stuff has been put in: (unfinished code, under development)
 
86
blender/source/blender/src/resources.c 
 
87
blender/source/blender/include/BIF_resources.h
 
88
 
 
89
Related code:
 
90
blender/source/blender/src/toolbox.c (extra GUI elements built on top of this API)
 
91
 
 
92
 
 
93
--------------2. Windows & Blocks 
 
94
 
 
95
All GUI elements are collected in uiBlocks, which in turn are linked together in a list that's 
 
96
part of a Blender Area-window.
 
97
 
 
98
        uiBlock *block= uiNewBlock(&curarea->uiblocks, "stuff", UI_EMBOSSX, UI_HELV, curarea->win);
 
99
 
 
100
The next code example makes a new block, and puts it in the list of blocks of the current active 
 
101
Area:
 
102
 
 
103
        uiDoBlocks(&curarea->uiblocks, event);
 
104
 
 
105
This code is usually available in each area-window event queue handler. You give uiDoBlocks
 
106
an event code, and the uiDoBlocks handles whatever is to be handled. Blocks can be 
 
107
standard buttons or pull down menus. Can return immediately, or jump to an internal handling 
 
108
loop.
 
109
 
 
110
2.1 Memory allocation
 
111
 
 
112
Important to know is that for this toolkit there's no difference in "creating blocks" or 
 
113
"drawing blocks". In fact, for each window redraw all blocks are created again. Constructing 
 
114
button interfaces in Blender always happens in the main drawing function itself.
 
115
 
 
116
Memory allocation is handled as follows:
 
117
- if in this window a uiBlock with the same name existed, it is freed
 
118
- when you close a window (or blender) the uiBlocks get freed.
 
119
- when you duplicate (split) a window, the uiBlocks get copied
 
120
 
 
121
2.2 And how it works internally
 
122
 
 
123
With a call to uiDoblocks, all blocks in the current active window are evaluated.
 
124
It walks through the lists in a rather complex manner:
 
125
 
 
126
- while(looping)
 
127
 
 
128
        /* the normal buttons handling */
 
129
        - for each block
 
130
                - call uiDoBlock (handles buttons for single block)
 
131
        - (end for)
 
132
        
 
133
        /* at this moment, a new block can be created, for a menu */
 
134
        /* so we create a 2nd loop for it */
 
135
        - while first block is a menu
 
136
                - if block is a menu and not initialized: 
 
137
                        - initalize 'saveunder'
 
138
                        - draw it 
 
139
                - get event from queue
 
140
                - call uiDoBlock (handles buttons for single block)
 
141
                /* here, a new block again can be created, for a sub menu */
 
142
                - if return "end" from uiDoBlock
 
143
                        restore 'saveunder's
 
144
                        free all menu blocks
 
145
                        exit from loop
 
146
                - do tooltip if nothing has happened
 
147
        - (end while)
 
148
        
 
149
        - if there was menu, it does this loop once more
 
150
          (when you click outside a menu, at another button)
 
151
        
 
152
- (end while)
 
153
 
 
154
- do tooltip if nothing has happened
 
155
 
 
156
 
 
157
 
 
158
-------------3. API for uiBlock 
 
159
 
 
160
Create a new buttons block, and link it to the window:
 
161
 
 
162
uiBlock *uiNewBlock(ListBase *lb, char *name, short dt, short font, short win)
 
163
        ListBase *lb    pointer to list basis, where the block will be appended to (blenlib)
 
164
        char *name              unique name to identify the block. When the name exists in the list,
 
165
                                        the old uiBlock gets freed.
 
166
        short dt                drawtype. See below
 
167
        short font              font id number
 
168
        short win               blender area-window id
 
169
 
 
170
drawtype:
 
171
        UI_EMBOSSX              0       /* Rounded embossed button (standard in Blender) */
 
172
        UI_EMBOSSW              1       /* Simpler embossed button */
 
173
        UI_EMBOSSN              2       /* Button with no border */
 
174
        UI_EMBOSSF              3       /* Square embossed button (file select) */
 
175
        UI_EMBOSSM              4       /* Colored, for pulldown menus */
 
176
        UI_EMBOSSP              5       /* Simple borderless coloured button (like blender sensors) */
 
177
 
 
178
font:
 
179
        UI_HELV                 0       /* normal font */
 
180
        UI_HELVB                1       /* bold font */
 
181
With the new truetype option in Blender, this is used for all font families
 
182
 
 
183
When a uiBlock is created, each uiButton that is defined gets the uiBlock properties.
 
184
Changing Block properties inbetween will affact uiButtons defined thereafter.
 
185
 
 
186
 
 
187
 
 
188
----------3.1 uiBlock Controlling functions:
 
189
 
 
190
void uiDrawBlock(block) 
 
191
        draws the block
 
192
 
 
193
void uiBlockSetCol(uiBlock *block, int col)     
 
194
 
 
195
col:
 
196
        BUTGREY,
 
197
        BUTGREEN,
 
198
        BUTBLUE,
 
199
        BUTSALMON,
 
200
        MIDGREY,
 
201
        BUTPURPLE,
 
202
 
 
203
void uiBlockSetEmboss(uiBlock *block, int emboss)
 
204
        changes drawtype
 
205
 
 
206
void uiBlockSetDirection(uiBlock *block, int direction) 
 
207
        for pop-up and pulldown menus:
 
208
 
 
209
direction:
 
210
        UI_TOP  
 
211
        UI_DOWN 
 
212
        UI_LEFT 
 
213
        UI_RIGHT
 
214
 
 
215
void uiBlockSetXOfs(uiBlock *block, int xofs)
 
216
        for menus, offset from parent
 
217
 
 
218
void uiBlockSetButmFunc(uiBlock *block, void (*menufunc)(void *arg, int event), void *arg)
 
219
        sets function to be handled when a menu-block is marked "OK"
 
220
        
 
221
void uiAutoBlock(uiBlock *block, float minx, float miny, float sizex, float sizey, UI_BLOCK_ROWS)
 
222
 
 
223
        Sets the buttons in this block to automatically align, and fit within boundaries. 
 
224
        Internally it allows multiple collums or rows as well. Only 'row order' has been implemented.
 
225
        The uiDefBut definitions don't need coordinates as input here, but instead:
 
226
        - first value (x1) to indicate row number
 
227
        - width and height values (if filled in) will be used to define a relative width/height.
 
228
        A call to uiDrawBlock will invoke the calculus to fit in all buttons.
 
229
 
 
230
 
 
231
 
 
232
---------- 3.2 Internal function to know:
 
233
 
 
234
These flags used to be accessible from outside of interface.c. Currently it is only
 
235
used elsewhere by toolbox.c, so it can be considered 'internal' somewhat.
 
236
 
 
237
void uiBlockSetFlag(uiBlock *block, int flag)   /* block types, can be 'OR'ed */
 
238
        UI_BLOCK_LOOP           1               a sublooping block, drawn in frontbuffer, i.e. menus
 
239
        UI_BLOCK_REDRAW         2               block needs a redraw
 
240
        UI_BLOCK_RET_1          4               block is closed when an event happens with value '1' (press key, not for mouse)
 
241
        UI_BLOCK_BUSY           8               internal
 
242
        UI_BLOCK_NUMSELECT      16              keys 1-2-...-9-0 can be used to select items
 
243
        UI_BLOCK_ENTER_OK       32              enter key closes block with "OK"
 
244
        
 
245
(these values are being set within the interface.c and toolbox.c code.)
 
246
 
 
247
 
 
248
-------------4. API for uiButton 
 
249
 
 
250
In Blender a button can do four things:
 
251
 
 
252
- directly visualize data, and write to it.
 
253
- put event codes (shorts) back in the queue, to be handled
 
254
- call a user-defined function pointer (while being pressed, etc)
 
255
- create and call another block (i.e. menu)
 
256
 
 
257
Internally, each button or menu item is a 'uiButton', with a generic API and handling:
 
258
ui_def_but(block, type, retval, str, x1, y1, x2, y2, poin, min, max, a1, a2, tip);
 
259
 
 
260
Beacause a lot of obscure generic (re-use) happens here, translation calls have been made 
 
261
for each most button types individually.
 
262
 
 
263
 
 
264
-----------4.1 UiDefBut
 
265
 
 
266
uiBut *UiDefBut[CSIF](  uiBlock *block, int type, int retval, char *str, 
 
267
                                short x1, short y1, short x2, short y2, xxxx *poin, 
 
268
                                float min, float max, float a1, float a2,  char *tip)
 
269
 
 
270
UiDefButC       operatates on char
 
271
UiDefButS       operatates on short
 
272
UiDefButI       operatates on int
 
273
UiDefButF       operatates on float
 
274
 
 
275
*block:         current uiBlock pointer
 
276
type:           see below
 
277
retval:         return value, which is put back in queue
 
278
*str:           button name
 
279
x1, y1:         coordinates of left-lower corner
 
280
x2, y2:         width, height
 
281
*poin:          pointer to char, short, int, float
 
282
min, max        used for slider buttons
 
283
a1, a2          extra info for some buttons
 
284
*tip:           tooltip string
 
285
 
 
286
type:
 
287
 
 
288
1. BUT
 
289
        Activation button. (like "Render")
 
290
        Passing on a pointer is not needed
 
291
        
 
292
2. TOG or TOGN or TOGR
 
293
        Toggle button (like "Lock")
 
294
        The pointer value is set either at 0 or 1
 
295
        If pressed, it calls the optional function with arguments provided.
 
296
        Type TOGN: works negative, when pressed it sets at 0
 
297
        Type TOGR: is part of a row, redraws automatically all buttons with same *poin
 
298
 
 
299
        "|BIT|<nr>"
 
300
        When added to type, it works on a single bit <nr> (lowest order bit: nr = '0')
 
301
 
 
302
3. TOG3|BIT|<nr>
 
303
        A toggle with 3 values!
 
304
        Can be only used for short *poin.
 
305
        In the third toggle setting, the bit <nr> of *( poin+1) is set.
 
306
        
 
307
4. ROW
 
308
        Button that's part of a row. 
 
309
        in "min" you set a row-id number, in "max" the value you want *poin to be
 
310
        assigned when you press the button. Always pass on these values as floats.
 
311
        When this button is pressed, it sets the "max" value to *poin, and redraws
 
312
        all buttons with the same row-id number.
 
313
 
 
314
5. SLI or NUMSLI or HSVSLI
 
315
        Slider, number-slider or hsv-slider button.
 
316
        "min" and "max" are to clamp the value to.
 
317
        If you want a button type "Col" to be updated, make 'a1' equal to 'retval'
 
318
        from the COL button.
 
319
        
 
320
6. NUM
 
321
        Number button
 
322
        Set the clamping values 'min' and 'max' always as float.
 
323
        For UiDefButF, set a 'step' in 'a1', in 1/100's. The step value is the increment or
 
324
        decrement when you click once on the right or left side of a button.
 
325
        The optional button function is additionally called for each change of the *poin value.
 
326
        
 
327
7. TEX
 
328
        Text string button.
 
329
        Pointertype is standard a char. Value 'max' is length of string (pass as float).
 
330
        When button is left with ESC, it doesn't put the 'retval' at the queue.
 
331
        
 
332
8. LABEL
 
333
        Label button.
 
334
        Only displays text. 
 
335
        If 'min' is set at 1.0, the text is printed in white.
 
336
        
 
337
9  SEPR
 
338
        A separator line, typically used within pulldown menus.
 
339
        
 
340
10. MENU
 
341
        Menu button.
 
342
        The syntax of the string in *name defines the menu items:
 
343
                - %t means the previous text becomes the title
 
344
                - item separator is '|'
 
345
                - return values are indicated with %x[nr] (i.e: %x12). 
 
346
                        without returnvalues, the first item gets value 0 (incl. title!)
 
347
        Example: "Do something %t| turn left %2| turn right %1| nothing %0"
 
348
        
 
349
11.     COL
 
350
        A special button that only visualizes a RGB value
 
351
        In 'retval' you can put a code, which is used to identify for sliders if it needs
 
352
        redraws while using the sliders. Check button '5'.
 
353
        As *poin you input the pointer to the 'r' value, 'g' and 'b' are supposed to be
 
354
        next to that. 
 
355
 
 
356
 
 
357
------------4.2 Icon buttons
 
358
 
 
359
Instead of a 'name', all buttons as described for uiDefBut also can have an icon:
 
360
 
 
361
uiBut *uiDefIconBut(uiBlock *block, int type, int retval, int icon, 
 
362
                        short x1, short y1, short x2, short y2, void *poin, 
 
363
                        float min, float max, float a1, float a2,  char *tip)
 
364
 
 
365
        Same syntax and types available as previous uiDefBut, but now with an icon code 
 
366
        instead of a name. THe icons are numbered in resources.c
 
367
 
 
368
uiBut *uiDefIconTextButF(uiBlock *block, int type, int retval, int icon, char *str, 
 
369
                        short x1, short y1, short x2, short y2, float *poin, 
 
370
                        float min, float max, float a1, float a2,  char *tip)
 
371
 
 
372
        Same again, but now with an icon and string as button name.
 
373
 
 
374
Two special icon buttons are available in Blender:
 
375
 
 
376
12. ICONROW
 
377
        (uiDefIconBut)
 
378
        This button pops up a vertical menu with a row of icons to choose from.
 
379
        'max' = amount of icons. The icons are supposed to be ordered in a sequence
 
380
        It writes in *poin which item in the menu was choosen (starting with 0).
 
381
 
 
382
13. ICONTEXTROW
 
383
        (uiDefIconTextBut)
 
384
        Same as previous, but with the texts next to it.
 
385
 
 
386
 
 
387
 
 
388
-----------4.3 pulldown menus / block buttons
 
389
 
 
390
14. BLOCK
 
391
void uiDefBlockBut(uiBlock *block, uiBlockFuncFP func, void *arg, char *str, 
 
392
        short x1, short y1, short x2, short y2, char *tip)
 
393
 
 
394
        This button creates a new block when pressed. The function argument 'func' is called
 
395
        to take care of this. An example func:
 
396
        
 
397
        static uiBlock *info_file_importmenu(void *arg_unused)
 
398
        {
 
399
                uiBlock *block;
 
400
                short yco= 0, xco = 20;
 
401
        
 
402
                block= uiNewBlock(&curarea->uiblocks, "importmenu", UI_EMBOSSW, UI_HELV, G.curscreen->mainwin);
 
403
                uiBlockSetXOfs(block, -40);  // offset to parent button
 
404
        
 
405
                /* flags are defines */
 
406
                uiDefBut(block, LABEL, 0, "VRML 2.0 options", xco, yco, 125, 19, NULL, 0.0, 0.0, 0, 0, "");
 
407
                uiDefButS(block, TOG|BIT|0, 0, "SepLayers", xco, yco-=20, 75, 19, &U.vrmlflag, 0.0, 0.0, 0, 0, "");
 
408
                uiDefButS(block, TOG|BIT|1, 0, "Scale 1/100", xco, yco-=20, 75, 19, &U.vrmlflag, 0.0, 0.0, 0, 0, "");
 
409
                uiDefButS(block, TOG|BIT|2, 0, "Two Sided", xco, yco-=20, 75, 19, &U.vrmlflag, 0.0, 0.0, 0, 0, "");
 
410
        
 
411
                uiBlockSetDirection(block, UI_RIGHT);
 
412
                uiTextBoundsBlock(block, 50);   // checks for fontsize
 
413
 
 
414
                return block;
 
415
        }
 
416
 
 
417
        The uiDef coordinates here are only relative. When this function is called, the interface 
 
418
        code automatically makes sure the buttons fit in the menu nicely. 
 
419
        
 
420
        Inside a menu uiBlock, other uiBlocks can be invoked to make a hierarchical menu.
 
421
 
 
422
 
 
423
 
 
424
-----------4.4 specials
 
425
 
 
426
15. KEYEVT
 
427
 
 
428
void uiDefKeyevtButS(uiBlock *block, int retval, char *str, 
 
429
                short x1, short y1, short x2, short y2, short *spoin, char *tip)
 
430
 
 
431
        A special button, which stores a keyvalue in *spoin. When the button is pressed,
 
432
        it displays the text 'Press any Key'. A keypress then stores the value.
 
433
        
 
434
16. LINK and INLINK
 
435
 
 
436
        These button present a method of linking data in Blender, by drawing a line from one
 
437
        icon to another. It consists of two button types:
 
438
        
 
439
        LINK, the 'linking from' part, can be:
 
440
        - a single pointer to data (only one line allowed)
 
441
        - an array of pointers to data. The LINK buttons system  keeps track of allocating 
 
442
          space for the array, and set the correct pointers in it.
 
443
        
 
444
        INLINK, the 'linking to' part activates creating a link, when a user releases the mouse 
 
445
        cursor over it, while dragging a line from the LINK button.
 
446
        
 
447
        These buttons are defined as follows:
 
448
        
 
449
                
 
450
uiBut but= uiDefIconBut(block, LINK, 0, ICON_LINK,      x1, y1, w, h, NULL, 0, 0, 0, 0, "");
 
451
        /* create the LINK icon */
 
452
 
 
453
uiSetButLink(but, void **pt, void ***ppt, short *totlink, short fromcode, short tocode);
 
454
        **pt: pointer to pointer (only one link allowed)
 
455
        ***ppt: pointer to pointerpointer (an array of pointers)
 
456
        (Either one of these values should be NULL)
 
457
        
 
458
        fromcode: (currently unused)
 
459
        tocode: a short indicating which blocks it can link to. 
 
460
        
 
461
        
 
462
uiDefIconBut(block, INLINK, 0, ICON_INLINK, x1, y1, w, h, void *poin, short fromcode, 0, 0, 0, "");
 
463
        poin: the pointer of the datablock you want to create links to
 
464
        fromcode: a short identifying which LINK buttons can connect to it                        
 
465
        
 
466
 
 
467
 
 
468
17. IDPOIN
 
469
void uiDefIDPoinBut(uiBlock *block, uiIDPoinFuncFP func, int retval, char *str, 
 
470
                        short x1, short y1, short x2, short y2, void *idpp, char *tip)
 
471
 
 
472
        The ID struct is a generic part in structs like Object, Material, Mesh, etc.
 
473
        Most linking options in Blender happens using ID's. (Mesh -> Material).
 
474
        
 
475
        This special button in Blender visualizes an ID pointer with its name. Typing in
 
476
        a new name, changes the pointer. For most ID types in Blender functions have been
 
477
        written already, needed by this button, to check validity of names, and assign the pointer.
 
478
        
 
479
        (BTW: the 'void *idpp' has to be a pointer to the ID pointer!)
 
480
 
 
481
        Example function that can be put in 'func':
 
482
        
 
483
        void test_scriptpoin_but(char *name, ID **idpp)
 
484
        {
 
485
                ID *id;
 
486
                
 
487
                id= G.main->text.first;
 
488
                while(id) {
 
489
                        if( strcmp(name, id->name+2)==0 ) {
 
490
                                *idpp= id;
 
491
                                return;
 
492
                        }
 
493
                        id= id->next;
 
494
                }
 
495
                *idpp= 0;
 
496
        }
 
497
 
 
498
 
 
499
------------- 4.5 uiButton control fuctions
 
500
 
 
501
 
 
502
void uiButSetFunc(uiBut *but, void (*func)(void *arg1, void *arg2), void *arg1, void *arg2)
 
503
        When the button is pressed and released, it calls this function, with the 2 arguments.
 
504
 
 
505
void uiButSetFlag(uiBut *but, int flag)
 
506
        set a flag for further control of button behaviour:
 
507
        flag:
 
508
        UI_TEXT_LEFT
 
509
        
 
510
int uiButGetRetVal(uiBut *but)
 
511
        gives return value
 
512
 
 
513
 
 
514
</body>
 
515
<br><br><br>