{"id":4379,"date":"2022-12-20T17:49:07","date_gmt":"2022-12-20T20:49:07","guid":{"rendered":"http:\/\/lode.uno\/linux-man\/index.php\/2022\/12\/20\/xli-loader-guide-man5\/"},"modified":"2022-12-20T17:49:07","modified_gmt":"2022-12-20T20:49:07","slug":"xli-loader-guide-man5","status":"publish","type":"post","link":"https:\/\/lode.uno\/linux-man\/2022\/12\/20\/xli-loader-guide-man5\/","title":{"rendered":"XLI LOADER GUIDE (man5)"},"content":{"rendered":"

XLI LOADER GUIDE<\/h1>\n

Guide to writing image loaders for xli<\/a>
Include files<\/a>
Identify function<\/a>
Loading the image<\/a>
Useful info in image_ops:<\/a>
Useful things to set in the image structure:<\/a>
Creating and destroying Image structures:<\/a>
File input resources:<\/a>
Memory allocation:<\/a>
Other facilities:<\/a>
If all else fails:<\/a> <\/p>\n

\n

Guide to writing image loaders for xli <\/a> <\/h2>\n

This is a introduction on how an image load routine should be written, and what resources are available for use by the writer.<\/p>\n

Include files <\/a> <\/h2>\n

The include file xli.h is generally sufficient to make all the xli resources available: ie:<\/p>\n

#include “xli.h”<\/p>\n

Identify function <\/a> <\/h2>\n

The identification function is used to implement the -identify<\/i> option of xli. It is generally of the form :
int xyyzIdent(fullname, name)
char \u2217fullname, \u2217name;
{
}<\/p>\n

where this is an xyyz type image loader file.<\/p>\n

fullname is the name including path, while name is the short name of the file that is used as a title, or to refer to the file in messages.<\/p>\n

Return 0 if the image is NOT identified.<\/p>\n

Return 1 if the image IS identified.<\/p>\n

If the file is identified, use a message something like:
printf(“%s is a %dx%d xyyz image with %d colorsn”,<\/p>\n\n\n
<\/td>\n<\/td>\n\n

name, width, height, ncolors);<\/p>\n<\/td>\n<\/tr>\n<\/table>\n

Try and be quick about identifying the image – don\u2019t read the whole image just to identify it !<\/p>\n

Use printf even if something is wrong with the file. Use perror for a system error – ie. unable to open file.<\/p>\n

Loading the image <\/a> <\/h2>\n

The load function is used to identify and load the file if it is recognized. It is of the form:
Image xyyzLoad(fullname, image_ops, verbose)
ImageOptions \u2217image_ops;
char \u2217fullname;
boolean verbose;
{
}<\/p>\n

Identify the image as quickly as possible.<\/p>\n

Return NULL if the image is not identified.<\/p>\n

Otherwise Return a pointer to an image structure with the image in it.<\/p>\n

If the image is properly identified, but there is something wrong with it before anything useful is read in, report the error – ie.
fprintf(stderr,”xyyzLoad: %s – corrupted color mapn”,name);<\/p>\n

clean up (ie. release the image structure and any allocated memory) and return NULL.<\/p>\n

If the image is properly identified, and there is something wrong with it, but something useful has been read in (ie. color maps etc. have been loaded, and part of the image is loaded), report the error using fprintf (as above) and return what there is of the image.<\/p>\n

Remember to release and temporary memory allocated on returning, whether the image is loaded ok, or if something goes wrong.<\/p>\n

Remember to read any trailing options before returning a successfully loaded image, and before closing the file. Trailing options are read by calling the function:
read_trail_opt(image_ops, zf, image, verbose)
ImageOptions \u2217image_ops;
ZFILE \u2217zf;
Image \u2217image;
boolean verbose;<\/p>\n

Remember to close the file before returning.<\/p>\n

Remember to add any additional info to the image structure – ie. name, gamma if known etc.<\/p>\n

NEVER EVER exit(). There may be other image loaders and other images to load.<\/p>\n

Use printf to give verbose output on image details.<\/p>\n

Use fprintf(stderr,” … “); to give error warning if the file is corrupted.<\/p>\n

use perror for a system error – ie. unable to open file.<\/p>\n

Useful info in image_ops: <\/a> <\/h2>\n\n\n
<\/td>\n\n

char \u2217name; \/\u2217 Short name of image \u2217\/<\/p>\n<\/td>\n<\/tr>\n<\/table>\n

Useful things to set in the image structure: <\/a> <\/h2>\n\n\n\n\n\n\n\n\n\n\n
<\/td>\n\n

char \u2217title; \/\u2217 name of image \u2217\/<\/p>\n<\/td>\n

<\/td>\n<\/td>\n<\/td>\n<\/td>\n<\/td>\n <\/td>\n<\/tr>\n
<\/td>\n\n

RGBMap rgb; \/ RGB map of image if IRGB type \u2217\/<\/p>\n<\/td>\n

<\/td>\n<\/td>\n<\/td>\n<\/td>\n<\/td>\n <\/td>\n<\/tr>\n
<\/td>\n\n

byte \u2217data; \/\u2217 data, rounded to full byte for each row \u2217\/<\/p>\n<\/td>\n

<\/td>\n<\/td>\n<\/td>\n<\/td>\n<\/td>\n <\/td>\n<\/tr>\n
<\/td>\n <\/td>\n<\/td>\n<\/td>\n<\/td>\n<\/td>\n<\/td>\n <\/td>\n<\/tr>\n
<\/td>\n\n

float<\/p>\n<\/td>\n

<\/td>\n<\/td>\n <\/td>\n<\/td>\n<\/td>\n <\/td>\n<\/tr>\n
<\/td>\n<\/td>\n<\/td>\n<\/td>\n\n

gamma;<\/p>\n<\/td>\n

<\/td>\n<\/td>\n\n

\/\u2217 gamma of display the image is adjusted \u2217\/<\/p>\n<\/td>\n<\/tr>\n

<\/td>\n <\/td>\n<\/td>\n<\/td>\n<\/td>\n<\/td>\n<\/td>\n <\/td>\n<\/tr>\n
<\/td>\n <\/td>\n<\/td>\n<\/td>\n <\/td>\n<\/td>\n<\/td>\n <\/td>\n<\/tr>\n
<\/td>\n<\/td>\n<\/td>\n<\/td>\n <\/td>\n<\/td>\n<\/td>\n\n

\/\u2217 for, if know. \u2217\/<\/p>\n<\/td>\n<\/tr>\n<\/table>\n

Creating and destroying Image structures: <\/a> <\/h2>\n

The image structure is created by a call to one of three routines:
\/\u2217 For a monochrome bitmap \u2217\/
Image \u2217newBitImage(width, height)
unsigned int width, height;<\/p>\n

\/\u2217 For a color image with a color map \u2217\/
Image \u2217newRGBImage(width, height, depth)
unsigned int width, height, depth;<\/p>\n

\/\u2217 For a true color image \u2217\/
Image \u2217newTrueImage(width, height)
unsigned int width, height;<\/p>\n

And the image can be freed with:
void freeImageData(image)
Image \u2217image;<\/p>\n

Examine another image loader (ie. gif.c) to see how to set up a color map.<\/p>\n

File input resources: <\/a> <\/h2>\n

A set of file input functions are available that automatically handle compressed files, and also by default buffer the file in memory to speed up the detection of the image type. The following functions are available:
\/\u2217
Open a file by name and return a pointer to
a file descriptor.
\u2217\/
ZFILE \u2217zopen(name)
char \u2217name;<\/p>\n

\/\u2217
Read some data into a buffer
\u2217\/
int zread(zf, buf, len)
ZFILE \u2217zf;
byte \u2217buf;
int len;<\/p>\n

\/\u2217
Macro that returns a character from the file.
\u2217\/
zgetc(zf)
ZFILE \u2217zf;<\/p>\n

\/\u2217
Function that reads a string into a buffer
\u2217\/
char \u2217zgets(buf, size, zf)
char \u2217buf;
unsigned int size;
ZFILE \u2217zf;<\/p>\n

\/\u2217 Return the files EOF status \u2217\/
int zeof(zf)
ZFILE \u2217zf;<\/p>\n

\/\u2217
Clear any errors (ie. EOF)
\u2217\/
void zclearerr(zf)
ZFILE \u2217zf;<\/p>\n

\/\u2217
Turn off caching when an image has been identified
and there is no need to re-open it. The cached part
of the file is still kept, but any reads past this
point are not cached.
\u2217\/
void znocache(zf)
ZFILE \u2217zf;<\/p>\n

\/\u2217
Rewind the cached file. This won\u2019t work if the file
is stdin and we have read past the cached part of
the file. Return TRUE on success.
\u2217\/
boolean zrewind(zf)
ZFILE \u2217zf;<\/p>\n

\/\u2217
Return a block of data back to the input stream.
Useful for a load routine that does its own buffering
and wants to return what is left after it has read
an image. (This is needed to allow trailing options
to be recognized.) Can also be used instead of ungetc().
\u2217\/
void zunread(zf, buf, len)
ZFILE \u2217zf;
byte \u2217buf;
int len;<\/p>\n

\/\u2217
Close a file.
The file is not actually closed until zreset is called,
in case another loader wants to re-open it.
\u2217\/
void zclose(zf)
ZFILE \u2217zf;<\/p>\n

\/\u2217
Really close a file. Not used by imageLoad functions.
\u2217\/
void zreset(filename)
char \u2217filename;<\/p>\n

Some macros are provided to facilitate reading and writing elements larger than a character from\/to a data buffer according to the desired endianness:<\/p>\n

Big endian:
#define memToVal(PTR,LEN)<\/p>\n

#define valToMem(VAL,PTR,LEN)<\/p>\n

Little Endian
#define memToValLSB(PTR,LEN)<\/p>\n

#define valToMemLSB(VAL,PTR,LEN)<\/p>\n

Memory allocation: <\/a> <\/h2>\n

The built in memory allocation routines are guaranteed not to fail.
\/\u2217 Duplicate a string. Good for making up the image title etc. \u2217\/
char \u2217dupString(s)
char \u2217s;<\/p>\n

byte \u2217lmalloc(size)
unsigned int size;<\/p>\n

byte \u2217lcalloc(size)
unsigned int size;<\/p>\n

void lfree(area)
byte \u2217area;<\/p>\n

Be careful not to call lfree with NULL. It may cause a fault.<\/p>\n

Other facilities: <\/a> <\/h2>\n

Memory manipulation
\/\u2217 Copy a block of memory \u2217\/
bcopy(S,D,N)<\/p>\n

\/\u2217 Zero a block of memory \u2217\/
bzero(P,N)<\/p>\n

\/\u2217 Fill a block of memory with a value \u2217\/
bfill(P,N,C)<\/p>\n

If all else fails: <\/a> <\/h2>\n

Read the source. xli.h and image.h are a good place to start. Look at one of the existing loaders ie. pcx.c Grep for anything else!<\/p>\n

\n","protected":false},"excerpt":{"rendered":"

XLI LOADER GUIDE Guide to writing image loaders for xli Include files Identify function Loading the image Useful info in image_ops: Useful things to set in the image structure: Creating and destroying Image structures: File input resources: Memory allocation: Other facilities: If all else fails: Guide to writing image loaders for xli This is a […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[959],"tags":[961,1291,1387],"class_list":["post-4379","post","type-post","status-publish","format-standard","hentry","category-5-formatos-de-ficheros","tag-961","tag-man5","tag-xliguide"],"gutentor_comment":0,"_links":{"self":[{"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/posts\/4379","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/comments?post=4379"}],"version-history":[{"count":0,"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/posts\/4379\/revisions"}],"wp:attachment":[{"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/media?parent=4379"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/categories?post=4379"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/tags?post=4379"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}