FILEINFO

Summary

The FILEINFO structure, which is loaded by calling the L_FileInfo function, provides information about the specified file.

Syntax

typedef struct _FILEINFO 
{ 
   L_UINT uStructSize;           // use sizeof(FILEINFO) 
   L_INT Format;                 // File format: FILE_PCX, ... 
   L_TCHAR Name[_MAX_FNAME+_MAX_EXT];// File name, including the Extension 
   L_INT Width;                  // Image width 
   L_INT Height;                 // Image height 
   L_INT BitsPerPixel;           // Bits per pixel 
   L_SSIZE_T SizeDisk;           // Size of file on disk 
   L_SSIZE_T SizeMem;           // Size of image in memory 
   L_TCHAR Compression[20];      // Compression method name 
   L_INT ViewPerspective;        // Image view perspective 
   L_INT Order;                  // RGB order 
   L_INT PageNumber;             // Page number 
   L_INT TotalPages;             // Total number of pages present in the file 
   L_INT XResolution;           // Resolution along the X axis, in dpi. 
   L_INT YResolution;           // Resolution along the Y axis, in dpi. 
   L_UINT Flags;                // Identifies file subtypes: progressive, interlaced 
   L_UINT GlobalLoop;           // Global animation loop count 0 = infinity 
   L_INT GlobalWidth;           // Global width, in pixels 
   L_INT GlobalHeight;           // Global height, in pixels 
   L_COLORREF GlobalBackground;  // Global background color (see Flags) 
   L_RGBQUAD GlobalPalette[256]; // Global palette (see Flags) 
   L_SIZE_T IFD;                 // IFD offset (for TIF files only) 
   L_INT Layers;                // The number of layers in the file 
   L_INT ColorSpace;            // The colorspace (RGB, CMYK, CIELAB, etc) 
   L_INT Channels;               // The number of channels in the file 
   L_BOOL bIsDocFile;           // Specifies whether the file is a DOC file 
   L_DOUBLE dDocPageWidth;       // (Only valid for DOC files), the width in uDocUnit 
   L_DOUBLE dDocPageHeight;      // (Only valid for DOC files), the height in uDocUnit 
   RASTERIZEDOC_UNIT uDocUnit;   // (Only valid for DOC files), the unit of measure to be used for the width and height 
   L_BOOL bIsVectorFile;         // Value that indicates whether the file is a vector file 
   VECTORPARALLELOGRAM VectorParallelogram;     // Bounding parallelogram for the vector 
   L_INT MessageCount; // Total number of messages (for PST files only) 
   L_INT nHorzTiles; // Number of horizontal tiles. 
   L_INT nVertTiles; // Number of vertical tiles. 
   L_VOID *pFilterData; // Filter data. 
   L_SIZE_T uFilterDataSize; // Size of the filter data. 
   L_INT nFilter; // Which filter allocated the filter data. 
   L_INT nAttachmentCount; // The number of attachments in this file. 
} FILEINFO, *pFILEINFO; 

Members

uStructSize

Size of this structure, in bytes (for versioning). Use the sizeof() operator to calculate this value.

Format

File format. For possible values, refer to Summary of All Supported Image File Formats.

Name

A character array containing the null-terminated string that is the filename. The name is truncated if it exceeds _MAX_FNAME + _MAX_EXT characters.

Width

Image width, in pixels.

Height

Image height, in pixels.

BitsPerPixel

Bits per pixel.

SizeDisk

Size of the file on disk (in bytes).

SizeMem

Amount of memory (in bytes) required to load the file.

Compression

A 20-character array containing the null-terminated string that describes the compression method.

ViewPerspective

Where the beginning of the image is stored. The following values are valid:

For descriptions, refer to Accounting for View Perspective.

Order

Color order of the bitmap. This field is meaningful if the image does not have a palette. It indicates whether the color values are in red-green-blue or blue-green-red order. The following values are valid:

PageNumber

The page number in a multipage file.

To determine the total number of pages in a file, call L_FileInfo with uFlags set to FILEINFO_TOTALPAGES.

TotalPages

The total number of pages present in a file.

To update this field, call L_FileInfo with uFlags set to FILEINFO_TOTALPAGES.

If you do not want this field updated, call L_FileInfo with uFlags set to 0.

XResolution

Horizontal resolution, in dots per inch. Some file formats save this value in the file header.

YResolution

Vertical resolution, in dots per inch. Some file formats save this value in the file header.

Flags

File characteristics. For possible values, refer to FILEINFO Flags.

GlobalLoop

Global animation loop count. 0 = infinity. This field is valid only if the FILEINFO_HAS_GLOBALLOOP flag is set.

GlobalWidth

Global width for animation playback

GlobalHeight

Global height for animation playback

GlobalBackground

Global background color for animation playback (FILEINFO Flags)

GlobalPalette[256]

Global palette for animation playback (FILEINFO Flags).

IFD

Offset within a TIFF file where a page starts. This member is updated when L_FileInfo is called.

Layers

The number of layers the PSD file contains (only PSD files can have layers). Layers is 0 if the file is not a PSD file, or if the file is a PSD file but does not have any layers.

ColorSpace

Color space of the file. The possible values are:

Value Meaning
COLORSPACE_BGR [0] RGB or BGR
COLORSPACE_YUV [1] YUV or YCbCr
COLORSPACE_CMYK [2] CMYK
COLORSPACE_CIELAB [3] CIELab

Channels

