Package org.eclipse.imagen

Class RenderableOp

Object
RenderableOp
All Implemented Interfaces:
RenderableImage, Serializable, OperationNode, PropertyChangeEmitter, PropertySource, WritablePropertySource
public class RenderableOp extends Object implements RenderableImage, OperationNode, WritablePropertySource, Serializable
A node in a renderable imaging chain. This is the Java Advanced Imaging version of the Java2D class RenderableImageOp. Instead of an explicit ContextualRenderedImageFactory, the indirection of the OperationRegistry is used.

A RenderableOp stores an operation name and a ParameterBlock containing sources and parameters. A set of nodes may be joined together via the source Vectors within their respective ParameterBlocks to form a directed acyclic graph (DAG). The topology, i.e., connectivity, of the graph may be altered by changing the node's sources. The operation name and parameters may also be changed.

Such chains provide a framework for resolution- and rendering- independent imaging. They are useful in that a chain may be manipulated dynamically and rendered multiple times. Thus for example the same chain of operations may be applied to different images or the parameters of certain operations in a chain may be modified interactively.

A RenderableOp may be constructed directly as, for example, 

 
 RenderableImage addend1;
 RenderableImage addend2;
 ParameterBlock pb =
     (new ParameterBlock()).addSource(addend1).addSource(addend2);
 RenderableOp node = new RenderableOp("add", pb);
or via the createRenderable() or createRenderableNS() methods defined in the ImageN class. The difference between direct construction of a node and creation via a convenience method is that in the latter case:
  1. It is verified that the operation supports the renderable mode.
  2. Using the validateArguments() method of the associated OperationDescriptor, the arguments (sources and parameters) are validated as being compatible with the specified operation.
  3. Global RenderingHints maintained by the ImageN instance are set on the RenderableOp using setRenderingHints().

When a chain of nodes is rendered by any any of the createRendering() methods, a "parallel" chain of RenderedImages is created. Each node in the chain of RenderableOps corresponds to a node in the chain of RenderedImages. A RenderedImage associated with a given node is referred to as a rendering of the node.

The translation between RenderableOp chains and RenderedImage (usually OpImage ) chains makes use of three levels of indirection provided by the OperationRegistry, ContextualRenderedImageFactory, (CRIF), and RenderedImageFactory (RIF) facilities. First, the OperationRegistry is used to map the operation name into a CRIF. This CRIF then constructs a RenderedImage via its create(RenderContext, ParameterBlock) method. The third level of indirection results from the operation name being mapped within create() into the optimum RIF which actually creates the RenderedImage. (Note that this third level of indirection is a function of the CRIF implementation of the renderable create() method: that provided by the convenience class CRIFImpl provides this indirection.) If the RenderedImage returned by the CRIF create() invocation is a RenderedOp, it is replaced with the rendering of the RenderedOp (usually an OpImage).

RenderingHints may be set on a RenderableOp to provide a set of common hints to be used in all invocations of the various createRendering() methods on the node. These hints are merged with any hints supplied to createRendering() either explicitly or via a RenderContext. Directly supplied hints take precedence over the common hints.

RenderableOp nodes may participate in Java Bean-style events. The PropertyChangeEmitter methods may be used to register and unregister PropertyChangeListeners. Certain PropertyChangeEvents may be emitted by the RenderableOp. These include the PropertyChangeEventImageNs and PropertySourceChangeEvents required by virtue of implementing the OperationNode interface.

RenderableOp nodes are WritablePropertySources and so manage a name-value database of image meta-data also known as image properties. Properties may be set on and requested from a node. The value of a property not explicitly set on the node (via setProperty()) is obtained from the property environment of the node. When a property is derived from the property environment it is cached locally to ensure synchronization, i.e., that properties do not change spontaneously if for example the same property is modified upstream.

The property environment of the RenderableOp is initially derived from that of the corresponding OperationDescriptor as maintained by the OperationRegistry. It may be modified locally by adding a PropertyGenerator or by suppressing a specific property. These modifications cannot be undone.

When a property value is requested an attempt will be made to derive it from the several entities in the following order of precedence:

  1. local properties;
  2. any registered PropertyGenerators, or
    a source specified via a copy-from-source directive;
  3. the first source which defines the property.
