Aros/Developer/Docs/Libraries/DataTypes

Introduction
The datatypes.library was introduced to decode file formats (#?.png #?.jpg etc.) easily using different classes which can be installed as they are needed.

First you should learn about BOOPSI (Amiga OOP object oriented system). Once understand, it's makes it easier to understand datatypes, MUI, etc

The descriptors in devs/datatypes contain the information how to identify a file type. Usually the file is opened only once by datatypes.library and a small buffer is used for comparisons which contains the first few bytes of the file (64 bytes IIRC).

dt descriptor is related to the struct DataTypeHeader dth_Name, dth_BaseName, etc.

Most datatype descriptors are held very simple, for example "compare the first 12 bytes with the pattern FORM????ILBM". The comparison is done by datatypes.library, there is no foreign code involved.

Only very few descriptors actually contain code. In this code everything can be done, though. For example, the code can close and reopen the file and read it entirely if needed. But this should not be done because identification needs to be very fast.

Dtdesc tool (and accompanied documentation) createdtdesc package is aimed at creating (picture) datatypes (as a whole, including makefiles). dtdescr is aimed at (only) viewing and creating the descriptor.

Once the file type is identified and the application wants to load the file, the class library from classes/datatypes is called. This library contains the code to decode the file contents and to make it available to datatypes.library.

Datatypes consist of a few libraries that exposes a couple of methods to load and save pictures of a certain type. Internally there is a 'common' storage method of the pixels that is used by the picture datatype, and so each 'library' that can handle its own type is able to 'convert' this common storage method into a specific format or load to this specific format.

The datatypes system itself exposes methods for the developer/user that allows for easy loading and saving by just calling some functions.

The only problem with AmigaOS implementation of datatypes is that they aren't really bidirectional. You can generally only save in IFF but AROS aspires to bring the original idea back

The ideal implementation would allow each datatype superclass (picture.datatype, sound.datatype etc.) to provide a list of all currently known sub-classes that support encoding. You'd then be able to pick one and encode data for that datatype and write it out to disk in that format.

Wanderer (AROS WB replacement) does not utilise the datatype subsystem directly "except" for loading window background imagery. The datatype system cannot deal with progressive loading and streaming yet.

How to Use
create a Datatype Object, use the NewDTObject function ...

gd->gd_DisplayObject = NewDTObject ((IPTR)gd->gd_Unit, DTA_SourceType, DTST_CLIPBOARD, GA_Immediate, TRUE,                                    GA_RelVerify, TRUE, DTA_TextAttr, (ULONG) & gd->gd_TextAttr, TAG_DONE))

The parameters of this functions uses Tags as defined in datatypes/datatypesclasses.h and intuition/gadgetclass.h

gf->gd_Unit = the Clipboard unit number DTST_Clipboard = the Clipboard is the data source GA_Immediate = Should the object be active when displayed GA_RelVerify = Verify that the pointer is over the object when it is selected gd_->gd_TextAttr = Pointer to text font attributes

Once a datatype object is no longer required, it is disposed of and memory released: e.g. DisposeDTObject (gd->gd_DisplayObject);

To get attributes from a datatype object, you can use the GetDTAttrs function e.g. GetDTAttrs (gd->gd_DisplayObject, DTA_DataType, (ULONG)&dtn, TAG_DONE);

and examining the results from the dtn structure you can retrieve: dtn->dtn_Header->dth_Name = Descriptive name of the datatype dtn->dtn_Header->dth_GroupID = The group the datatype belongs to

The function GetDTString returns a localised Datatypes string of the id given. This string could be syst, text, docu, soun, inst, musi, pict, anim or movi (see datatypes.h). e.g. GetDTString (dtn->dtn_Header->dth_GroupID)

opening a file and know the base class it is, you just need:

Object *dto; if(dto = NewDTObject(filename, DTA_GroupID, GID_TEXT, TAG_DONE)) DisposeDTObvject(dto);

The DTA_GroupID tag ensure that the file is of that type. Otherwise you'll get problems later when you try to read data.

You'll need to use GetDTAttrs or call some methods before DisposeDTObject, if you want to do anything useful.

If you merely want to find out what filetype a file is, you need something like:

struct DataTypeHeader *dth = NULL; struct DataType *dtn;

if (dtn = ObtainDataTypeA (DTST_FILE, (APTR)lock, NULL)) { dth = dtn->dtn_Header; printf("Group: %sn",dth->dth_GroupID); printf("BaseName: %sn",dth->dth_BaseName); ReleaseDataType(dtn); }

You can then open the file and handle it as per the base type dth_GroupID

what you usually do is, to create an object (initial state), get/set some attributes (attribute change) and then do layout or extract a type.

in that case there many programs that call remap but doesn't have a gpinfo structure.

