dyn dynamic object management

Transcription

1 1 dyn dynamic object management Thomas Grill, Vienna September 2004 Abstract dyn 1 is a sketch of a uniform, well-documented programming interface to Pure Data s native object management functionality. It is a generalization of the existing prototypical dyn~ external, seeking to provide a means for simple ad-hoc scripting, poly~-like objects and access for external patcher systems and dynamic signal graph generators. It is accompanied by a Python module enabling access to the dyn interface for usage with the py/pyext external. 1. Introduction Real-time systems like PD 2 or Max/MSP 3 have a patcher -oriented interface, where the user can interactively build up signal and messaging flow by putting functional elements ( objects ) into a document ( patcher ). While this is the most common usage it is often desirable to automate this building process for e.g. duplication and variation of functionality. This is known as scripting. At patcher level, the PD system has built-in scripting facilities 4 making it possible to create objects and interconnect them by sending special messages to the respective patcher. Figure 1 Messages sent to the patcher create the objects on the right 1 Downloadable at 2 Pure Data was written by Miller Puckette and others. See msp/software.html and 3 See 4 See various patches in the folder doc/7.stuff/pd-msg of the PD distribution

2 Looking at the connect message it becomes obvious that it s not always easy to keep track of the object numbering, especially when there s a more complex logic involved for the scripting. In order to delete objects it is possible to simulate mouse-based user interaction by selecting parts and cut them. 2 Figure 2 Deleting objects in the patcher is possible if the position and size is known It s helpful to organize scripted elements in newly created sub-patchers so that numbering starts at zero and it s important to be straight about the positions and spatial extensions the objects will have. However, one has to make sure that object creation can t fail, because there s no way to find out from within the patcher whether they have really been created ok. With this readily available functionality remarkable things can be done 5, but it s limited and programming is an exhaustive task because of much trial and error. From the perspective of an external, there is a variety of ways to create and manage patcher elements. On the one hand, the same message-based communication may be used, though with the same limitations. On the other hand, it s possible to try to do it the way how PD deals with the objects internally. This seems to be straightforward, but there are difficulties: Many of the functions necessary for versatile object management are not laid open, and the same applies to the data structures used for storing vital information about the objects. Though it would be possible to make them accessible, they may be subject to change, hence applications using them would be in danger to be non-portable to further PD versions. This is where dyn comes in it s a plain C API exposing a functionality to deal with PD objects in a comfortable way and across thread boundaries, making it possible to easily create, manage, query and get rid of patcher elements. It s also possible to attach custom information to objects. dyn uses as many information it can get from PD, and where it cannot, it tries to keep track of things itself. When there are non-portable changes to the PD functions used, a workaround can be built into dyn, while applications using the dyn API don t have to worry about it. 2. The API The dyn API has been defined using the standard C programming language to be most compatible, therefore also accessible from all common scripting languages. The dyn.h header file contains the entire interface and is fairly well documented. All API functions return int-typed values, where values >= 0 mean successful execution, while values < 0 are error codes. 5 nqpoly (not-quite-poly) at

3 3 There are functions to retrieve dyn status information, e.g. int dyn_version(); New patcher elements can be created with functions like int dyn_newobject(int sched,dyn_id *id,dyn_callback cb,dyn_id pid,const t_symbol *obj,int argc,const t_atom *argv); int dyn_newmessagestr(int sched,dyn_id *id,dyn_callback cb,dyn_id pid,const char *msg); and sub-patchers with int dyn_newpatcher(int sched,dyn_id *id,dyn_callback cb,dyn_id pid); Obviously, all functionality is centered around the dyn_id type, which serves as a reference to any kind of object dyn is able to handle. These objects fall into two groups: patchable objects like abstractions and sub-patchers, object and message boxes, and other types like connections and listeners. Internally, dyn handles these object types in an object-oriented manner, also making sure that a specific function is valid for that type. The actual type of an object referenced by an ID can be queried with int dyn_gettype(dyn_id id); All kinds of objects can be destroyed by the same function int dyn_free(int sched,dyn_id id); Data pointers can be associated to any ID with int dyn_setdata(dyn_id oid,void *data); and retrieved with int dyn_getdata(dyn_id oid,void **data); An external patcher system could use this to store additional information about the visual appearance of patcher elements or other kinds of things. For most of the functions of the API there is a scheduling parameter 6 which can either have the value DYN_SCHED_NOW, which causes dyn to handle a specific request synchronously, probably also blocking execution if PD is busy, or DYN_SCHED_QUEUE which puts the request into a queue, letting PD handle it when it has the time to do so, or DYN_SCHED_AUTO which adapts the scheduling depending on whether the request has been made from the PD system thread or an external thread. The possibility of scheduling requests goes hand in hand with some complications. For the case of synchronous creation of an object, like with // create a print object on the root canvas dyn_id oid; dyn_newobjectstr(dyn_sched_now,&oid,null,dyn_id_none, print ); 6 for the current implementation status all functions are called synchronously

