[Bf-taskforce25] Proposal: Blender API revisited

[Brecht Van Lommel]

Hi,

On Fri, 2009-03-20 at 18:52 +0100, vekoon wrote:
> Was operators in "and not have the operators call any auto-generated 
> functions" a typo I guess? Because when I said auto-generated bridge 
> functions I meant functions that are generated in the makesapi module 
> and used only in the makesapi module. They're basically meant to 
> automatically convert parameters from BlenderAPI parameters list to C 
> functions, they have nothing to do with operators.

Ok, must have misunderstood something about the Blender API design then.

> Initially when designing the API I did want to put it in the various 
> modules but then decided not to. The reason for this is that API "code" 
> is actually just creation of meta description for Blender's 
> core/module/kernel functions. There's no real code in the makesapi 
> module except for the code that handles the definition/access of course. 
> The API export is just those API_def_* calls. So because it's just 
> meta-code in the end it could be put in a separate location without 
> generating too much confusion because in the end its peculiarity is that 
> it exports functionality while instead what type of functionality (i.e. 
> object, scene or whatever) is secondary as there's not really any code 
> that cares or reference that, just the included headers.
> Also the other advantage in having it separate is that it can be 
> preprocessed (like RNA) which not only is faster but as I said can 
> generate bridge functions automatically, otherwise you'd have to define 
> those yourself (which I think creates even more confusion).

The reason to put it in the module itself is to ensure that it is all
kept in sync and close together. The important thing to avoid is having
a separate piece of code that you have to keep in sync, like the current
python API. It has to be designed in such a way that when you work on
operators, you also work on the API for it.

Regarding preprocessing, that is just an implementation issue that can
be solved I think (it's a bit tricky, but no reason to let it influence
design).

> I agree that having API+operators generates doc duplication but that's a 
> good deal if you consider what not having an API at all would mean. Also 
> this could partially be tackled if we just add a function that iterates 
> through the parameters for an API function and adds properties to the 
> operator accordingly.
> 
>  From the example code you posted it seems you want to make API like 
> static functions? I really think for a very complex application API like 
> Blender was (and ultimately will end up being again) a Type system is 
> more suitable in that it allows for better distinction. Think for 
> instance of py constraints, py nodes, Game Engine etc. They're already 
> logically an object system which makes them very well fit into a type 
> system.

Sure, this should be a member function of Scene. If you look at the
code that's what it is supposed to do, but not very clearly.

Brecht.