datatypehandler.doc

Contents

0_ABOUT
1_INDEX
2_STRUCTURES

Function reference

DTDescData
DTListItem
TDthDoMethod
TDthGetAttrs
TDthListDatatypes
TDthOpen
TDthSimpleLoadPicture

0_ABOUT

Index - TOC
    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:


1_INDEX

Index - TOC
    FUNCTIONS
        TDthOpen
        TDthGetAttrs
        TDthDoMethod
        TDthListDatatypes
        TDthSimpleLoadPicture


2_STRUCTURES

Index - TOC
    DTDescData
    DTListItem


TDthOpen

Index - TOC
    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



TDthGetAttrs

Index - TOC
    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


TDthDoMethod

Index - TOC
    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


TDthListDatatypes

Index - TOC
    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


TDthSimpleLoadPicture

Index - TOC
    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


DTDescData

Index - TOC
    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


DTListItem

Index - TOC
    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