4 the requested object will have been readily created by PD as soon as the function returns to the caller. This might not be true for queued scheduling. Here, the caller will be notified about the actual creation of an object via a callback function, signalling the point of time the object has come to life. The dyn_id-typed object identifier will be valid and accessible at any time, from the point of return of a creation function up to the moment it is destroyed using the dyn_free function. It may be regarded as a ticket for an object, which allows scheduled requests to be sent although the object itself might not yet be present. Synchronous requests would fail in the latter case, naturally. Patchable objects can be interconnected just as known from interactive patcher design, with int dyn_newconnection(int sched,dyn_id *id,dyn_callback cb,dyn_id sid,int outlet,dyn_id did,int inlet); but can also be sent messages from the outside world with int dyn_send(int sched,dyn_id id,int inlet,const t_symbol *sym,int argc,const t_atom *argv); On the other hand, messages coming from object outlets may be eavesdropped with int dyn_listen(int sched,dyn_id *lid,dyn_id id,int outlet,dyn_listener cb,void *data); Here a special listener object is created which will send the output messages to a callback function of type dyn_listener until it or the associated object is destroyed. It s possible to enumerate the elements of a patcher with int dyn_enumobjects(dyn_id pid,dyn_enumfun fun,void *data); where an enumeration function of type dyn_enumfun will be called for each object, or query some information about patcher elements with e.g. int dyn_getinletcount(dyn_id id); int dyn_getoutlettype(dyn_id id,int outlet); It is also possible to enumerate inlet and outlet connections with e.g. int dyn_enuminletconnections(dyn_id id,int inlet,dyn_enumfun fun,void *data); and retrieve the IDs of connected objects int dyn_getconnectiondrain(dyn_id id,dyn_id *did,int *inlet); 3. Python binding While most future clients using the dyn API will be written in C/C++ for efficiency reasons, it is also useful to have an interface to scripting languages for ad-hoc solutions, experimenting or testing. Since the py/pyext 7 external is readily available it was only logical to write a Python extension module, using the object-oriented PyCXX 8 interface. Creating two objects in a new patcher is as easy as 4 7 Python scripting external for PD, see 8 See

5 5 import dyn patcher = dyn.patcher() object1 = patcher.object("* 2") object2 = patcher.object("print") object1.connect(0,object2,0) with a function to send some data to object1 s leftmost inlet def send(args): object1.send(0,args) # import dyn module # make new patcher # insert * object into patcher # insert print object # connect the two objects # send arguments to inlet of object1 In a PD patcher this short.py script will be used like this: Figure 3 Sending a float to the script will print the doubled value to the PD console The dyn extension module currently defines the methods and dyn.version() dyn.patcher() dyn.object(*args) dyn.message(*args) # retrieve dyn version number # create a patcher at root level # create an object or abstraction at root level # create a message box at root level Each of the latter methods returns an ID object on success, which refers to the above-mentioned dyn_id type. The objects will not be destroyed when the user (with del) or Python s garbage collector deletes the variables. dyn objects will have to be destroyed explicitly with object.free() Other object methods include object.patcher() object.object(*args) object.message(*args) # create sub-patcher # create object or abstraction # create sub-patcher which are only valid for patcher objects. The following methods can be used for all patchable objects: object.inlets() object.outlets() object.inlettype(index) object.outlettype(index) # get number of inlets # get number of inlets object.connect(index,object,index) # connect objects object.send(index,*args) object.listen(index,function) # get inlet type (0 for message, 1 for signal) # get outlet type (0 for message, 1 for signal) # send message to an inlet # receive messages from an outlet More functionality, mirroring all of the dyn API can be added easily.

6 4. Example a poly~ implementation The archive of the dyn Python module distribution contains poly.py which is a pyext-based implementation of a poly~-like object. In a PD patcher it is used like this: 6 Figure 4 a patcher using the poly.py script The pyext object (here in its pyx. incarnation) takes as arguments the filename of the Python script, the number of poly voices, the name of the PD object or abstraction to load along with any additional arguments. Although any PD objects - also DSP-based - can be used with poly.py, the handling of signals is quite awkward, just because the pyext object has no signal capabilities 9. For each signal inlet a recv~ object is created and each signal outlet is given a corresponding throw~ object, which also means that the output of all voices are summed up before catch~. 5. Limitations There is still a lot to learn about the way PD deals with objects and dyn has to become much more efficient, above all in terms of memory usage. Much of the internal dyn object management duplicates data structures that are also present in PD. By the time of this writing dyn still lacks functionality to provide access to signal inlets and outlets, which is necessary for a complete poly~ implementation. 6. Future In principle the dyn interface could also be implemented for Max/MSP, provided the respective Max API functions be disclosed which hasn t been the case yet. An interesting completion would be a system generating signal graphs by the use of a script language, as it is done in SuperCollider. While Supercollider signal objects ( ugens ) have a different architecture than PD objects it would sure be possible to find a feasible formulation for PD too. Ultimately, it s most desirable that PD adopt a comparable native API and render dyn useless. 9 and dyn has no DSP interface functions yet