miBoolean mi_img_create(
miImg_file *ifp,
char *name,
miImg_type type,
miImg_format format,
int width,
int height)
To create a file, a name, data type, and file format must be specified. type determines the internal scanline data type (c[ ] or s[ ], see mi_img_alloc) that the caller will use when it calls mi_img_write. type must be one of the internal types; see OPEN in the next paragraph ( miIMG_TYPE_ANY is not allowed though). format determines the type of the file. If both are different, the data will be converted. When creating a file that supports multiple data types by default the best_type will be used. To request a different data type the ftype member of the miImg_file structure must be set. The field will be further used in the reading functions of IMG (see below).
No file name extensions are removed or added. width and height determine the size of the image. left, right, bottom, and top are copied to the file header if the file format supports it, and are ignored otherwise. If mi_img_create succeeds (returns miTRUE), mi_img_close must be called after all scanlines have been written. Null files can be created and written to, but no data will appear in the file, and it will be removed when closed. Note that the memory location to which ifp points should be zeroed before calling this function; the fields filter and magic are examined by this function, so correct initialization of them is mandatory.
miBoolean mi_img_open(
miImg_file *ifp,
char *name,
miImg_type type)
For opening a file, a name and preferred type must be specified. the type must be one of the supported internal data formats. These types specify both the requested internal scanline data type (8/16/32 bits and the number of components), and the type of conversion if applicable. For example, miIMG_TYPE_A and miIMG_TYPE_S act the same if the file is a scalar texture, but if the file is a color file with alpha, miIMG_TYPE_A takes the alpha and miIMG_TYPE_S takes the RGB intensity.
The conversion routines try to do the most reasonable thing; miIMG_TYPE_A will use the RGB intensity of a color file if there is no alpha available. The conversion of vector texture files to an internal format other than miIMG_TYPE_VTA and miIMG_TYPE_VTS (which require no conversion) is dubious, it is done in a way that is not very useful except for image display programs. The same is true for conversions of tag channels and normal vector maps to RGB or S. If the actual data type found in the file is different from the type requested then the ftype member of the miImg_file structure is set to type + miIMG_NTYPES.
This can be used to check what data type really was supplied in the file. This field will be further used in the writing functions. If miIMG_TYPE_ANY is requested, ifp->format can be accessed to determine the type of the file; it will be one of miIMG_FORMAT_* (see mi_img_create above). ifp->type will contain the suggested miIMG_TYPE_*. Note that the memory location to which ifp points should be zeroed before calling this function; the field magic is examined by this function, so correct initialization is mandatory. It is however correct to use the ifp initialized by mi_img_create continue to use ifp after mi_img_close.
miBoolean mi_img_close(
miImg_file *ifp)
After a file has been opened successfully, it must be closed to release allocated memory and file descriptors. It is safe to use mi_img_close on an miImg_file structure for which the open or create failed, but it is not required. If the file has type miIMG_FORMAT_NULL, it will be deleted.
miBoolean mi_img_image_read(
miImg_file *ifp,
miImg_image *image)
miBoolean mi_img_image_write(
miImg_file *ifp,
miImg_image *image)
These calls are similar to the scanline rading and writing routines, but return an entire image. They cannot be mixed with scanline reads or writes. The image module always stores the bottom line as the first scanline in the image data structure.
void mi_img_image_release(
miImg_image *image)
Release an image pointer created with mi_img_mmap_address or mi_img_image_alloc.
miImg_type mi_img_type_identify(
char *typename)
Look up the alphanumeric data type, and return the corresponding miIMG_TYPE_* code. If the alphanumeric type is unknown, return miIMG_TYPE_ERROR. The alphanumeric type must be all-lowercase.
miImg_format mi_img_format_identify(
char *formatname)
Look up the alphanumeric file format, and return the corresponding miIMG_FORMAT_* code. If the alphanumeric file format is unknown, return miIMG_FORMAT_ERROR. Upper and lower case is significant; "Zpic" must be spelled with a capital Z.
miImg_type mi_img_best_type(
miImg_format format)
Returns the preferred data type for the file format. The file can be read or written without conversion if the scanline buffer has this type. The type returned is equal to the type chosen by mi_img_create if called with miIMG_TYPE_ANY. mi_img_best_type is useful if scanlines or images need to be allocated before the file is actually created.
char *mi_img_type_name(
miImg_type type)
Returns the name of the specifies data type as a string. This is the reverse operation to mi_img_type_identify.
char *mi_img_format_name(
miImg_format format)
Returns the name of the specifies file format as a string. This is the reverse operation to mi_img_format_identify.
miImg_image *mi_img_image_alloc(
miImg_file *ifp)
This function allocates a large buffer that contains enough
scanlines for the entire image specified by the ifp
argument. To release an image allocated with
mi_img_image_alloc, use
mi_img_release on the pointer returned by
mi_img_image_alloc. The allocated
image is zeroed. In order to call this function, ifp need not
reference an open file, but ifp→type,
ifp→width, and ifp→height must
be defined. If the file is not open, all others must be set to 0;
except for ifp→name which may contain something
descriptive. If ifp→filter is set to miTRUE, this
function allocates an image pyramid structure which makes
elliptical filtering faster.
miImg_image *mi_img_access(
miImg_image *image,
int y,
int comp,
Returns a pointer to a component scanline of an image.
This call replaces the deprecated macros to access an image.
void mi_img_err_handler(
void (*cb)(miImg_file *ifp)
Install an error handler that is called by mi_img_err_msg after printing the error message. The callback has the option of exiting the program with a fatal error message, or returning to proceed with the program. Not installing an error handler always proceeds. This can be used to make the inability to find a texture file or to write an output image a fatal error for standalone processes but not for embedded library versions that must not kill their client application. If mi_img_err_msg is called and no error condition exists, the callback is not called. The callback may use ifp to exit only for some error codes. This call is typically used during library initialization, before mi_mem_init and mi_raylib_init.
void mi_img_debug(
int level)
Turn on debugging by setting the img_debug variable. This call is intended to be used in a debugger, or set by a command-line front-end or an environment variable or something similar. See below.
Copyright © 1986, 2015 NVIDIA ARC GmbH. All rights reserved.