Activates the installed IIOParamController for this IIOParam object and returns the resulting value. When this method returns true, all values for this IIOParam object will be ready for the next read or write operation. If false is returned, no settings in this object will have been disturbed (i.e., the user canceled the operation).

Ordinarily, the controller will be a GUI providing a user interface for a subclass of IIOParam for a particular plug-in. Controllers need not be GUIs, however.

Returns true if this reader allows the source image to be rendered at an arbitrary size as part of the decoding process, by means of the setSourceRenderSize method. If this method returns false, calls to setSourceRenderSize will throw an UnsupportedOperationException.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

• It is reflexive: for any non-null reference value x, x.equals(x) should return true.
• It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
• It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
• It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
• For any non-null reference value x, x.equals(null) should return false.

The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any non-null reference values x and y, this method returns true if and only if x and y refer to the same object (x == y has the value true).

Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.

Returns the runtime class of an object. That Class object is the object that is locked by static synchronized methods of the represented class.

Returns whatever IIOParamController is currently installed. This could be the default if there is one, null, or the argument of the most recent call to setController.

Returns the default IIOParamController, if there is one, regardless of the currently installed controller. If there is no default controller, returns null.

Returns the BufferedImage currently set by the setDestination method, or null if none is set.

Returns the set of band indices where data will be placed. If no value has been set, null is returned to indicate that all destination bands will be used.

Returns the offset in the destination image at which pixels are to be placed.

If setDestinationOffsets has not been called, a Point with zero X and Y values is returned (which is the correct value).

Returns the type of image to be returned by the read, if one was set by a call to setDestination(ImageTypeSpecifier), as an ImageTypeSpecifier. If none was set, null is returned.

Returns the set of of source bands to be used. The returned value is that set by the most recent call to setSourceBands, or null if there have been no calls to setSourceBands.

Semantically, the array returned is a copy; changes to array contents subsequent to this call have no effect on this IIOParam.

If getSourceNumProgressivePasses is equal to Integer.MAX_VALUE, returns Integer.MAX_VALUE. Otherwise, returns getSourceMinProgressivePass() + getSourceNumProgressivePasses() - 1.

Returns the index of the first progressive pass that will be decoded. If no value has been set, 0 will be returned (which is the correct value).

Returns the number of the progressive passes that will be decoded. If no value has been set, Integer.MAX_VALUE will be returned (which is the correct value).

Returns the source region to be used. The returned value is that set by the most recent call to setSourceRegion, and will be null if there is no region set.

Returns the width and height of the source image as it will be rendered during decoding, if they have been set via the setSourceRenderSize method. A nullvalue indicates that no setting has been made.

Returns the number of source columns to advance for each pixel.

If setSourceSubsampling has not been called, 1 is returned (which is the correct value).

Returns the number of rows to advance for each pixel.

If setSourceSubsampling has not been called, 1 is returned (which is the correct value).

Returns the horizontal offset of the subsampling grid.

If setSourceSubsampling has not been called, 0 is returned (which is the correct value).

Returns the vertical offset of the subsampling grid.

If setSourceSubsampling has not been called, 0 is returned (which is the correct value).

Returns true if there is a controller installed for this IIOParam object. This will return true if getController would not return null.

Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

• Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
• If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
• It is not required that if two objects are unequal according to the method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the Java^TM programming language.)

Wakes up a single thread that is waiting on this object's monitor. If any threads are waiting on this object, one of them is chosen to be awakened. The choice is arbitrary and occurs at the discretion of the implementation. A thread waits on an object's monitor by calling one of the wait methods.

The awakened thread will not be able to proceed until the current thread relinquishes the lock on this object. The awakened thread will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened thread enjoys no reliable privilege or disadvantage in being the next thread to lock this object.

This method should only be called by a thread that is the owner of this object's monitor. A thread becomes the owner of the object's monitor in one of three ways:

• By executing a synchronized instance method of that object.
• By executing the body of a synchronized statement that synchronizes on the object.
• For objects of type Class, by executing a synchronized static method of that class.

Only one thread at a time can own an object's monitor.

Wakes up all threads that are waiting on this object's monitor. A thread waits on an object's monitor by calling one of the wait methods.

The awakened threads will not be able to proceed until the current thread relinquishes the lock on this object. The awakened threads will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened threads enjoy no reliable privilege or disadvantage in being the next thread to lock this object.

This method should only be called by a thread that is the owner of this object's monitor. See the notify method for a description of the ways in which a thread can become the owner of a monitor.

Sets the IIOParamController to be used to provide settings for this IIOParam object when the activateController method is called, overriding any default controller. If the argument is null, no controller will be used, including any default. To restore the default, use setController(getDefaultController()).

