SAVEFILEOPTION

Summary

The SAVEFILEOPTION structure specifies extra options for writing an image file. See L_GetDefaultSaveFileOption for information about default save options.

Syntax

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_IFDTYPE IFD; 
   L_TCHAR szPassword[255]; 
   PHOTMTRICINTERP PhotometricInterpretation; 
   L_UINT TileWidth; 
   L_UINT TileHeight; 
   L_UINT Flags2; 
} SAVEFILEOPTION, * pSAVEFILEOPTION; 

Members

uStructSize

Size of the SAVEFILEOPTION structure. This should be sizeof(SAVEFILEOPTION). Be sure to fill this member.

Reserved1

Reserved for future use. Pass 0.

Reserved2

Reserved for future use. Pass 0.

Flags

Any of the following flags. (Use a bitwise OR to specify more than one value.) Also see the Flags2 member for additional flags.

Value Meaning
ESO_REVERSEBITS [0x00000001] Reverses the bit order when writing CCITT Group 3 and 4 files and RAW uncompressed data, so that the least significant bit (LSB) is first.
ESO_NOSUBFILETYPE [0x00000002] Prevents writing a subfile type TIFF tag when writing any TIFF file.
ESO_GLOBALBACKGROUND [0x00000004] Causes a GIF or WebP file to be saved with the global background color specified by the GlobalBackground field.
ESO_GLOBALPALETTE [0x00000008] Causes a GIF file to be saved with the global palette specified by the GlobalPalette field.
ESO_INTERLACED [0x00000010] Causes a GIF file to be saved as an interlaced file.
ESO_GLOBALLOOP [0x00000020] Enables looping when saving an animated file. This flag must be on for the GlobalLoop field to be used.
ESO_NOPALETTE [0x00000040] Causes a TIFF or PNG file to be saved as grayscale, without a palette.
ESO_SAVEWITHSTAMP [0x00000080] Causes a CMP, JPEG, or Exif file to be saved with a stamp (thumbnail image), in addition to the normal image.
ESO_FIXEDPALETTESTAMP [0x00000100] Causes a CMP or JPEG stamp image to be saved with a fixed palette.
ESO_YCCSTAMP [0x00000200] Causes an Exif stamp image to be saved with YCbCr color space.
ESO_REPLACEPAGE [0x00000400] Replaces the page specified by PageNumber.
ESO_INSERTPAGE [0x00000800] Inserts the new page before the page specified by PageNumber.
ESO_JPEGSTAMP [0x00001000] Saves JPEG compressed stamps.
ESO_DISABLEMMX [0x00002000] Do not use MMX optimized code.
ESO_SAVEOLDJTIF [0x00004000] Writes old style JTIF files.
ESO_NOPAGENUMBER [0x00008000] Do not update and save the PageNumber tag associated with the pages of a multipage TIFF file.
ESO_DISABLEP3 [0x00010000] Do not use P3-specific optimized code.
ESO_USEIFD [0x00020000] Uses the IFD offset.
ESO_MOTOROLAORDER [0x00040000] Saves files in Motorola byte order when possible.
ESO_WITHOUTTIMESTAMP [0x00080000] Saves file without time stamp.
ESO_PDF_TEXT_ENCODING_NONE [0x00000000] No text encoding is used for image data.
ESO_PDF_TEXT_ENCODING_ASCII_BASE85 [0x00100000] PDF, ASCII BASE 85 text encoding is used for image data.
ESO_PDF_TEXT_ENCODING_ASCII_HEX [0x00200000] PDF, ASCII HEX text encoding is used for image data.
ESO_PDF_ENCODING_MASK [0x00300000] Mask of the flags is used for PDF text encoding.
ESO_PDF_SAVE_USE_BITMAP_DPI [0x01000000] Uses the bitmap DPI in calculating page dimensions when saving a PDF file.
ESO_PAD4 [0x00400000] Pads each line to a multiple of 4 bytes. (raw data only).
ESO_PLT_BEZIER_CURVES [0x00800000] PLT filter should save bezier curves.
ESO_PDF_SAVE_USE_BITMAP_DPI [0x01000000] Uses bitmap DPI in calculating page dimensions when saving a PDF file.
ESO_PHOTOMETRICINTERPRETATIONVALID [0x02000000] Uses PhotometricInterpretation when saving TIFF files.
ESO_TILEINFOVALID [0x04000000] Uses the TileWidth and TileHeight members when saving TIFF files.
ESO_USEDITHERINGMETHOD [0x08000000] Uses the DitheringMethod in the BITMAPHANDLE.
ESO_PRESERVEPALETTE [0x10000000] Preserves the palette when saving TIFF CCITT files (might decrease the compression ratio).
ESO_PDF_SAVE_LOW_MEMORY_USAGE [0x20000000] Tries to use less memory when creating a PDF file with JPEG or Fax compression.
ESO_GENERATEGLOBALPALETTE [0x40000000] Generates a global palette when saving GIF files.
ESO_USEPREDICTOR [0x80000000] Uses a predictor when saving LZW data. This is for TIF LZW or Raw LZW data that is 8 bpp or more. This flag is ignored if the LZW data is less than 8 bpp.

