lowlevel.library Reference¶
Comprehensive function reference for lowlevel.library, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/AG/lowlevel).
This page documents 15 functions of lowlevel.library. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.
Function index¶
AddKBInt()AddTimerInt()AddVBlankInt()ElapsedTime()GetKey()GetLanguageSelection()QueryKeys()ReadJoyPort()RemKBInt()RemTimerInt()RemVBlankInt()SetJoyPortAttrsA()StartTimerInt()StopTimerInt()SystemControlA()
AddKBInt()¶
AddKBInt -- adds a routine to the keyboard interrupt. (V40)
Synopsis
intHandle = AddKBInt(intRoutine, intData);
D0 A0 A1
APTR AddKBInt(APTR, APTR);
Function
This routine extends the functionality of the keyboard interrupt to include intRoutine. Since this is an extention of the normal keyboard interrupt all of the keyboard handshaking is handled. The keyboard error codes are filtered out and not passed to intRoutine.
The routine is called whenever the user enters a key on the
keyboard.
The routine is called from within an interrupt, so normal
restrictions apply. The routine must preserve the following
registers: A2, A3, A4, A7, D2-D7. Other registers are
scratch, except for D0, which MUST BE SET TO 0 upon
exit. On entry to the routine, A1 holds 'intData' and A5
holds 'intRoutine', and D0 contains the rawkey code read
from the keyboard.
The routine is not called when a reset is received from the
keyboard.
This is a low level function that does not fit the normal Amiga
multitasking model. The interrupt installed will have no knowledge
of which window/screen currently has input focus.
If your program is to exit without reboot, you MUST call RemKBInt()
before exiting.
Only one interrupt routine may be added to the system. ALWAYS
check the return value in case some other task has previously
used this function.
Inputs
intRoutine - the routine to invoke every vblank. This routine should be as short as possible to minimize its effect on overall system performance. intData - data passed to the routine in register A1. If more than one long word of data is required this should be a pointer to a structure that contains the required data.
Results
intHandle - a handle used to manipulate the interrupt, or NULL if it was not possible to attach the routine.
See also
AddTimerInt()¶
AddTimerInt -- adds an interrupt that is executed at regular intervals. (V40)
Synopsis
intHandle = AddTimerInt(intRoutine, intData);
D0 A0 A1
APTR AddTimerInt(APTR, APTR);
Function
Calling this routine causes the system to allocate a CIA timer and set up 'intRoutine' to service any interrupts caused by the timer. Although the timer is allocated it is neither running, nor enabled. StartIntTimer() must be called to establish the time interval and start the timer.
The routine is called from within an interrupt, so normal
restrictions apply. The routine must preserve the following
registers: A2, A3, A4, A7, D2-D7. Other registers are
scratch, except for D0, which MUST BE SET TO 0 upon
exit. On entry to the routine, A1 holds 'intData' and A5
holds 'intRoutine'.
Only a single CIA timer will be allocated by this routine. So this
routine may only be called once without an intervening call to
RemTimerInt().
The CIA timer used by this routine is not guaranteed to always be
the same. This routine utilizes the CIA resource and uses an
unallocated CIA timer.
If your program is to exit without reboot, you MUST match all
calls to this function with calls to RemTimerInt() before exiting.
Even if you only use the function once in your program; checking
the return value will make your program more tolerant for
mulititasking on the Amiga computer platforms.
Inputs
intRoutine - the routine to invoke upon timer interrupts. This routine should be as short as possible to minimize its effect on overall system performance. intData - data passed to the routine in register A1. If more than one long word of data is required this should be a pointer to a structure that contains the required data.
Results
intHandle - a handle used to manipulate the interrupt, or NULL if it was not possible to attach the routine.
See also
RemTimerInt(), StopTimerInt(), StartTimerInt()
AddVBlankInt()¶
AddVBlankInt -- adds a routine executed every vertical blank. (V40)
Synopsis
intHandle = AddVBlankInt(intRoutine, intData);
D0 a0 a1
APTR AddVBlankInt(APTR, APTR);
Function
Lets you attach a routine to the system which will get called everytime a vertical blanking interrupt occurs.
The routine is called from within an interrupt, so normal
restrictions apply. The routine must preserve the following
registers: A2, A3, A4, A7, D2-D7. Other registers are
scratch, except for D0, which MUST BE SET TO 0 upon
exit. On entry to the routine, A1 holds 'intData' and A5
holds 'intRoutine'.
If your program is to exit without reboot, you MUST call
RemVBlankInt() before exiting.
Only one interrupt routine may be added to the system. ALWAYS check
the return value in case some other task has previously used this
function.
Inputs
intRoutine - the routine to invoke every vblank. This routine should be as short as possible to minimize its effect on overall system performance. intData - data passed to the routine in register A1. If more than one long word of data is required this should be a pointer to a structure that contains the required data.
Results
intHandle - a handle used to manipulate the interrupt, or NULL if it was not possible to attach the routine.
See also
ElapsedTime()¶
ElapsedTime -- returns the time elapsed since it was last called. (V40)
Synopsis
fractionalSeconds = ElapsedTime(context);
D0 A0
ULONG ElapsedTime(struct EClockVal*);
Function
This function utilizes the timer.device/ReadEClock() function to get an accurate elapsed time value. Since the context needs to be established the first call to this routine will return a nonsense value.
The return value for this function only allows for sixteen bits
worth for the integer number of seconds and sixteen bits for the
factional number of seconds.
With sixteen bits worth of integer seconds this function can be
used to timer an interval up to about 16 hours. If the actual time
interval is larger this function will return this maximum value.
The sixteen bits for fractional seconds gives a resolution of
approximately 20 microseconds. However, it is not recomended
to expect this function to be accurate for a time interval of
less than 200 microseconds.
Inputs
context - pointer to an EClockVal structure. The first time you call this function, you should initialize the structure to 0s. You should then reuse the same structure for subsequent calls to this function, as this is how the elapsed time is calculated.
Results
fractionalSeconds - The elapsed time as a fixed point 32-bit number with the point fixed in the middle. That is, the upper order sixteen bits represent the number of seconds elapsed. The low order sixteen bit represent the fractional number of seconds elapsed. This value is limited to about sixteen hours. Although this value is precise to nearly 20 microseconds it is only accurate to within 200 microseconds.
See also
GetKey()¶
GetKey -- returns the currently pressed rawkey code and qualifiers. (V40)
Synopsis
key = GetKey();
D0
ULONG GetKey(VOID);
Function
This function returns the currently pressed non-qualifier key and all pressed qualifiers.
This function is safe within an interrupt.
This is a low level function that does not fit the normal Amiga
multitasking model. The values returned by this function are
not modified by which window/screen currently has input focus.
Results
key - key code for the last non-qualifier key pressed in the low order word. If no key is pressed this word will be FF. The upper order word contains the qualifiers which can be found within the long word as follows: Qualifier Key LLKB_LSHIFT Left Shift LLKB_RSHIFT Rigt Shift LLKB_CAPSLOCK Caps Lock LLKB_CONTROL Control LLKB_LALT Left Alt LLKB_RALT Right Alt LLKB_LAMIGA Left Amiga LLKB_RAMIGA Right Amiga
GetLanguageSelection()¶
GetLanguageSelection -- returns the current language selection. (V40)
Synopsis
language = GetLanguageSelection();
D0
ULONG GetLanguageSelection (VOID);
Function
Determine what the user has specified as a language.
Results
language - user specified language, or zero if none has yet been
specified. See
QueryKeys()¶
QueryKeys -- return the states for a set of keys. (V40)
Synopsis
QueryKeys(queryArray, arraySize);
A0 D1
VOID QueryKeys(struct KeyQuery*, UBYTE);
Function
Scans the keyboard to determine which of the rawkey codes listed in the QueryArray are currently pressed. The state for each key is returned in the array.
This function may be invoked from within an interrupt, but the size
of QueryArray should be kept as small as possible.
This is a low level function that does not fit the normal Amiga
multitasking model. The values returned have no knowledge
of which window/screen currently has input focus.
Inputs
queryArray - an array of KeyQuery structures. The kq_KeyCode fields of these structures should be filled with the rawkey codes you wish to query about. Upon return from this function, the kq_Pressed field of these structures will be set to TRUE if the associated key is down, and FALSE if not. arraySize - number of key code entries in queryArray
ReadJoyPort()¶
ReadJoyPort -- return the state of the selected joy/mouse port. (V40)
Synopsis
portState = ReadJoyPort(portNumber);
D0 D0
ULONG ReadJoyPort(ULONG);
Function
This function is used to determine what device is attached to the joy port and the current position/button state. The user may attach a mouse, game controller, or joystick to the port and this function will dynamically detect which device is attached and return the appropriatly formatted portState.
To determine the type of controller that is attached, this function
clocks the game controller and/or interprets changes in the joy
port data. Valid clocked data from the game controller is immediately
detected. However, to accuratly determine if a mouse or joystick is
attached, several calls to this function are required along with some
movement at the joy port by the user.
This function always executes immediatly.
This is a low level single threaded function that does not fit the
normal Amiga multitasking model. Only one task can be executing
this routine at any time. All others will return immediately with
JP_TYPE_NOTAVAIL.
The nature of this routine is not meant to encourage non-multitasking
friendly programming practices like polling loops. If your task
is waiting for a transition to be returned use a WaitTOF() between
calls to minimize the total system impact.
When called the first time, for each port, this function attempts to
acquire certain system resources. In order to aquire these resources
this function MUST be called from a task, or a DOS process. If this
function fails to aquire the necessary resources, it will
return with JP_TYPE_NOTAVAIL. Once the resources are aquired (return
value other than JP_TYPE_NOTAVAIL) this function may be used in
interrupts.
Inputs
portNumber - port to read, in the range 0 to 3.
Results
portState - bit map that identifies the device and the current state of that device. The format of the bit map is dependant on the type of device attached.
The following constants from <libraries/lowlevel.h>
are used to determine which device is attached and
the state of that device.
The type of device can be determined by applying
the mask JP_TYPE_MASK to the return value and comparing
the resultant value with the following:
JP_TYPE_NOTAVAIL port data unavailable
JP_TYPE_GAMECTLR game controller
JP_TYPE_MOUSE mouse
JP_TYPE_JOYSTK joystick
JP_TYPE_UNKNOWN unknown device
If type = JP_TYPE_GAMECTLR the bit map of portState is:
JPF_BUTTON_BLUE Blue - Stop
JPF_BUTTON_RED Red - Select
JPF_BUTTON_YELLOW Yellow - Repeat
JPF_BUTTON_GREEN Green - Shuffle
JPF_BUTTON_FORWARD Charcoal - Forward
JPF_BUTTON_REVERSE Charcoal - Reverse
JPF_BUTTON_PLAY Grey - Play/Pause
JPF_JOY_UP Up
JPF_JOY_DOWN Down
JPF_JOY_LEFT Left
JPF_JOY_RIGHT Right
If type = JP_TYPE_JOYSTK the bit map of portState is:
JPF_BUTTON_BLUE Right
JPF_BUTTON_RED Fire
JPF_JOY_UP Up
JPF_JOY_DOWN Down
JPF_JOY_LEFT Left
JPF_JOY_RIGHT Right
If type = JP_TYPE_MOUSE the bit map of portState is:
JPF_BUTTON_BLUE Right mouse
JPF_BUTTON_RED Left mouse
JPF_BUTTON_PLAY Middle mouse
JP_MVERT_MASK Mask for vertical counter
JP_MHORZ_MASK Mask for horizontal counter
See also
RemKBInt()¶
RemKBInt -- remove a previously installed keyboard interrupt. (V40)
Synopsis
RemKBInt(intHandle);
A1
VOID RemKBInt(APTR);
Function
Remove a keyboard interrupt routine previously added with AddKBInt().
Inputs
intHandle - handle obtained from AddKBInt(). This may be NULL, in which case this function does nothing.
See also
RemTimerInt()¶
RemTimerInt -- remove a previously installed timer interrupt. (V40)
Synopsis
RemTimerInt(intHandle);
A1
VOID RemTimerInt(APTR);
Function
Removes a timer interrupt routine previously installed with AddTimerInt.
Inputs
intHandle - handle obtained from AddTimerInt(). This may be NULL, in which case this function does nothing.
See also
AddTimerInt(), StopTimerInt(), StartTimerInt()
RemVBlankInt()¶
RemVBlankInt -- remove a previously installed vertical blank routine. (V40)
Synopsis
RemVBlankInt(intHandle);
A1
VOID RemVBlankInt(APTR);
Function
Removes a vertical blank interrupt routine previously added with AddVBlankInt().
Inputs
intHandle - handle obtained from AddVBlankInt(). This may be NULL, in which case this function does nothing.
See also
SetJoyPortAttrsA()¶
SetJoyPortAttrsA -- change the attributes of a port. (V40.27) SetJoyPortAttrs -- varargs stub for SetJoyPortAttrsA(). (V40.27)
Synopsis
success = SetJoyPortAttrsA(portNumber, tagList);
D0 D0 A1
BOOL SetJoyPortAttrsA(ULONG,TagItem*);
Success = SetJoyPortAttrs(portNumber, firstTag, ...);
BOOL SetJoyPortAttrs(Tag, ...);
Function
This function allows modification of several attributes held by ReadJoyPort() about both it's operation and the type of controller currently plugged into the port.
ReadJoyPort()'s default behavior is to attempt to automatically
sense the type of controller plugged into any given port, when
asked to read that port. This behavior is beneficial, to allow
simple detection of the type of controller plugged into the port.
Unfortunately, rare cases are possible where extremely fine
mouse movements appear to be real joystick movements. Also, this
ability to auto-sense the controller type causes most reads to
take longer than if there were no auto-sensing.
SetJoyPortAttrs() is intended to provide for both of these cases.
It allows the programmer to notify ReadJoyPort() to stop spending
time attempting to sense which type of controller is in use -- and,
optionally, to force ReadJoyPort() into utilizing a certain
controller type.
Inputs
portNumber - the joyport in question (0-3). tagList - a pointer to an array of tags providing parameters to SetJoyPortAttrs(); if NULL, the function will return TRUE, but do nothing.
Results
success - TRUE if everything went according to plan, or FALSE upon failure
See also
StartTimerInt()¶
StartTimerInt -- start the timer associated with the timer interrupt. (V40)
Synopsis
StartTimerInt(intHandle, timeInterval, continuous);
A1 D0 D1
VOID StartTimerInt(APTR, ULONG, BOOL);
Function
This routine starts a stopped timer that is assocatied with a timer interrupt created by AddTimerInt().
Inputs
intHandle - handle obtained from AddTimerInt(). timeInterval - number of micoseconds between interrupts. The maximum value allowed is 90,000. If higher values are passed there will be unexpected results. continuous - FALSE for a one shot interrupt. TRUE for multiple interrupts.
See also
AddTimerInt(), RemTimerInt(), StopTimerInt()
StopTimerInt()¶
StopTimerInt -- stop the timer associated with the timer interrupt. (V40)
Synopsis
StopTimerInt(intHandle);
A1
VOID StopTimerInt(APTR);
Function
Stops the timer associated with the timer interrupt handle passed. This is used to stop a continuous timer started by StartTimerInt().
Inputs
intHandle - handle obtained from AddTimerInt().
See also
AddTimerInt(), RemTimerInt(), StartTimerInt()
SystemControlA()¶
SystemControlA - Method for selectively disabling OS features. (V40) SystemControl - varargs stub for SystemControlA().
Synopsis
failTag = SystemControlA(tagList);
D0 A1
ULONG SystemControlA(TagItem*);
failTag = SystemControl(firstTag, ...);
ULONG SystemControl(Tag, ...);
Function
This function is used to alter the operation of the system. Some of the alterations involve controlling what are normally regarded as system resources. In order to minimize confusion only one task is allowed to control any part of the system resources. This prevents the possiblity of two tasks fighting, each controlling a part of the system. If a tag is identified as task exclusive, it means that only one task can hold (set to TRUE) that tag. If another task attempts to set the same tag to TRUE, the call to SystemControl() will fail.
It is important to remember that SystemControl() can fail.
This is a low level function and certain tags do not fit the normal
Amiga multitasking model.
Inputs
tagList - pointer to an array of tags listing the features of the system to be enabled/disabled.
Results
failTag - zero if all tags succeeded. A non-zero return indicates a tag that has failed. It is possible that other tags may fail as well.
If any tag fails there will be no change in the system due
to other tags.