AROS

The Amiga Research OS


(C) Copyright 1996 AROS - The Amiga Research OS


6.6 Sample HIDDs

6.6.1 Alarm HIDD

The alarm HIDD allows to call a hook after a certain time.

The type of an alarm HIDD is HIDDV_Type_Alarm and the names for alarm specific things is prefixed with HIDD?_Alarm_.

Subtypes of this HIDD are HIDDV_Type_Alarm_VB (vertical blank interrupt), HIDDV_Type_Alarm_Real (real time clock).

This kind of HIDD cannot be shared. If you try to create a second alarm HIDD of a specific class, you will get the error HIDDV_Error_UniqueObject. If you need shared access to this HIDD, use the timer.hidd.

HIDDM_Alarm_TicksToTime(ULONG, struct tv *) Ticks are the smallest intervall an alarm HIDD can provide. This tells how long n ticks would last in real life.

HIDDM_Alarm_TimeToTicks(struct tv *, ULONG ticks) How many ticks would a certain time be ?

HIDDA_Alarm_Time,struct tv *,ISG
This is the time for the next alarm. This implies single shot mode. The hook is called only once. The time is specified as absolute system time.

HIDDA_Alarm_Intervall,struct tv * intervall,ISG
This is the time for the next alarm. This implies repeat mode. The hook is called every time after intervall has elapsed.

HIDDA_Alarm_Hook,struct Hook *,ISG
Call this function when the alarm comes.

HIDDA_Alarm_Active,BOOL,SG
(De-)Activate this alarm HIDD. When created, the alarm hidd is always inactive.

HIDDA_Alarm_Unit,ULONG,G
This is a tag of the class. It contains the unit number you must pass to the timer.hidd if you want to access this alarm HIDD.

6.6.2 Serial HIDD

The type of a serial HIDD is HIDDV_Type_Serial and the names for serial specific things is prefixed with HIDD?_Serial_.

Subtypes of serial HIDDs are HIDDV_Type_Serial_RS232 and HIDDV_Type_Serial_RS488, for example.

HIDDA_Serial_BPSRate,ULONG,ISG
The bits per second or a logical BPS rate (300baud, 600baud, 1200baud, 2400baud, 4800, 9600, 19200, 31500 (MIDI), 38400, etc.) The logical BPS rates have the bit 31 set.

When you query the list of available modes, you will get an HIDDT_Limit for this attribute. If the limits have bit 31 set, the device supports only fixed BPS rates. If the limits don't have this bit set, this means that the device supports variable BPS rates. If you use a logical BPS rate, you must make sure that you don't exceed the limits. For example, some device might support any BPS rate between 5000bps and 100000bps. This means that only the logical BPS rates between 9600 and 74k (including both) are available.

Also note that a HIDD might not support every BPS rate in the range. There might be arbitrary steps, so you must set the BPS rate and then read it back to see what the HIDD can do. The HIDD should always select a BPS rate which is next to the one the user wants.

HIDDA_Serial_DataLength,ULONG,ISG
The number of data bits. Most HIDDs support only 7 or 8 bits but you should expect at least anything between 5 and 8.

HIDDA_Serial_StopBits,ULONG,ISG
The number of stopbits between two data bytes multiplied by 16 (ie. one stopbit is 16, one and a half would be 24 and two stopbits is 32).

6.6.3 Keyboard HIDD

ULONG HIDDM_QueryKeys (ULONG ** keyptr)
Ask for all really available keys on this keyboard. The method will fill in a pointer to a read-only array and return the number of elements in that array. You must not free this array nor write to it.

ULONG HIDDM_QueryKeyStates (ULONG ** keyptr)
Ask for all currently pressed keys on this keyboard. The method will fill in a pointer to an array and return the number of elements in that array.

ULONG HIDDM_FreeKeyStates (ULONG * keyptr)
Free the result of a HIDDM_QueryKeyStates().

