[Bf-taskforce25] data api proposal

[Brecht Van Lommel]

Hi,

Joshua Leung wrote:
> A few comments regarding this proposal and/or notes on details of the 
> way I had attempted it:
> * The reason why my attempt was written in Python was mainly because it 
> was an easier language to quickly "whack-together" some code which would 
> parse the C-code. Also, by using python, there are some niceties we can 
> introduce into the way of defining info embedded in comments (see my 
> sdna2kt.py approach for details). There wasn't much of an issue with the 
> mixing of the two languages, as the job of any python code was merely to 
> autogenerate the c-code to use as the api.

I think that a fair number of C callbacks will need to written too, 
for notifiers, ui hide/show checks, list iterators, and properties 
that are stored in non standard ways. So my reasoning is kind of if 
it's going to be accompanied with C code, it may as well be all C code.

> * Regarding the embedding of info in comments inside the headers - one 
> of the main issues this aimed to solve was to prevent having a situation 
> where definitions for various attributes of properties (i.e. name, 
> limits, etc.) were spread out over several lists/arrays/whatever (like 
> the current IPO system, which is hellish in that regard), by defining 
> everything about a SINGLE location. Everything that is necessary to 
> define is set out there, right beside the member of the SDNA data that 
> it is intended to work on. Thus, it becomes harded for people to make 
> mistakes regarding defining vars more than once or skipping some (more 
> on that later). In the process, the SDNA gets documented. This is also a 
> rather compact form when it comes to maintainence, as definitions are 
> quite compact (to make sure they fit nicely).

I don't really agree here if we assume the data API is used for more 
than IPO's:
* For the UI, properties will need to be grouped and ordered, to 
display in a list like way (think maya/modo/..). By defining them 
separate you already can do this ordering then instead of a) using 
some confusing numbering in the DNA header or b) adding a second place 
anyway to order the properties.
* There isn't really a way to overlook properties and forget to define 
  them because this will be how their buttons are defined, so you need 
to define a property anyway to create the button.
* There are more things to define per property (tooltips, notifier 
functions, ui show/hide functions, soft min/max/step/precision, UI 
groups), so it is really not that compact.
* The fact that it automatically adds documentation is nice though.

> However, that is really just the definitions that need to be converted 
> into another form that can actually be used by Blender. This proposal 
> does cover this well, however, in terms of compactness, the 
> function-call mechanism is a bit yuck IMO. It's rather more verbose than 
> would be nice to have, and also, what are the implications for startup 
> time? Sure, the UI code does stuff like this all the time, though there 
> it's much fewer items. Perhaps, compressing some of these function calls 
> into functions which set a number of related aspects of a property 
> together would be helpful?

It's not that compact indeed, and here you can do some nicer things in 
python, though I consider it pretty readable. OK, there is more text, 
but not that bad. Note that the functions already set related aspects, 
BDP_property sets cname/type/subtype, BDP_prop_describe sets 
name/tooltip, BDP_prop_ui_range sets soft min/max/step/precision, 
though this can be balanced different of course.

About performance, these function calls could run as part of the 
autogeneration and then dump the results into static structs, that is 
no problem. However I would be surprised if running this for all 
Blender data would take more than 0.1 second.

> Also, this raises the auto-generation issue. If we are to autogenerate, 
> then when is this done? By makesdna - in which case will it dump out a 
> file (or a few) with the necessary code, and what will happen to those 
> things that need special tweaks? At runtime - how do we define any 
> special cases then? Manually run as a tool - once again, how do we 
> reapply any tweaks that are inevitable? Would the autogeneration redo 
> the entire set of mappings or only those in certain areas? Even if it 
> only redid parts, how much work would be required to manually port back 
> any special tweaks?

The assumption is that few special tweaks would be needed, and that 
for all get/set/.. whatever functions there would be a way to specify 
function pointers to manually written functions to override them. 
Basically the auto generated code itself should never be changed 
manually and always completely regenerated, into separate files or 
predefined parts of files.

A more clever system could also be possible, where you can change 
autogenerated code and it detects that, but I don't see that much 
advantages in it versus the potential issues that can give.

> * I see that this covers arrays, vectors, and such. How would this apply 
> to things like "LocX"/loc[0] or "QuatZ"/quat[3]?  Although the 
> IPO-system notes are not done in the version of the proposal I read, it 
> appears that there isn't really much provision for this sort of stuff? 
> If these were treated as vectors, then this would be fine for a large 
> number of places, except the anim system, where single value <=> 
> ipo-curve, and also the UI to some degree.

I had not thought of this indeed. I think an ipo curve would 
correspond to a property + array index then, so there is a simple 
one-to-one mapping here.  I can't think of a particular UI problem.

Cheers,
Brecht.