AmigaLib

From Freepascal Amiga wiki
Jump to: navigation, search

As of FPC 3.1.1 revision 36777, the use of unit Amigalib is deprecated.

Introduction

Unit amigalib is a unit that has its origin in Classic Amiga amiga_lib headers.


The Problem

Functions declared inside unit AmigaLib are primarily dictated by their c counter part on the underlying platform (plus some additional helpful routines that we can use ?).

On Classic there are c headers for amiga_lib, on AROS there are the alib headers, while on MorphOS we have something similar also using alib headers.

As usual, none of the available c headers offer any kind of unification, making a big mess of things when attempting to transfer to Pascal. AROS alib complicate things even further because alib was heavily expanded there, overlapping most of the functions declared in classic Amiga unit sysvartags.

Since (currently) none of the available AmigaLib units contain all function implementations, there is room to toy around a little and attempting to organize the big messy pile.

In order to do so, you can find a very large table, that contains all functions declared in their c counterparts that originates from their c-headers and which theoretically all belong to unit AmigaLib. The fact that some functions are not available on all supported platforms does not really matter as much.

The goal of the table is to provide information on where the functions originate from, and be able to decide into which Pascal unit they need to end up.

Note that implementing all functions inside the same unit poses the same difficulties encountered with classic Amiga unit sysvartags. There are some questions that requires answering before able to continue with this unit (See Below).

AmigaLib Table

In the table below the left subtable contains the original c location, while the right subtable displays the pascal unit location in which the function (is) located).

