datatypehandler.doc
Contents
0_ABOUT
1_INDEX
2_STRUCTURES
Function reference
DTDescData
DTListItem
TDthDoMethod
TDthGetAttrs
TDthListDatatypes
TDthOpen
TDthSimpleLoadPicture
SHORT
API documentation for the datatypehandler module.
The datatypehandler is some kind of a manager for the miscellaneous
available datatype modules, managing loading and saving of
various types of data. This gives the ability to handle pictures, audio
data and other without any deeper knowledge about the current file
format.
VERSION
$Id: datatypehandler.html,v 1.1 2004/07/01 09:54:25 tmueller Exp $
REVISION HISTORY
$Log:
FUNCTIONS
TDthOpen
TDthGetAttrs
TDthDoMethod
TDthListDatatypes
TDthSimpleLoadPicture
DTDescData
DTListItem
NAME
TDthOpen - opens a existing file for loading or a datatype codec for
writing
SYNOPSIS
dthandle = TDthOpen(dthandler, tags)
THNDL* TAPTR TTAGITEM*
FUNCTION
If the given taglist contains a filehandle, this function opens a
existing file for loading data. If there is also an valid datatype
name, it will read this file with the given datatype codec.
If there is no filehandle inside the taglist, there must be a datatype
name, and this datatype module will be opened for writing data.
INPUT TAGS
TDOPENTAG_FILEHANDLE, (TAPTR)
a filehandle to a allready opened file to reading from
TDOPENTAG_DTNAME, (TSTRPTR)
a name of a datatype module. this name will be used to read a file
without preceding file format identification (in some applications
this is called "OPEN AS"), or to write as this format, if there is
no filehandle.
RESULTS
dthandle - a handle to a datatype module or TNULL
NOTES
can be closed with TDestroy(), will automagically closed if you close the
datatypehandler
SEE ALSO
TDthDoMethod
NAME
TDthGetAttrs - returns a taglist filled up with some informations
SYNOPSIS
tags = TDthGetAttrs(dthandler, dthandle)
TTAGITEM* TAPTR THNDL*
FUNCTION
If the datatype module was opened for reading, the returned taglist
contains informations about the opened file, depending on the file
type.
For writing the taglist contains informations about the abilities of
the datatype module.
INPUTS
dthandle - handle to a opened datatype module
RESULT TAGS
TDTAG_CLASS, (TINT)
object class, can be one of following:
DTCLASS_PIC - picture
DTCLASS_SOUND - audio
DTCLASS_ANIM - animation
DTCLASS_EXTENDED - for wild datatype modules
DTCLASS_NONE - unknown
TDTAG_FULLNAME, (TSTRPTR)
full name of object type
TDTAG_SHORTNAME, (TSTRPTR)
the short name, i.e. "ilbm" for a IFF picture
TDTAG_COMMENT, (TSTRPTR)
file comment
TDTAG_NUMSUBCLASSES, (TINT)
number of subclasses for compounded datatypes, i.e. animation
with sound
tags only concerning DTCLASS_PIC or DTCLASS_ANIM:
TDTAG_PICWIDTH, (TINT)
width of a picture or animframe
TDTAG_PICHEIGHT, (TINT)
height of a picture or animframe
TDTAG_PICDEPTH, (TINT)
color depth
TDTAG_PICBYTESPERROW, (TINT)
bytes per row
TDTAG_PICPIXELWIDTH, (TINT)
TDTAG_PICPIXELHEIGHT, (TINT)
indicate the aspect ration. i.e. a lowres interlaced
ilbm picture will have a PIXELWIDTH of 1 and a
PIXELHEIGHT of 2
TDTAG_PICFORMAT, (TUINT)
the picture format, see imgproc documentation
tags only concerning DTCLASS_SOUND:
TDTAG_SOUND_LENGTH, (TINT)
Number of samples
TDTAG_SOUND_RATE, (TINT)
Hertz
TDTAG_SOUND_CHANNELS, (TINT)
Number of channels
TDTAG_SOUND_FORMAT, (TINT)
As defined in
tags only concerning DTCLASS_ANIM:
TDTAG_ANIMTYP, (TINT)
one of the following:
DTANIM_NODELTA - every frame is
independend from his
predecessor
DTANIM_SINGLEDELTA - every frame must be
decoded into the same
buffer
DTANIM_DOUBLEDELTA - like SINGLEDELTA, just
double buffered
TDTAG_ANIMNUMFRAMES, (TINT)
number of frames
TDTAG_ANIMFRAMETIME, (TINT)
time to show a single frame in milliseconds
tags only of use if writing data:
TDTAG_CANSAVE, (TBOOL)
indicates if datatype module can write data
TDTAG_COMPRESSION, (TINT)
maximum value for compression, if 0 no compression is supported
more picture tags for writing pictures
TDTAG_SAVEPICMAXWIDTH, (TINT)
maximum width supported
TDTAG_SAVEPICMAXHEIGHT, (TINT)
maximum height supported
TDTAG_SAVEPICMINDEPTH, (TINT)
minimum color depth supported
TDTAG_SAVEPICMAXDEPTH, (TINT)
maximum color depth supported
NOTES
SEE ALSO
NAME
TDthDoMethod - reads or writes data
SYNOPSIS
success=TDthDoMethod(dthandler, dthandle, taglist)
TBOOL TAPTR THNDL* TTAGITEM*
FUNCTION
according to the former operations with TDthOpen and the given tags,
it will execute loading or writing of data
INPUTS
dthandle - handle to opened datatype module
INPUT TAGS
tags for reading:
TDOTAG_GETDATATYP, (TUINT)
indicates for compounded file types, which type of
data are wished to read in, those are the same as
defined for TDTag_Class in TDthGetAttrs
TDOTAG_GETDATA, (TAPTR)
pointer to an allocated memory area for reading in
data
extra picture Tags:
TDOTAG_GETPALETTE, (TAPTR)
pointer to an allocated array of TIMGARGBCOLOR
structures to read in the palette, if
picture depth <= 8
extra anim Tags:
TDOTAG_ANIMSTEP, (TINT)
one of the following:
DTANIM_FORWARD - steps forward to the next
frame
DTANIM_REWIND - steps back to the first
frame
extra sound Tags:
TDOTAG_NUMSAMPLES, (TINT)
number of sampels read in
tags for writing:
TDOTAG_SETDATATYP, (TUINT)
indicates which type of data should be written. those
are the same as defined for TDTag_Class in
TDthGetAttrs
TDOTAG_SETDATA, (TAPTR)
points to data to be written.
for pictures it has to point to a valid filled
TIMGPICTURE structure
TDOTAG_COMPRESSION, (TINT)
compression value, depending from TDTAG_COMPRESSION in
TDthGetAttrs
TDOTAG_WRITEFILE, (TAPTR)
a handle to a already opened file to write to
RESULTS
TTRUE, if data successfully were read in or written
NOTES
SEE ALSO
TDthOpen, TDthGetAttrs
NAME
TDthListDatatypes - gives a list of available datatype modules
SYNOPSIS
list=TDthListDatatypes(dthandler, filtertags)
TLIST* TAPTR TTAGITEM*
FUNCTION
fills a list the properties of available datatype modules, filtered
according to the given taglist
INPUT TAGS
TDFILTER_CLASS, (TUINT)
list only datatypes of this class. the classes are the same
as defined for TDTAG_CLASS in TDthGetAttrs
TDFILTER_SHORTNAME, (TSTRPTR)
this is to check the availability of a single datatype module
TDFILTER_CANSAVE, (TBOOL)
list only datatype modules able to write data
RESULTS
a pointer to a list of DTListItem structures
SEE ALSO
TDthOpen
NAME
TDthSimpleLoadPicture - loads a picture on the easy way
SYNOPSIS
res = TDthSimpleLoadPicture(dthandler, filename, pic)
TBOOL TAPTR TSTRPTR TIMGPICTURE*
FUNCTION
this function collects anything needed to load a picture in a single
function call.
INPUTS
filename - the filename in host specific spelling
pic - a pointer to a TIMGPICTURE struct. this will be allocated
by this function. it can be freed with TImgFreeBitmap, or
by hand. if the last method is prefered, at first have
pic->data and, if allocated, pic->palette to be freed, and
then the pic itself.
RESULTS
res - TTRUE, if picture could be loaded
SEE ALSO
NAME
DTDescData - contains the description of a datatype module
CONTENTS
TSTRPTR datatypecodecname - name of the datatype codec module, i.E.
"datatype_codec_bmp". this is essential
for TDthOpen
TSTRPTR datatypefullname - full name of datatype, i.E. "BMP Picture"
TSTRPTR datatypeshortname - short name of datatype, i.E. "ilbm". this
is essential for TDthListDatatypes
TSTRPTR datatypesuffix - the common suffix for files saved as this
data type
TINT8 datatypeclass - the class of data read or written with
this datatype module
TBOOL canwrite - TTRUE, if this datatype module can write
data
TINT dtnum - private
NOTES
SEE ALSO
TDthOpen, TDthListDatatypes
NAME
DTListItem - a single Item of the list returned by TDthListDatatypes
CONTENTS
struct TNode li_Node - Node header
DTDescData *li_ddat - pointer to a DTDescData structure
TDFUNC li_DestroyFunc - Destroy function for this handle
TAPTR li_ExecBase - Exec base pointer
NOTES
the only interesting thing inside this is the pointer to DTDescData,
the remains are standard list stuff
SEE ALSO
TDthListDatatypes
Rendered with docco TEKlib document generator