SAVEFILEOPTION

typedef struct _SAVEFILEOPTION 
{ 
   L_UINT uStructSize; 
   L_INT Reserved1; 
   L_INT Reserved2; 
   L_UINT Flags; 
   L_INT Passes; 
   L_INT PageNumber; 
   L_INT GlobalWidth; 
   L_INT GlobalHeight; 
   L_UINT GlobalLoop; 
   L_COLORREF GlobalBackground; 
   L_RGBQUAD GlobalPalette[256]; 
   L_UINT StampWidth; 
   L_UINT StampHeight; 
   L_UINT StampBits; 
   L_SIZE_T IFD; 
   L_TCHAR szPassword[255]; 
   PHOTMTRICINTERP PhotometricInterpretation; 
   L_UINT TileWidth; 
   L_UINT TileHeight; 
   L_UINT Flags2; 
   L_UINT64 IFD64; /* 32-bit apps only */ 
} SAVEFILEOPTION, * pSAVEFILEOPTION; 

The SAVEFILEOPTION structure specifies extra options for writing an image file.

The following functions make use of this structure:

LFile::FileConvert

LFile::DeletePage

LFile::WriteFileTransforms

LFile::Save

LFile::SaveList

LMemoryFile::Save

LFile::SaveWithLayers

LFile::SaveFile

LFile::SaveTile

LFile::SaveOffset

LMemoryFile::StartCompressBuffer

LFile::WriteComment

LFile::WriteStamp

LSegment::MrcSaveBitmap

LSegment::MrcSaveBitmapT44

See LBaseFile::GetDefaultSaveFileOption for information on default save options.

Comments

IFD Offsets

For technical reasons, the following restrictions apply when you pass an IFD offset by setting the IFD member of the SAVEFILEOPTION structure if you set PageNumber to 1:

• You cannot add tags, comments or GeoKeys to this IFD. You can only update existing tags, comments or GeoKeys in this IFD.
• You cannot replace the TIFF page indicated by this IFD.
• You cannot add a page before the this IFD.
• You cannot delete the page indicated by this IFD.
• You can, however, add tags, comments or GeoKeys to a IFD that follows the specified IFD (for example, if PageNumber is >= 2). You can also replace or delete a page that follows the specified IFD and you can insert a page after this IFD.

Stamp Images

To load a stamp image, you must use the LFile::ReadStamp function.

Saving a stamp image is valid for the following formats: LEAD, JFIF, LEAD2JFIF, LEAD1JFIF, FILE_EXIF, FILE_EXIF_YCC, and FILE_EXIF_JPEG. For short descriptions, refer to File Formats: JPEG and LEAD Compressed (JPG, J2K, JP2, JPM, CMP, and CMW).

• When saving a stamp image in a FILE_EXIF or FILE_EXIF_YCC file, the stamp is appended as the second page of a multi-page file.
• When saving a stamp image in an Exif JPG file, the stamp size is restricted to 160x120x24. When saving Exif files, the StampWidth, StampHeight, and StampBits members of the SAVEFILEOPTION structure will be ignored and 160 (StampWidth), 120 (StampHeight) and 24 (StampBits) will be used instead. That limitation has been imposed in order to conform with the ExifR98 interoperability rules imposed by Japanese digital camera manufacturers. The save function will return an error (ERROR_INVALID_STAMP_SIZE) if you exceed any of these size limitations.
• If you are working with uncompressed (TIFF) Exif files, the stamp size is (width x height x 24 bpp), with no limitations on width and height.
• When saving a stamp image in a LEAD, JFIF, LEAD2JFIF, or LEAD1JFIF file, neither the width nor the height of the stamp can exceed 255 pixels. In addition, the following overall size limitations apply.The save function will return an error (ERROR_INV_RANGE) if you exceed any of these size limitations:
• If you save an 8-bit stamp, the following calculation cannot exceed 65,535:

(width * height) + 778. - If you save a 24-bit stamp, the following calculation cannot exceed 65,535:
(width * height * 3) + 10. - If SAVEFILE_MULTIPAGE is passed to LFile::SaveFile, it will take precedence over ESO_REPLACEPAGE or ESO_INSERTPAGE.

If ESO_JPEGSTAMP is set, then the stamps being saved in an Exif JPEG file will be JPEG compressed. The stamps saved in uncompressed Exif TIFF files cannot be JPEG compressed. They can only be RGB or YCbCr.

Page Number Tags