List of amiga lib functions and their location/status (c/Pascal) per platform
Function OS3.x AROS MorphOS OS3.x AROS MorphOS Remark(s)
ACrypt amiga_lib alib alib n/i amigalib n/i MAG
AddAmigaguideHost amigaguide alib systemvartags n/a AmigaGuide
AddAppIcon workbench alib n/i workbench workbench
AddAppMenuItem workbench alib systemvartags workbench workbench
AddAppWindow workbench alib systemvartags workbench workbench
AddAppWindowDropZone workbench alib n/i workbench workbench
AllocAslRequestTags asl alib systemvartags asl
AllocDosObjectTags dos alib systemvartags amigados dos
AllocNamedObject utility alib systemvartags utility utility
AllocSpriteData graphics alib systemvartags agraphics graphics
AndRectRect n/a alib n/a agraphics MAG
AddTOF amiga_lib n/i alib n/i n/i n/i MAG
afp amiga_lib n/i alib n/i n/i n/i MAG
ArgArrayDone amiga_lib alib alib n/i amigalib n/i MAG
ArgArrayInit amiga_lib alib alib n/i amigalib n/i MAG
ArgInt amiga_lib alib alib n/i amigalib n/i MAG
ArgString amiga_lib alib alib n/i amigalib n/i MAG
ArosInquire n/a alib n/a n/a amigalib n/a MAG
arnd amiga_lib n/i alib n/i n/i n/i MAG
AslRequestTags asl alib systemvartags asl
asmallocpooled n/a alib n/a n/a amigalib MAG
asmcreatepool n/a alib n/a n/a amigalib MAG
asmdeletepool n/a alib n/a n/a amigalib MAG
asmfreepooled n/a alib n/a n/a amigalib MAG
BeginIO amiga_lib alib alib amigalib amigalib n/i MAG
BestCModeIDTags n/a alib cybergraphics cybergraphics CyberGfx
BestModeID graphics alib systemvartags agraphics Gfx
BuildEasyRequest intuition alib n/i intuition intuition
CallHook amiga_lib alib alib n/i amigalib/utility n/i MAG
CallHookA amiga_lib alib alib n/i amigalib n/i MAG
ChangeExtSprite graphics alib systemvartags agraphics Gfx
CheckRexxMsg amiga_lib alib alib n/i amigalib n/i  ???
CloseWorkbenchObject workbench alib n/i workbench workbench
CoerceMethod amiga_lib alib alib n/i amigalib/intuition n/i MAG
CoerceMethodA amiga_lib alib alib amigalib amigalib/intuition n/i MAG
CopyRegion n/a alib n/a n/a amigalib/agraphics MAG
CreateExtIO amiga_lib alib alib amigalib amigalib n/i MAG
CreateGadget gadtools alib systemvartags n/i gadtools
CreateMenus gadtools alib systemvartags n/i gadtools
CreateNewProcTags dos alib systemvartags amigados dos
CreatePort amiga_lib alib alib amigalib amigalib n/i MAG
CreateStdIO amiga_lib alib alib amigalib amigalib n/i MAG
CreateTask amiga_lib alib alib amigalib amigalib n/i MAG
CxCustom amiga_lib commodities amigalib amigalib n/i  ???
CxDebug amiga_lib commodities amigalib amigalib n/i  ???
CxFilter amiga_lib commodities amigalib amigalib n/i  ???
CxSender amiga_lib commodoties amigalib amigalib n/i  ???
CxSignal amiga_lib commodities amigalib amigalib n/i  ???
CxTranslate amiga_lib commodities amigalib amigalib n/i  ???
dbf amiga_lib n/i alib n/i n/i n/i MAG
DISPATCHERARG n/a n/a n/a n/a n/a amigalib/purple  ???
DeleteExtIO amiga_lib alib alib amigalib amigalib n/i MAG
DeletePort amiga_lib alib alib amigalib amigalib n/i MAG
DeleteStdIO amiga_lib alib alib amigalib amigalib n/i MAG
DeleteTask amiga_lib alib alib amigalib amigalib n/i MAG
DoDTMethod datatypes alib n/i datatypes datatypes
DoGadgetMethod intuition alib n/i intuition
DoMethod amiga_lib alib alib n/i amigalib amigalib MAG
DoMethodA amiga_lib alib alib amigalib amigalib amigalib MAG
DoSuperMethod amiga_lib alib alib n/i amigalib amigalib MAG
DoSuperMethodA amiga_lib alib alib amigalib amigalib amigalib MAG
DoSuperNew n/a alib alib n/a amigalib n/i MAG
DoTimer n/a n/a alib n/a n/a  ???
DrawBevelBox gadtools alib systemvartags n/i gadtools
EasyRequest intuition alib n/i intuition intuition
ErrorOutput n/a alib n/a amigalib MAG
ExtendFontTags graphics alib systemvartags agraphics gfx
FastRand amiga_lib alib alib n/i amigalib n/i MAG
fpa amiga_lib n/a alib n/i n/i n/i MAG
fpbcd n/a n/a alib n/a n/a MAG
fprintf amiga_lib alib n/i n/i  ???
FreeIEvents amiga_lib alib alib amigalib amigalib n/i MAG
fwritef n/a alib n/i n/i n/i  ???
GetDTAttrs datatypes alib systemvartags datatypes datatypes
GetExtSprite graphics alib systemvartags agraphics gfx
GetRexxVar amiga_lib alib alib n/i amigalib n/i  ???
GetRPAttrs graphics alib systemvartags agraphics gfx
GetVisualInfo gadtools alib systemvartags n/i gadtools
GT_GetGadgetAttrs gadtools alib systemvartags n/i gadtools
GT_SetGadgetAttrs gadtools alib systemvartags n/i gadtools
HookEntry amiga_lib alib alib amigalib amigalib/purple amigalib/purple MAG
HotKey amiga_lib alib alib n/i amigalib n/i MAG
InvertString amiga_lib alib alib n/i amigalib n/i MAG
InvertStringForward n/a alib n/a amigalib MAG
LayoutMenuItems gadtools alib systemvartags n/i gadtools
LayoutMenus gadtools alib systemvartags n/i gadtools
LibAllocAligned n/a alib n/a amigalib MAG
LibAllocPooled amiga_lib alib alib n/i amigalib n/i MAG
LibCreatePool amiga_lib alib alib n/i amigalib n/i MAG
LibDeletePool amiga_lib alib alib n/i amigalib n/i MAG
LibFreePooled amiga_lib alib alib n/i amigalib n/i MAG
LockBitmapTags n/a alib cybergraphics cybergraphics/purple cgfx
MakeDirAll n/a n/a alib n/a n/a  ???
MakeWorkbenchObjectVisible workbench alib n/i workbench woprkbench
MergeSortList n/a alib n/a n/i  ???
NewDTObject datatypes alib systemvartags datatypes datatypes
NewList amiga_lib alib alib amigalib amigalib/exec n/i  ???
NewLoadSegTags dos alib systemvartags amigados amigados
NewObject intuition alib systemvartags intuition intuition
NewRawDoFmt n/a alib n/a n/i  ???
NewRectRegion n/a alib n/a amigalib/agraphics  ???
ObtainBestPen graphics alib systemvartags agraphics gfx
ObtainInfo bullet alib systemvartags n/a  ???
OpenAmigaGuide amigaguide alib systemvartags n/a amigaguide
OpenAmigaGuideAsync amigaguide alib systemvartags n/a amigaguide
OpenCatalog locale alib systemvartags locale locale
OpenMakeDir n/a n/a alib n/a n/a  ???
OpenScreenTags intuition alib systemvartags intuition intuition
OpenWindowTags intuition alib systemvartags intuition intuition
OpenWorkbenchObject workbench alib n/i workbench workbench
printf amiga_lib alib amigalib n/i n/i  ???
RangeRand amiga_lib alib alib n/i amigalib n/i MAG
RefreshDTObject datatypes alib systemvartags datatypes datatypes
RefreshDTObjects n/a alib n/a n/i  ???
ReleaseInfo bullet alib systemvartags n/a  ???
RemTOF amiga_lib n/a alib n/i n/i n/i  ???
RemoveAmigaGuideHost amigaguide alib systemvartags n/a amigaguide
SelectErrorOutput n/a alib n/a amigalib MAG
SendAmigaGuideCmd amigaguide alib systemvartags n/a amigaguide
SendAmigaGuideContext amigaguide alib systemvartags n/a amigaguide
SetAmigaGuideAttrs amigaguide alib systemvartags n/a amigaguide
SetAmigaGuideContext amigaguide alib systemvartags n/a amigaguide
SetAttrs intuition alib n/i intuition
SetDTAttrs datatypes alib systemvartags datatypes datatypes
SetGadgetAttrs intuition alib systemvartags intuition intuition
SetInfo bullet alib systemvartags n/a  ???
SetRexxVar amiga_lib alib alib n/i amigalib n/i  ???
SetRPAttrs graphics alib systemvartags agraphics gfx
SetSuperAttrs amiga_lib alib n/i amigalib/intuition n/i MAG
SetSuperAttrsA alib alib amigalib amigalib/purple n/i MAG
SetWindowPointer intuition alib n/i intuition intuition
sprintf amiga_lib alib libc? n/i n/i n/i  ???
strdup amiga_lib alib libc? n/i n/i n/i  ???
SystemTags dos alib systemvartags amigados amigados
TimeDelay amiga_lib alib alib n/i amigalib n/i MAG
UnlockBitmapTags n/a alib cybergraphics cybergraphics/purple cybergfx
VideoControlTags graphics alib systemvartags agraphics gfx
waitbeam n/a n/a alib n/a n/a n/i  ???
WorkbenchControl workbench alib n/i workbench workbench

