/****************************************************************************** * * Purpose: Documentation for the PCIDSKFile class. * ****************************************************************************** * Copyright (c) 2009 * PCI Geomatics, 50 West Wilmot Street, Richmond Hill, Ont, Canada * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), * to deal in the Software without restriction, including without limitation * the rights to use, copy, modify, merge, publish, distribute, sublicense, * and/or sell copies of the Software, and to permit persons to whom the * Software is furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included * in all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER * DEALINGS IN THE SOFTWARE. ****************************************************************************/ /** \fn PCIDSKInterfaces *PCIDSK::PCIDSKFile::GetInterfaces(); \brief Fetch hookable interfaces in use with this file. \fn PCIDSKChannel *PCIDSK::PCIDSKFile::GetChannel( int band ); \brief Fetch channel interface object. The returned channel object remains owned by the PCIDSKFile and should not be deleted by the caller, and will become invalid after the PCIDSKFile is closed (deleted). @param band the band number to fetch (one based). @return pointer to internally managed channel object. \fn PCIDSKSegment *PCIDSK::PCIDSKFile::GetSegment( int segment ); \brief Fetch segment interface object. The returned segment object remains owned by the PCIDSKFile and should not be deleted by the caller, and will become invalid after the PCIDSKFile is closed (deleted). @param segment the segment number to fetch (one based). @return pointer to internally managed segment object. \fn int PCIDSK::PCIDSKFile::GetWidth() const \brief Fetch image width. @return the width of the file in pixels. \fn int PCIDSK::PCIDSKFile::GetHeight() const \brief Fetch image height. @return the height of the file in pixels. \fn int PCIDSK::PCIDSKFile::GetChannels() const \brief Fetch channel (band) count. @return the number of channels on this file. \fn const char *PCIDSK::PCIDSKFile::GetInterleaving() const \brief Fetch file interleaving method. @return the interleaving name, one of "PIXEL", "BAND" or "FILE". Note that tiled files will be reported as "FILE" interleaving. \fn void PCIDSK::PCIDSKFile::WriteToFile( const void *buffer, uint64 offset, uint64 size); \brief Write data to file. This method is normally only used by the PCIDSK library itself, and provides a mechanism to write directly to the PCIDSK file. Applications should normally use the PCIDSK::PCIDSKChannel::ReadBlock(), and PCIDSK::PCIDSKChannel::WriteBlock() methods for imagery, or appropriate PCIDSK::PCIDSKSegment methods for updating segment data. @param buffer pointer to the data to write to disk. @param offset the byte offset in the file (zero based) at which to write the data. @param size the number of bytes from buffer to write. \fn void PCIDSK::PCIDSKFile::ReadFromFile( void *buffer, uint64 offset, uint64 size); \brief Read data from file. This method is normally only used by the PCIDSK library itself, and provides a mechanism to read directly from the PCIDSK file. Applications should normally use the PCIDSK::PCIDSKChannel::ReadBlock() method for imagery, or appropriate PCIDSK::PCIDSKSegment methods for reading segment data. @param buffer pointer to the buffer into which the data should be read. @param offset the byte offset in the file (zero based) at which to read the data. @param size the number of bytes from the file to read. \fn void PCIDSK::PCIDSKFile::GetIODetails( void ***io_handle_pp, Mutex ***io_mutex_pp, const char *filename = "" ); \brief Fetch details for IO to named file. This method is normally only used by the PCIDSK library itself to request io accessors for a file. If filename is empty, accessors for the PCIDSK file are returned. Otherwise accessors for a dependent file (ie. FILE linked file) are returned. @param io_handle_pp pointer to a pointer into which to load the IO handle. @param io_mutex_pp pointer to a pointer into which to load the associated mutex. @param filename the name of the file to access or an empty string for the PCIDSK file itself. \fn int PCIDSK::PCIDSKFile::GetPixelGroupSize() const; \brief fetch number of bytes per pixel Returns the number of bytes for each pixel group. Each pixel group consists of the values for all the channels in the file in order. @note This method should only be called for GetInterleaving() == "PIXEL" files. @return the size of a pixel group in bytes. @see ReadAndLockBlock() \fn uint8 *PCIDSK::PCIDSKFile::ReadAndLockBlock( int block_index, int win_xoff=-1, int win_xsize=-1 ); \brief Read a block. Returnst the pointer to an internal buffer for the indicated block. The buffer is owned by the PCIDSKFile object, but will be considered locked and available for the application code to read and modify until the UnlockBlock() method is called. The buffer will contain all the pixel values for the requested block in pixel interleaved form. The win_xoff, and win_xsize parameters may be used to select a subregion of the scanline block to read. By default the whole scanline is read. @note This method should only be called for GetInterleaving() == "PIXEL" files. Normal imagery access should be via the PCIDSKChannel class. This method is provided on the PCIDSKFile for pixel interleaved files to allow optimized access for this one case. @param block_index the zero based block(scanline) to be read. @param win_xoff the offset into the scanline to start reading values. @param win_xsize the number of pixels to read. @return pointer to an internal buffer with pixel data in it. \fn void PCIDSK::PCIDSKFile::UnlockBlock( bool mark_dirty=false); \brief Unlock block. This method should be called after use of the buffer from ReadAndLockBlock() is complete. If the buffer was modified and will need to be written to disk the argument "mark_dirty" should be passed in as true. @note This method should only be called for GetInterleaving() == "PIXEL" files. @param mark_dirty true if the block data was modified, else false. @see ReadAndLockBlock() \fn void PCIDSK::PCIDSKFile::FlushBlock(); \brief force write of dirty buffer This method may be used for force the flushing of any previously modified pixel data for the current pixel interleaved scanline to disk. The imagery buffer is that returned by ReadAndLockBlock(), and the data would have had to have been marked dirty when UnlockBlock() was called. Dirty data will be automatically flushed to disk on file close, or when another block is read with ReadAndLockBlock(). This method is primarily used to force flushing to disk without closing the file. @note This method should only be called for GetInterleaving() == "PIXEL" files. @see ReadAndLockBlock() ****************************************************************************** \fn std::vector PCIDSK::PCIDSKFile::GetMetadataKeys(); \brief Fetch metadata keys Returns a vector of metadata keys that occur on this object. The values associated with each may be fetched with GetMetadataValue(). @return list of keys @see GetMetadataValue() ****************************************************************************** \fn const char *PCIDSK::PCIDSKFile::GetMetadataValue( const char *key ); \brief Fetch metadata value Note that the returned pointer is to an internal structure and it may become invalid if another thread modifies the metadata for this object. @param key the key to fetch the value for. @return the value of the indicated metadata item, or NULL if it does not exist on the target object. @see GetMetadataKeys() */