@DATABASE "xbm.datatype.guide"
@$VER: xbm.datatype.guide 43.7 (3.8.1998)
@AUTHOR "Deok-Min Yun"

@NODE Main "xbm.datatype Documentation"

@{JCENTER}This is documentation for XBM DataType 43.7.

@{JCENTER}The XBM DataType is ©1997-1998 by Deok-Min Yun.


@{JCENTER}@{B}Table of Contents@{UB}

@{JCENTER}@{" Introduction     " link Introduction}
@{JCENTER}@{" Legal Stuff      " link LegalStuff}
@{JCENTER}@{" Requirements     " link Requirements}
@{JCENTER}@{" How to Install   " link Installation}
@{JCENTER}@{" How To Use       " link Usage}
@{JCENTER}@{" Revision History " link XBM_DT.History/Main}
@{JCENTER}@{" Things To Do     " link XBM_DT.ToDo/Main}
@{JCENTER}@{" Preferences      " link Prefs}
@{JCENTER}@{" Acknowledgements " link Acknowledgements}
@{JCENTER}@{" Author           " link Author}

@ENDNODE

@NODE Introduction
@{B}Introduction@{UB}

@{U}Description@{UU}

The following is an excerpt from XBM specification.


                      XBM - X BitMap Format


XBM is a native file format of The X Window System and is used for
storing cursor and icon bitmaps that are used in the X GUI.  XBM files
are quite different in that they are actually C language source files
that are created to be read by a C compiler rather than a graphical
display program.

XBM was created by the X Consortium as part of the X Window System.
Refer to the /bitmaps directory of the X Window distribution for
examples of XBM files.


@{U}Features@{UU}

- DTWM_RAW DTM_WRITE support (can use DTConvert to convert back to XBM).
- Transparency support for web browsers, etc.
- Preferences for background colour and foreground colour settings.
- Compatible with IPrefs (no need for FastIPrefs).
- Compatible with MultiView with stack size of 4096 bytes.

@ENDNODE

@NODE LegalStuff
@{B}Legal Stuff@{UB}

@{U}Copyright@{UU}

This program is Freeware.  You can do whatever you want with this
software.  It is permitted to include this program into another package
as long as all the documentation and utilities are also included.
Before re-distributing this package, please contact the @{"Author" link Author}.


@{U}Disclaimer@{UU}

This program is provided "AS IS" without warranty of any kind.  The
author assumes no responsibility or liability whatsoever for any damage
or data loss caused by using this program.

@ENDNODE

@NODE Requirements
@{B}Requirements@{UB}

- Workbench 3.0 or better.
- Any Amiga with more than 2 colours (really?).
- MUI for the preferences editor (optional).

@ENDNODE

@NODE Installation
@{B}How to Install@{UB}

You have two ways to install the XBM DataType.  One way is using the
supplied installer script.  Just double-click the 'Install_XBM_DT' icon
from Workbench or execute it from CLI (e.g.  'Execute Install_XBM_DT').

The other way is to install it manually by hand.  The following
procedure is for the manual installation.

1) Copy the file 'Classes/DataTypes/xbm.datatype' to
   'SYS:Classes/DataTypes/'.

2) Copy the file 'Devs/DataTypes/XBM' and 'Devs/DataTypes/XBM.info' to
   'DEVS:DataTypes/'.

3) If you have installed previous versions of XBM DataType or AMS
   package, delete (or backup) the file 'DEVS:DataTypes/X-Bitmap' and
   'DEVS:DataTypes/X-Bitmap.info'.  You better reboot Amiga after this.

4) If you haven't installed XBM DataType before, you can activate it by
   double-clicking on its icon in 'DEVS:DataTypes/' directory or do
   'AddDataTypes REFRESH' from CLI.

5) Copy the file 'Prefs/XBMPrefs' and 'Prefs/XBMPrefs.info' to anywhere
   you want.  You could copy these files to 'SYS:Prefs/' but it is not
   mandatory.


I have included 'Uninstall_XBM_DT' just in case somebody might want to
uninstall it from the hard drive.  Just double-click on the icon to
perform the uninstallation.

@ENDNODE

@NODE Usage
@{B}How To Use@{UB}

There are a lot of softwares that support DataType system on Amiga.  XBM
DataType will work with most of these softwares if not all.  For a
simple viewing purpose, the MultiView program supplied with Workbench
3.0 or better should be enough.

@ENDNODE

@NODE Prefs
@{B}Preferences@{UB}

@{U}How To Configure@{UU}

Beginning with V43.7, XBM DataType supports preferences for background
and foreground colours.  To change the preferences you have to use the
supplied 'XBMPrefs' utility as the preferences file is in binary format.

It will create or modify the preferences file, xbm.prefs, in
ENV:Classes/DataTypes/ and ENVARC:Classes/DataTypes.


@{U}Format of The Preferences File@{UU}

If you want to make your own version of preferences program for XBM
DataType or create a utility to configure multiple datatype preferences,
refer to the following as a guideline.

xbm.prefs is an IFF-PREF file containing a PRHD chunk and an XBDT chunk.
Please refer to Amiga ROM Kernal Reference Manual 3rd Edition
(Addison-Wesley, 1992) for further information about IFF-PREF files,
PRHD chunk, etc.

The XBDT chunk consists of its ID name, chunk size, and chunk data.
ID name has 4 bytes and is a collection of four characters 'X', 'B',
'D', 'T'.  Chunk size has 4 bytes (a long word) and is the size of the
chunk data which is always 6.  Chunk data is just an XbmDTPrefs
structure as shown below.

struct XbmDTPrefs {
  struct ColorRegister BG;
  struct ColorRegister FG;
};

ColorRegister structure is defined as the following,

struct ColorRegister {
  UBYTE red, green, blue;
};

@ENDNODE

@NODE Acknowledgements
@{B}Acknowledgements@{UB}

Andreas R. Kleinert  : For his C-V43 DataTypes example code.
Roland 'Gizzy' Mainz : For DTypesLib example code using DTWM_RAW
                       DTM_WRITE.
Erik Engdahl         : For MacPICT2 DataType descriptor code.
David Junod          : For the original XBM DataType.
Stefan Stuntz        : For MUI (Magic User Interface).
Martin Taillefer     : For AsyncIO.
Magnus Holmgren      : For updating AsyncIO.
Phil Vedovatti       : For NewIcons.
You                  : For using this software.

@ENDNODE

@NODE Author
@{B}Author@{UB}

Name   : Deok-Min Yun
E-Mail : dmyun@mailexcite.com
         dmyun@hotmail.com
         dmyun@rocketmail.com
WWW    : http://www.geocities.com/SiliconValley/Horizon/7576/
         http://members.tripod.com/~dmyun/


My other programs include,

Aminet2DB : Aminet RECENT, CSV, TSV converter.
CUR2ILBM  : Windows cursor/icon to ILBM converter.
KLS       : Korean Locale System for Amiga.
MrCAMD    : GUI frontend for CAMD_Toolkit using MUIRexx.
MrMIDI    : GUI frontend for GMPlay using MUIRexx.
MrMPEG    : GUI frontend for MPEGA using MUIRexx.
RGBx_DT   : RGBx DataType for RGBN and RGB8.
WinRes    : Windows resource extractor (.EXE, .ICL, etc.).
XSA       : XSA compressor/decompressor.

@ENDNODE