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. Compound proxy definition includes the state of all added proxies. Any proxies not added to the compound proxy, but referred to by one of the properties are not included in the definition. Since definition has the complete current state of the proxy, when a new instance is created from the definition, it will be also have the same state.

  // 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);

vtkSMProxyManager provides API to add arbitrary proxy definitions to the proxy manager. This makes it possible for the user to register proxy definition xmls (similar to those in the server manager configuration xml files) on the fly. We can use the same API to register a compound proxy definition with the proxy manager. Once registered multiple instances of the compound proxy can be created just like any other proxy, using vtkSMProxyManager::NewProxy().

  
  // Description:
  // Register a custom proxy definition with the proxy manager. 
  // This can be a compound proxy definition (look at
  // vtkSMCompoundSourceProxy.h) or a regular proxy definition.
  // For all practical purposes, there's no difference between a proxy
  // definition added using this method or by parsing a server manager
  // configuration file.
  void RegisterCustomProxyDefinition(
    const char* group, const char* name, vtkPVXMLElement* top);

Use

Since vtkSMCompoundSourceProxy is a vtkSMSourceProxy subclass, it can be treated just like a proxy for a filter/source. If it has exposed output ports, one can directly add it as input to other filters. If it has exposed input properties, one can set other source proxies as input to it. It supports all source proxy methods such as UpdatePipeline(), UpdateDataInformation() etc.