HIDDA_Keyboard_Type,ULONG,ISG
If the Keyboard HIDD can work with more than one type of keyboard, you can specify the type here or if the HIDD can figure the type of keyboard itself, it can offer the type here. If the HIDD doesn't support this, this value is 0 and can't be changed by setting it. The method HIDDM_QueryModes() should return a type HIDDT_Limit with min and max both 0.

HIDDA_Keyboard_MsgPort,struct MsgPort *,ISG
When the user presses a key, the HIDD should report this by sending a HIDDT_Keyboard_Event message to this port. The message looks like this:

ke_Key[] contains the X11 code for the key. See /usr/include/X11/keysymdef.h for available keycodes. If the key has been pressed, bit 31 will be set. If the key has been released, bit 31 will be cleared.

If the user pressed more then one key, the other keys are in ke_Key[1], ke_Key[2], etc. The number of keys in the message is calculated by the macro HIDDQ_Keyboard_GetNumKeys(msg).

6.6.4 Graphics HIDD

A graphics HIDD allows to create bitmaps, display them and draw in them.

The graphics HIDD supports the following methods:

IPTR HIDDM_Graphics_QCmd,UWORD Length,UWORD Command,...)
Make the HIDD execute a simple command. Simple commands execute very fast and don't do any checks. They were implemented to give you raw speed when you need it.

Command is the command to execute and Length is the size of the command (including both Command and Length).

The result of HIDDM_Graphics_QCmd() depends on the command which is to be executed.

IPTR HIDDM_Graphics_Cmd,UWORD Length,UWORD Command,...)
Make the HIDD execute a command. The commands executed this way are checked for validity (eg. clipping is performed) and they may take very long to execute.

Command is the command to execute and Length is the size of the command (including both Command and Length).

The result of HIDDM_Graphics_Cmd() depends on the command which is to be executed.

void HIDDM_Graphics_MCmd,UWORD length,UWORD length1, UWORD cmd1, ...)
This is like HIDDM_Graphics_Cmd() but executes more than one command at once. length is the size of all commands plus all parameters. The format of the separate commands is the same as in HIDDM_Graphics_Cmd().

You can't use commands which return values with HIDDM_Graphics_MCmd(). If you use such commands with HIDDM_Graphics_MCmd(), the returned values will be lost.

void HIDDM_Graphics_MQCmd,UWORD length,UWORD length1, UWORD cmd1, ...)
This is like HIDDM_Graphics_QCmd() but executes more than one command at once. length is the size of all commands plus all parameters. The format of the separate commands is the same as in HIDDM_Graphics_QCmd().

void HIDDV_Graphics_Cmd_WaitTOF (void)
Wait for the vertical blank. This is a short time span during which updates of the screen are invisible because the hardware of the monitor moves the ray from the bottom right to the top left corner. This will block until the next time this happens. If you use this command in HIDDM_Graphics_MCmd() or HIDDM_Graphics_MQCmd(), the drawing command after the HIDDV_Graphics_Cmd_WaitTOF() will be executed exactly right after the system has been signalled that the vblank is happening. If several processes try to do this, they will be executed in first-come-first-served order.

BOOL HIDDV_Graphics_Cmd_CheckTOF (void)
Query whether a vertical blank is happening right now. This isn't really useful because you can't use it to draw because in a multitasking system, you might loose the CPU just after HIDDV_Graphics_Cmd_CheckTOF() told you that a vblank is happening right now.

HIDDT_BitMap HIDDV_Graphics_Cmd_CreateBitMap (Tag tag, ...)
Create a drawing area with the specified attributes.

HIDDA_BitMap_Width,ULONG,ISG
Create a bitmap with this width or query the width. Note that most HIDD don't support to resize a bitmap. The width is in HIDD units. Some graphics HIDDs support text mode, then this is in characters. But most of the time, this will be in screen or printer pixels.

HIDDA_BitMap_Height,ULONG,ISG
Create a bitmap with this height or query the height. Note that most HIDD don't support to resize a bitmap. The height is in HIDD units. Some graphics HIDDs support text mode, then this is in characters. But most of the time, this will be in screen or printer pixels.