By default, the ESO_NOPAGENUMBER is not set. Therefore, all TIFF files will be saved with an updated PageNumber tag. This is required for Class-F compatibility

When LEADTOOLS saves TIFF files and writes the PageNumber tag, it has to do extra processing when appending, inserting or deleting pages as follows:

1. When appending a page, the PageNumber tag of the first page is updated to reflect the change in the number of pages.
2. When inserting a page, the PageNumber tag of the pages that will be after the page being inserted will be updated top reflect the change in the page index. Also, the PageNumber tag of the first file is updated to reflect the increase in the number of pages.
3. When deleting a page (by calling LFile::DeletePage), the PageNumber tag of the first page is updated to reflect the change in the number of pages. Also, the PageNumber of all the pages that follow the page being deleted are updated to reflect their new index.

These updates take usually very little time. However, when inserting a page into a TIFF file that contains thousands of images, these updates might be time consuming. In that case, you can gain some speed by disabling this functionality.

If ESO_NOPAGENUMBER is set, then LFile::DeletePage will not update the PageNumber tag of any page.

If the ESO_NOPAGENUMBER is not set, then LEADTOOLS will write the PageNumber tag so do not call LFileSettings::SetTag to set this tag (tag 297).

When saving RAW uncompressed data, the bits in each byte can be reversed by passing the ESO_REVERSEBITS flag. In addition, each line of data can be padded so that the length is a multiple of four bytes by passing the ESO_PAD4 flag. The raw data can be saved at any offset in the file by using the LFile::SaveOffset function.

Tiled TIFF Images

Note: For more information about loading and saving large TIFF files faster, refer to Loading and Saving Large TIFF/BigTIFF Files.

When saving TIFF files, the size of the tiles or strips saved in the file can be controlled.

Some graphic packages cannot load TIFF files unless the files are saved with a certain tile or strip size. LEADTOOLS can load files of any strip and tile size, so modifying these settings is not necessary when saving files that will be loaded with LEADTOOLS.

If ESO_TILEINFOVALID is not set, then the TileWidth and TileHeight members of the SAVEFILEOPTION structure are ignored. In this case, the bitmap will be saved like in the previous versions of LEADTOOLS.

If TileWidth is less than or equal to the bitmap width, the bitmap will be saved as tiles. If TileWidth is greater than the bitmap width, the bitmap will be saved as strips.

If the bitmap is saved as tiles, TileHeight controls the height of the tile.

If the bitmap is saved as strips, TileHeight controls the height of the strip. The image can be saved as one strip by setting TileHeight to a value greater than or equal to the bitmap height.

Some compressions (like JPEG or CMP) have limits on the size of the tiles used when saving a file. For example, the JPEG compression requires the tile width and height are multiple of 8 or 16 depending on the subsampling chosen. For these files, if you specified a certain tile size (by setting ESO_TILEINFOVALID and TileWidth and TileHeight), the requested tile size might be updated to the nearest acceptable tile size.

Note: When using the Flags and Flags2 members take care not to mix the placement of the flags. All the EXO_XXX flags should be set in the Flags member, while the ESO2_XXX flags should be set in the Flags2 member.

ESO2_NOLZWAUTOCLEAR can be used when saving TIFF LZW files to save files compatible with some buggy LZW decoders that cannot handle early CLEAR codes. Some IBM decoders are known to have this problem. They will not decode LEAD TIFF LZW files unless this flag is set. This flag is not set by default, which allows LEADTOOLS to insert CLEAR LZW codes and reset the LZW compression engine if the compression ratio is not adequate.

If the ESO2_BIGTIFF flag is set, the file or page being saved will use the BigTIFF format with 64-bit file offsets instead of the 32-bit file offsets that regular TIFF files use. The format passed to the save function determines which compression and color space to use. For example, if the FILE_TIF_J2K format, the file or page being saved will use J2K compression but in the BigTIFF file format instead of the TIFF file format. The BigTIFF file format is less common, but can be used to save files > 4GB.

TIFF and BigTIFF pages cannot be mixed in the same file. For example, you can only append TIFF pages to a TIFF file and BigTIFF pages to a BigTIFF file format.  Trying to append/insert TIFF pages into BigTIFF files or vice versa will generate the ERROR_FORMAT_MISMATCH error.

To determine whether a file is TIFF or BigTIFF, call the LFile::GetInfo function and check whether the FILEINFO_BIGTIFF flag is set in FILEINFO.Flags.