is there some info what remap have on initial state ?

AROS dt set it to true.

pd->Remap = TRUE;

when a program has no gpinfo with screen, then remap should be set to false. Maybe AmigaOS AOS does that somewhere.

same can happen on AROS dt too, maybe on AOS dt bitmap (state change and get/set); however it is not clearly defined in which way state changes may affect attributes (screen, colors) or what happens in case some attributes have not been set prior triggering the state change; it's not even exactly clear which states are possible

Your application can find out when a refresh is appropriate by using the Boopsi ICATarget attribute with the ICTargetIDCMP value. This causes the datatype (gadget) to send an IDCMP_IDCMPUpdate IntuiMessage to the window port on certain status changes. That message carries a pointer to one or more attributes and if DTA_Sync is in that list with a value of 1 then the datatype object is ready for refresh.

You get one of these on attaching the datatype object to your window, and also a stream of them when the window is resized.

In order to create a jpeg datatype object (jpeg subclass of picture class)

DTImage = NewDTObject(NULL, DTA_SourceType, DTST_RAM, DTA_BaseName, "jpeg", PDTA_DestMode, PMODE_V43, TAG_DONE);

Text
AROS/workbench/classes/datatypes/text/ V44.5 of the text.datatype replacement sebauer@t-online.de (Sebastian Bauer)

Most OS outside AROS prefer XML but others like doc, docx, ood, rtf, etc

Originally, FTXT was used by the the clipboard for cut/copy function on AmigaOS, current apps use only use raw ASCII data. IFF FTXT is supposed to be Formatted TeXT, but there's very little formatting apparently supported, and this impacts what can be put on the clipboard too (copying a table with all the formatting intact is not easy).


 * 1) include 
 * 2) include 
 * 3) include 
 * 4) include 
 * 5) include 


 * 1) ifndef LNF_MARKED
 * 2) define LNF_MARKED (1<<15)
 * 3) endif

struct Text_Data {   LONG 	left, top;		/* Offsets of the gadget 			*/ LONG 	width, height;		/* Dimensions of the gadget			*/ LONG	fillpen, filltextpen;	/* pens for marking */

struct Screen 	*screen;	/* Screen on which the gadget lies 		*/ struct DrawInfo 	*drinfo;	/* Resulting from screen			*/
 * 1) ifndef COMPILE_DATATYPE

struct RastPort 	*rp; APTR 	line_pool; LONG 	update_type; LONG 	update_arg; LONG 	mouse_pressed; LONG	redraw;
 * 1) else
 * 1) endif

STRPTR 		title; UBYTE 		*buffer_allocated; ULONG 		buffer_allocated_len; struct List 	line_list;	/* double linked list of the lines		*/ char *word_delim; LONG word_wrap;

struct TextFont 	*font; struct TextAttr 	attr;

LONG 	horiz_visible; LONG 	vert_visible;

LONG 	vert_top; LONG 	horiz_top;

LONG	horiz_unit; LONG	vert_unit;

LONG 	vert_diff;		/* For optimized Scrolling			*/ LONG 	use_vert_diff; LONG 	horiz_diff; LONG 	use_horiz_diff;

LONG 	mark_x1; LONG 	mark_x2; LONG 	mark_y1; LONG 	mark_y2; struct Line *mark_line1; struct Line *mark_line2; LONG 	pressed; LONG 	copy_text;		/* if mb is released, copy the text into the clipboard */

LONG 	doubleclick;		/* 1 if doubleclicked, 2 if trippleclicked 	*/ LONG 	lastsecs;		/* For Doubleclick check			*/ LONG 	lastmics;

struct	TextExtent te; struct	RastPort font_rp;

char	search_buffer[128]; struct Process	*search_proc;	/* the search requester process */ struct GadgetInfo	search_ginfo;	/* for the search process */ int		search_line; int		search_pos;		/* x position */ int		search_case;

LONG       links; struct Line *marked_line; struct Line *selected_line; struct Line *last_marked_line; LONG       shinepen, shadowpen; BOOL       link_pressed; Object     *obj; UBYTE      word[128];     /* double clicked word */ struct GadgetInfo *ginfo; };
 * 1) ifdef MORPHOS_AG_EXTENSION
 * 1) endif


 * 1) ifdef __cplusplus

extern "C" {
 * 1) endif

