Compound Source Proxies

This document replaces Compound proxies in SM. This discusses the new vtkSMCompoundSourceProxy which is a replacement for vtkSMCompoundProxy.

---

vtkSMCompoundSourceProxy is a source proxy encapsulating a pipeline of proxies. It can have multiple input ports i.e. input properties as well as multiple output ports. Input ports are simply exposed input properties from the contained proxies (subproxies) while, output ports are exposed output ports from the contained proxies.

Setup a Compound Proxy

This API is used to create a compound proxy. One sets up a pipeline using regular proxies (or other compound proxies). Then adds all the proxies that need to be encapsulated using AddProxy. Then we expose the properties from the added proxies that we want the user to be able to change/set including the input properties that act as the input to this compound proxy. Then, we expose the output ports from the added proxies that we want the user to be able to connect to. The API is as follows:

  // Description:
  // Add a proxy to be included in this compound proxy.
  // The name must be unique to each proxy added, otherwise the previously
  // added proxy will be replaced.
  void AddProxy(const char* name, vtkSMProxy* proxy);

  // Description:
  // Expose a property from the sub proxy (added using AddProxy).
  // Only exposed properties are accessible externally. Note that the sub proxy
  // whose property is being exposed must have been already added using
  // AddProxy().
  void ExposeProperty(const char* proxyName, 
                      const char* propertyName,
                      const char* exposedName);

  // Description:
  // Expose an output port from a subproxy. Exposed output ports are treated as
  // output ports of the vtkSMCompoundSourceProxy itself. 
  // This method does not may the output port available. One must call
  // CreateOutputPorts().
  void ExposeOutputPort(const char* proxyName, 
                        const char* portName,
                        const char* exposedName);

  // Description:
  // Expose an output port from a subproxy. Exposed output ports are treated as
  // output ports of the vtkSMCompoundSourceProxy itself. 
  // This method does not may the output port available. One must call
  // CreateOutputPorts().
  void ExposeOutputPort(const char* proxyName,
                        unsigned int portIndex,
                        const char* exposedName);

Definition

Once a compound proxy is set up, we want to be able to create instances of this, just like we create filters. For that, we must register the definition of the compound proxy with the proxy manager. vtkSMCompoundProxy::SaveDefinition can be used to save the compound proxy definition in an XML.

  // Description:
  // This is the same as save state except it will remove all references to
  // "outside" proxies. Outside proxies are proxies that are not contained
  // in the compound proxy.  As a result, the saved state will be self
  // contained.  Returns the top element created. It is the caller's
  // responsibility to delete the returned element. If root is NULL,
  // the returned element will be a top level element.
  vtkPVXMLElement* SaveDefinition(vtkPVXMLElement* root);

This XML can be registered with the proxy manager using vtkSMProxyManager::RegisterCompoundProxyDefinition(). Once registered multiple instances of the compound proxy can be created using vtkSMProxyManager::NewCompoundProxy().

  
  // Description:
  // Register a compound proxy definition with the proxy manager. This
  // definition (represented as a tree of vtkPVXMLElement objects) can
  // then be used to instantiate a copy of the compound proxy. See
  // vtkSMCompoundSourceProxy.h for details.
  void RegisterCompoundProxyDefinition(const char* name, vtkPVXMLElement* top); 

  // Description:
  // Creates a compound proxy from compound proxy definition.
  vtkSMCompoundSourceProxy* NewCompoundProxy(const char* name);