Passes

The number of passes (scans through the image) when saving a JPEG or LEAD CMP file. (This value is not used when saving interlaced PNG files.)

Possible Values When Saving

Value Meaning
Any positive number Saves the file as a progressive file with the specified number of passes.
0 Saves the file as an ordinary JPEG or LEAD CMP file (not a progressive file).
Any negative number Saves the file as a progressive file with the LEADTOOLS default number of passes.

Possible Values When Saving Non-progressive Files

Value Meaning
0 Saves the file with fixed Huffman tables (faster save, lower compression).
<>0 Saves the file with optimized Huffman tables (2-pass compression, lower speed, higher compression).

PageNumber

The page number of a multipage file, which can contain more than one image. When saving a file, any value greater than 1 will cause the page to be appended to the end of the file. For more information on multipage files, refer to Multipage File Formats.

GlobalWidth

Width of animation in an animated GIF or WebP file.

GlobalHeight

Height of animation in an animated GIF or WebP file.

GlobalLoop

Loop count when playing an animation. Use 0 for continuous looping. For no looping, turn off the ESO_GLOBALLOOP flag in the Flags field.

GlobalBackground

Background color of animation in an animated GIF or WebP file. This field is used only if the ESO_GLOBALBACKGROUND flag is set in the Flags field. Specify a COLORREF value, such as the return value of the Windows RGB macro, or use the PALETTEINDEX macro to specify a palette color.

GlobalPalette

Palette for images in an animated GIF file. This field is used only if the ESO_GLOBALPALETTE flag is set in the Flags field.

StampWidth

Width, in pixels, of the stamp image to save. A stamp is saved only if the ESO_SAVEWITHSTAMP flag is set in the Flags field.

StampHeight

Height, in pixels, of the stamp image to save. A stamp is saved only if the ESO_SAVEWITHSTAMP flag is set in the Flags field.

StampBits

Bits per pixel of the stamp image to save. A stamp is saved only if the ESO_SAVEWITHSTAMP flag is set in the Flags field.

IFD

Offset within a TIFF file where a page starts. This serves as a reference page for saving pages to a large TIFF file. According to TIFF specifications, the minimum value for the first IFD is 8.

szPassword

Password for saving encrypted files.

PhotometricInterpretation

(TIFF only) Photometric interpretation that should be saved in the file instead of the regular value. Used only if ESO_PHOTOMETRICINTERPRETATIONVALID is set.

TileWidth

Width of the tile to use when saving TIFF files. This value is in pixels. Used only if ESO_TILEINFOVALID is set. This value might be modified slightly if necessary. See the notes below for mode details.

TileHeight

Height of the tile to use when saving TIFF files. This value is in pixels. Used only if ESO_TILEINFOVALID is set. This value might be modified slightly if necessary. See the notes below for mode details.

Flags2

Any of the following flags (Use a bitwise OR to specify more than one value.) Also see the Flags member for additional flags.