APTR Text_Create(void); VOID Text_SetFrameBox( APTR mem, struct Screen *scr, struct RastPort *rp, LONG left, LONG top, LONG width, LONG height); VOID Text_Load(APTR mem, STRPTR); VOID Text_ChangeDimension( APTR mem, LONG left, LONG top, LONG width, LONG height); VOID Text_Redraw( APTR mem ); VOID Text_Free(APTR mem); ULONG Text_PageHeight( APTR mem ); ULONG Text_PageWidth( APTR mem ); ULONG Text_VisibleHeight( APTR mem ); ULONG Text_VisibleTop( APTR mem ); ULONG Text_VisibleHoriz( APTR mem ); VOID Text_SetVisibleTop( APTR mem, ULONG newy ); VOID Text_SetVisibleLeft( APTR mem, ULONG newx ); VOID Text_HandleMouse( APTR mem, LONG x, LONG y, LONG code, ULONG secs, ULONG mics); VOID Text_Print( APTR mem );

}
 * 1) ifdef __cplusplus
 * 1) endif

Picture
AROS/workbench/classes/datatypes/picture/

/*   Copyright (C) 1995-2020, The AROS Development Team. All rights reserved.


 * 1) define	MIN(a,b) (((a) < (b)) ?	(a) : (b))
 * 2) define	MAX(a,b) (((a) > (b)) ?	(a) : (b))


 * 1) include

IPTR DTD__OM_NEW(Class *cl, Object *o, struct opSet *msg) {

} /* DTD_OM_New */

/**************************************************************************************************/

static BOOL DTD_Load(struct IClass *cl, Object *o) {

}

static BOOL DTD_Save(struct IClass *cl, Object *o, struct dtWrite *dtw ) {

}

IPTR DTD__DTM_WRITE(struct IClass *cl, Object *o, struct dtWrite *dtw) {

}

/**************************************************************************************************/

STATIC IPTR DT_SetMethod(struct IClass *cl, struct Gadget *g, struct opSet *msg) {

}

STATIC IPTR DT_GetMethod(struct IClass *cl, struct Gadget *g, struct opGet *msg) {

}

STATIC IPTR DT_LayoutMethod(struct IClass *cl, struct Gadget *g, struct gpLayout *msg) {

}

Sound
Sound Datatype the Sound_Write function is the SuperMethod. Normally when a datatype has two methods: OM_NEW & DTM_WRITE. The first links the Load function of the datatype with Datatypes Library for getting new datatypes. The second links the Save function of the datatype or if DT Write Method is not DTWM_RAW then it is supposed to defer to the SuperMethod. In this case it would send the DTWM_IFF message to the Sound Datatype function Sound_Write

Should it be better to use DTMethod to decompress on a buffer and then use this uncompressed buffer ? For sound, get the data using the SDTA_Sample (or SDTA_LeftSample/SDTA_RightSample) attributes. You can retrieve sample data using SDTA_Sample tag but AmigaOS lacks support for SDTA_SampleType so you can get only 8-bit sample data there. AROS and MorphOS are more advanced there.

Any applications will query the methods supported by your class. Make sure that if you choose to implement support for the OM_GET/DTA_Methods tag the methods you return should also include the methods supported by your superclass. Otherwise, the user will be unable to use functions such as "Copy" or "Print".

NAME sound.datatype -- root data type for sounds.

FUNCTION The sound.datatype is the super-class for any sound related classes.

METHODS OM_NEW -- Create a new sound object.

OM_GET -- Obtain the value of an attribute.

OM_SET -- Set the values of multiple attributes.

OM_UPDATE -- Update the values of multiple attributes.

OM_DISPOSE -- Dispose of a sound object.

GM_LAYOUT -- Layout the object and notify the application of the title and size.

GM_HITTEST -- Determine if the object has been hit with the mouse.

GM_GOACTIVE -- Tell the object to go active. On SELECTDOWN, the sound will start playing.

GM_HANDLEINPUT -- Handle input. Currently input (other than           SELECTDOWN) doesn't affect the sound.

GM_RENDER -- Cause the graphic to render. Currently the graphic for the sound is just a static icon.

DTM_TRIGGER -- Cause an event to occur. Currently the only trigger event is STM_PLAY, which will cause the sound to start playing.

NOTE: Subclasses which support streaming data access may support more than just the STM_PLAY event.

DTM_COPY -- Copy the entire sound to the clipboard as 8SVX.

NOTE: Up to and including V40 sound.datatype never stored a valid VoiceHeader with the file. This was fixed in V44.

Subclasses which support streaming data access may not support this method.

DTM_WRITE -- Write the entire sound to a file as 8SVX.

NOTE: Up to and including V40 sound.datatype never stored a valid VoiceHeader with the file. This was fixed in V44.

Subclasses which support streaming data access may not support this method.

TAGS SDTA_VoiceHeader (struct VoiceHeader *) -- Set and get the base information for the sound. VoiceHeader is defined in

that's code of diskobjpngio.c.read

sound function
assume you are trying to manipulate images? Load images using datatypes but read image data to ARGB array using ReadPixelArray methods and dispose source object. For images, to get the raw data use PDTM_READPIXELARRAY (that's the uncompressed data).