HIDDA_BitMap_Depth,UWORD,IG
- Create a bitmap with this depth. When the bitmap has been created, you can query the attribute. The number of distinct colors is 1L << depth. Most HIDDs will support depths like 1, 8, 15, 16, 24 and 32 bit.

HIDDA_BitMap_Showable,BOOL,IG
- Create a bitmap which should later be displayed. When the bitmap has been created, you can query the attribute. On some systems, this will also display the bitmap when the method returns. To be safe, always call HIDDV_Graphics_Cmd_ShowBitmap() afterwards.

HIDDA_BitMap_Visible,ULONG,G
Check if a bitmap is visible. Can return HIDDV_Bitmap_Visible_No, HIDDV_Bitmap_Visible_Yes and HIDDV_Bitmap_Visible_Partial (if it's not fully visible).

HIDDA_BitMap_Mode,ULONG,ISG
The display mode. Every HIDD defines its own list and uses its own values. Use the method HIDDM_ValueToString() to get the meanings of this attribute.

HIDDA_BitMap_BaseAddress,APTR,ISG
This is the address of the RAM of the graphics memory. Note that most HIDDs don't support to set this value. This can be used to access the video hardware directly. If you plan this, you must check if the HIDD supports this and if it does, then you must take the appropriate steps specified in the HIDDs' docs to tell the HIDD what you are doing (eg. disable the HIDD). After you did this, you can use HIDDA_Graphics_Format to find out the format in which the data is stored here.

A HIDD which doesn't support direct memory access will return NULL.

HIDDA_BitMap_Format,ULONG,G
Tell the format of the data at HIDDA_BitMap_BaseAddress. See this tag for details.

HIDDA_BitMap_BytesPerRow,ULONG,G
Query the number of bytes which make up one line on the display. This can be different from HIDDA_BitMap_BytesPerPixel * HIDDA_BitMap_Width.

HIDDA_BitMap_BytesPerPixel,ULONG,G
Query the number of bytes which make up one pixel on the display. This can be different from the number of bits divided by eight. If one byte contains informations of several pixels, then this will be 0.

HIDDA_BitMap_BestSize,ULONG,G
Query the HIDD for the best size for drawing areas or drawing commands. Most graphics chips have a certain blocking size, ie. it doesn't matter if you copy 6 bits or 30 but 33 is slow. The HIDD will return 32 in this case.

HIDDA_BitMap_LeftEdge,LONG,IG
Query or initialize the left edge position of a bitmap which is displayable. The position can be change with HIDDV_Graphics_Cmd_MoveBitMap. The value of the position is in HIDD units. Some graphics HIDDs support text mode, then this is in characters. But most of the time, this will be in screen or printer pixels.

HIDDA_BitMap_TopEdge,LONG,IG
Query or initialize the top edge position of a bitmap which is displayable. The position can be change with HIDDV_Graphics_Cmd_MoveBitMap. The value of the position is in HIDD units. Some graphics HIDDs support text mode, then this is in characters. But most of the time, this will be in screen or printer pixels.

ULONG HIDDV_Graphics_Cmd_ShowBitMap (HIDDT_BitMap bm, BOOL wait)
Make a bitmap visible. Some systems allow to show more than one bitmap at a time. On these systems, the specified bitmap appears before all other bitmaps. If wait is TRUE, then the call will block until the bitmap is made visible (ie. at the next HIDDV_Graphics_Cmd_WaitTOF). The call return whether bitmap is visible or not if wait is FALSE or TRUE otherwise.

VOID HIDDV_Graphics_Cmd_MoveBitMap (HIDDT_BitMap bm, WORD horizontal, WORD vertical)
Move a visible bitmap around the screen. Positive values mean move to the left or down, negative values means right and up. If the horizontal and vertical variables you specify would move the bitmap beyond any restrictions then the bitmap is move only as far as possible. You can query the real position to which the bitmap was move with the HIDDA_BitMap_LeftEdge and HIDDA_BitMap_TopEdge attributes.

ULONG HIDDV_Graphics_Cmd_DepthArrangeBitMap (HIDDT_BitMap bm, ULONG mode, HIDDT_BitMap other)
Move a bitmap to the front or back of all bitmaps or a specific bitmap. mode can be HIDDV_Graphics_DepthArrange_ToFront and HIDDV_Graphics_DepthArrange_ToBack. If other is != NULL, then the bitmap will be moved just in front or behind that bitmap. The other is NULL, then bitmap will be moved in front or behind all other bitmaps. If the bitmap was invsible, then HIDDV_Graphics_Cmd_ShowBitMap() will implicitly be called.

void HIDDV_Graphics_Cmd_DeleteBitMap (HIDDT_BitMap bm)
Return a drawing area for reuse. You can also dispose it with DisposeObject().

HIDDT_GC HIDDV_Graphics_Cmd_CreateGC (HIDDT_BitMap bm)
Create a graphics context. The graphics context is used to store information which is needed for more than one command (for example the color or the drawmode). A GC is a BOOPSI object and can be changed with the normal BOOPSI API.

void HIDDV_Graphics_Cmd_DeleteGC (HIDDT_GC gc)
Return a gc for reuse. You can also dispose the GC with DisposeObject(). The bitmap which is connected to this graphics context will not be deleted.

BOOL HIDDV_Graphics_Cmd_CopyArea (HIDDT_GC src, WORD srcX, WORD srcY, UWORD width, UWORD height, HIDDT_GC dest, WORD destX, WORD destY)
Copy a rectangular area from the drawing area src to the drawing area stored in dest (which may be src). The source area is not changed (except when both rectangles overlap). The mode of the GC dest determines how the copy takes place.

In quick mode, the following restrictions are not checked: It's not checked whether the source or destination rectangle is completely inside the valid area or whether the areas overlap. If they overlap, the results are unpredictable. Also drawing modes are ignored. If the two bitmaps in the GCs have a different depth, copying might be slow.

When copying bitmaps between two different HIDDs, the following pseudo algorithm is executed: First the destination HIDD is queried whether it does understand the format of the source HIDD. If it does, then the destination HIDD does the copying. If it doesn't, then the source is asked whether it understands the destination HIDDs' format. If it does, then the source HIDD will do the copying. If it doesn't, then the default CopyArea of the graphics HIDD base class will be invoked which copies the bitmaps pixel by pixel with HIDDV_Graphics_Cmd_GetPixel() and HIDDV_Graphics_Cmd_SetPixel().

BOOL HIDDV_Graphics_Cmd_WritePixelDirect (HIDDT_GC gc, WORD x, WORD y, ULONG val)
Set the pixel at ( x, y) direct to val without making use of the gc attributes like colors, drawmode, colormask etc. This command is available in quick and normal mode.

In quick mode, the pixel is always set, even if the coordinates are illegal, and it will always return 1 (but might crash the machine if the coordinates are invalid).

BOOL HIDDV_Graphics_Cmd_WritePixel (HIDDT_GC gc, WORD x, WORD y)
Changes the pixel at ( x, y). The color of the pixel depends on the attributes of gc, eg. colors, drawmode, colormask etc. This command is available in quick and normal mode.

If the command is executed in normal mode, the coordinates are checked. If the pixel could be set, the command will return 1 else 0.

In quick mode, the pixel is always set, even if the coordinates are illegal, and it will always return 1 (but might crash the machine if the coordinates are invalid).

ULONG HIDDV_Graphics_Cmd_ReadPixel (HIDDT_GC gc, WORD x, WORD y)
Queries the color of the pixel at ( x, y). This command is available in quick and normal mode. When executed in quick mode, the color will be returned as the physical value for that color in the format used by the HIDD. If the command is executed in normal mode, the coordinates are checked and the color returned is a logical color (ie. a 24bit RGB value). If the pixel could be queried, the command will return its value and ~0 (ie. all bits set) otherwise.

Note that in quick mode, the command always returns something but if the coordinates are outside the valid coordinates, this can crash your machine or return random values.

BOOL HIDDV_Graphics_Cmd_DrawLine (HIDDT_GC gc, WORD x1, WORD y1, WORD x2, WORD y2)
Draws a line from ( x1, y1) to ( x2, y2) in the specified gc. This command is available in quick and normal mode. In normal mode, the line is clipped against the drawing area.

BOOL HIDDV_Graphics_Cmd_DrawRect (HIDDT_GC gc, WORD x1, WORD y1, WORD x2, WORD y2)
Draws a hollow rectangle from ( x1, y1) to ( x2, y2) in the specified gc. This command is available in quick and normal mode. In normal mode, the rectangle is clipped against the drawing area.

BOOL HIDDV_Graphics_Cmd_FillRect (HIDDT_GC gc, WORD x1, WORD y1, WORD x2, WORD y2)
Draws a solid rectangle from ( x1, y1) to ( x2, y2) in the specified gc. This command is available in quick and normal mode. In normal mode, the rectangle is clipped against the drawing area.

BOOL HIDDV_Graphics_Cmd_DrawEllipse (HIDDT_GC gc, WORD x1, WORD y1, WORD rx, WORD ry)
Draws a hollow ellipse from ( x1, y1) with the radii rx and ry in the specified gc. This command is available in quick and normal mode. In normal mode, the ellipse is clipped against the drawing area.

BOOL HIDDV_Graphics_Cmd_FillEllipse (HIDDT_GC gc, WORD x1, WORD y1, WORD rx, WORD ry)
Draws a solid ellipse from ( x1, y1) with the radii rx and ry in the specified gc. This command is available in quick and normal mode. In normal mode, the ellipse is clipped against the drawing area.

BOOL HIDDV_Graphics_Cmd_DrawPolygon (HIDDT_GC gc, UWORD n, WORD coords[2*n])
Draws a hollow polygon from the list of coordinates in the specified gc. This command is available in quick and normal mode. In normal mode, the polygon is clipped against the drawing area and no point is drawn twice.

BOOL HIDDV_Graphics_Cmd_FillPolygon (HIDDT_GC gc, UWORD n, WORD coords[2*n])
Draws a solid polygon from ( x1, y1) to ( x2, y2) in the specified gc. This command is available in quick and normal mode. In normal mode, the polygon is clipped against the drawing area and no point is drawn twice.

In quick mode, the polygon should be convex, otherwise the results are unpredictable.

BOOL HIDDV_Graphics_Cmd_DrawText (HIDDT_GC gc, WORD x, WORD y, STRPTR text, UWORD length)
Draws the first length characters of text at ( x, y). This command is available in quick and normal mode. In normal mode, the text is clipped against the drawing area.

BOOL HIDDV_Graphics_Cmd_FillText (HIDDT_GC gc, WORD x, WORD y, STRPTR text, UWORD length)
Fills the area of the text with the background color and draws the first length characters of text at ( x, y). This command is available in quick and normal mode. In normal mode, the text is clipped against the drawing area.

BOOL HIDDV_Graphics_Cmd_FillSpan (HIDDT_GC gc, HIDDT_Span span)
Draws a solid from a shape description in the specified gc. This command is available in quick and normal mode. In normal mode, the spans are clipped against the drawing area.

void HIDDV_Graphics_Cmd_Clear (HIDDT_GC gc)
Sets all pixels of the drawing area to the background color stored in gc. This command is available in quick and normal mode and behaves similar in both modes.

IPTR HIDDV_Graphics_Cmd_Special (...)
This is for HIDD specific commands. You can use this for sending commands to the HIDD which are not covered by this doc. This command is available in quick and normal mode. It's behaviour is HIDD specific.

A HIDDs' GC has the following attributes:

HIDDA_GC_UserData,APTR,SG
The user can store arbitrary data in here.

HIDDA_GC_BitMap,HIDDT_BitMap,G
This is the bitmap which is connected to this GC.

HIDDA_GC_Foreground,ULONG,SG
This is the foreground color.

HIDDA_GC_Background,ULONG,SG
This is the foreground color.

HIDDA_GC_DrawMode,ULONG,SG
This is the draw mode. There are 16 possible modes and they are defined as follows:

The most useful values are HIDDV_GC_DrawMode_Copy ( 0x03) which copies src into dest (this is the default) and HIDDV_GC_DrawMode_XOr ( 0x06) which inverts dest according to src.

HIDDA_GC_Font,HIDDT_Font,SG
The current font.

HIDDA_GC_ColorMask,ULONG,SG
Prevents some color bits from changing. This attribute is only considered in normal mode. This can slow rendering somewhat.

HIDDA_GC_LinePattern,UWORD,SG
Provide a simple pattern while drawing lines. This attribute is only considered in normal mode.

HIDDA_GC_PlaneMask,HIDDT_BitMap,SG
This is a shape bitmap. When drawing into the destination bitmap, only those bits will be changed where this bitmap has bits set. This bitmap can be smaller than the destination bitmap; bits outside this bitmap are considered to be 0.

To disable this, set the attribute to NULL (this is also the default). Note that enabling this slows rendering down, sometimes very much.

6.6.5 Sound HIDD

Okay, here are some examples, how a sound.hidd could be implemented on different hardware-bases. This is how the class would behave, if a method HIDDM_SendMIDI was sent (I don't know, if such a method would make sense, but it's only for illustration issues).

Amiga with internal sound (subclass of hiddclass):

There are two possibilities of how to handle it. The first is to not handle it, so that the method is passed on to the hiddclass (which doesn't know this method either) and then on to the rootclass, which returns 0 (FALSE) on unknown methods. The second possibility is to implement it in soundhiddclass and return FALSE immediatly (because we know that the internal Amiga soundsystem can't handle MIDI).

Amiga with sound-card on zorro-bus (subclass of zorroclass):

The sound-card passes all methods through to its superclass, except methods for playing/receiving/whatever music. It can either implement them totally on its own or might use some features of its superclass, for example a general method for sending data to a zorro-card.

Amiga with internal sound or soundcard and additional MIDI-card:

This configuration would have two HIDDs, one for MIDI only and one for sound in general. For the implementation of the last one see above (either Amiga with internal sound or Amiga with sound-card). The MIDI HIDD-class could subclass the general sound class (without knowing if it is capable of playing MIDI) and pass on all methods except MIDI relevant methods. It would fully overload these. Another solution would be to subclass hiddclass directly and ignore every non-MIDI sound command. While the general class would be unit 0, the MIDI class would be unit 1, so that an application can choose between the normal sound-system (either the internal Amiga soundsystem or a sound-card, which might have MIDI capabilities on its own) or the MIDI card. If the MIDI class would subclass the normal soundhidd, it would feature non-MIDI sound too (by passing the methods on). Of course, it had to pass a query to a HIDDA_Capabilities attribute on to the superclass, so that the capabilities of the superclass can be recognized by the application for unit 1, too.

PC with soundblaster-super-ultra-pro-whatever:

This HIDD could(!) subclass a class, which handles soundblaster-cards in general, i.e. the functions that are common to all soundblaster-card (which itself could subclass something like a pcbusclass). Normally this class would pass all methods on to its superclass, but it could implement some methods on its own or partly overload some methods, where this specific soundblaster-card had advantages/different features than the other soundblaster-cards.

o Some thoughts about the sound.hidd:

o An attribute HIDDA_Capabilities [..G], which could define things like: o HIDDV_Sound_MIDI - sound-system is able to play MIDI sounds (possibly by using an external MIDI device, such as a keyboard) o HIDDV_Sound_SFX - sound-system is capable of playing simple sounds (e.g. the internal pc-speaker) o HIDDV_Sound_Music o HIDDV_Sound_Speech

o Possible attributes HIDDA_Sound_ActivateHook, ..._InactivateHook [ISG] These attributes could be used by an application to provide hooks, which are called if a not-locked unit is exclusively locked by another application (or this exclusive lock is freed). So these attributes makes only sense with HIDDV_Sound_NonExclusiveNotLocked.


prev up next

If you have comments or suggestions, email me at digulla@aros.fh-konstanz.de. 24. Jul 1999