Local properties are those which have been cached locally either by virtue of direct invocation of setProperty() or due to caching of a property derived from the property environment.

The properties of a RenderableOp node are copied to each rendering generated by any of the createRendering() methods. Properties already set on the rendering are not copied, i.e., those of the rendering take precedence.

A RenderableOp chain created on a client may be passed to a server via a RemoteImage. Any RenderedImage sources which are not Serializable will be wrapped in SerializableRenderedImages for serialization. The tile transmission parameters will be determined from the common RenderingHints of the node. All other non-serializable objects will attempt to be serialized using SerializerFactory. If no Serializer is available for a particular object, a java.io.NotSerializableException may result. Image properties (meta-data) are serialized insofar as they are serializable: non-serializable components are simply eliminated from the local cache of properties and from the property environment.

See Also:

  • Constructor Details

    • RenderableOp

      public RenderableOp(OperationRegistry registry, String opName, ParameterBlock pb, RenderingHints hints)
      Constructs a RenderableOp given the name of the operation to be performed and a ParameterBlock containing RenderableImage sources and other parameters. Any RenderedImage sources referenced by the ParameterBlock will be ignored.

      The ParameterBlock may include DeferredData parameters. These will not be evaluated until their values are actually required, i.e., when a rendering of the node is requested or the renderable dimensions are queried.

      Parameters:
      registry - The OperationRegistry to be used for instantiation. if null, the default registry is used. Saved by reference.
      opName - The operation name. Saved by reference.
      pb - The sources and other parameters. If null, it is assumed that this node has no sources and parameters. This parameter is cloned.
      hints - The common node RenderingHints to be set; it may be null. This parameter is cloned.
      Throws:
      IllegalArgumentException - if opName is null.

    • RenderableOp

      public RenderableOp(OperationRegistry registry, String opName, ParameterBlock pb)
      Constructs a RenderableOp given the name of the operation to be performed and a ParameterBlock containing RenderableImage sources and other parameters. Any RenderedImage sources referenced by the ParameterBlock will be ignored.

      The ParameterBlock may include DeferredData parameters. These will not be evaluated until their values are actually required, i.e., when a rendering of the node is requested or the renderable dimensions are queried.

      Parameters:
      registry - The OperationRegistry to be used for instantiation. if null, the default registry is used. Saved by reference.
      opName - The operation name. Saved by reference.
      pb - The sources and other parameters. If null, it is assumed that this node has no sources and parameters. This parameter is cloned.
      Throws:
      IllegalArgumentException - if opName is null.

    • RenderableOp

      public RenderableOp(String opName, ParameterBlock pb)
      Constructs a RenderableOp given the name of the operation to be performed and a ParameterBlock containing RenderableImage sources and other parameters. The default operation registry is used. Any RenderedImage sources referenced by the ParameterBlock will be ignored.

      The ParameterBlock may include DeferredData parameters. These will not be evaluated until their values are actually required, i.e., when a rendering of the node is requested or the renderable dimensions are queried.

      Parameters:
      opName - The operation name. Saved by reference.
      pb - The sources and other parameters. If null, it is assumed that this node has no sources and parameters. This parameter is cloned.
      Throws:
      IllegalArgumentException - if opName is null.

  • Method Details

    • getRegistryModeName

      public String getRegistryModeName()
      Returns the name of the RegistryMode corresponding to this RenderableOp. This method always returns the String "renderable".
      Specified by:
      getRegistryModeName in interface OperationNode

    • getRegistry

      public OperationRegistry getRegistry()
      Returns the OperationRegistry that is used by this node. If the registry had not been set, the default registry is returned.
      Specified by:
      getRegistry in interface OperationNode

    • setRegistry

      public void setRegistry(OperationRegistry registry)
      Sets the OperationRegistry that is used by this node. If the specified registry is null , the default registry is used.

      If the supplied registry does not equal the current registry, a PropertyChangeEventImageN named "OperationRegistry" will be fired

      Specified by:
      setRegistry in interface OperationNode
      Parameters:
      registry - The new OperationRegistry to be set; it may be null.

    • getOperationName

      public String getOperationName()
      Returns the name of the operation this node represents as a String.
      Specified by:
      getOperationName in interface OperationNode

    • setOperationName

      public void setOperationName(String opName)
      Sets the name of the operation this node represents. The parameter is saved by reference.

      If the supplied name does not equal the current operation name, a PropertyChangeEventImageN named "OperationName" will be fired.

      Specified by:
      setOperationName in interface OperationNode
      Parameters:
      opName - The new operation name to be set.
      Throws:
      IllegalArgumentException - if opName is null.

    • getParameterBlock

      public ParameterBlock getParameterBlock()
      Returns a clone of the ParameterBlock of this node.
      Specified by:
      getParameterBlock in interface OperationNode

    • setParameterBlock

      public void setParameterBlock(ParameterBlock pb)
      Sets the ParameterBlock of this node. If the specified new ParameterBlock is null , it is assumed that this node has no input sources and parameters. The supplied parameter is cloned.

      This method does not validate the content of the supplied ParameterBlock. The caller should ensure that the sources and parameters in the ParameterBlock are suitable for the operation this node represents; otherwise some form of error or exception may occur at the time of rendering.

      If the supplied ParameterBlock does not equal the current ParameterBlock, a PropertyChangeEventImageN named "ParameterBlock", "Sources", or "Parameters" will be fired.

      The ParameterBlock may include DeferredData parameters. These will not be evaluated until their values are actually required, i.e., when a rendering of the node is requested or the renderable dimensions are queried.

      Specified by:
      setParameterBlock in interface OperationNode
      Parameters:
      pb - The new ParameterBlock to be set; it may be null.

    • getRenderingHints

      public RenderingHints getRenderingHints()
      Returns a clone of the common RenderingHints of this node or null.
      Specified by:
      getRenderingHints in interface OperationNode

    • setRenderingHints

      public void setRenderingHints(RenderingHints hints)
      Sets the common RenderingHints of this node. The supplied parameter is cloned if non-null .

      If the supplied RenderingHints does not equal the current RenderingHints, a PropertyChangeEventImageN named "RenderingHints" will be fired.

      Specified by:
      setRenderingHints in interface OperationNode
      Parameters:
      hints - The new RenderingHints to be set; it may be null.

    • getSources

      public Vector getSources()
      Returns a vector of RenderableImages that are the sources of image data for this RenderableImage. Note that this method may return an empty vector, to indicate that the image has sources but none of them is a RenderableImage, or null to indicate the image has no source of any type.
      Specified by:
      getSources in interface RenderableImage
      Returns:
      a (possibly empty) Vector of RenderableImages, or null.

    • getWidth

      public float getWidth()
      Return the rendering-independent width of the image.
      Specified by:
      getWidth in interface RenderableImage
      Returns:
      the image width as a float.

    • getHeight

      public float getHeight()
      Return the rendering-independent height of the image.
      Specified by:
      getHeight in interface RenderableImage
      Returns:
      the image height as a float.

    • getMinX

      public float getMinX()
      Gets the minimum X coordinate of the rendering-independent image data.
      Specified by:
      getMinX in interface RenderableImage

    • getMinY

      public float getMinY()
      Gets the minimum Y coordinate of the rendering-independent image data.
      Specified by:
      getMinY in interface RenderableImage

    • createDefaultRendering

      public RenderedImage createDefaultRendering()
      Returns a default rendering of this RenderableImage. In all cases the area of interest will equal the image bounds. Any hints set on the node via setRenderingHints() will be used.

      The dimensions of the created RenderedImage are determined in the following order of precedence:

      1. If a ImageN.KEY_DEFAULT_RENDERING_SIZE hint is set on the node it is used unless both its dimensions are non-positive.
      2. The value returned by ImageN.getDefaultRenderingSize() is used unless it is null.
      3. An identity transform from renderable to rendered coordinates is applied.
      Either dimension of the default rendering size set in the hints or on the default ImageN instance may be non-positive in which case the other dimension and the renderable aspect ratio will be used to compute the rendered image size.

      This method does not validate sources and parameters supplied in the ParameterBlock supplied at construction against the specification of the operation this node represents. It is the caller's responsibility to ensure that the data in the ParameterBlock are suitable for this operation. Otherwise, some kind of exception or error will occur. Invoking this method will cause any DeferredData parameters to be evaluated.

      Specified by:
      createDefaultRendering in interface RenderableImage
      Returns:
      The default RenderedImage.

    • createScaledRendering

      public RenderedImage createScaledRendering(int w, int h, RenderingHints hints)
      Gets a RenderedImage instance of this image with width w, and height h in pixels. The RenderContext is built automatically with an appropriate usr2dev transform and an area of interest of the full image. The rendering hints come from hints passed in. These hints will be merged with any set on the node via setRenderingHints() with the hints passed in taking precedence.

      If w == 0, it will be taken to equal Math.round(h*(getWidth()/getHeight())). Similarly, if h == 0, it will be taken to equal Math.round(w*(getHeight()/getWidth())). One of w or h must be non-zero or else an IllegalArgumentException will be thrown.

      This method does not validate sources and parameters supplied in the ParameterBlock supplied at construction against the specification of the operation this node represents. It is the caller's responsibility to ensure that the data in the ParameterBlock are suitable for this operation. Otherwise, some kind of exception or error will occur. Invoking this method will cause any DeferredData parameters to be evaluated.

      Specified by:
      createScaledRendering in interface RenderableImage
      Parameters:
      w - the width of rendered image in pixels, or 0.
      h - the height of rendered image in pixels, or 0.
      hints - a RenderingHints object containg hints.
      Returns:
      a RenderedImage containing the rendered data.
      Throws:
      IllegalArgumentException - if both w and h are zero.

    • createRendering

      public RenderedImage createRendering(RenderContext renderContext)
      Gets a RenderedImage that represents a rendering of this image using a given RenderContext. This is the most general way to obtain a rendering of a RenderableImage.

      This method does not validate sources and parameters supplied in the ParameterBlock supplied at construction against the specification of the operation this node represents. It is the caller's responsibility to ensure that the data in the ParameterBlock are suitable for this operation. Otherwise, some kind of exception or error will occur. Invoking this method will cause any DeferredData parameters to be evaluated.

      The RenderContext may contain a Shape that represents the area-of-interest (aoi). If the aoi is specifed, it is still legal to return an image that's larger than this aoi. Therefore, by default, the aoi, if specified, is ignored at the rendering.

      Any hints in the RenderContext will be merged with any set on the node via setRenderingHints() with the hints in the RenderContext taking precedence.

      Specified by:
      createRendering in interface RenderableImage
      Parameters:
      renderContext - the RenderContext to use to produce the rendering.
      Returns:
      a RenderedImage containing the rendered data.

    • isDynamic

      public boolean isDynamic()
      Returns false, i.e., successive renderings with the same arguments will produce identical results.
      Specified by:
      isDynamic in interface RenderableImage

    • getPropertyNames

      public String[] getPropertyNames()
      Returns the names of properties available from this node. These properties are a combination of those derived from prior nodes in the imaging chain and those set locally.
      Specified by:
      getPropertyNames in interface PropertySource
      Specified by:
      getPropertyNames in interface RenderableImage
      Returns:
      An array of Strings containing valid property names or null if there are none.

    • getPropertyNames

      public String[] getPropertyNames(String prefix)
      Returns an array of Strings recognized as names by this property source that begin with the supplied prefix. If no property names match, null will be returned. The comparison is done in a case-independent manner.
      Specified by:
      getPropertyNames in interface PropertySource
      Returns:
      an array of Strings giving the valid property names.
      Throws:
      IllegalArgumentException - if prefix is null.

    • getPropertyClass

      public Class getPropertyClass(String name)
      Returns the class expected to be returned by a request for the property with the specified name. If this information is unavailable, null will be returned.
      Specified by:
      getPropertyClass in interface PropertySource
      Parameters:
      name - the name of the property, as a String.
      Returns:
      The Class expected to be return by a request for the value of this property or null .
      Throws:
      IllegalArgumentException - if name is null.

    • getProperty

      public Object getProperty(String name)
      Gets a property from the property set of this image. If the property name is not recognized, java.awt.Image.UndefinedProperty will be returned.
      Specified by:
      getProperty in interface PropertySource
      Specified by:
      getProperty in interface RenderableImage
      Parameters:
      name - the name of the property to get, as a String.
      Returns:
      a reference to the property Object, or the value java.awt.Image.UndefinedProperty.
      Throws:
      IllegalArgumentException - if name is null.

    • setProperty

      public void setProperty(String name, Object value)
      Sets a local property on a node. Local property settings override properties derived from prior nodes in the imaging chain.

      If the node is serialized then serializable properties will also be serialized but non-serializable properties will be lost.

      Specified by:
      setProperty in interface WritablePropertySource
      Parameters:
      name - a String representing the property name.
      value - the property's value, as an Object.
      Throws:
      IllegalArgumentException - if name or value is null.

    • removeProperty

      public void removeProperty(String name)
      Removes the named property from the local property set of the RenderableOp as well as from its property environment.
      Specified by:
      removeProperty in interface WritablePropertySource
      Parameters:
      name - the name of the property, as a String.
      Throws:
      IllegalArgumentException - if name is null.

    • getDynamicProperty

      public Object getDynamicProperty(String name)
      Returns the property associated with the specified property name, or java.awt.Image.UndefinedProperty if the specified property is not set on the image. This method is dynamic in the sense that subsequent invocations of this method on the same object may return different values as a function of changes in the property environment of the node, e.g., a change in which PropertyGenerators are registered or in the values associated with properties of node sources. The case of the property name passed to this method is ignored.
      Specified by:
      getDynamicProperty in interface OperationNode
      Parameters:
      name - A String naming the property.
      Throws:
      IllegalArgumentException - if name is null.

    • addPropertyGenerator

      public void addPropertyGenerator(PropertyGenerator pg)
      Adds a PropertyGenerator to the node. The property values emitted by this property generator override any previous definitions.
      Specified by:
      addPropertyGenerator in interface OperationNode
      Parameters:
      pg - a PropertyGenerator to be added to this node's property environment.

    • copyPropertyFromSource

      public void copyPropertyFromSource(String propertyName, int sourceIndex)
      Forces a property to be copied from the specified source node. By default, a property is copied from the first source node that emits it. The result of specifying an invalid source is undefined.
      Specified by:
      copyPropertyFromSource in interface OperationNode
      Parameters:
      propertyName - the name of the property to be copied.
      sourceIndex - the index of the from which to copy the property.
      Throws:
      IllegalArgumentException - if propertyName is null.

    • suppressProperty

      public void suppressProperty(String name)
      Removes a named property from the property environment of this node. Unless the property is stored locally either due to having been set explicitly via setProperty() or to having been cached for property synchronization purposes, subsequent calls to getProperty(name) will return java.awt.Image.UndefinedProperty, and name will not appear on the list of properties emitted by getPropertyNames(). To delete the property from the local property set of the node, removeProperty() should be used.
      Specified by:
      suppressProperty in interface OperationNode
      Parameters:
      name - a String naming the property to be suppressed.

    • addPropertyChangeListener

      public void addPropertyChangeListener(PropertyChangeListener listener)
      Add a PropertyChangeListener to the listener list. The listener is registered for all properties.
      Specified by:
      addPropertyChangeListener in interface PropertyChangeEmitter

    • addPropertyChangeListener

      public void addPropertyChangeListener(String propertyName, PropertyChangeListener listener)
      Add a PropertyChangeListener for a specific property. The listener will be invoked only when a call on firePropertyChange names that specific property. The case of the name is ignored.
      Specified by:
      addPropertyChangeListener in interface PropertyChangeEmitter

    • removePropertyChangeListener

      public void removePropertyChangeListener(PropertyChangeListener listener)
      Remove a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties.
      Specified by:
      removePropertyChangeListener in interface PropertyChangeEmitter

    • removePropertyChangeListener

      public void removePropertyChangeListener(String propertyName, PropertyChangeListener listener)
      Remove a PropertyChangeListener for a specific property. The case of the name is ignored.
      Specified by:
      removePropertyChangeListener in interface PropertyChangeEmitter

    • getSource

      public Object getSource(int index)
      Returns one of the node's sources as an Object.
      Parameters:
      index - the index of the source.

    • setSource

      public void setSource(Object source, int index)
      Sets one of the node's sources to an Object. This is a convenience method that invokes setParameterBlock() and so adheres to the same event firing behavior.
      Parameters:
      source - the source, as an Object.
      index - the index of the source.
      Throws:
      IllegalArgumentException - if source is null.

    • removeSources

      public void removeSources()
      Removes all the node's sources. This is a convenience method that invokes setParameterBlock() and so adheres to the same event firing behavior.

    • getByteParameter

      public byte getByteParameter(int index)
      Returns one of the node's parameters, as a byte.
      Parameters:
      index - the index of the parameter.

    • getCharParameter

      public char getCharParameter(int index)
      Returns one of the node's parameters, as a char.
      Parameters:
      index - the index of the parameter.

    • getShortParameter

      public short getShortParameter(int index)
      Returns one of the node's parameters, as a short.
      Parameters:
      index - the index of the parameter.

    • getIntParameter

      public int getIntParameter(int index)
      Returns one of the node's parameters, as an int.
      Parameters:
      index - the index of the parameter.

    • getLongParameter

      public long getLongParameter(int index)
      Returns one of the node's parameters, as a long.
      Parameters:
      index - the index of the parameter.

    • getFloatParameter

      public float getFloatParameter(int index)
      Returns one of the node's parameters, as a float.
      Parameters:
      index - the index of the parameter.

    • getDoubleParameter

      public double getDoubleParameter(int index)
      Returns one of the node's parameters, as a double.
      Parameters:
      index - the index of the parameter.

    • getObjectParameter

      public Object getObjectParameter(int index)
      Returns one of the node's parameters, as an Object.
      Parameters:
      index - the index of the parameter.

    • setParameter

      public void setParameter(byte param, int index)
      Sets one of the node's parameters to a byte. This is a convenience method that invokes setParameter(Object,int) and so adheres to the same event firing behavior.
      Parameters:
      param - the parameter, as a byte.
      index - the index of the parameter.

    • setParameter

      public void setParameter(char param, int index)
      Sets one of the node's parameters to a char. This is a convenience method that invokes setParameter(Object,int) and so adheres to the same event firing behavior.
      Parameters:
      param - the parameter, as a char.
      index - the index of the parameter.

    • setParameter

      public void setParameter(short param, int index)
      Sets one of the node's parameters to a short. This is a convenience method that invokes setParameter(Object,int) and so adheres to the same event firing behavior.
      Parameters:
      param - the parameter, as a short.
      index - the index of the parameter.

    • setParameter

      public void setParameter(int param, int index)
      Sets one of the node's parameters to an int. This is a convenience method that invokes setParameter(Object,int) and so adheres to the same event firing behavior.
      Parameters:
      param - the parameter, as an int.
      index - the index of the parameter.

    • setParameter

      public void setParameter(long param, int index)
      Sets one of the node's parameters to a long. This is a convenience method that invokes setParameter(Object,int) and so adheres to the same event firing behavior.
      Parameters:
      param - the parameter, as a long.
      index - the index of the parameter.

    • setParameter

      public void setParameter(float param, int index)
      Sets one of the node's parameters to a float. This is a convenience method that invokes setParameter(Object,int) and so adheres to the same event firing behavior.
      Parameters:
      param - the parameter, as a float.
      index - the index of the parameter.

    • setParameter

      public void setParameter(double param, int index)
      Sets one of the node's parameters to a double. This is a convenience method that invokes setParameter(Object,int) and so adheres to the same event firing behavior.
      Parameters:
      param - the parameter, as a double.
      index - the index of the parameter.

    • setParameter

      public void setParameter(Object param, int index)
      Sets one of the node's parameters to an Object. This is a convenience method that invokes setParameterBlock() and so adheres to the same event firing behavior.

      The Object may be a DeferredData instance. It will not be evaluated until its value is actually required, i.e., when a rendering of the node is requested or the renderable dimensions are queried.

      Parameters:
      param - the parameter, as an Object.
      index - the index of the parameter.