356 lines
7.0 KiB
Plaintext
356 lines
7.0 KiB
Plaintext
@database "zcodeclib Dev. Guide"
|
|
@subject "Documentation"
|
|
@author "Zorro"
|
|
@$VER: ZCODEC.HYP (@:"__DATE__")
|
|
@options +Z
|
|
@options -S
|
|
|
|
@default Index
|
|
|
|
@node Index "zcodeclib dev."
|
|
zcodeclib dev.
|
|
@line 1 70 0 0 1
|
|
|
|
|
|
1. Introduction
|
|
2. Functions
|
|
3. Global variables
|
|
4. The IMAGE structure.
|
|
5. Do you use MEM.LDG in your application?
|
|
|
|
|
|
@endnode
|
|
|
|
|
|
@node "Introduction"
|
|
1. Introduction
|
|
@line 1 70 0 0 1
|
|
|
|
Make a basic GEM application is a very easy task but problems
|
|
become when we have to draw something on the screen.
|
|
|
|
Indeed, on Atari and others TOS computers, there are many
|
|
different screens' formats and, of course, we can't deal with
|
|
it in the same manner.
|
|
|
|
The problem is worst when we have to load and to draw a picture
|
|
from, for example, a JPG file. We have to make ourselves loading
|
|
routines, etc... A real nightmare!
|
|
|
|
The goal of this library is to offer easy and fast functions for
|
|
load images from file and for, especially, deal with the screen.
|
|
It provide also useful functions like MFDB zooming and others.
|
|
|
|
This library load and use the zview's codecs, so it's fast and
|
|
stable.
|
|
|
|
@{B}For use this library, you need:@{0}
|
|
|
|
- A VDI with a valid EDDI (like NovaVDI, NVDI > 2.5, fVDI, etc..).
|
|
- The zview's codec correctly installed with mem.ldg (provided in
|
|
the zview archive).
|
|
- the LDG library ( http://ldg.org.free.fr)
|
|
- A recent GEMLIB.
|
|
|
|
|
|
(Index)
|
|
|
|
@endnode
|
|
|
|
@node "Functions"
|
|
2. Functions
|
|
@line 1 70 0 0 1
|
|
|
|
|
|
1. codecs_init()
|
|
2. codecs_quit()
|
|
3. load_img()
|
|
4. delete_img()
|
|
5. pic_resize()
|
|
6. delete_mfdb()
|
|
|
|
|
|
(Index)
|
|
|
|
@endnode
|
|
|
|
|
|
@node "codecs_init()"
|
|
codecs_init()
|
|
@line 1 70 0 0 1
|
|
|
|
@{B}NAME@{0}
|
|
codec_init - initialise and load the wanted codecs.
|
|
|
|
@{B}PROTOTYPAGE@{0}
|
|
int16 codecs_init( char *codec_name);
|
|
|
|
|
|
@{B}PARAMETERS@{0}
|
|
codec_name: the name of the codec to load.
|
|
|
|
return: 0 if an error occurs else 1.
|
|
|
|
|
|
@{B}DESCRIPTION@{0}
|
|
It's the first function to call.
|
|
|
|
The function's job is to initialize the VDI's informations,
|
|
load MEM.LDG ( for shareable allocation) and load the wanted
|
|
codecs.
|
|
|
|
For example:
|
|
|
|
codecs_init( "jpg.ldg");
|
|
|
|
If you need others codecs, you can to call this function any
|
|
numbers of times like:
|
|
|
|
codecs_init( "jpg.ldg");
|
|
codecs_init( "png.ldg");
|
|
....
|
|
|
|
Cool feature, you can load the complete codec's pack with:
|
|
|
|
codec_init( "all");
|
|
|
|
|
|
@{B}IMPORTANT@{0}
|
|
Be careful, you can't load two times the same codec so, don't
|
|
call again this function after a codec_init( "all").
|
|
|
|
|
|
(Index)
|
|
|
|
@endnode
|
|
|
|
@node "codecs_quit()"
|
|
codecs_quit()
|
|
@line 1 70 0 0 1
|
|
|
|
@{B}NAME@{0}
|
|
codecs_quit - unload the codecs and MEM.LDG.
|
|
|
|
@{B}PROTOTYPAGE@{0}
|
|
void codecs_quit( void);
|
|
|
|
|
|
@{B}DESCRIPTION@{0}
|
|
You must call this function at the end of your code or when we
|
|
don't use anymore the functions form this library.
|
|
|
|
It unloads MEM.LDG and the codecs previously loaded.
|
|
|
|
|
|
(Index)
|
|
|
|
@endnode
|
|
|
|
@node "load_img()"
|
|
load_img()
|
|
@line 1 70 0 0 1
|
|
|
|
@{B}NAME@{0}l
|
|
load_img() - load, convert and zoom a image.
|
|
|
|
@{B}PROTOTYPAGE@{0}
|
|
IMAGE *load_img( const char *file, int16 w, int16 h, int16 keep_ratio);
|
|
|
|
|
|
@{B}PARAMETERS@{0}
|
|
file: the file to load.
|
|
|
|
w: the wanted image's width.
|
|
-1 for to keep the image's width.
|
|
|
|
h: the wanted image's height.
|
|
-1 for to keep the image's height.
|
|
|
|
keep_ratio: in the case where you set the wanted image's size
|
|
with the w and h variables, if 'keep_ratio' if TRUE,
|
|
the image is resized to fit in w and h for maintain
|
|
the aspect ratio else the image will be exactly at
|
|
the wanted size.
|
|
|
|
|
|
return: NULL if an error occurs else a valid IMAGE structure.
|
|
|
|
|
|
@{B}DESCRIPTION@{0}
|
|
The most important function of this library; it loads, converts
|
|
to screen format and eventually, zooms a picture. All in one
|
|
function!
|
|
|
|
|
|
@{B}IMPORTANT@{0}
|
|
Don't allocate the IMG structure yourself, the function make it
|
|
for you (see example.c).
|
|
|
|
|
|
(Index)
|
|
|
|
@endnode
|
|
|
|
|
|
|
|
@endnode
|
|
|
|
@node "delete_img()"
|
|
delete_img()
|
|
@line 1 70 0 0 1
|
|
|
|
@{B}NAME@{0}
|
|
delete_img - free a IMAGE structure.
|
|
|
|
@{B}PROTOTYPAGE@{0}
|
|
void delete_img( IMAGE *img);
|
|
|
|
|
|
@{B}DESCRIPTION@{0}
|
|
This function frees all the memories previously allocated for
|
|
the "img" structure and also "img" itself.
|
|
|
|
(Index)
|
|
|
|
@endnode
|
|
|
|
|
|
@node "pic_resize()"
|
|
pic_resize()
|
|
@line 1 70 0 0 1
|
|
|
|
@{B}NAME@{0}l
|
|
pic_resize() - resize a MFDB.
|
|
|
|
@{B}PROTOTYPAGE@{0}
|
|
MFDB *pic_resize( MFDB *in, int16 w, int16 h, int16 keep_ratio);
|
|
|
|
|
|
@{B}PARAMETERS@{0}
|
|
in: the input MFDB address.
|
|
|
|
w: the wanted MFDB's width.
|
|
|
|
h: the wanted MFDB's height.
|
|
|
|
keep_ratio: if 'keep_ratio' if TRUE, the MFDB is resized for to
|
|
fit in 'w' and 'h' for maintain the aspect ratio
|
|
else the MFDB will be exactly at the 'w' and 'h' size.
|
|
|
|
return: NULL if an error occurs else a valid MFDB address.
|
|
|
|
|
|
@{B}DESCRIPTION@{0}
|
|
Return a MFDB resized with the data of 'in'.
|
|
|
|
|
|
@{B}IMPORTANT@{0}
|
|
1) Don't allocate the "out" MFDB yourself, the function make it
|
|
for you (see example.c).
|
|
2) You can't free the MFDB youself, use delete_mfdb() for do that.
|
|
|
|
|
|
(Index)
|
|
|
|
@endnode
|
|
|
|
|
|
|
|
@node "delete_mfdb()"
|
|
delete_mfdb()
|
|
@line 1 70 0 0 1
|
|
|
|
@{B}NAME@{0}l
|
|
delete_mfdb() - delete one or more MFDB structure(s).
|
|
|
|
@{B}PROTOTYPAGE@{0}
|
|
void delete_mfdb( MFDB *bm, int16 nbr);
|
|
|
|
|
|
@{B}PARAMETERS@{0}
|
|
bm: the MFDB to free.
|
|
|
|
nbr: the number of MFDB in 'bm'.
|
|
|
|
return: nothing.
|
|
|
|
|
|
@{B}DESCRIPTION@{0}
|
|
Free one or more MFDB created with pic_resize().
|
|
|
|
|
|
(Index)
|
|
|
|
@endnode
|
|
|
|
|
|
@node "Global variables"
|
|
Global variables
|
|
@line 1 70 0 0 1
|
|
|
|
|
|
All this global variable are in in16 format( short).
|
|
|
|
planar: The screen format, 1 if planar else 0.
|
|
|
|
nplanes: the screen planes' number.
|
|
|
|
vdi_work_in[10], vdi_work_out[57]: useful information about
|
|
the VDI.
|
|
|
|
vdi_handle: a "ready to use" VDI handle.
|
|
|
|
|
|
(Index)
|
|
|
|
@endnode
|
|
|
|
|
|
@node "IMAGE"
|
|
IMAGE
|
|
@line 1 70 0 0 1
|
|
|
|
|
|
typedef struct
|
|
{
|
|
int16 page;
|
|
uint16 *delay;
|
|
MFDB *image;
|
|
} IMAGE;
|
|
|
|
|
|
delay: exists only if the image is a animated one ( for example:
|
|
animated GIF, FLI, etc..).
|
|
|
|
page: is the number of image returned (For animated picture or
|
|
multi-pages documents like FAX).
|
|
|
|
image: is one of many MFDB structure(s) ready to be transferred to
|
|
the screen.
|
|
|
|
|
|
@endnode
|
|
|
|
|
|
@node "Do you use MEM.LDG in your application?"
|
|
Do you use MEM.LDG in your application?
|
|
@line 1 70 0 0 1
|
|
|
|
|
|
Libzcodec loads already the MEM.LDG so you can't do it again in your
|
|
code!
|
|
|
|
For this prupose, in the header's file, we can find
|
|
'shared_malloc( a)' and 'shared_free( a)'.
|
|
|
|
This functions are only ldg_malloc() and ldg_free() binded; you
|
|
can use it without any problem and if far better that Mintlib malloc's
|
|
function.
|
|
|
|
If you need ldg_realloc or ldg_calloc, you need to make a
|
|
ldg_find( "ldg_calloc", ldg_mem) youself. ( ldg_mem is a global
|
|
variable used for load MEM.LDG).
|
|
|
|
|
|
@endnode
|