The number of channels the PSD file contains (only PSD files can have channels). If this value is 0, then the file does not contain channels.

bIsDocFile

TRUE if the image file or stream is a document format, FALSE otherwise.

When the value of this member is TRUE, then the image file or stream passed to the L_FileInfo is a document file such as PDF or XPS and dDocPageWidth, dDocPageHeight and uDocUnit will contain the original document logical size. The physical load (rasterization size) is calculated based on the current rasterization values and is stored in Width, Height, XResolution and YResolution.

When the value of this member is FALSE, then the image file or stream is a raster image such as JPEG or TIFF. These files have physical size so dDocPageWidth, dDocPageHeight and uDocUnit should not be used.

dDocPageWidth

The logical width of the document. This value is in uDocUnit.

The logical width and height of the document is the original size before rasterization. LEADTOOLS usually returns the logical size in inches.

Use dDocPageWidth only if the value of bIsDocFile is TRUE.

dDocPageHeight

The logical height of the document. This value is in uDocUnit.

The logical width and height of the document is the original size before rasterization. LEADTOOLS usually returns the logical size in inches.

Use dDocPageHeight only if the value of bIsDocFile is TRUE.

uDocUnit

The unit for dDocPageWidth and dDocPageHeight. Valid values are as follows:

Value Meaning
RASTERIZEDOC_UNIT_PIXEL [0] Page width and height measurements are in pixels.
RASTERIZEDOC_UNIT_INCH [1] Page width and height measurements are in inches.
RASTERIZEDOC_UNIT_MILLIMETER [2] Page width and height measurements are in millimeters.

bIsVectorFile

TRUE if the image file or stream is a vector format, FALSE otherwise.

VectorParallelogram

Parallelogram structure that contains the bounding parallelogram for the vector. Only valid when loading vector files and the value of bIsVectorFile is TRUE.

When loading vector files such as DXF and DWG, the parallelogram values retrieved by L_FileInfo and set in FILEINFO may not always be correct because the values depend on the file's saved data. L_FileInfo does not load file objects but reads the file dimensions which may not be saved within the file.

MessageCount

Total number of messages (for PST files only).

nHorzTiles

Number of horizontal tiles.

nVertTiles

Number of vertical tiles.

pFilterData

A pointer to a filter data structure used to speed up loading. pFilterData is valid only if the FILEINFO_USEFILTERDATA flag was passed to L_FileInfo. If not NULL, pass the data through the LOADFILEOPTION structure and free it by calling L_FreeFilterData when it is no longer needed.

See the Using Filter Data to Speed up Loading Large Files topic for more information.

uFilterDataSize

Size of the filter data. Returned only if the FILEINFO_USEFILTERDATA flag was passed to L_FileInfo.

If 0, it is possible that the filter data contains handles or pointers that are valid only in the current process. Also, if 0, the filter data can be used only in one thread at a time. Currently, this is the case for most filters.

If not 0, the filter data is flat and can be saved to disk and reloaded later.

See the Using Filter Data to Speed up Loading Large Files topic for more information.

nFilter

The filter that allocated the filter data. Returned only if the FILEINFO_USEFILTERDATA flag was passed to L_FileInfo.

See the Using Filter Data to Speed up Loading Large Files topic for more information.

nAttachmentCount

Number of attachments in this file if this file has any; otherwise, 0.

Comments

Notes:

pFILEINFO is a pointer to a FILEINFO structure. Where the function parameter type is pFILEINFO, you can declare a FILEINFO variable, update the structure's fields, and pass the variable's address in the parameter. Declaring a pFILEINFO variable is necessary only if your program requires a pointer.

Some functions which take this structure as a parameter require that the structure must be initialized prior to the function call. You must set the uStructSize member to the total size, in bytes, of the structure. Use the sizeof() operator to calculate this value. Functions that do not require the structure to be initialized will take the total size of the structure, in bytes, as an additional function parameter.

Multipage files can be loaded more quickly using two mechanisms, as follows:

  1. TIFF files can use the IFD (offset of each page). For more information about loading and saving large TIFF files more quickly, refer to Loading and Saving Large TIFF/BigTIFF Files.

  2. Files other than TIFF files can use a filter data mechanism. Retrieve the filter data by calling L_FileInfo with the FILEINFO_USEFILTERDATA flag. If the filter supports this mechanism, the filter data is returned by filling the pFilterData, uFilterDataSize and nFilter members of the FILEINFO structure. You then pass the filter data through LOADFILEOPTION structures to the load or convert functions and then free them with L_FreeFilterData when they are not needed anymore. See the Using Filter Data to Speed up Loading Large Files topic for more information.

Note that if Format is FILE_JPEG or FILE_TIF_JPEG and BitsPerPixel is 8, then the image uses the 4:0:0 color space, not the 4:4:4 color space.

Currently only PSD files support layers.

Attachments

LEADTOOLS has attachment support for the following file formats:

Therefore, nAttachmentCount will contain a valid value only if the file is one of the formats listed above.

PDF files can be created as a portfolio which contains multiple files assembled into an integrated unit. In these types of documents, the file contains a single generic help page with text such as "For the best experience, open this PDF portfolio in a compatible viewer" and any number of attachments and a schema to control how to view the document. Flags will contain FILEINFO_PORTFOLIO if the file is a PDF portfolio and it is up to the application to determine how to further handle the file. See PDF Portfolio for more information.

Usage

Data Types

Functions

Help Version 23.0.2024.2.29
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2024 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.