[vos-d] More new S5 classes/concepts

[Peter Amstutz]

On Tue, Jan 22, 2008 at 11:12:05AM -0500, Reed Hedges wrote:
> 
> I'm going through S5 a bit more deeply now.
> 
> Pete, can you give a summary explanation of these new classes/concepts, 
> and how you use them, what they do, etc.
>
> What are:
>    ComponentWrapper

A Component is an object that is attached to a vobject to extend its 
capabilities -- what was called a MetaObject in s4.

Wrapper classes are handles which control access to the actual 
underlying object.  They provide reference counting, support for 
Promises/Futures, and (eventually) marshalling arguments in order to do 
inter-thread and inter-process method calls.

>    Promise
>    Status (used with a Promise it seems?)

A Promise is returned by a method call in order to represent the result 
of a computation that may or may not have completed.  In normal 
object-oriented programming, a method call is synchronous and only 
returns control to the caller by completing the call and returning a 
result, or signaling an error by throwing an exception.  When making 
method calls between threads or over the network, it is useful to be 
able to return control to the caller with a status of "pending".  A 
"Promise" is a promise to provide the result of the computation at some 
point in the future (which is why it is closely connected to the 
"Future" class).  The "Status" is an enum which is one of "Completed", 
"Pending" or "Failed" (the last one signaling an error).

>    IVobject
>    VobjectImpl

IVobject is an interface class.  VobjectImpl inherits from IVobject and 
is the concrete implementation.

>    ImplementationWrapper
>    ImplementationComponent

An "Implementation" in VOS is a component which represents a 
native-language class (C++, or later other language binding) that 
implements some abstract VOS class.  The main purpose of the 
implementation is to instantiate new instances.

>    ConstructorFunctionWrapper
>    ConstructonFunctionFunctor
>    ConstructorFunctionComponent

A ConstructorFunction is a function that is called to instantiate a new 
VOS component.  The "Implementation" class has a link to the 
ConstructorFunction.

>    The host's factory (i.e. from Host::getFactory())

In order to create new objects attached to a particular Site, you use 
the Factory object on that site (Hosts are a special type of Site.)  
This is the basically the same as s4 with Site::createVobject(), but 
separating the Factory out to a distinct Vobject.

>    ParentChildLinkWrapper

Handle to ParentChildLink (same as a s4 ParentChildRelation.)

>    the "SITE_...blahblah..._NAMESPACE" namespace

VOS classes are themselves Vobjects, which are associated with a 
particular site.  When compiling the VOS class descriptions into C++ 
classes, the site is used as part of the namespace.  The namespace 
includes the revision number of the site, so a macro is #defined so that 
every use of the namespace does not need to be updated every time the 
revision changes.

>    DataType
>    DataTypeWrapper

The base class for all VOS data types.  Data types are split into 
fundamental (int, float, string) and compound (arrays, structs, classes, 
lambdas.)

>    Class
>    ClassWrapper

Defines a class known to VOS, in most cases derived from "Component", 
meaning the class is attached to a Vobject.  Defines member properties, 
methods, and valid children.

>    the "vos:abcdefg12345...[1]/foo/bar" strings that appear various places

vos:        url qualifiers
abcde...    site identifier, in hexadecimal
[1]         specific site revision
/foo/bar    path to some vobject

>    What is something's "owner" (i.e. the getOwner() virtual methods that 
> lots of classes have)

For Component classes which must be attached to a Vobject, getOwner() 
gets the Vobject it is attached to.

> What kinds of things are generated by the code generator, and from what 
> bits of information?

Interface classes beginning with "I", classes ending in "Wrapper", 
classes ending in "Component", classes ending in "Impl".

The interface, wrapper and component/impl classes are generated from the 
class descriptions in the XOD file.  In the case of the VOS core, this 
includes the contents of core.hh, coreComponents.hh and 
coreComponents.cc.  The "concrete" classes are also autogenerated (with 
stub implementations) if they are not present; this is where the user 
fills in the actual implementation code.

> Can you explain 'MVC' a bit more (it seems to now be part of the library?)

The idea is to have a general purpose API for creating views/controls 
given a certain context and data type.

> In interreality3D, how does it use MVC? What is, for example, an object 
> like wxMultiframeContextWrapper and wxMultiframeContextComponent?  What 
> is the wxgui namespace.

For example, a wxMultiFrameContext is a View context that permits 
creating new wxFrames.  A wxWindowContext is a view context for a 
wxWindow drawing surface.  The View Factory matches on a VOS type that 
it can display and a particular view context, and produces a view that 
uses that view context.

In the interreality3d app, the TreeView can view any VOS data type 
(since displays the vobject children) and requires a wxWindowContext.  
It creates a view object which then actually adds the necessary 
wxWidgets controls to the supplied wxWindow to display the tree view.

> What does it mean to append children to the local host?  I am guessing 
> this is so the object doesn't get destroyed (by reference count/garbage 
> collection), and so you can also obtain it by name later?  Do all 

The local host is a special site.  Sites now have a root child list 
which is like a root directory.

> objects need to be added to the local host (like they were all children
> of the local site in s4)? And if so, why not do that automatically when 
> created?

When created, vobjects must be associated with some site (such as the 
local host).  The intention is that in order for the vobject to be 
persistant, it must be connected to the vobject structure so there is a 
path from the root to the vobject.  Vobjects which are not connected to 
the root are not persistent.

> Can you explain more these changes to A3DL? What is a scene, what is a 
> render layer, clock, node, etc.?

I'm in the process of redesigning A3DL based on my experience with 
several mature scene graph APIs (Gamebryo, Open Scene Graph and 
Lightfeather.)  The new A3DL design is pretty preliminary and not 
actually implemented at all.  I'll go over it when I've actually put a 
bit more work into it and there is some code that actually does 
something.

-- 
[ Peter Amstutz ][ tetron at interreality.org ][peter.amstutz at tseboston.com]
[Lead Programmer][Interreality Project][Virtual Reality for the Internet]
[ VOS: Next Generation Internet Communication][ http://interreality.org ]
[ http://interreality.org/~tetron ][ pgpkey:  pgpkeys.mit.edu  18C21DF7 ]

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://www.interreality.org/pipermail/vos-d/attachments/20080127/99a37bc0/attachment.pgp