Value Meaning
ESO2_NITF [0x00000001] Saves files compatible with NITF requirements. This flag is used internally.
ESO2_SAVEPLANAR [0x00000002] Saves the TIF CMYK images as planar (instead of chunky).
ESO2_NOLZWAUTOCLEAR [0x00000004] Do not automatically insert CLEAR codes during LZW compression.
ESO2_ALPHAINIT [0x00000010] Initializes the alpha channel for 32 or 64-bit color images) to all ones (0xFF for 8-bit alpha channels and 0xFFFF for 16-bit alpha channels). Without this flag, a created alpha channel initializes to zeros.
ESO2_XPS_SAVE_USE_BITMAP_DPI [0x00000080] Uses the bitmap DPI in calculating page dimensions when saving a XPS file.
ESO2_PDFA_PROFILE [0x00000100] When saving as PDF, saves PDF files as PDF/A format.
ESO2_PDF_V13 [0x00004000] When saving as PDF, saves PDF files as PDF v1.3.
ESO2_PDF_V14 [0x00000200] When saving as PDF, saves PDF files as PDF v1.4.
ESO2_PDF_V15 [0x00000400] When saving as PDF, saves PDF files as PDF v1.5.
ESO2_PDF_V16 [0x00002000] When saving as PDF, saves PDF files as PDF v1.6.
ESO2_PDF_V17 [0x00008000] When saving as PDF, saves PDF files as PDF v1.7.
ESO2_ENDWITH3EOL [0x00000800] Ends Fax G3 (1D/2D) files with 3 EOLs (00 01 00 01 00 01) instead of EOL EOFB (00 01 00 10 01).
ESO2_OPTIMIZEDHUFFMAN [0x00001000] Saves JPEG files with optimized Huffman tables.
ESO2_NOGRAYCONVERT [0x00010000] Avoid automatic conversion when saving 12/16 bit grayscale data as JPX or JPEG-LS. In this case you have to handle saving or restoring LowBit, HighBit, and/or the LUT through other means.
ESO2_BIGTIFF [0x00020000] Saves TIFF files using the BigTiff format, which allows TIFF files to exceed 4GB.
ESO2_PDF_LINEARIZED [0x00080000] Saves linearized PDF files (web-optimized).
ESO2_ADJUST_STAMP_SIZE [0x0x00100000] If set, the stamp width and height is adjusted so it fits inside the StampWidth x StampHeight rectangle. If not set, the stamp size is exactly StampWidth x StampHeight.

Comments

pSAVEFILEOPTION is a pointer to a SAVEFILEOPTION structure. Where the function parameter type is pSAVEFILEOPTION, declare an SAVEFILEOPTION variable, update the structure's fields, and pass the variable's address in the parameter. Declaring a pSAVEFILEOPTION variable is necessary only if the program requires a pointer.

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 multipage 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 returns an error (ERROR_INVALID_STAMP_SIZE) if any of these size limitations gets exceeded.

When 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:

To load a stamp image, use the L_ReadFileStamp function.

Notes:

By default, the ESO_NOPAGENUMBER is not set. Therefore, all TIFF files are 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 to 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 L_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 usually take 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, it is possible to gain some speed by disabling this functionality.

If ESO_NOPAGENUMBER is set, then L_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 L_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 L_SaveFileOffset 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 it was 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 to be a multiple of 8 or 16 depending on the subsampling chosen. For such files, specifying 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.

IFD Offsets

For technical reasons, the following restrictions apply when passing an IFD offset by setting the IFD member of the SAVEFILEOPTION structure and the PageNumber is set to 1:

  1. It is not possible to add tags, comments or GeoKeys to this IFD. It is possible to update existing tags, comments, or GeoKeys in this IFD.
  2. It is not possible to replace the TIFF page indicated by this IFD.
  3. It is not possible to add a page before the this IFD.
  4. It is not possible to delete the page indicated by this IFD.

It is possible, however, to add tags, comments or GeoKeys to an IFD that follows the specified IFD (for example, if PageNumber is >= 2). It is also possible to replace or delete a page that follows the specified IFD, and insert a page after this IFD.

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 when using 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, it is only possible to 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 L_FileInfo function and check whether the FILEINFO_BIGTIFF flag is set in FILEINFO.Flags.

Usage

Help Version 22.0.2023.7.11
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS Raster Imaging C API Help

Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.