SAVEFILEOPTION

typedef struct _SAVEFILEOPTION
{
   L_UINT uStructSize;
   L_UINT Flags;
   L_INT Passes;
   L_INT PageNumber;
   L_INT GlobalWidth;
   L_INT GlobalHeight;
   L_UINT GlobalLoop;
   COLORREF GlobalBackground;
   RGBQUAD GlobalPalette[256];
   L_UINT StampWidth;
   L_UINT StampHeight;
   L_UINT StampBits;
   L_BOOL Constrained;
   L_BOOL FieldPic;
   L_INT FrameRate;
   L_INT FramesGOP;
   L_INT PelAspectRatio;
   L_INT ProfileID;
   L_INT LevelID;
   L_INT ChromaFormat;
   L_INT VideoFormat;
   L_INT IntraDcPrec;
   L_INT32 BitRate;
   L_UCHAR UserInfo[255];
   L_UINT32 IFD;
   L_TCHAR szPassword[255];
   L_TCHAR szPassword[255];
   PHOTMTRICINTERP PhotometricInterpretation;
   L_UINT TileWidth;
   L_UINT TileHeight;
   L_UINT Flags2;
} SAVEFILEOPTION, L_FAR * pSAVEFILEOPTION;

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

The following functions make use of this structure:

L_FileConvert

L_CompressBitmapWithStamp

L_DeletePage

L_WriteFileTransforms

L_SaveBitmap

L_SaveBitmapList

L_SaveBitmapMemory

L_SaveBitmapWithLayers

L_StartCompressBuffer

L_WriteFileCommentExt

L_WriteFileStamp

L_MrcSaveBitmap

L_MrcSaveBitmapT44

See L_GetDefaultSaveFileOption for information on default save options.

Member	Description
uStructSize	Size of the SAVEFILEOPTION structure. This should be sizeof(SAVEFILEOPTION). You must fill this member.
Flags	Any of the following flags. (You can 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 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 loading 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] Replace the page specified by PageNumber.
	ESO_INSERTPAGE	[0x00000800] Insert the new page before the page specified by PageNumber.
	ESO_JPEGSTAMP	[0x00001000] Save JPEG compressed stamps.
	ESO_DISABLEMMX	[0x00002000] Do not use MMX optimized code
	ESO_SAVEOLDJTIF	[0x00004000] Write old style JTIF files
	ESO_NOPAGENUMBER	[0x00008000] Do not update and save the PageNumber tag associated with the pages of a multi-page TIFF file.
	ESO_DISABLEP3	[0x00010000] Do not use P3-specific optimized code.
	ESO_USEIFD	[0x00020000] Use the IFD offset.
	ESO_MOTOROLAORDER	[0x00040000] Save files in Motorola byte order when possible.
	ESO_WITHOUTTIMESTAMP	[0x00080000] Save 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] Use the bitmap DPI in calculating page dimensions when saving a PDF file.
	ESO_PAD4	[0x00400000] Each line is padded 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] Use bitmap DPI in calculating page dimensions when saving a PDF file.
	ESO_PHOTOMETRICINTERPRETATIONVALID	[0x02000000] Use PhotometricInterpretation when saving TIFF files.
	ESO_TILEINFOVALID	[0x04000000] Use the TileWidth and TileHeight members when saving TIFF files.
	ESO_USEDITHERINGMETHOD	[0x08000000] Use the DitheringMethod in the BITMAPHANDLE.
	ESO_PRESERVEPALETTE	[0x10000000] Preserve the palette when saving TIFF CCITT files (might decrease the compression ratio)
	ESO_PDF_SAVE_LOW_MEMORY_USAGE	[0x20000000] Try to use less memory when creating a PDF file with JPEG or Fax compression.
	ESO_USEPREDICTOR	[0x80000000] Use 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	Save the file as a progressive file with the specified number of passes.
	0	Save the file as an ordinary JPEG or LEAD CMP file (not a progressive file).
	Any negative number	Save the file as a progressive file with the LEADTOOLS default number of passes.
	Possible values when saving non-progressive files:
	Value	Meaning
	0	Save the file with fixed Huffman tables (faster save, lower compression).
	<>0	Save the file with optimized Huffman tables (2-pass compression, lower speed, higher compression)

PageNumber	The page number of a multi-page 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 multi-page files refer to Multipage File Formats.
GlobalWidth	Width of images in a multi-page GIF file.
GlobalHeight	Height of images in a multi-page GIF 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 images in a multi-page GIF file. This field is used only if the ESO_GLOBALBACKGROUND flag is set in the Flags field. You can specify a COLORREF value, such as the return value of the Windows RGB macro, or you can use the PALETTEINDEX macro to specify a palette color.
GlobalPalette	Palette for images in a multi-page 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.
Constrained	Flag that indicates whether the video corresponds to set standards. (This member can only be set using the LEADTOOLS Multimedia Imaging or LEADTOOLS Multimedia Imaging Pro toolkits.) This member is valid only for MPEG-1 files. Possible values are:
	Value	Meaning
	TRUE	The video corresponds to set standards.
	FALSE	The video does not correspond to set standards.
FieldPic	Flag that indicates whether to use field or frame pictures. This member is valid only for MPEG-1 files. (This member can only be set using the LEADTOOLS Multimedia Imaging or LEADTOOLS Multimedia Imaging Pro toolkits.) Possible values are:
	Value	Meaning
	TRUE	Use field pictures.
	FALSE	Use frame pictures.