Supplies a BufferedImage to be used as the destination for decoded pixel data. The currently set image will be written to by the read, readAll, and readRaster methods, and a reference to it will be returned by those methods.

Pixel data from the aforementioned methods will be written starting at the offset specified by getDestinationOffset.

If destination is null, a newly-created BufferedImage will be returned by those methods.

At the time of reading, the image is checked to verify that its ColorModel and SampleModel correspond to one of the ImageTypeSpecifiers returned from the ImageReader's getImageTypes method. If it does not, the reader will throw an IIOException.

Sets the indices of the destination bands where data will be placed. Duplicate indices are not allowed.

A null value indicates that all destination bands will be used.

Choosing a destination band subset will not affect the number of bands in the output image of a read if no destination image is specified; the created destination image will still have the same number of bands as if this method had never been called. If a different number of bands in the destination image is desired, an image must be supplied using the ImageReadParam.setDestination method.

At the time of reading or writing, an IllegalArgumentException will be thrown by the reader or writer if a value larger than the largest destination band index has been specified, or if the number of source bands and destination bands to be used differ. The ImageReader.checkReadParamBandSettings method may be used to automate this test.

Specifies the offset in the destination image at which future decoded pixels are to be placed, when reading, or where a region will be written, when writing.

When reading, the region to be written within the destination BufferedImage will start at this offset and have a width and height determined by the source region of interest, the subsampling parameters, and the destination bounds.

Normal writes are not affected by this method, only writes performed using ImageWriter.replacePixels. For such writes, the offset specified is within the output stream image whose pixels are being modified.

There is no unsetDestinationOffset method; simply call setDestinationOffset(new Point(0, 0)) to restore default values.

Sets the indices of the source bands to be used. Duplicate indices are not allowed.

A null value indicates that all source bands will be used.

At the time of reading, an IllegalArgumentException will be thrown by the reader or writer if a value larger than the largest available source band index has been specified or if the number of source bands and destination bands to be used differ. The ImageReader.checkReadParamBandSettings method may be used to automate this test.

Semantically, a copy is made of the array; changes to the array contents subsequent to this call have no effect on this IIOParam.

Sets the range of progressive passes that will be decoded. Passes outside of this range will be ignored.

A progressive pass is a re-encoding of the entire image, generally at progressively higher effective resolutions, but requiring greater transmission bandwidth. The most common use of progressive encoding is found in the JPEG format, where successive passes include more detailed representations of the high-frequency image content.

The actual number of passes to be decoded is determined during decoding, based on the number of actual passes available in the stream. Thus if minPass + numPasses - 1 is larger than the index of the last available passes, decoding will end with that pass.

A value of numPasses of Integer.MAX_VALUE indicates that all passes from minPass forward should be read. Otherwise, the index of the last pass (i.e., minPass + numPasses - 1) must not exceed Integer.MAX_VALUE.

There is no unsetSourceProgressivePasses method; the same effect may be obtained by calling setSourceProgressivePasses(0, Integer.MAX_VALUE).

Sets the source region of interest. The region of interest is described as a rectangle, with the upper-left corner of the source image as pixel (0, 0) and increasing values down and to the right. The actual number of pixels used will depend on the subsampling factors set by setSourceSubsampling. If subsampling has been set such that this number is zero, an IllegalStateException will be thrown.

The source region of interest specified by this method will be clipped as needed to fit within the source bounds, as well as the destination offsets, width, and height at the time of actual I/O.

A value of null for sourceRegion will remove any region specification, causing the entire image to be used.

If the image is able to be rendered at an arbitrary size, sets the source width and height to the supplied values. Note that the values returned from the getWidth and getHeight methods on ImageReader are not affected by this method; they will continue to return the default size for the image. Similarly, if the image is also tiled the tile width and height are given in terms of the default size.

Typically, the width and height should be chosen such that the ratio of width to height closely approximates the aspect ratio of the image, as returned from ImageReader.getAspectRatio.

If this plug-in does not allow the rendering size to be set, an UnsupportedOperationException will be thrown.

To remove the render size setting, pass in a value of null for size.

Specifies a decimation subsampling to apply on I/O. The sourceXSubsampling and sourceYSubsampling parameters specify the subsampling period (i.e., the number of rows and columns to advance after every source pixel). Specifically, a period of 1 will use every row or column; a period of 2 will use every other row or column. The subsamplingXOffset and subsamplingYOffset parameters specify an offset from the region (or image) origin for the first subsampled pixel. Adjusting the origin of the subsample grid is useful for avoiding seams when subsampling a very large source image into destination regions that will be assembled into a complete subsampled image. Most users will want to simply leave these parameters at 0.

The number of pixels and scanlines to be used are calculated as follows.

The number of subsampled pixels in a scanline is given by

truncate[(width - subsamplingXOffset + sourceXSubsampling - 1) / sourceXSubsampling].

