# M68K Trap tasks

[M68K Documentation](https://asm-editor.specy.app/documentation/m68k.md)

Web page: https://asm-editor.specy.app/documentation/m68k/traps

Call an editor service with `trap #15`. Put its decimal task number in D0.B and use the registers listed for its inputs and results. `trap #0` through `trap #14` call handlers installed by the program.

79 entries, each with its own page of markdown:

- [Calling trap #15](https://asm-editor.specy.app/documentation/m68k/traps/calling-trap-15.md): Call a simulator task with trap #15: put the task number in D0.B, set the listed input registers, execute the instruction, then read the output registers.
- [Input routing](https://asm-editor.specy.app/documentation/m68k/traps/differences.md): Interactive reads (tasks 2, 4, 5, and 18) start in the console.
- [Text I/O](https://asm-editor.specy.app/documentation/m68k/traps/text.md) `tasks 0 to 20`: Printed text is appended to the console transcript and drawn on the screen at the text cursor.
- [Display string with CR, LF](https://asm-editor.specy.app/documentation/m68k/traps/task-0.md) `D0.B = 0`: Displays D1.W characters of the string at (A1), at most 255, stopping early at a NUL, then a new line.
- [Display string](https://asm-editor.specy.app/documentation/m68k/traps/task-1.md) `D0.B = 1`: Displays D1.W characters of the string at (A1), at most 255, stopping early at a NUL, without a new line.
- [Read string](https://asm-editor.specy.app/documentation/m68k/traps/task-2.md) `D0.B = 2`: Reads a line ended with Enter from the current input source; a testcase supplies its next scripted input.
- [Display signed number](https://asm-editor.specy.app/documentation/m68k/traps/task-3.md) `D0.B = 3`: Displays D1.L in decimal, in the smallest field it fits.
- [Read number](https://asm-editor.specy.app/documentation/m68k/traps/task-4.md) `D0.B = 4`: Reads a line ended with Enter from the current input source, keeping its first 79 characters and dropping the rest.
- [Read character](https://asm-editor.specy.app/documentation/m68k/traps/task-5.md) `D0.B = 5`: Reads one key from the current input source as soon as it is typed, without waiting for Enter.
- [Display character](https://asm-editor.specy.app/documentation/m68k/traps/task-6.md) `D0.B = 6`: Displays one character.
- [Terminate](https://asm-editor.specy.app/documentation/m68k/traps/task-9.md) `D0.B = 9`: Ends the program.
- [Set or get the text cursor, or clear the screen](https://asm-editor.specy.app/documentation/m68k/traps/task-11.md) `D0.B = 11`: The text cursor is where printed text lands, in character cells counted from the top left.
- [Keyboard echo](https://asm-editor.specy.app/documentation/m68k/traps/task-12.md) `D0.B = 12`: Whether input read by tasks 2, 4, 5 and 18 is echoed in the console and on the screen.
- [Display NUL terminated string with CR, LF](https://asm-editor.specy.app/documentation/m68k/traps/task-13.md) `D0.B = 13`: Displays the NUL terminated string at (A1), then a new line.
- [Display NUL terminated string](https://asm-editor.specy.app/documentation/m68k/traps/task-14.md) `D0.B = 14`: Displays the NUL terminated string at (A1) without a new line.
- [Display unsigned number in a base](https://asm-editor.specy.app/documentation/m68k/traps/task-15.md) `D0.B = 15`: Displays D1.L as an unsigned number in the base in D2.B, using upper case digits past 9: 255 in base 16 is FF.
- [Input prompt and line feed](https://asm-editor.specy.app/documentation/m68k/traps/task-16.md) `D0.B = 16`: Controls the prompt shown while input is waiting and whether a key read of Enter adds a line feed.
- [Display string and number](https://asm-editor.specy.app/documentation/m68k/traps/task-17.md) `D0.B = 17`: Task 14 then task 3: the NUL terminated string, then the signed number.
- [Display string and read number](https://asm-editor.specy.app/documentation/m68k/traps/task-18.md) `D0.B = 18`: Task 14 then task 4: the NUL terminated string as a prompt, then a number from the current input source.
- [Display signed number in a field](https://asm-editor.specy.app/documentation/m68k/traps/task-20.md) `D0.B = 20`: Task 3 right justified in a field D2.B columns wide.
- [Graphics](https://asm-editor.specy.app/documentation/m68k/traps/graphics.md) `tasks 33 to 96`: The origin is the top left, coordinates are signed pixels, and drawing outside the screen is clipped.
- [Colors](https://asm-editor.specy.app/documentation/m68k/traps/colors.md): A color is a long written $00BBGGRR: blue in bits 23-16, green in bits 15-8 and red in bits 7-0.
- [Pictures in files](https://asm-editor.specy.app/documentation/m68k/traps/pictures.md): A program can draw a picture it reads from a file, such as a sprite sheet.
- [Set or get the screen size](https://asm-editor.specy.app/documentation/m68k/traps/task-33.md) `D0.B = 33`: Resizes the screen and clears it.
- [Set pen color](https://asm-editor.specy.app/documentation/m68k/traps/task-80.md) `D0.B = 80`: The color lines, outlines, pixels and text are drawn in.
- [Set fill color](https://asm-editor.specy.app/documentation/m68k/traps/task-81.md) `D0.B = 81`: The color the insides of rectangles and ellipses and a flood fill are drawn in.
- [Draw pixel](https://asm-editor.specy.app/documentation/m68k/traps/task-82.md) `D0.B = 82`: One pixel in the pen color.
- [Get pixel color](https://asm-editor.specy.app/documentation/m68k/traps/task-83.md) `D0.B = 83`: Reads the pixel of the image being drawn on, which with double buffering is the off screen one.
- [Draw line](https://asm-editor.specy.app/documentation/m68k/traps/task-84.md) `D0.B = 84`: A line in the pen color, leaving the drawing point at X2, Y2.
- [Draw line to](https://asm-editor.specy.app/documentation/m68k/traps/task-85.md) `D0.B = 85`: A line in the pen color from the drawing point to X, Y, which becomes the new drawing point: a polyline is one task per point.
- [Move to](https://asm-editor.specy.app/documentation/m68k/traps/task-86.md) `D0.B = 86`: Moves the drawing point without drawing.
- [Draw rectangle](https://asm-editor.specy.app/documentation/m68k/traps/task-87.md) `D0.B = 87`: Filled with the fill color and outlined with the pen.
- [Draw ellipse](https://asm-editor.specy.app/documentation/m68k/traps/task-88.md) `D0.B = 88`: The ellipse inscribed in that rectangle, filled with the fill color and outlined with the pen.
- [Flood fill](https://asm-editor.specy.app/documentation/m68k/traps/task-89.md) `D0.B = 89`: Spreads the fill color from X, Y over every neighbouring pixel of the color that was there, four ways.
- [Draw unfilled rectangle](https://asm-editor.specy.app/documentation/m68k/traps/task-90.md) `D0.B = 90`: The outline of task 87 in the pen color, with nothing inside.
- [Draw unfilled ellipse](https://asm-editor.specy.app/documentation/m68k/traps/task-91.md) `D0.B = 91`: The outline of task 88 in the pen color, with nothing inside.
- [Set drawing mode](https://asm-editor.specy.app/documentation/m68k/traps/task-92.md) `D0.B = 92`: Mode 4 draws normally and is the default; mode 2 moves the drawing point without changing any pixel; mode 16 turns double buffering off and mode 17 turns it…
- [Set pen width](https://asm-editor.specy.app/documentation/m68k/traps/task-93.md) `D0.B = 93`: The width of lines and of the outlines of rectangles and ellipses.
- [Repaint the screen](https://asm-editor.specy.app/documentation/m68k/traps/task-94.md) `D0.B = 94`: Shows the off screen image drawn under mode 17.
- [Draw text at a pixel position](https://asm-editor.specy.app/documentation/m68k/traps/task-95.md) `D0.B = 95`: Draws the string in the pen color with its top left corner at X, Y, over whatever is already there, so a label can sit on a drawing.
- [Get the drawing point](https://asm-editor.specy.app/documentation/m68k/traps/task-96.md) `D0.B = 96`: Where the next line-to would start.
- [Keyboard and mouse](https://asm-editor.specy.app/documentation/m68k/traps/input.md) `tasks 7 to 61`: Poll the keyboard and mouse with these tasks, or configure interrupt requests for key events with task 62 and mouse events with task 60.
- [Key codes](https://asm-editor.specy.app/documentation/m68k/traps/key-codes.md): A letter key is the ASCII code of its capital, so A is $41 and Z is $5A.
- [Check for keyboard input](https://asm-editor.specy.app/documentation/m68k/traps/task-7.md) `D0.B = 7`: Selects screen input and polls without consuming anything: the character it reports is the one task 5 or task 2 reads next.
- [Get key state](https://asm-editor.specy.app/documentation/m68k/traps/task-19.md) `D0.B = 19`: Reads the current state of up to four keys, returning one byte per key in the request order.
- [Enable or disable the simulator shortcut keys](https://asm-editor.specy.app/documentation/m68k/traps/task-24.md) `D0.B = 24`: Accepted and ignored: the screen panel already hands every key it takes to the program, so there are no simulator shortcuts to give up.
- [Read the mouse](https://asm-editor.specy.app/documentation/m68k/traps/task-61.md) `D0.B = 61`: The pointer position is in screen pixels with the same origin drawing uses, whatever the panel’s zoom.
- [Program time](https://asm-editor.specy.app/documentation/m68k/traps/time.md) `tasks 8 to 23`: Reading the clock and delaying execution.
- [Get time](https://asm-editor.specy.app/documentation/m68k/traps/task-8.md) `D0.B = 8`: Returns hundredths of a second since local midnight.
- [Delay](https://asm-editor.specy.app/documentation/m68k/traps/task-23.md) `D0.B = 23`: Lets D1.L hundredths of a second of program time pass.
- [Cycle counter](https://asm-editor.specy.app/documentation/m68k/traps/cycles.md) `tasks 30 to 31`: The cycle counter follows the processor selected by opt p=: 68000 by default, 68010 for opt p=68010, and estimated 68020 counts for opt p=68020.
- [Clear the cycle counter](https://asm-editor.specy.app/documentation/m68k/traps/task-30.md) `D0.B = 30`: Sets the cycle counter to 0, so it counts again from the next instruction.
- [Read the cycle counter](https://asm-editor.specy.app/documentation/m68k/traps/task-31.md) `D0.B = 31`: Reads the counter without changing it.
- [Interrupt requests](https://asm-editor.specy.app/documentation/m68k/traps/interrupts.md) `tasks 32 to 62`: An interrupt request, or IRQ, transfers control to a handler between instructions.
- [Interrupt timers](https://asm-editor.specy.app/documentation/m68k/traps/task-32.md) `D0.B = 32`: D1.B selects the operation: D1.B operation --- --- 4 Return the EASy68K-compatible version value $00051001 in D1.L.
- [Mouse IRQ](https://asm-editor.specy.app/documentation/m68k/traps/task-60.md) `D0.B = 60`: Assigns an IRQ level to each selected mouse event on the screen panel.
- [Keyboard IRQ](https://asm-editor.specy.app/documentation/m68k/traps/task-62.md) `D0.B = 62`: Assigns an IRQ level to each selected key event on the focused screen panel.
- [Files](https://asm-editor.specy.app/documentation/m68k/traps/files.md) `tasks 50 to 59`: Reading and writing files: the ones shown in the editor’s file explorer, never your computer’s disk.
- [Close all files](https://asm-editor.specy.app/documentation/m68k/traps/task-50.md) `D0.B = 50`: Closes every file the program has open.
- [Open an existing file](https://asm-editor.specy.app/documentation/m68k/traps/task-51.md) `D0.B = 51`: Opens the existing file at the path at its start.
- [Open a new file](https://asm-editor.specy.app/documentation/m68k/traps/task-52.md) `D0.B = 52`: Creates the file at the path, or empties the one that is there, and opens it for reading and writing.
- [Read a file](https://asm-editor.specy.app/documentation/m68k/traps/task-53.md) `D0.B = 53`: Reads up to D2.L bytes from the file’s position into the buffer, and moves the position past them.
- [Write a file](https://asm-editor.specy.app/documentation/m68k/traps/task-54.md) `D0.B = 54`: Writes the D2.L bytes at (A1) at the file’s position, growing the file as needed, and moves the position past them.
- [Position a file](https://asm-editor.specy.app/documentation/m68k/traps/task-55.md) `D0.B = 55`: Moves the file’s position to D2.L bytes from its start.
- [Close a file](https://asm-editor.specy.app/documentation/m68k/traps/task-56.md) `D0.B = 56`: Closes the file, so that its number can be given to the next one opened.
- [Delete a file](https://asm-editor.specy.app/documentation/m68k/traps/task-57.md) `D0.B = 57`: Removes the file at the path.
- [File dialog](https://asm-editor.specy.app/documentation/m68k/traps/task-58.md) `D0.B = 58`: Asks for the path of a file, for the program to open with task 51 or create with task 52.
- [Check that a file exists](https://asm-editor.specy.app/documentation/m68k/traps/task-59.md) `D0.B = 59`: Whether there is a file at the path.
- [Sound](https://asm-editor.specy.app/documentation/m68k/traps/sound.md) `tasks 70 to 77`: Play sound files using two separate players.
- [Sound in this editor](https://asm-editor.specy.app/documentation/m68k/traps/sound-differences.md): After a program requests sound, the Sound button appears in the execution dock as a mute/unmute control.
- [Play a sound file](https://asm-editor.specy.app/documentation/m68k/traps/task-70.md) `D0.B = 70`: Plays the WAV file at the path once on the standard player.
- [Load a sound file](https://asm-editor.specy.app/documentation/m68k/traps/task-71.md) `D0.B = 71`: Loads the file into a standard-player slot for task 72 or 76, and returns no value.
- [Play a loaded sound](https://asm-editor.specy.app/documentation/m68k/traps/task-72.md) `D0.B = 72`: Plays the file loaded by task 71 once on the standard player.
- [Play a sound file with DirectX](https://asm-editor.specy.app/documentation/m68k/traps/task-73.md) `D0.B = 73`: Plays the WAV or MIDI file once on the DirectX player, mixed with any other sounds already playing.
- [Load a sound file with DirectX](https://asm-editor.specy.app/documentation/m68k/traps/task-74.md) `D0.B = 74`: Loads the WAV or MIDI file into a DirectX-player slot for task 75 or 77.
- [Play a loaded DirectX sound](https://asm-editor.specy.app/documentation/m68k/traps/task-75.md) `D0.B = 75`: Plays the file loaded by task 74 once, mixed with any other sounds already playing.
- [Control the sound player](https://asm-editor.specy.app/documentation/m68k/traps/task-76.md) `D0.B = 76`: Controls the standard player using a slot loaded by task 71.
- [Control the DirectX sound player](https://asm-editor.specy.app/documentation/m68k/traps/task-77.md) `D0.B = 77`: Controls the DirectX player using a slot loaded by task 74.
- [Unsupported tasks](https://asm-editor.specy.app/documentation/m68k/traps/unsupported.md): Each task listed here stops the program with an error naming the task and the unsupported operation.