From 42782dd434acd587e297da3b38fbbdd31b171aa5 Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Sun, 15 Feb 2026 10:53:44 +0200 Subject: [PATCH] Expanded and clarified virtual machine documentation, added examples for instruction usage. --- doc/virtual machine.org | 461 +++++++++++++++++++++++++++++----------- 1 file changed, 338 insertions(+), 123 deletions(-) diff --git a/doc/virtual machine.org b/doc/virtual machine.org index d10e704..fabd2cc 100644 --- a/doc/virtual machine.org +++ b/doc/virtual machine.org @@ -28,56 +28,56 @@ Virtual CPU, commands (most of them are avaiable as ordinary commands 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 | | | | -| 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 | | | | | +| 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: @@ -121,6 +121,11 @@ in programming language): 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: @@ -132,6 +137,11 @@ in programming language): 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: @@ -144,6 +154,11 @@ in programming language): 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: @@ -153,6 +168,12 @@ in programming language): - *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: @@ -162,6 +183,12 @@ in programming language): - *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: @@ -171,6 +198,12 @@ in programming language): - *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: @@ -180,6 +213,12 @@ in programming language): - *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: @@ -192,6 +231,12 @@ in programming language): 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: @@ -202,6 +247,10 @@ in programming language): - *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: @@ -213,37 +262,60 @@ in programming language): 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: @@ -255,6 +327,12 @@ in programming language): 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: @@ -266,6 +344,12 @@ in programming language): 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: @@ -278,6 +362,12 @@ in programming language): - *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: @@ -289,6 +379,11 @@ in programming language): 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: @@ -299,6 +394,12 @@ in programming language): - *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: @@ -310,6 +411,12 @@ in programming language): 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: @@ -320,6 +427,12 @@ in programming language): - *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: @@ -331,6 +444,12 @@ in programming language): 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: @@ -342,6 +461,12 @@ in programming language): 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: @@ -353,6 +478,12 @@ in programming language): 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: @@ -364,6 +495,12 @@ in programming language): 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: @@ -371,10 +508,16 @@ in programming language): :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: @@ -382,10 +525,16 @@ in programming language): :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: @@ -396,6 +545,12 @@ in programming language): - *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: @@ -407,6 +562,13 @@ in programming language): 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: @@ -417,6 +579,11 @@ in programming language): - *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: @@ -427,6 +594,12 @@ in programming language): - *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: @@ -438,6 +611,13 @@ in programming language): 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: @@ -449,6 +629,13 @@ in programming language): 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: @@ -460,6 +647,13 @@ in programming language): 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: @@ -471,6 +665,13 @@ in programming language): 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: @@ -480,6 +681,12 @@ in programming language): - *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: @@ -489,6 +696,12 @@ in programming language): - *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: @@ -526,24 +739,12 @@ Parameters: - 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 @@ -553,6 +754,7 @@ memory: for 640x480x8). - Requires VESA BIOS support and proper initialization via =set_vesa_mode=. + ** mouse@ :PROPERTIES: :CUSTOM_ID: mouse @@ -561,7 +763,7 @@ memory: 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: @@ -569,7 +771,6 @@ 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). @@ -579,6 +780,13 @@ driver. Returns three values on the stack: - 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 @@ -590,7 +798,7 @@ Copies a portion of image1 to image2 at the specified (x, y) 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). @@ -601,17 +809,21 @@ support - every pixel is copied regardless of value. - *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: @@ -626,6 +838,13 @@ regions correctly. - *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: @@ -637,6 +856,13 @@ regions correctly. 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: @@ -650,7 +876,7 @@ coordinates with transparency support. Pixels in image1 with value 255 (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). @@ -661,48 +887,23 @@ destination. - *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 @@ -718,6 +919,12 @@ structure at =0x2000=, starting at (50, 50): 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: @@ -734,7 +941,7 @@ source buffer represents one row of the character (8 bits per row), 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. @@ -748,14 +955,22 @@ color for that pixel. - *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 -- 2.20.1