mirror of
https://github.com/alfishe/amiga-bootcamp.git
synced 2026-06-13 00:26:28 +00:00
Expand documentation suite: 30+ articles enriched with diagrams, code examples, and hardware details
Graphics: text_fonts (bitmap layout, styles), sprites (DMA, multiplexing), gfx_base (chipset detection), rastport (draw modes, clipping), ham_ehb (mermaid fixes), display_modes (HAM palettes) Devices: scsi (per-model interfaces, Gayle limits, CD-ROM, native vs vendor drivers), console (ANSI sequences, CON:/RAW:), parallel (CIA registers, pinout), timer (resource exhaustion), gameport (quadrature, XOR state) Libraries: workbench (WBStartup, AppWindow/Icon/MenuItem), rexxsyslib (ARexx port hosting, command parsing), diskfont (font directory, colour fonts), keymap (rawkey codes, dead keys), locale (catalogue system, date formatting), layers (ClipRect, refresh types), utility (TagItem chains), icon (DiskObject, ToolTypes), iffparse (IFF structure, ByteRun1), expansion (Zorro AutoConfig) Networking: tcp_ip_stacks (major rewrite - Amiga vs Unix architecture, SANA-II pipeline, PPP/SLIP dial-up, Ethernet cards, MiSTer), bsdsocket (pure API ref), sana2 (buffer hooks, driver requirements), protocols (all code examples). Deduplicated overlap between the three files. Toolchain: debugging (Enforcer patterns, SnoopDOS, GDB remote, kprintf checklist), sasc (pragma encoding, __saveds idioms), stormc (NEW - StormC IDE, C++, PowerPC) References: error_codes (DOS, Exec, trackdisk, Intuition error tables) Driver development: rtg_driver (Native driver analysis, P96 tuning) All 22 README indexes updated. Root README synced with stormc.md entry.
This commit is contained in:
Ilia Sharin
parent
0ded078134
commit
f61c26b542
38 changed files with 6402 additions and 1065 deletions
|
|
@ -4,7 +4,28 @@
|
|||
|
||||
## Overview
|
||||
|
||||
Every Workbench-visible file has a companion `.info` file containing its icon imagery, tooltypes, and default tool. `icon.library` provides reading/writing these structures.
|
||||
Every Workbench-visible file has a companion `.info` file containing its icon imagery, tool types (key=value metadata), default tool, stack size, and position. `icon.library` provides reading, writing, and manipulating these structures.
|
||||
|
||||
The `.info` file format is binary, not text. icon.library handles all serialisation.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph "Disk"
|
||||
FILE["myapp"]
|
||||
INFO["myapp.info"]
|
||||
end
|
||||
|
||||
subgraph "icon.library"
|
||||
GET["GetDiskObject"] --> DO["struct DiskObject"]
|
||||
DO --> IMG["Icon imagery<br/>(selected + unselected)"]
|
||||
DO --> TT["ToolTypes<br/>(key=value strings)"]
|
||||
DO --> DT["DefaultTool<br/>(path to handler)"]
|
||||
DO --> POS["Position<br/>(x, y on Workbench)"]
|
||||
end
|
||||
|
||||
INFO --> GET
|
||||
style DO fill:#e8f4fd,stroke:#2196f3,color:#333
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -14,16 +35,16 @@ Every Workbench-visible file has a companion `.info` file containing its icon im
|
|||
/* workbench/workbench.h — NDK39 */
|
||||
struct DiskObject {
|
||||
UWORD do_Magic; /* $E310 = WB_DISKMAGIC */
|
||||
UWORD do_Version; /* WB_DISKVERSION */
|
||||
struct Gadget do_Gadget; /* the icon gadget */
|
||||
UBYTE do_Type; /* WBDISK, WBTOOL, WBPROJECT, etc. */
|
||||
UWORD do_Version; /* WB_DISKVERSION (1) */
|
||||
struct Gadget do_Gadget; /* the icon gadget (contains imagery) */
|
||||
UBYTE do_Type; /* icon type: WBDISK, WBTOOL, etc. */
|
||||
char *do_DefaultTool; /* default tool path */
|
||||
char **do_ToolTypes; /* NULL-terminated string array */
|
||||
LONG do_CurrentX; /* icon X position */
|
||||
LONG do_CurrentX; /* icon X position on Workbench */
|
||||
LONG do_CurrentY; /* icon Y position */
|
||||
BPTR do_DrawerData; /* drawer window position (BPTR) */
|
||||
char *do_ToolWindow; /* tool window spec */
|
||||
LONG do_StackSize; /* stack size for tool */
|
||||
char *do_ToolWindow; /* tool window spec (CON: string) */
|
||||
LONG do_StackSize; /* stack size for tool launch */
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -31,36 +52,137 @@ struct DiskObject {
|
|||
|
||||
## Icon Types
|
||||
|
||||
| Constant | Value | Description |
|
||||
|---|---|---|
|
||||
| `WBDISK` | 1 | Disk/volume icon |
|
||||
| `WBDRAWER` | 2 | Drawer (directory) |
|
||||
| `WBTOOL` | 3 | Executable tool |
|
||||
| `WBPROJECT` | 4 | Project (document) |
|
||||
| `WBGARBAGE` | 5 | Trashcan |
|
||||
| `WBDEVICE` | 6 | Device |
|
||||
| `WBKICK` | 7 | Kickstart disk |
|
||||
| `WBAPPICON` | 8 | AppIcon (OS 2.0+) |
|
||||
| Constant | Value | Description | Workbench Behaviour |
|
||||
|---|---|---|---|
|
||||
| `WBDISK` | 1 | Disk/volume icon | Opens drawer showing disk contents |
|
||||
| `WBDRAWER` | 2 | Drawer (directory) | Opens drawer window |
|
||||
| `WBTOOL` | 3 | Executable tool | Launches the program |
|
||||
| `WBPROJECT` | 4 | Project (document) | Launches `do_DefaultTool` with this file as argument |
|
||||
| `WBGARBAGE` | 5 | Trashcan | Special drawer for deleted files |
|
||||
| `WBDEVICE` | 6 | Device | Shown in Workbench root |
|
||||
| `WBKICK` | 7 | Kickstart disk | ROM update disk |
|
||||
| `WBAPPICON` | 8 | AppIcon (OS 2.0+) | Application-registered dynamic icon |
|
||||
|
||||
---
|
||||
|
||||
## ToolTypes
|
||||
|
||||
ToolTypes are key=value strings stored in `do_ToolTypes`:
|
||||
## Reading Icons
|
||||
|
||||
```c
|
||||
struct Library *IconBase = OpenLibrary("icon.library", 0);
|
||||
|
||||
/* Load a DiskObject from disk: */
|
||||
struct DiskObject *dobj = GetDiskObject("SYS:Utilities/MultiView");
|
||||
if (dobj)
|
||||
{
|
||||
Printf("Type: %ld\n", dobj->do_Type);
|
||||
Printf("Default tool: %s\n", dobj->do_DefaultTool ?
|
||||
dobj->do_DefaultTool : "(none)");
|
||||
Printf("Stack: %ld bytes\n", dobj->do_StackSize);
|
||||
|
||||
FreeDiskObject(dobj);
|
||||
}
|
||||
|
||||
/* Get the default icon for a file type: */
|
||||
struct DiskObject *defIcon = GetDefDiskObject(WBPROJECT);
|
||||
/* ... use defIcon ... */
|
||||
FreeDiskObject(defIcon);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ToolTypes — Key/Value Metadata
|
||||
|
||||
ToolTypes are the Amiga's equivalent of application-specific metadata. They're stored as a NULL-terminated array of strings in the `.info` file.
|
||||
|
||||
```c
|
||||
/* Example .info file ToolTypes:
|
||||
PUBSCREEN=Workbench
|
||||
NOBLITTER=YES
|
||||
DONOTWAIT
|
||||
CX_PRIORITY=0
|
||||
(DISABLED_OPTION)
|
||||
*/
|
||||
|
||||
struct DiskObject *dobj = GetDiskObject("myapp");
|
||||
if (dobj) {
|
||||
char *val = FindToolType(dobj->do_ToolTypes, "PUBSCREEN");
|
||||
if (val) Printf("Screen: %s\n", val);
|
||||
if (MatchToolValue(FindToolType(dobj->do_ToolTypes, "FLAGS"), "DEBUG"))
|
||||
Printf("Debug mode\n");
|
||||
if (dobj)
|
||||
{
|
||||
/* Find a specific ToolType: */
|
||||
char *screen = FindToolType(dobj->do_ToolTypes, "PUBSCREEN");
|
||||
if (screen)
|
||||
Printf("Public screen: %s\n", screen); /* "Workbench" */
|
||||
|
||||
/* Check if a ToolType exists (no value): */
|
||||
if (FindToolType(dobj->do_ToolTypes, "DONOTWAIT"))
|
||||
Printf("DONOTWAIT is set\n");
|
||||
|
||||
/* Check for a specific value within a multi-value ToolType: */
|
||||
char *flags = FindToolType(dobj->do_ToolTypes, "FLAGS");
|
||||
if (MatchToolValue(flags, "DEBUG"))
|
||||
Printf("Debug mode enabled\n");
|
||||
|
||||
/* Enumerate all ToolTypes: */
|
||||
char **tt = dobj->do_ToolTypes;
|
||||
while (*tt)
|
||||
{
|
||||
Printf(" ToolType: %s\n", *tt);
|
||||
tt++;
|
||||
}
|
||||
|
||||
FreeDiskObject(dobj);
|
||||
}
|
||||
```
|
||||
|
||||
### ToolType Conventions
|
||||
|
||||
| Convention | Meaning | Example |
|
||||
|---|---|---|
|
||||
| `KEY=VALUE` | Named setting with value | `PUBSCREEN=Workbench` |
|
||||
| `KEY` (no value) | Boolean flag — presence = true | `DONOTWAIT` |
|
||||
| `(KEY)` | Disabled/commented out | `(CX_POPUP=NO)` |
|
||||
| `KEY=val1|val2` | Multi-value (check with `MatchToolValue`) | `FLAGS=DEBUG|VERBOSE` |
|
||||
|
||||
---
|
||||
|
||||
## Writing / Modifying Icons
|
||||
|
||||
```c
|
||||
/* Write a DiskObject to disk: */
|
||||
PutDiskObject("myfile", dobj);
|
||||
|
||||
/* Create a new icon programmatically: */
|
||||
struct DiskObject *newIcon = GetDefDiskObject(WBPROJECT);
|
||||
newIcon->do_DefaultTool = "SYS:Utilities/MultiView";
|
||||
newIcon->do_StackSize = 8192;
|
||||
|
||||
char *toolTypes[] = {
|
||||
"PUBSCREEN=Workbench",
|
||||
"DONOTWAIT",
|
||||
NULL
|
||||
};
|
||||
newIcon->do_ToolTypes = toolTypes;
|
||||
|
||||
PutDiskObject("myfile", newIcon);
|
||||
FreeDiskObject(newIcon);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## OS 3.5+ New-Style Icons
|
||||
|
||||
AmigaOS 3.5 introduced **true-colour icons** (PNG-based) alongside the legacy planar format. The `icon.library` v46+ handles both transparently — `GetDiskObject` returns the best available format.
|
||||
|
||||
| Feature | Legacy (OS 1.x–3.1) | New-Style (OS 3.5+) |
|
||||
|---|---|---|
|
||||
| Format | Planar bitplane imagery | PNG/true-colour embedded |
|
||||
| Colours | 4–16 (Workbench palette) | 24-bit true colour |
|
||||
| Size | Fixed (standard sizes) | Scalable |
|
||||
| Transparency | 1-bit mask | 8-bit alpha channel |
|
||||
| Storage | `do_Gadget.GadgetRender` | Extended chunks in `.info` |
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- NDK39: `workbench/workbench.h`, `workbench/icon.h`
|
||||
- ADCD 2.1: icon.library autodocs
|
||||
- See also: [workbench.md](workbench.md) — Workbench integration (AppIcon, AppWindow)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue