home *** CD-ROM | disk | FTP | other *** search
/ The Best of Mecomp Multimedia 2 / MECOMP-CD-II.iso / amiga / datatypes / acbm_datatype / acbm.datatype.doc < prev    next >
Encoding:
Text File  |  1997-11-09  |  11.5 KB  |  316 lines
  1. TABLE OF CONTENTS
  2.  
  3. acbm.datatype/--datasheed--
  4. acbm.datatype/--input_format--
  5. acbm.datatype/DTM_WRITE
  6. acbm.datatype/MAIN
  7. acbm.datatype/OM_NEW
  8. acbm.datatype/--datasheed--                       acbm.datatype/--datasheed--
  9.  
  10.    NAME
  11.        acbm.datatype -- data type for IFF ACBM pictures
  12.  
  13.    SUPERCLASS
  14.        picture.datatype
  15.  
  16.    DESCRIPTION
  17.        The acbm datatype, a sub-class of the picture.datatype, is
  18.        used to load and save IFF ACBM pictures.
  19.  
  20.        This class is offloaded from the datatypes.library V45 example code
  21.        and is the reference implementation of a picture.datatype subclass
  22.        (using V42 API) which supports saving in it's local format (as used
  23.        by converters like "DTConvert").
  24.  
  25.    METHODS
  26.        OM_NEW -- Create a new picture object from a description file. The
  27.            source may be a file or a clipboard unit. An empty object
  28.            (using DTST_RAM) may also be created.
  29.  
  30.        OM_UPDATE -- Perform an ICM_CHECKLOOP check, and if succesfull, the
  31.            method will be executed like OM_SET downstairs.
  32.  
  33.        OM_SET -- Pass msg to superclass and call GM_RENDER if retval from
  34.            superclass was != 0UL.
  35.  
  36.        DTM_WRITE -- Save data in local (IFF ACBM) or superclass (IFF ILBM)
  37.            format.
  38.  
  39.        All other methods are passed unchanged to superclass.
  40.  
  41.    ATTRIBUTES
  42.        Following attributes are set by the object and are READ-ONLY for
  43.        applications (if the datatype is used for saving (e.g. the
  44.        application creates an empty acbm.datatype object and fills
  45.        in some required attributes as shown in the "DTConvert" example),
  46.        these attributes are used by the encoder to create an IFF ACBM
  47.        picture file):
  48.  
  49.        DTA_ObjName         -- Set by an IFF NAME chunk. If missing,
  50.                               DTA_ObjName will take DTA_Name's value.
  51.        DTA_ObjAuthor       -- Set by an IFF AUTH chunk.
  52.        DTA_ObjAnnotation   -- Set by an IFF ANNO chunk.
  53.        DTA_ObjCopyright    -- Set by an IFF (C) chunk.
  54.        DTA_ObjVersion      -- Set by an IFF FVER chunk.
  55.        DTA_NominalHoriz    -- Same as PDTA_BitMapHeader -> bmh_Width
  56.        DTA_NominalVert     -- Same as PDTA_BitMapHeader -> bmh_Height
  57.        PDTA_BitMapHeader   -- Filled by the IFF ILBM BMHD chunk
  58.        PDTA_ModeID         -- Set by an IFF ILBM/ACBM CAMG chunk. If missing
  59.                               or the value here is 0, the datatype will
  60.                               select a value based on BMHD information.
  61.        PDTA_NumColors      -- Set by IFF ILBM/ACBM CMAP chunk
  62.        PDTA_ColorRegisters -- Set by IFF ILBM/ACBM CMAP chunk
  63.        PDTA_CRegs          -- Set by IFF ILBM/ACBM CMAP chunk
  64.        PDTA_BitMap         -- The image itself, created from IFF ACBM ABIT
  65.                               chunk and some IFF ILBM/ACBM BMHD infos.
  66.  
  67.    BUGS
  68.        - ModeID selecttion does not support SUPERHIRES.
  69.  
  70.        - Images deeper than 8 planes are not fully supported yet; a colormap
  71.          is everytimes expected.
  72.  
  73.    TODO
  74.        - Fixing the bugs above.
  75.  
  76.        - Add GRAB support (e.g. IFF ILBM GRAB chunk and matching PDTA_Grab
  77.          chunk).
  78.  
  79.        - Add support for non-planar 8 bit deep bitmaps in the encoder.
  80.  
  81.    HISTORY
  82.        V1.1
  83.          First public release.
  84.  
  85.        V1.2
  86.          - Recompiled with SAS/C 6.58. Should fix some mc68060 related
  87.            problems.
  88.  
  89.          - Added 020, 040, 060 versions and the matching makefile to show
  90.            how to do this correctly (e.g. no mc68040 version attempts to run
  91.            on a plane mc68000, it rejects opening it silently instead of
  92.            crashing).
  93.  
  94.          - Moved BOOPSI class definitions to "classdata.h".
  95.  
  96.          - Added example "what to do" when no encoder is implemented
  97.            (e.g. returns result == 0 and result2 == ERROR_NOT_IMPLEMENTED)
  98.            if complied with the NO_ENCODER switch.
  99.  
  100.          - Moved "iffparse.library"'s OpenLibrary and CloseLibrary from
  101.            LibInit to LibOpen to handle it more dynamically...
  102.  
  103.          - Added missing ObtainSemaphoreShared/ReleaseSemaphore locking to
  104.            the encoder part.
  105.  
  106.          - Fixed the bug that on rare conditions (error after the bitmap has
  107.            been loaded) wasn't freed.
  108.            Fixed.
  109.  
  110.          - Improved iffparse.library handling; more speed and corrected
  111.            error handling.
  112.  
  113.          - Updates docs and source comments a little bit
  114.  
  115.          - Fixed the bug that some generic IFF chunks were not loaded
  116.            (like NAME, FVER, AUTH, (C) etc.).
  117.            Fixed.
  118.  
  119.          - The stack swapping code now allocates it's memory without the
  120.            MEMF_CLEAR bit which results in a small speedup.
  121.  
  122.          - Replaced BestModeIDA code by a simple flag setting code.
  123.            picture.datatype does BestModeIDA if the requested mode does
  124.            not exist.
  125.  
  126.          - Now allocates the bitmap with the BMF_MINPLANES flag set. Now
  127.            the datatype supports deeper images, but a colormap is still
  128.            expected.
  129.  
  130.          - Added missing MAIN section in the autodoc.
  131.  
  132.        V1.3
  133.          - Replaced stack swapping code by my "standard" module
  134.  
  135.          - Improved the "smakefile" a little bit
  136.  
  137.          - Minor code changes
  138.  
  139.    SEE ALSO
  140.        picture.datatype
  141.  
  142. acbm.datatype/--input_format--                 acbm.datatype/--input_format--
  143.  
  144.     NAME
  145.         IFF ACBM -- Amiga Contiguous BitMap
  146.  
  147.     DESCRIPTION
  148.         FORM ACBM has the same format as FORM ILBM except the normal BODY
  149.         chunk (Interleaved Bitmap) is replaced by an ABIT chunk (Amiga
  150.         BITplanes).
  151.  
  152.         The ABIT chunk contains continous bitplane data. The chunk contains
  153.         sequential data fro planes 0 through plane i.
  154.  
  155.     SEE ALSO
  156.         - ARKM Devices: IFF part
  157.  
  158.         - iffparse.library autodocs
  159.  
  160.         - AmigaBasic LoadACBM/SaveACBM
  161.  
  162.     THANKS TO
  163.         Carolyn Scheppner (CBM) for creating this format
  164.  
  165. acbm.datatype/DTM_WRITE                               acbm.datatype/DTM_WRITE
  166.  
  167.     NAME
  168.         DTM_WRITE -- Save data
  169.  
  170.     FUNCTION
  171.         This method saves the object's contents to disk.
  172.  
  173.         If dtw_Mode is DTWM_IFF, the method is passed unchanged to the
  174.         superclass, picture.datatype, which writes an IFF ILBM picture.
  175.  
  176.         If dtw_mode is DTWM_RAW, the object writes an IFF ACBM picture to
  177.         the filehandle given.
  178.         (If the class library was compiled with the NO_ENCODER switch
  179.         (not the default), result == 0 and resul2 == ERROR_NOT_IMPLEMENTED 
  180.         are returned).
  181.  
  182.     TAGS
  183.         None defined.
  184.  
  185.     RESULT
  186.         Returns 0 for failure (IoErr() returns result2), non-zero
  187.         for success.
  188.  
  189. acbm.datatype/MAIN                                         acbm.datatype/MAIN
  190.  
  191.     INTRODUCTION
  192.         Datatypes class for IFF ACBM pictures. Based on the CBM datatypes
  193.         example source/ documents written by David Junod and the AmigaBasic
  194.         ACBM tools
  195.  
  196.     REQUIREMENTS
  197.         - You need at least Kick/WB 3.0.
  198.  
  199.         - "datatypes/picture.datatype", >= V39.
  200.  
  201.     USAGE
  202.         If the datatypes descriptor file was activated, any attempt to load
  203.         an IFF ACBM picture using GMultiView, MultiView, AmigaGuide or
  204.         SwitchWindow will load and view the picture.
  205.  
  206.         acbm.datatype supports also the clipboard as input, e.g.
  207.         "MultiView CLIPBOARD", ClipView or SwitchWindow are able to show
  208.         IFF ACBMs from clipboard.
  209.  
  210.         If you want to save the current picture in acbm.datatype's local
  211.         format, use MultiView's "Project/Save As..." menu (or GMultiView's
  212.         "Project/Save As Raw...").
  213.         acbm.datatype saves then the current picture.
  214.  
  215.     INSTALLATION
  216.         After unpacking this archive:
  217.         Because this version does not include an Installer script, you have
  218.         to do the installation manually through the shell:
  219.  
  220.           - Unpack this archive and copy the "acbm.datatype" to
  221.             SYS:Classes/DataTypes:
  222.  
  223.      Copy CLONE FROM "acbm.datatype" TO "SYS:Classes/DataTypes/acbm.datatype"
  224.  
  225.           - Then copy the datatypes descriptor into the DEVS:DataTypes
  226.             directory.
  227.             If the descriptor already exists, you should not replace it,
  228.             otherwise you may loose "toolnodes" and other settings stored in
  229.             the existing descriptor.
  230.  
  231.      Copy CLONE FROM "ACBM(%|.info)" TO DEVS:Datatypes/
  232.  
  233.     SOURCE
  234.         This is the official datatypes.library V45 reference implementation
  235.         of a picture.datatype subclass which supports saving in it's local
  236.         format (such an encoder is used by "DTConvert" and other tools which
  237.         uses DataTypes for conversion, e.g. DataType -> DataType (e.g. GIF
  238.         -> IFF ACBM etc.)).
  239.  
  240.         Source is fully included here.
  241.  
  242.     AUTHOR
  243.         If you want to blame me, report any bugs, or wants a new version
  244.         send your letter to:
  245.                         Roland Mainz
  246.                         Hohenstaufenstraße 8
  247.                         52388 Nörvenich
  248.                         GERMANY
  249.  
  250.         Phone: (+49)(0)2426/901568
  251.         Fax:   (+49)(0)2426/901569
  252.  
  253.         EMAIL is also available (if you want to send me attachments
  254.         larger than 1MB (up to 5MB, more with my permission):
  255.  
  256.         GISBURN@w-specht.rhein-ruhr.de
  257.  
  258.         Up to December 1997 I'm reachable using this email address, too:
  259.         Reinhold.A.Mainz@KBV.DE
  260.  
  261.         | Please put your name and address in your mails !
  262.         | German mailers should add their phone numbers.
  263.         | See BUGS section above when submitting bug reports.
  264.  
  265.         Sorry, but I can only look once a week for mails.
  266.         If you don't hear something from me within three weeks, please
  267.         send your mail again (but watch about new releases) (problems with
  268.         this email port are caused by reconfigurations, hackers, network
  269.         problems etc.).
  270.  
  271.         The  entire  "acbm.datatype"  package  may  be  noncommercially
  272.         redistributed, provided  that  the package  is always  distributed
  273.         in it's complete  form (including it's documentation). A small
  274.         copy fee  for media costs is okay but any kind of commercial
  275.         distribution is strictly forbidden without my permission !
  276.         Comments and suggestions how to improve this program are
  277.         generally appreciated!
  278.  
  279.         Thanks to David Junod, who wrote the datatypes environment and lots
  280.         of the datatypes example code, Carolyn Scheppner and other people
  281.         for their file formats, Matt Dillon for his DICE, Olaf 'Olsen' 
  282.         Barthel for his help, ideas and some text clips from his 
  283.         documentations.
  284.  
  285. acbm.datatype/OM_NEW                                     acbm.datatype/OM_NEW
  286.  
  287.     NAME
  288.         OM_NEW -- Create a acbm.datatype object.
  289.  
  290.     FUNCTION
  291.         The OM_NEW method is used to create an instance of the acbm.datatype
  292.         class.  This method is passed to the superclass first. After this,
  293.         acbm.datatype parses the description file and loads the colormap,
  294.         the bitmap and so on.
  295.  
  296.     ATTRIBUTES
  297.         The following attributes can be specified at creation time.
  298.  
  299.         DTA_SourceType (ULONG) -- Determinates the type of DTA_Handle
  300.             attribute. DTST_FILE, DTST_CLIPBOARD and DTST_RAM are supported.
  301.             If any other type was set in a given DTA_SourceType,
  302.             OM_NEW will be rejected.
  303.             Defaults to DTST_FILE.
  304.  
  305.         DTA_Handle -- For both supported DTST_FILE and DTST_CLIPBOARD, a
  306.             (struct IFFHandle *) is expected.
  307.             (DTST_FILE expects a IFF Stream handle because this is a IFF
  308.             type DataType (DTF_IFF)).
  309.             A DTST_RAM (create empty object) source type requires a NULL
  310.             handle.
  311.  
  312.     RESULT
  313.         If the object was created a pointer to the object is returned,
  314.         otherwise NULL is returned.
  315.  
  316.