001/*
002 * $RCSfile: BlkImgDataSrc.java,v $
003 * $Revision: 1.1 $
004 * $Date: 2005/02/11 05:02:11 $
005 * $State: Exp $
006 *
007 * Class:                   BlkImgDataSrc
008 *
009 * Description:             Defines methods to transfer image data in blocks.
010 *
011 *
012 *
013 * COPYRIGHT:
014 *
015 * This software module was originally developed by Raphaël Grosbois and
016 * Diego Santa Cruz (Swiss Federal Institute of Technology-EPFL); Joel
017 * Askelöf (Ericsson Radio Systems AB); and Bertrand Berthelot, David
018 * Bouchard, Félix Henry, Gerard Mozelle and Patrice Onno (Canon Research
019 * Centre France S.A) in the course of development of the JPEG2000
020 * standard as specified by ISO/IEC 15444 (JPEG 2000 Standard). This
021 * software module is an implementation of a part of the JPEG 2000
022 * Standard. Swiss Federal Institute of Technology-EPFL, Ericsson Radio
023 * Systems AB and Canon Research Centre France S.A (collectively JJ2000
024 * Partners) agree not to assert against ISO/IEC and users of the JPEG
025 * 2000 Standard (Users) any of their rights under the copyright, not
026 * including other intellectual property rights, for this software module
027 * with respect to the usage by ISO/IEC and Users of this software module
028 * or modifications thereof for use in hardware or software products
029 * claiming conformance to the JPEG 2000 Standard. Those intending to use
030 * this software module in hardware or software products are advised that
031 * their use may infringe existing patents. The original developers of
032 * this software module, JJ2000 Partners and ISO/IEC assume no liability
033 * for use of this software module or modifications thereof. No license
034 * or right to this software module is granted for non JPEG 2000 Standard
035 * conforming products. JJ2000 Partners have full right to use this
036 * software module for his/her own purpose, assign or donate this
037 * software module to any third party and to inhibit third parties from
038 * using this software module for non JPEG 2000 Standard conforming
039 * products. This copyright notice must be included in all copies or
040 * derivative works of this software module.
041 *
042 * Copyright (c) 1999/2000 JJ2000 Partners.
043 * */
044package jj2000.j2k.image;
045
046/**
047 * This interface defines the methods to transfer image data in blocks,
048 * without following any particular order (random access). This interface does
049 * not define the methods to access the image characteristics, such as width,
050 * height, number of components, tiles, etc., or to change the current
051 * tile. That is provided by other interfaces such as ImgData.
052 *
053 * <P>This interface has the notion of a current tile. All data, coordinates
054 * and dimensions are always relative to the current tile. If there is only
055 * one tile then it is equivalent as having no tiles.
056 *
057 * <P>A block of requested data may never cross tile boundaries. This should
058 * be enforced by the implementing class, or the source of image data.
059 *
060 * <P>This interface defines the methods that can be used to retrieve image
061 * data. Implementing classes need not buffer all the image data, they can ask
062 * their source to load the data they need.
063 *
064 * @see ImgData
065 * */
066public interface BlkImgDataSrc extends ImgData {
067
068    /**
069     * Returns the position of the fixed point in the specified component, or
070     * equivalently the number of fractional bits. This is the position of the
071     * least significant integral (i.e. non-fractional) bit, which is
072     * equivalent to the number of fractional bits. For instance, for
073     * fixed-point values with 2 fractional bits, 2 is returned. For
074     * floating-point data this value does not apply and 0 should be
075     * returned. Position 0 is the position of the least significant bit in
076     * the data.
077     *
078     * @param c The index of the component.
079     *
080     * @return The position of the fixed-point, which is the same as the
081     * number of fractional bits. For floating-point data 0 is returned.
082     * */
083     public int getFixedPoint(int c);
084
085    /**
086     * Returns, in the blk argument, a block of image data containing the
087     * specifed rectangular area, in the specified component. The data is
088     * returned, as a reference to the internal data, if any, instead of as a
089     * copy, therefore the returned data should not be modified.
090     *
091     * <P>The rectangular area to return is specified by the 'ulx', 'uly', 'w'
092     * and 'h' members of the 'blk' argument, relative to the current
093     * tile. These members are not modified by this method. The 'offset' and
094     * 'scanw' of the returned data can be arbitrary. See the 'DataBlk' class.
095     *
096     * <P>This method, in general, is more efficient than the 'getCompData()'
097     * method since it may not copy the data. However if the array of returned
098     * data is to be modified by the caller then the other method is probably
099     * preferable.
100     *
101     * <P>If possible, the data in the returned 'DataBlk' should be the
102     * internal data itself, instead of a copy, in order to increase the data
103     * transfer efficiency. However, this depends on the particular
104     * implementation (it may be more convenient to just return a copy of the
105     * data). This is the reason why the returned data should not be modified.
106     *
107     * <P>If the data array in <tt>blk</tt> is <tt>null</tt>, then a new one
108     * is created if necessary. The implementation of this interface may
109     * choose to return the same array or a new one, depending on what is more
110     * efficient. Therefore, the data array in <tt>blk</tt> prior to the
111     * method call should not be considered to contain the returned data, a
112     * new array may have been created. Instead, get the array from
113     * <tt>blk</tt> after the method has returned.
114     *
115     * <P>The returned data may have its 'progressive' attribute set. In this
116     * case the returned data is only an approximation of the "final" data.
117     *
118     * @param blk Its coordinates and dimensions specify the area to return,
119     * relative to the current tile. Some fields in this object are modified
120     * to return the data.
121     *
122     * @param c The index of the component from which to get the data.
123     *
124     * @return The requested DataBlk
125     *
126     * @see #getCompData
127     * */
128    public DataBlk getInternCompData(DataBlk blk, int c);
129
130    /**
131     * Returns, in the blk argument, a block of image data containing the
132     * specifed rectangular area, in the specified component. The data is
133     * returned, as a copy of the internal data, therefore the returned data
134     * can be modified "in place".
135     *
136     * <P>The rectangular area to return is specified by the 'ulx', 'uly', 'w'
137     * and 'h' members of the 'blk' argument, relative to the current
138     * tile. These members are not modified by this method. The 'offset' of
139     * the returned data is 0, and the 'scanw' is the same as the block's
140     * width. See the 'DataBlk' class.
141     *
142     * <P>This method, in general, is less efficient than the
143     * 'getInternCompData()' method since, in general, it copies the
144     * data. However if the array of returned data is to be modified by the
145     * caller then this method is preferable.
146     *
147     * <P>If the data array in 'blk' is 'null', then a new one is created. If
148     * the data array is not 'null' then it is reused, and it must be large
149     * enough to contain the block's data. Otherwise an 'ArrayStoreException'
150     * or an 'IndexOutOfBoundsException' is thrown by the Java system.
151     *
152     * <P>The returned data may have its 'progressive' attribute set. In this
153     * case the returned data is only an approximation of the "final" data.
154     *
155     * @param blk Its coordinates and dimensions specify the area to return,
156     * relative to the current tile. If it contains a non-null data array,
157     * then it must be large enough. If it contains a null data array a new
158     * one is created. Some fields in this object are modified to return the
159     * data.
160     *
161     * @param c The index of the component from which to get the data.
162     *
163     * @see #getInternCompData
164     * */
165    public DataBlk getCompData(DataBlk blk, int c);
166}