legend:

red = unimplemented
red + n/a = unimplemented, no other implementation available (e.g. no c, no pascal meaning implement from scratch).
blue = implemented, untested
purple = difficulty, discuss first
Green = implemented, tested, and having correct (pascal) location mentioned

Questions

  • Initially, what (official) funcs/procs should go in amigalib ?
  • do we want ^^ those ^^ for all 3 platforms ?
  • What additional funcs/procs need to go in ?
  • In case related functions included, how to solve the fact that libs get auto-opened (or don't we care) ?

Remarks

After some work done on the actual implementation of unit amigalib, some practical issues presented itself.

In order to not fall into the same pitfall of systemvartags unit, some (if not most) functions that originally are located inside amigalib actually need to be located inside their respective units.

But, when applying that rule a full 100%, unit amigalib ends up with the following 3 functions:

  • function ACrypt(buffer: PChar; password: PChar; username: PChar): PChar;
  • function FastRand(seed: ULONG): ULONG;
  • function RangeRand(maxValue: ULONG): ULONG;

The two random related functions have no meaning for Pascal whatsoever, as it offers its own random functions.

Which leaves the ACrypt function.

There was talk about wanting to add some helper functions inside unit AmigaLib, such as SetHook(), but that actually belongs to unit utility (when applying the same rule for not falling for the systemvartags pitfall).

Other then what was mentioned in this paragraph, we need to be fair. Amigalib also adds a couple of clib function such as printf(). Do we want a pascal implementation for that (and inside unit amigalib) ?

To make things complete, there are a couple of other function inside the original AmigaLib, such as dbf, but there isn't an actual implementation available in source.


So... "what again was the purpose of unit amigalib", i started wondering.