| synopsis || arguments || prev || next |
Overload navigation: 1, 2
kdu_image_in( char const * fname, siz_params * siz, int & next_comp_idx, bool & vflip, kdu_rgb8_palette * palette=NULL)
[Declared in "../apps/image/kdu_image.h"]
Attempts to open a file with the indicated name, generating an error message (through kdu_error) if unsuccessful. It automatically creates and installs an appropriate internal file reading object, based on the file suffix or some other property (e.g., a magic number found at the start of the file). The method used to ascertain the file format and the set of file formats which are supported is entirely dependent on the implementation.
Component indices for the image components represented by the file start from the value supplied via the next_comp_idx argument. These component indices are used to access dimensional and other parameters for the relevant components in the siz object.
If the dimensions of the new image components can be deduced from a file header, the function sets the relevant dimensions in the Sdims attribute of the supplied siz object. Similarly, if the sample bit-depth or the signed/unsigned character of the image samples can be deduced up front, they are written to the Sprecision and Ssigned attributes of the siz object.
Otherwise, the function expects to extract the unknown attributes from the siz object and generates an error if they cannot be found. The most important example where this behaviour is required is in reading raw image files which have no header. In this case, the kdu_params::parse_string function might be used to parse the relevant dimensional parameters from command line arguments before calling this constructor.
Relative path name of the image file to be opened.
Pointer to a siz_params object in which image component dimensions, bit-depth and signed/unsigned characteristics will be recorded (if they can be determined).
Identifies the component index assigned to the first image component (starting from 0) in the file. Upon return, the value of this argument is augmented by the number of image components available from the file. Once all image files have been opened, the value of next_comp_idx (assuming it was initially 0) will hold the total number of image components, which could then be used to set the siz object's Scomponents attribute (this is not done automatically).
This argument is provided to support bottom-up image file formats, such as the well-known BMP format. The value of vflip is set to true if the image lines are going to be supplied in bottom-up fashion, allowing the compressor to configure itself for processing the data in reverse order (see kdu_codestream::change_appearance for more on this).
May be non-NULL if the JPEG2000 compressed file format supports signalling of colour palette information (JP2 files provide such support). BMP files, for example, may contain palettized data. In this case, the palette object's entries are filled out to reflect the index of the image component to which the palette is applied, along with the palette itself. Palettes which require more than 8-bit indices should be expanded directly by the file reader. If the palette.input_bits is set to a non-zero value already, the palette is in use and a new palette cannot be created for the present image file. In this case, or if the palette argument is NULL, the image sample values are to be depalettized by the image reader, which will normally provide a full set of colour channels.