in programming language):
-| # | name | stack footprint | description |
-|----+----------+--------------------------------------+-------------------------------------------------------------|
-| 0 | [[id:4f0dee8a-647e-4d91-a252-aaf4782b5edc][nop]] | -- | No operation |
-| 1 | [[#halt][halt]] | -- | Halt CPU (exit emulator) |
-| 2 | [[id:820b1b90-4f4c-4ab1-b49f-9b4a52ea2528][kbd@]] | -- c | Read scancode of pressed or released key |
-| 3 | [[id:8721dc8c-b237-4e9a-a509-0ded1c02329b][num]] | -- n | Put immidiate number into datastack |
-| 4 | [[#jmp][jmp]] | -- | Jump to specified code |
-| 5 | [[#call][call]] | | Jump to specified code, save return address to return stack |
-| 6 | [[#section][1+]] | n -- n+1 | |
-| 7 | [[#section-1][1-]] | n -- n-1 | |
-| 8 | [[#dup][dup]] | n -- n n | Duplicate top of data stack |
-| 9 | [[#drop][drop]] | n -- | Drop last element in data stack |
-| 10 | [[#if][if]] | n -- | Jump to addr if top element was 0 |
-| 11 | [[#ret][ret]] | | Jump to code, specified in return stack. |
-| 12 | [[#c][c@]] | addr -- n | Read byte from memory at specified address |
-| 13 | [[#c-1][c!]] | n addr -- | Store byte to specified memory |
-| 14 | [[#push][push]] | DSTK -> RSTK | Move top of datastack to returnstack |
-| 15 | [[id:21871d09-4d58-440f-8c94-231105aa4e3f][pop]] | RSTK -> DSTK | Move top of returnstack to datastack |
-| 16 | <unused> | | |
-| 17 | [[#rot][rot]] | n1 n2 n3 -- n2 n3 n1 | Rotate stack elements |
-| 18 | [[#disk][disk@]] | FromDiskSect ToMem -- | Read 1KB from disk into RAM |
-| 19 | [[#disk-1][disk!]] | FromMem ToDiskSect -- | Write 1KB to disk |
-| 20 | [[#section-2][@]] | addr -- n | Read 32 bit number from memory |
-| 21 | [[#section-3][!]] | n addr -- | Store 32 bit number to memory |
-| 22 | [[#over][over]] | n1 n2 -- n1 n2 n1 | |
-| 23 | [[#swap][swap]] | n1 n2 -- n2 n1 | |
-| 24 | [[#section-4][+]] | n1 n2 -- n1+n2 | |
-| 25 | [[#section-5][-]] | n1 n2 -- n1-n2 | |
-| 26 | [[#section-6][*]] | n1 n2 -- n1*n2 | |
-| 27 | [[#section-7][/]] | n1 n2 -- n1/n2 | |
-| 28 | [[#section-8][>]] | n1 n2 -- result | Is true when n1 > n2 |
-| 29 | [[#section-9][<]] | n1 n2 -- result | Is true when n1 < n2 |
-| 30 | [[#not][not]] | n1 -- not_n1 | Logical not |
-| 31 | [[#i][i]] | -- n | Copies top of return stack into datastack |
-| 32 | [[#cprt][cprt@]] | addr -- n | Read one byte from hardware port |
-| 33 | [[#cprt-1][cprt!]] | n addr -- | Store one byte to hardware port |
-| 34 | [[#i2][i2]] | -- n | Like "i" but takes second top stack element |
-| 35 | [[#i3][i3]] | -- n | Like "i" but takes third top stack element |
-| 36 | [[#shl][shl]] | n amount -- n | Left bit shift |
-| 37 | [[#shr][shr]] | n amount -- n | Right bit shift |
-| 38 | [[#or][or]] | n1 n2 -- n | Logical or |
-| 39 | [[#xor][xor]] | n1 n2 -- n | Exclusive logical or |
-| 40 | [[#vidmap][vidmap]] | addr -- | Copy memory from "addr" to video memory |
-| 41 | [[#mouse][mouse@]] | -- x y button | Read mouse coordinates & buttons |
-| 42 | [[id:238e8b03-57b6-424d-bfee-b6bb652cefbc][vidput]] | addr1 addr2 x y -- | Put image1 into image2, at location x, y |
-| 43 | [[id:79e1916f-4103-42cc-ac10-bb1ee776ed50][cmove]] | addr1 addr2 amount | Move memory from addr1 to addr2 |
-| 44 | [[#cfill][cfill]] | c addr amount -- | Fill memory starting at "addr" with "c" bytes |
-| 45 | [[id:ab45247c-44c3-464d-9e2a-337f483b4616][tvidput]] | addr1 addr2 x y -- | Put image with transparency support |
-| 46 | [[id:77fa76d3-9cd0-49c1-882c-f30383347352][depth]] | -- depth | Returns current depth of data stack. |
-| 47 | [[id:4bb479cf-aae0-4128-9868-f016c286a162][charput]] | colorfg colorbg addrsrc addrdest x y | Draw text character |
+| # | Name | Stack effect | Description | Notes |
+|----+----------+-----------------------+----------------------------------------------------------+---------------------------------------------------------------------|
+| 0 | [[id:4f0dee8a-647e-4d91-a252-aaf4782b5edc][nop]] | -- | No operation | |
+| 1 | [[#halt][halt]] | -- | Halt CPU (exit emulator) | |
+| 2 | [[id:820b1b90-4f4c-4ab1-b49f-9b4a52ea2528][kbd@]] | -- scancode | Read scancode of pressed or released key | |
+| 3 | [[id:8721dc8c-b237-4e9a-a509-0ded1c02329b][num]] | -- n | Push immediate 32-bit number onto data stack | |
+| 4 | [[#jmp][jmp]] | -- | Unconditional jump to specified address | |
+| 5 | [[#call][call]] | | Call subroutine (save return address on return stack) | |
+| 6 | [[#section][1+]] | n -- n+1 | Increment top of data stack by 1 | |
+| 7 | [[#section-1][1-]] | n -- n-1 | Decrement top of data stack by 1 | |
+| 8 | [[#dup][dup]] | n -- n n | Duplicate top of data stack | |
+| 9 | [[#drop][drop]] | n -- | Drop top of data stack | |
+| 10 | [[#if][if]] | n -- | Jump to address if top of stack is zero | |
+| 11 | [[#ret][ret]] | | Return from subroutine (pop return address) | |
+| 12 | [[#c][c@]] | addr -- byte | Read byte from memory at specified address | |
+| 13 | [[#c-1][c!]] | byte addr -- | Store byte to specified memory address | |
+| 14 | [[#push][push]] | n -- | Move top of data stack to return stack | |
+| 15 | [[id:21871d09-4d58-440f-8c94-231105aa4e3f][pop]] | -- n | Move top of return stack to data stack | |
+| 16 | <unused> | | | |
+| 17 | [[#rot][rot]] | n1 n2 n3 -- n2 n3 n1 | Rotate top three stack elements | |
+| 18 | [[#disk][disk@]] | sector addr -- | Read 1KB from disk into RAM at specified address | |
+| 19 | [[#disk-1][disk!]] | addr sector -- | Write 1KB from RAM to disk at specified sector | |
+| 20 | [[#section-2][@]] | addr -- n | Read 32-bit value from memory | |
+| 21 | [[#section-3][!]] | n addr -- | Store 32-bit value to memory | |
+| 22 | [[#over][over]] | n1 n2 -- n1 n2 n1 | Duplicate second item on data stack | |
+| 23 | [[#swap][swap]] | n1 n2 -- n2 n1 | Swap top two items on data stack | |
+| 24 | [[#section-4][+]] | n1 n2 -- n1+n2 | Add top two items on data stack | |
+| 25 | [[#section-5][-]] | n1 n2 -- n1-n2 | Subtract second item from top item on data stack | TODO: verify argument order |
+| 26 | [[#section-6][*]] | n1 n2 -- n1*n2 | Multiply top two items on data stack | |
+| 27 | [[#section-7][/]] | n1 n2 -- n1/n2 | Divide top item by second item on data stack | TODO: verify argument order |
+| 28 | [[#section-8][>]] | n1 n2 -- result | Compare n1 > n2 (returns true, false otherwise) | TODO: document, what true and false means |
+| 29 | [[#section-9][<]] | n1 n2 -- result | Compare n1 < n2 (returns true, false otherwise) | TODO: document, what true and false means |
+| 30 | [[#not][not]] | n -- ~n | Bitwise NOT on top of data stack | |
+| 31 | [[#i][i]] | -- n | Push top of return stack to data stack | |
+| 32 | [[#cprt][cprt@]] | port -- byte | Read byte from hardware I/O port | |
+| 33 | [[#cprt-1][cprt!]] | byte port -- | Write byte to hardware I/O port | |
+| 34 | [[#i2][i2]] | -- n | Push second item from return stack to data stack | |
+| 35 | [[#i3][i3]] | -- n | Push third item from return stack to data stack | |
+| 36 | [[#shl][shl]] | value shift -- result | Left shift value by shift amount | TODO: Document example. What happens to bits that are shifted away? |
+| 37 | [[#shr][shr]] | value shift -- result | Right shift value by shift amount | |
+| 38 | [[#or][or]] | n1 n2 -- result | Bitwise OR of top two items on data stack | |
+| 39 | [[#xor][xor]] | n1 n2 -- result | Bitwise XOR of top two items on data stack | |
+| 40 | [[#vidmap][vidmap]] | addr -- | Copy memory to video memory | |
+| 41 | [[#mouse][mouse@]] | -- x y buttons | Read mouse coordinates and button states | |
+| 42 | [[id:238e8b03-57b6-424d-bfee-b6bb652cefbc][vidput]] | addr1 addr2 x y -- | Blit image1 to image2 at (x,y) without transparency | |
+| 43 | [[id:79e1916f-4103-42cc-ac10-bb1ee776ed50][cmove]] | addr1 addr2 len -- | Copy memory block from addr1 to addr2 | |
+| 44 | [[#cfill][cfill]] | byte addr len -- | Fill memory with specified byte value | |
+| 45 | [[id:ab45247c-44c3-464d-9e2a-337f483b4616][tvidput]] | addr1 addr2 x y -- | Blit image1 to image2 at (x,y) with transparency support | |
+| 46 | [[id:77fa76d3-9cd0-49c1-882c-f30383347352][depth]] | -- depth | Push current data stack depth | |
+| 47 | [[id:4bb479cf-aae0-4128-9868-f016c286a162][charput]] | fg bg src dest x y -- | Draw character from source buffer to destination buffer | |
** nop
:PROPERTIES:
opcode.
- *Notes:* The value is loaded from =[es:esi]=, then =esi= is
incremented by 4 to skip over the immediate data.
+- *Example:*
+ #+begin_example
+ 42 ; Push 42 onto stack
+ num
+ #+end_example
** jmp
:PROPERTIES:
by the next 32-bit value in the instruction stream.
- *Notes:* The target address is added to =xms_addr= to convert from
virtual to physical memory address before jumping.
+- *Example:*
+ #+begin_example
+ 0x1000 ; Jump target address
+ jmp
+ #+end_example
** call
:PROPERTIES:
before jumping.
- *Notes:* The return address is pushed to the return stack before the
jump occurs.
+- *Example:*
+ #+begin_example
+ 0x2000 ; Subroutine address
+ call
+ #+end_example
** 1+
:PROPERTIES:
- *Stack Effect:* =n -- n+1=
- *Description:* Increments the top value on the data stack by 1.
- *Notes:* Directly increments the dword at the data stack pointer.
+- *Example:*
+ #+begin_example
+ 5
+ 1+
+ #+end_example
+ After execution, stack contains 6.
** 1-
:PROPERTIES:
- *Stack Effect:* =n -- n-1=
- *Description:* Decrements the top value on the data stack by 1.
- *Notes:* Directly decrements the dword at the data stack pointer.
+- *Example:*
+ #+begin_example
+ 10
+ 1-
+ #+end_example
+ After execution, stack contains 9.
** dup
:PROPERTIES:
- *Stack Effect:* =n -- n n=
- *Description:* Duplicates the top value on the data stack.
- *Notes:* Creates a copy of the top item and pushes it onto the stack.
+- *Example:*
+ #+begin_example
+ 42
+ dup
+ #+end_example
+ After execution, stack contains 42 42.
** drop
:PROPERTIES:
- *Stack Effect:* =n --=
- *Description:* Removes the top value from the data stack.
- *Notes:* Simply increments the data stack pointer by 4 bytes.
+- *Example:*
+ #+begin_example
+ 42
+ drop
+ #+end_example
+ After execution, stack is empty.
** if
:PROPERTIES:
Otherwise, skips the address.
- *Notes:* Used for conditional branching. The address is added to
=xms_addr= for physical address conversion.
+- *Example:*
+ #+begin_example
+ 0
+ 0x1000 ; Jump target if zero
+ if
+ #+end_example
** ret
:PROPERTIES:
- *Description:* Returns from a subroutine by popping the return address
from the return stack and jumping to it.
- *Notes:* The return stack pointer is incremented after the jump.
+- *Example:*
+ #+begin_example
+ ret
+ #+end_example
** c@
:PROPERTIES:
Replaces the address on the stack with the byte value.
- *Notes:* The address is adjusted by =xms_addr= to convert to physical
memory before reading.
+- *Example:*
+ #+begin_example
+ 0x1000 ; Read from address 0x1000
+ c@
+ #+end_example
+ After execution, stack contains the byte at address 0x1000.
** c!
:PROPERTIES:
:CUSTOM_ID: c-1
:ID: f129ef87-a31a-40fe-b8d3-984da2db90e2
:END:
-- *Stack Effect:* =n addr --=
+- *Stack Effect:* =byte addr --=
- *Description:* Stores a byte value to the specified memory address.
- *Notes:* Takes two values from the stack: the byte to store and the
address. The address is adjusted by =xms_addr= before writing.
+- *Example:*
+ #+begin_example
+ 0x42 ; Byte to store
+ 0x1000 ; Address to store to
+ c!
+ #+end_example
** push
:PROPERTIES:
:CUSTOM_ID: push
:ID: e4bcbaf1-7724-4051-b19c-1aa7cd06eae6
:END:
-- *Stack Effect:* =DSTK -> RSTK=
+- *Stack Effect:* =n --=
- *Description:* Moves the top value from the data stack to the return
stack.
- *Notes:* Used for transferring values between the two stacks without
modifying the value.
+- *Example:*
+ #+begin_example
+ 42
+ push
+ #+end_example
+ After execution, data stack is empty and return stack contains 42.
** pop
:PROPERTIES:
:ID: 21871d09-4d58-440f-8c94-231105aa4e3f
:END:
-- *Stack Effect:* =RSTK -> DSTK=
+- *Stack Effect:* =-- n=
- *Description:* Moves the top value from the return stack to the data
stack.
- *Notes:* Used for transferring values between the two stacks without
modifying the value.
+- *Example:*
+ #+begin_example
+ pop
+ #+end_example
+ After execution, data stack contains the value that was on top of the return stack.
** rot
:PROPERTIES:
third item becomes the top, the top becomes the second, and the second
becomes the third.
- *Notes:* Useful for reordering stack items without temporary storage.
+- *Example:*
+ #+begin_example
+ 1 2 3
+ rot
+ #+end_example
+ After execution, stack contains 2 3 1.
** disk@
:PROPERTIES:
specified sector into the specified memory address.
- *Notes:* The sector number is the top of the stack, followed by the
destination address. The disk is accessed via DOS interrupt calls.
+- *Example:*
+ #+begin_example
+ 16 ; Sector 16
+ 0x2000 ; Destination address
+ disk@
+ #+end_example
** disk!
:PROPERTIES:
- *Notes:* The destination address is on top of the stack, followed by
the sector number. Data is first copied to a temporary buffer before
writing.
+- *Example:*
+ #+begin_example
+ 0x2000 ; Source address
+ 16 ; Sector 16
+ disk!
+ #+end_example
** @
:PROPERTIES:
Replaces the address on the stack with the value.
- *Notes:* The address is adjusted by =xms_addr= before reading. This is
the 32-bit equivalent of =c@=.
+- *Example:*
+ #+begin_example
+ 0x1000 ; Read 32-bit value from address 0x1000
+ @
+ #+end_example
** !
:PROPERTIES:
- *Description:* Stores a 32-bit value to the specified memory address.
- *Notes:* Takes two values: the value to store and the address. The
address is adjusted by =xms_addr= before writing.
+- *Example:*
+ #+begin_example
+ 0x12345678 ; Value to store
+ 0x1000 ; Address to store to
+ !
+ #+end_example
** over
:PROPERTIES:
it on top.
- *Notes:* Commonly used to access the second item without popping the
top item.
+- *Example:*
+ #+begin_example
+ 1 2
+ over
+ #+end_example
+ After execution, stack contains 1 2 1.
** swap
:PROPERTIES:
- *Description:* Swaps the top two values on the data stack.
- *Notes:* Essential for reordering stack items during complex
operations.
+- *Example:*
+ #+begin_example
+ 1 2
+ swap
+ #+end_example
+ After execution, stack contains 2 1.
** +
:PROPERTIES:
replaces both values.
- *Notes:* Performs unsigned 32-bit addition. The top value (n1) is
added to the second value (n2).
+- *Example:*
+ #+begin_example
+ 1 2
+ +
+ #+end_example
+ After execution, stack contains 3.
** -
:PROPERTIES:
data stack. The result replaces both values.
- *Notes:* Performs unsigned 32-bit subtraction. The second value (n2)
minus the top value (n1).
+- *Example:*
+ #+begin_example
+ 1 2
+ -
+ #+end_example
+ After execution, stack contains 1 (2 - 1).
** *
:PROPERTIES:
result replaces both values.
- *Notes:* Uses 32-bit signed multiplication (IMUL). The top value (n1)
is multiplied by the second value (n2).
+- *Example:*
+ #+begin_example
+ 2 3
+ *
+ #+end_example
+ After execution, stack contains 6.
** /
:PROPERTIES:
stack. The quotient replaces both values.
- *Notes:* Uses signed integer division (IDIV). The second value (n2) is
divided by the top value (n1).
+- *Example:*
+ #+begin_example
+ 2 6
+ /
+ #+end_example
+ After execution, stack contains 3 (6 / 2).
** >
:PROPERTIES:
:ID: abcc14d3-6cbf-46c3-8a93-ee7180f350d4
:END:
- *Stack Effect:* =n1 n2 -- result=
-- *Description:* Compares the second value with the top value. Returns
- -1 (true) if n1 > n2, otherwise 0.
+- *Description:* Compares the second value (n1) with the top value (n2).
+ Returns -1 (true) if n1 > n2, otherwise 0.
- *Notes:* The comparison is between the second item (n1) and top item
(n2) on the stack.
+- *Example:*
+ #+begin_example
+ 2 3
+ >
+ #+end_example
+ After execution, stack contains 0 (since 2 < 3).
** <
:PROPERTIES:
:ID: 68362f38-c9e4-43f8-809c-8e15725a58c8
:END:
- *Stack Effect:* =n1 n2 -- result=
-- *Description:* Compares the second value with the top value. Returns
- -1 (true) if n1 < n2, otherwise 0.
+- *Description:* Compares the second value (n1) with the top value (n2).
+ Returns -1 (true) if n1 < n2, otherwise 0.
- *Notes:* The comparison is between the second item (n1) and top item
(n2) on the stack.
+- *Example:*
+ #+begin_example
+ 2 3
+ <
+ #+end_example
+ After execution, stack contains -1 (since 2 < 3).
** not
:PROPERTIES:
- *Description:* Performs a bitwise NOT operation on the top value of
the data stack.
- *Notes:* Inverts all bits of the dword at the top of the stack.
+- *Example:*
+ #+begin_example
+ 0x0000FFFF
+ not
+ #+end_example
+ After execution, stack contains 0xFFFF0000.
** i
:PROPERTIES:
data stack.
- *Notes:* Commonly used to access loop counters or subroutine
parameters.
+- *Example:*
+ #+begin_example
+ 42
+ push
+ i
+ #+end_example
+ After execution, data stack contains 42.
** cprt@
:PROPERTIES:
- *Description:* Reads a byte from the specified hardware I/O port.
- *Notes:* Uses IN instruction to read from the port. Replaces the port
address with the read byte.
+- *Example:*
+ #+begin_example
+ 0x60 ; Keyboard port
+ cprt@
+ #+end_example
** cprt!
:PROPERTIES:
- *Description:* Writes a byte to the specified hardware I/O port.
- *Notes:* Uses OUT instruction to write to the port. Consumes both the
byte and port address.
+- *Example:*
+ #+begin_example
+ 0x42 ; Byte to write
+ 0x60 ; Keyboard port
+ cprt!
+ #+end_example
** i2
:PROPERTIES:
data stack.
- *Notes:* Useful for accessing deeper items in the return stack without
popping.
+- *Example:*
+ #+begin_example
+ 1 2
+ push push
+ i2
+ #+end_example
+ After execution, data stack contains 1.
** i3
:PROPERTIES:
data stack.
- *Notes:* Allows access to the third item in the return stack for
deeper subroutine contexts.
+- *Example:*
+ #+begin_example
+ 1 2 3
+ push push push
+ i3
+ #+end_example
+ After execution, data stack contains 1.
** shl
:PROPERTIES:
bits.
- *Notes:* The shift amount is the top item, and the value to shift is
the second item. Uses SHL instruction.
+- *Example:*
+ #+begin_example
+ 2 ; Shift amount
+ 1 ; Value to shift
+ shl
+ #+end_example
+ After execution, stack contains 2 (1 << 2).
** shr
:PROPERTIES:
bits.
- *Notes:* The shift amount is the top item, and the value to shift is
the second item. Uses SHR instruction.
+- *Example:*
+ #+begin_example
+ 1 ; Shift amount
+ 2 ; Value to shift
+ shr
+ #+end_example
+ After execution, stack contains 1 (2 >> 1).
** or
:PROPERTIES:
- *Stack Effect:* =n1 n2 -- n1|n2=
- *Description:* Performs a bitwise OR operation on the top two values.
- *Notes:* The top value (n1) is ORed with the second value (n2).
+- *Example:*
+ #+begin_example
+ 1 2
+ or
+ #+end_example
+ After execution, stack contains 3 (0b01 | 0b10).
** xor
:PROPERTIES:
- *Stack Effect:* =n1 n2 -- n1^n2=
- *Description:* Performs a bitwise XOR operation on the top two values.
- *Notes:* The top value (n1) is XORed with the second value (n2).
+- *Example:*
+ #+begin_example
+ 1 2
+ xor
+ #+end_example
+ After execution, stack contains 3 (0b01 ^ 0b10).
** vidmap
:PROPERTIES:
- Restore original segments and clean up stack.
*** Example
-:PROPERTIES:
-:CUSTOM_ID: example-4
-:END:
Copy a 640x480x8 image (307,200 bytes) from memory at =0x10000= to video
memory:
-
-1. *Stack Operation*:
-
- #+begin_example
- 0x10000
- vidmap
- #+end_example
-
-2. *Result*:
-
- - The image data is copied to video memory.
- - For 640x480x8 mode, 307,200 bytes are copied across multiple VESA
- pages.
+#+begin_example
+0x10000
+vidmap
+#+end_example
*** Notes
for 640x480x8).
- Requires VESA BIOS support and proper initialization via
=set_vesa_mode=.
+
** mouse@
:PROPERTIES:
:CUSTOM_ID: mouse
Stack Footprint:
: -- x y buttons
-*** Description
+*Description:*
Reads the current mouse position and button states from the mouse
driver. Returns three values on the stack:
- Y-coordinate,
- button states.
-*** Parameters
- *Returns*:
- *x* (32-bit): Current X-coordinate of the mouse cursor (0-based).
- Bit 1: Right button (1 = pressed)
- Bit 2: Middle button (1 = pressed)
+*Example:*
+
+#+begin_example
+mouse@
+#+end_example
+After execution, stack contains buttons (top), y, x (bottom).
+
** vidput - put image1 into image2, at location x, y
:PROPERTIES:
:ID: 238e8b03-57b6-424d-bfee-b6bb652cefbc
coordinates with clipping. Unlike =tvidput=, there is no transparency
support - every pixel is copied regardless of value.
-*** Parameters
+*Parameters:*
- *addr1* (32-bit): Address of the source image structure (width,
height, data address).
- *y* (32-bit): Y-coordinate in the destination image where the copy
starts.
-*** Image Structure Format
+*Image Structure Format:*
Identical to =tvidput=:
- *Offset 0*: Image width (32-bit)
- *Offset 4*: Image height (32-bit)
- *Offset 8*: Base address of image data (32-bit pointer)
-*** Example
-Same as =tvidput= example but without transparency handling. Copying a
-100x100 image from =0x1000= to =0x2000= at (50, 50) would copy all
-pixels (including those with value 255).
+*Example:*
+#+begin_example
+0x1000 ; Source image structure
+0x2000 ; Destination image structure
+50 ; x
+50 ; y
+vidput
+#+end_example
** cmove - copy memory array
:PROPERTIES:
- *Notes:* If =addr1 > addr2=, copies backwards to avoid data
corruption; otherwise copies forwards.
+- *Example:*
+ #+begin_example
+ 100 ; Length
+ 0x2000 ; Destination address
+ 0x1000 ; Source address
+ cmove
+ #+end_example
** cfill
:PROPERTIES:
specified byte value.
- *Notes:* Simple byte-by-byte filling operation. Used for initializing
memory regions.
+- *Example:*
+ #+begin_example
+ 0xFF ; Fill byte
+ 0x1000 ; Start address
+ 100 ; Length
+ cfill
+ #+end_example
** tvidput - put image with transparency support
:PROPERTIES:
(0xFF) are treated as transparent and are not copied to the
destination.
-*** Parameters
+*Parameters:*
- *addr1* (32-bit): Address of the source image structure (contains
width, height, and data address).
- *y* (32-bit): Y-coordinate in the destination image where the copy
starts.
-*** Image Structure Format
+*Image Structure Format:*
Each image structure is stored in memory as follows:
- *Offset 0*: Image width (32-bit integer)
- *Offset 4*: Image height (32-bit integer)
- *Offset 8*: Base address of image data (32-bit pointer)
-*** Example
-
-Copy a 100x100 image from source structure at =0x1000= to destination
-structure at =0x2000=, starting at (50, 50):
-
-1. *Source Structure (0x1000)*:
-
- - Width: 100
- - Height: 100
- - Data Address: =0x3000=
-
-2. *Destination Structure (0x2000)*:
-
- - Width: 640
- - Height: 480
- - Data Address: =0x5000=
-
-3. *Stack Operations*:
-
- #+begin_example
- 50 ; y
- 50 ; x
- 0x2000 ; addr2 (destination structure)
- 0x1000 ; addr1 (source structure)
- tvidput
- #+end_example
-
-4. *Result*:
-
- - Only the overlapping region (100x100) is copied.
- - Any pixel in the source image with value 255 is skipped
- (transparent).
- - The copied image starts at (50, 50) in the destination buffer.
+*Example:*
+#+begin_example
+0x1000 ; Source image structure
+0x2000 ; Destination image structure
+50 ; x
+50 ; y
+tvidput
+#+end_example
-*** Notes
+*Notes:*
- Transparency is fixed at value 255 (0xFF).
- The operation handles clipping automatically to ensure the copy stays
stack onto the stack.
- *Notes:* Calculated by comparing the data stack pointer to the base
address of the stack.
+- *Example:*
+ #+begin_example
+ 1 2 3
+ depth
+ #+end_example
+ After execution, stack contains 3 (depth) followed by 1 2 3.
** charput - draw text character
:PROPERTIES:
where each bit determines whether to use the foreground or background
color for that pixel.
-*** Parameters
+*Parameters:*
- *colorfg* (1 byte): Foreground color value (0-255). Typically a
grayscale value where 0 is black and 255 is white.
- *y* (32-bit): Y-coordinate (0-based) where the character's top edge
starts.
-*** Example
+*Example:*
-To draw the letter 'A' (ASCII 65) at position (10, 20) in a 640x480
-VGA image buffer starting at address =0x5000=, with white foreground
-(0xFF) and black background (0x00):
+TODO: Create dedicated page that explains this instruction in
+depth. Link to this new page from current one.
+#+begin_example
+0xFF ; White foreground
+0x00 ; Black background
+0x3000 ; Character data address
+0x5000 ; Video memory address
+20 ; y
+10 ; x
+charput
+#+end_example
-Character data for 'A' (8 rows):
+Character data for 'A' (ASCII 65):
#+begin_example
0x00, 0x18, 0x24, 0x24, 0x24, 0x3C, 0x24, 0x24
#+end_example
projects / fifth.git / commitdiff