If the region is such that this width is zero, an IllegalStateException is thrown.

The number of scanlines to be used can be computed similarly.

The ability to set the subsampling grid to start somewhere other than the source region origin is useful if the region is being used to create subsampled tiles of a large image, where the tile width and height are not multiples of the subsampling periods. If the subsampling grid does not remain consistent from tile to tile, there will be artifacts at the tile boundaries. By adjusting the subsampling grid offset for each tile to compensate, these artifacts can be avoided. The tradeoff is that in order to avoid these artifacts, the tiles are not all the same size. The grid offset to use in this case is given by:
grid offset = [period - (region offset modulo period)] modulo period)

If either sourceXSubsampling or sourceYSubsampling is 0 or negative, an IllegalArgumentException will be thrown.

If either subsamplingXOffset or subsamplingYOffset is negative or greater than or equal to the corresponding period, an IllegalArgumentException will be thrown.

There is no unsetSourceSubsampling method; simply call setSourceSubsampling(1, 1, 0, 0) to restore default values.

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Causes current thread to wait until another thread invokes the method or the method for this object. In other words, this method behaves exactly as if it simply performs the call wait(0).

The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until another thread notifies threads waiting on this object's monitor to wake up either through a call to the notify method or the notifyAll method. The thread then waits until it can re-obtain ownership of the monitor and resumes execution.

As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:

     synchronized (obj) {
         while (<condition does not hold>)
             obj.wait();
         ... // Perform action appropriate to condition
     }
 

This method should only be called by a thread that is the owner of this object's monitor. See the notify method for a description of the ways in which a thread can become the owner of a monitor.

Causes current thread to wait until either another thread invokes the method or the method for this object, or a specified amount of time has elapsed.

The current thread must own this object's monitor.

This method causes the current thread (call it T) to place itself in the wait set for this object and then to relinquish any and all synchronization claims on this object. Thread T becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:

• Some other thread invokes the notify method for this object and thread T happens to be arbitrarily chosen as the thread to be awakened.
• Some other thread invokes the notifyAll method for this object.
• Some other thread interrupts thread T.
• The specified amount of real time has elapsed, more or less. If timeout is zero, however, then real time is not taken into consideration and the thread simply waits until notified.

The thread T is then removed from the wait set for this object and re-enabled for thread scheduling. It then competes in the usual manner with other threads for the right to synchronize on the object; once it has gained control of the object, all its synchronization claims on the object are restored to the status quo ante - that is, to the situation as of the time that the wait method was invoked. Thread T then returns from the invocation of the wait method. Thus, on return from the wait method, the synchronization state of the object and of thread T is exactly as it was when the wait method was invoked.

A thread can also wake up without being notified, interrupted, or timing out, a so-called spurious wakeup. While this will rarely occur in practice, applications must guard against it by testing for the condition that should have caused the thread to be awakened, and continuing to wait if the condition is not satisfied. In other words, waits should always occur in loops, like this one:

     synchronized (obj) {
         while (<condition does not hold>)
             obj.wait(timeout);
         ... // Perform action appropriate to condition
     }
 

(For more information on this topic, see Section 3.2.3 in Doug Lea's "Concurrent Programming in Java (Second Edition)" (Addison-Wesley, 2000), or Item 50 in Joshua Bloch's "Effective Java Programming Language Guide" (Addison-Wesley, 2001).

If the current thread is interrupted by another thread while it is waiting, then an InterruptedException is thrown. This exception is not thrown until the lock status of this object has been restored as described above.

Note that the wait method, as it places the current thread into the wait set for this object, unlocks only this object; any other objects on which the current thread may be synchronized remain locked while the thread waits.

This method should only be called by a thread that is the owner of this object's monitor. See the notify method for a description of the ways in which a thread can become the owner of a monitor.

Causes current thread to wait until another thread invokes the method or the method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.

This method is similar to the wait method of one argument, but it allows finer control over the amount of time to wait for a notification before giving up. The amount of real time, measured in nanoseconds, is given by:

 1000000*timeout+nanos

In all other respects, this method does the same thing as the method of one argument. In particular, wait(0, 0) means the same thing as wait(0).

The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until either of the following two conditions has occurred:

• Another thread notifies threads waiting on this object's monitor to wake up either through a call to the notify method or the notifyAll method.
• The timeout period, specified by timeout milliseconds plus nanos nanoseconds arguments, has elapsed.

The thread then waits until it can re-obtain ownership of the monitor and resumes execution.

As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:

     synchronized (obj) {
         while (<condition does not hold>)
             obj.wait(timeout, nanos);
         ... // Perform action appropriate to condition
     }
 

This method should only be called by a thread that is the owner of this object's monitor. See the notify method for a description of the ways in which a thread can become the owner of a monitor.