FrameRate	The frame rate code. (This member can only be set using the LEADTOOLS Multimedia Imaging or LEADTOOLS Multimedia Imaging Pro toolkits.) Possible values are:
	Value	Meaning
	MPEG_FRAMERATE_23	[1] 23.976
	MPEG_FRAMERATE_24	[2] 24
	MPEG_FRAMERATE_25	[3] 25
	MPEG_FRAMERATE_29	[4] 29.97
	MPEG_FRAMERATE_30	[5] 30
	Note: If you are converting an existing AVI file, you can pass –1 to use the current frame rate. The frames per second of the file must be 10, 12, 15, 23.976, 24, 25, 29.97, or 30.
FramesGOP	Number of frames in a group of pictures. (This member can only be set using the LEADTOOLS Multimedia Imaging or LEADTOOLS Multimedia Imaging Pro toolkits.)
PelAspectRatio	The ratio of the nominal vertical height of pel on the display to its nominal vertical width. (This member can only be set using the LEADTOOLS Multimedia Imaging or LEADTOOLS Multimedia Imaging Pro toolkits.) Possible values are:
	Value	Meaning
	MPEG_ASPECT_SQUARE	[1] Square pel
	MPEG_ASPECT_4_3	[2] 4:3
	MPEG_ASPECT_16_9	[3] 16:9
	MPEG_ASPECT_2_1	[4] 2.11:1
	MPEG_ASPECT_625	[8] CCIR601 625 Line
	MPEG_ASPECT_525	[9] CCIR601 525 Line
ProfileID	Profile. (Simple, Main, SNR, Spatial. SNR not currently supported). (This member can only be set using the LEADTOOLS Multimedia Imaging or LEADTOOLS Multimedia Imaging Pro toolkits.) Possible values are:
	Value	Meaning
	MPEG_PROFILE_SIMPLE	5
	MPEG_PROFILE_MAIN	4
	MPEG_PROFILE_SNR	3
	MPEG_PROFILE_SPATIAL	2
	MPEG_PROFILE_HIGH	1
LevelID	Level. (This member can only be set using the LEADTOOLS Multimedia Imaging or LEADTOOLS Multimedia Imaging Pro toolkits.) Possible values are:
	Value	Meaning
	MPEG_LEVEL_LOW	[10] Low
	MPEG_LEVEL_MAIN	[8] Main
	MPEG_LEVEL_HIGH14440	[6] High 14440
	MPEG_LEVEL_HIGH	[4] High
ChromaFormat	Chroma format. (This member can only be set using the LEADTOOLS Multimedia Imaging or LEADTOOLS Multimedia Imaging Pro toolkits.) Possible values are:
	Value	Meaning
	PEG_CHROMA_420	[1] 4:2:0
	PEG_CHROMA_422	[2] 4:2:2
	PEG_CHROMA_444	[3] 4:4:4
VideoFormat	The video format. (This member can only be set using the LEADTOOLS Multimedia Imaging or LEADTOOLS Multimedia Imaging Pro toolkits.) Possible values are:
	Value	Meaning
	MPEG_VIDEO_COMP	[0] Component.
	MPEG_VIDEO_PAL	[1] PAL
	MPEG_VIDEO_NTSC	[2] NTSC
	MPEG_VIDEO_SECAM	[3] SECAM
	MPEG_VIDEO_MAC	[4] MAC
	MPEG_VIDEO_UNSP	[5] Unspecified
IntraDcPrec	DC coefficient precision for intra coded blocks. (This member can only be set using the LEADTOOLS Multimedia Imaging or LEADTOOLS Multimedia Imaging Pro toolkits.) Possible values are:
	Value	Meaning
	MPEG_INTRA_8	[0] 8 bit
	MPEG_INTRA_9	[1] 9 bit
	MPEG_INTRA_10	[2] 10 bit
	MPEG_INTRA_11	[3] 11 bit
BitRate	Rate at which the compressed bitstream is delivered from the storage medium to the input of a decoder. The value is in bits per second. (This member can only be set using the LEADTOOLS Multimedia Imaging or LEADTOOLS Multimedia Imaging Pro toolkits.)
UserInfo[255]	User defined data to be put in an mpeg stream. (This member can only be set using the LEADTOOLS Multimedia Imaging or LEADTOOLS Multimedia Imaging Pro toolkits.)
IFD	Offset within a TIFF file where a page starts. This serves as a reference page for saving pages to a large TIFF file.
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.
TileHeight	Height of the tile to use when saving TIFF files. This value is in pixels.
Flags2	Any of the following flags (You can 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] Save the TIF CMYK images as planar (instead of chunky)
	ESO2_NOLZWAUTOCLEAR	[0x00000004] Do not automatically insert CLEAR codes during LZW compression.
	ESO2_ALPHAINIT	[0x00000010] Initialize 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.

Comments

pSAVEFILEOPTION is a pointer to an SAVEFILEOPTION structure. Where the function parameter type is pSAVEFILEOPTION, you can 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 your 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 Formats of Output Files.

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:

$image\sqrblit.gif$ If you save an 8-bit stamp, the following calculation cannot exceed 65,535:

(width * height) + 778.

$image\sqrblit.gif$ If you save a 24-bit stamp, the following calculation cannot exceed 65,535:

(width * height * 3) + 10.

The save function will return an error (ERROR_INV_RANGE) if you exceed any of these size limitations.

To load a stamp image, you must use the L_GetCompressFileStamp function.

Note: If SAVEFILE_MULTIPAGE is passed to L_SaveFile, it will take precedence over ESO_REPLACEPAGE or ESO_INSERTPAGE.

Note: 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.

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 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 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 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.

Note:

For more information about loading and saving large TIFF files faster, refer to Loading and Saving Large TIFF 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.

Note: Take care when you use the Flags and Flags2 members to not 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.