Custom Image Formats

New user-defined image file formats can be registered by defining a number of functions, and specifying some information about the format. There are 16 slots for user-defined file formats. They can be defined with:

mi_img_custom_format
miBoolean mi_img_custom_format(
    miImg_format    format,
    miBoolean       (*test)  (miImg\_file * const, char * const),
    miBoolean       (*create)(miImg\_file * const),
    miBoolean       (*open)  (miImg\_file * const, char * const),
    miBoolean       (*close) (miImg\_file * const),
    miBoolean       (*read)  (miImg\_file * const, miImg\_line * const),
    miBoolean       (*write) (miImg\_file * const, miImg\_line * const),
    miBoolean       tdown,
    char            *name,
    miUint          tmap,
    int             btype,
    int             flags)

This function registers the new format format, which must be one of the enumeration tags in the range miIMG_FORMAT_CUSTOM_0 through miIMG_FORMAT_CUSTOM_15. It may not be called before raylib is initialized. Six C functions must be passed. All of them return miFALSE on failure and miTRUE on success.

test
is given the first 256 bytes of an open file to be read. It must return miTRUE if the file has a type understood by the read function, and miFALSE otherwise. This is typically done by checking magic numbers at the beginning of the file, or by verifying whether the information in the file header makes sense. If the file cannot be identified with confidence, miFALSE must be returned. It may not call any error functions because failure is not an exceptional event. The custom formats are tested early, which means that they can be used to override a built-in format. It also means that the test function should be careful not to incorrectly return miTRUE.
create
begin a new file. The file has already been created empty on disk. Typically this function writes the file header, and allocates whatever variables or scanline buffers are required during scanline writing later.
open
begin reading a file. The file has already been opened and rewound to file position 0. Typically this function reads the entire file header, identifies the subtype (for example, if both RGB and RGBA variants are supported), and fails if it is not supported), and allocates variables or scanline buffers for reading with the read function later. The first 256 bytes of the file are passed as the second argument like for test. The width, height, comp, and bits fields of the miImg_file structure passed as the first argument must be set by this function.
close
stop reading or writing the file. Normally this is the place to release all data allocated by the create or open calls. It may also rewind and modify the file header if required. The file should not be closed; this is done by mental ray.
read
read a single scanline into the scanline buffer passed as the second argument. Pointers to the component scanlines can be retrieved with the (deprecated) miIMG_LINEACCESS macro.
write
write a single scanline from the scanline buffer passed as the second argument. Pointers to the component scanlines can be retrieved with the (deprecated) miIMG_LINEACCESS macro.

All functions may use the data field (a void pointer) of the miImg_file structure passed as the first argument to attach local data, such as scanline buffers or other format-specific data. If used, mi_mem_allocate should be used in the open and create functions to allocate a buffer, and mi_mem_release should be used in the close function to delete it. It is not a good idea to let data point to static storage because these functions must be reentrant. All functions except test (which fails silently) may use mi_img_custom_format_error to report errors.

Finally, the tdown argument should be miTRUE if the file is stored with the top scanline first, or miFALSE otherwise. The name is the name of the format, which is also the name of the extension. For example, jpg is a good name. The function imposes no restrictions, but it is a good idea to keep the name short (typically three or four characters), and to use only lowercase letters and, if necessary, digits. Do not begin with a dot, and do not use a name already supported by mental ray. The tmap is a bitmap of allowed data types, and should be set to the logical-OR or expressions like 1<<miIMG_TYPE_RGB. The btype argument must be set to the best type for the format. For example, miIMG_TYPE_RGB is the best type for JPEG/JFIF files. This type is automatically added to the tmap bitmap (effectively it performs tmap |= 1<< btype). The flags argument is reserved for future extensions and must be set to 0.

mi_img_custom_format_err
miBoolean mi_img_custom_format_error(
    miImg_file      *ifp,
    miImg_error     error,
    int             os_error)

This function should be used only by one of the six functions installed with mi_img_custom_format. It saves an error code for later printing. If a file is being written, it is deleted on disk to prevent partial files. After calling this function, the caller will normally return miFALSE without further processing. The ifp is the same that the caller got as its first argument, error is a code number such as miIMG_ERR_WRITE, and os_error should have the value of the operating system's errno variable if the failure was the result of a failed OS or C library function, or 0 for non-OS failures. See above for a list of available failure codes. The caller may also use mi_error before calling this function to provide more information.

See section Defining Custom Image File Formats for a detailed example.

Copyright © 1986, 2015 NVIDIA ARC GmbH. All rights reserved.