Document and clarify image blit routines in `vidput.inc` and `tvidput.inc`: added...

diff --git a/emulator/tvidput.inc b/emulator/tvidput.inc
index 3c52a25..5398c9e 100644 (file)
--- a/emulator/tvidput.inc
+++ b/emulator/tvidput.inc
@@ -1,140 +1,173 @@
-; part of virtual processor, emulator for FIFTH\r
-\r
-\r
-xtvidput:\r
-mov    ebx, edi      ; read data from stack, and save it to variables\r
-mov    eax, [es:ebx]\r
-mov    [cory], eax\r
-add    ebx, 4\r
-mov    eax, [es:ebx]\r
-mov    [corx], eax\r
-\r
-add    ebx, 4\r
-mov    eax, [es:ebx]\r
-add    eax, [xms_addr]\r
-mov    ecx, [es:eax]\r
-mov    [img2x], ecx\r
-add    eax, 4\r
-mov    ecx, [es:eax]\r
-mov    [img2y], ecx\r
-add    eax, 4\r
-mov    [img2a], eax\r
-\r
-add    ebx, 4\r
-mov    eax, [es:ebx]\r
-add    eax, [xms_addr]\r
-mov    ecx, [es:eax]\r
-mov    [img1x], ecx\r
-add    eax, 4\r
-mov    ecx, [es:eax]\r
-mov    [img1y], ecx\r
-add    eax, 4\r
-mov    [img1a], eax\r
-\r
-add    ebx, 4\r
-mov    edi, ebx\r
-\r
-cmp    dword [cory] , 0        ; calculate Y start\r
-jl     tvidl1\r
-mov    dword [starty], 0\r
-jmp    tvidl2\r
-tvidl1:\r
-mov    eax, [cory]\r
-neg    eax\r
-mov    [starty], eax\r
-tvidl2:\r
-\r
-cmp    dword [corx] , 0        ; calculate X start\r
-jl     tvidl3\r
-mov    dword [startx], 0\r
-jmp    tvidl4\r
-tvidl3:\r
-mov    eax, [corx]\r
-neg    eax\r
-mov    [startx], eax\r
-tvidl4:\r
-\r
-mov    eax, [cory]             ; calculate Y end\r
-add    eax, [img1y]\r
-cmp    eax, [img2y]\r
-jg     tvidl5\r
-mov    eax, [img1y]\r
-mov    [endy], eax\r
-jmp    tvidl6\r
-tvidl5:\r
-mov    eax, [img2y]\r
-sub    eax, [cory]\r
-mov    [endy], eax\r
-tvidl6:\r
-\r
-mov    eax, [corx]             ; calculate X end\r
-add    eax, [img1x]\r
-cmp    eax, [img2x]\r
-jg     tvidl7\r
-mov    eax, [img1x]\r
-mov    [endx], eax\r
-jmp    tvidl8\r
-tvidl7:\r
-mov    eax, [img2x]\r
-sub    eax, [corx]\r
-mov    [endx], eax\r
-tvidl8:\r
-\r
-mov    eax, [endy]             ; calculate Y length\r
-sub    eax, [starty]\r
-cmp    eax, 0\r
-jle    emu\r
-mov    [lengthy], eax\r
-\r
-mov    eax, [endx]             ; calculate X length\r
-sub    eax, [startx]\r
-cmp    eax, 0\r
-jle    emu\r
-mov    [lengthx], eax\r
-\r
-mov    eax, [starty]           ; calculate img1 start address\r
-mov    ebx, [img1x]\r
-sub    edx, edx\r
-mul    ebx\r
-add    eax, [img1a]\r
-add    eax, [startx]\r
-mov    [img1start], eax\r
-\r
-mov    eax, [cory]             ; calculate img2 start address\r
-add    eax, [starty]\r
-mov    ebx, [img2x]\r
-sub    edx, edx\r
-mul    ebx\r
-add    eax, [img2a]\r
-add    eax, [corx]\r
-add    eax, [startx]\r
-mov    [img2start], eax\r
-\r
-tvidl9:\r
-mov    ebx, [img1start]\r
-mov    ecx, [lengthx]\r
-mov    edx, [img2start]\r
-\r
-tmemmove:               ; ebx - from, edx - to, ecx - amount\r
-cmp    ecx, 0\r
-je     tl11\r
-mov    al, [es:ebx]\r
-cmp    al, 255\r
-je     tl12\r
-mov    [es:edx], al\r
-tl12:\r
-inc    ebx\r
-inc    edx\r
-dec    ecx\r
-jmp    tmemmove\r
-tl11:\r
-\r
-mov    eax, [img1x]\r
-add    [img1start], eax\r
-mov    eax, [img2x]\r
-add    [img2start], eax\r
-dec    dword [lengthy]\r
-cmp    [lengthy], 0\r
-jg     tvidl9\r
-\r
-jmp    emu\r
+; Blit image with transparency support
+;
+; Stack Effect: addr1 addr2 x y --
+;
+; Copies a portion of image1 to image2 at the specified (x, y)
+; coordinates with transparency support. Pixels in image1 with value
+; 255 (0xFF) are treated as transparent and are not copied to the
+; destination.
+;
+; Parameters:
+; - addr1: Address of the source image structure (width, height, data)
+; - addr2: Address of the destination image structure
+; - x: X-coordinate in destination where to start copying
+; - y: Y-coordinate in destination where to start copying
+;
+; Image Structure Format:
+; - Offset 0: Image width (32-bit)
+; - Offset 4: Image height (32-bit)
+; - Offset 8: Base address of image data (32-bit pointer)
+;
+; Example:
+;   0x1000  ; Source image structure
+;   0x2000  ; Destination image structure
+;   50      ; x
+;   50      ; y
+;   tvidput
+;
+; Memory layout before execution:
+;   [es:edi] = y
+;   [es:edi+4] = x
+;   [es:edi+8] = addr2
+;   [es:edi+12] = addr1
+;
+; Memory layout after execution:
+;   Destination image updated with source image data (transparent pixels skipped)
+
+xtvidput:
+mov    ebx, edi      ; read data from stack, and save it to variables
+mov    eax, [es:ebx]
+mov    [cory], eax
+add    ebx, 4
+mov    eax, [es:ebx]
+mov    [corx], eax
+
+add    ebx, 4
+mov    eax, [es:ebx]
+add    eax, [xms_addr]
+mov    ecx, [es:eax]
+mov    [img2x], ecx
+add    eax, 4
+mov    ecx, [es:eax]
+mov    [img2y], ecx
+add    eax, 4
+mov    [img2a], eax
+
+add    ebx, 4
+mov    eax, [es:ebx]
+add    eax, [xms_addr]
+mov    ecx, [es:eax]
+mov    [img1x], ecx
+add    eax, 4
+mov    ecx, [es:eax]
+mov    [img1y], ecx
+add    eax, 4
+mov    [img1a], eax
+
+add    ebx, 4
+mov    edi, ebx
+
+cmp    dword [cory] , 0        ; calculate Y start
+jl     tvidl1
+mov    dword [starty], 0
+jmp    tvidl2
+tvidl1:
+mov    eax, [cory]
+neg    eax
+mov    [starty], eax
+tvidl2:
+
+cmp    dword [corx] , 0        ; calculate X start
+jl     tvidl3
+mov    dword [startx], 0
+jmp    tvidl4
+tvidl3:
+mov    eax, [corx]
+neg    eax
+mov    [startx], eax
+tvidl4:
+
+mov    eax, [cory]             ; calculate Y end
+add    eax, [img1y]
+cmp    eax, [img2y]
+jg     tvidl5
+mov    eax, [img1y]
+mov    [endy], eax
+jmp    tvidl6
+tvidl5:
+mov    eax, [img2y]
+sub    eax, [cory]
+mov    [endy], eax
+tvidl6:
+
+mov    eax, [corx]             ; calculate X end
+add    eax, [img1x]
+cmp    eax, [img2x]
+jg     tvidl7
+mov    eax, [img1x]
+mov    [endx], eax
+jmp    tvidl8
+tvidl7:
+mov    eax, [img2x]
+sub    eax, [corx]
+mov    [endx], eax
+tvidl8:
+
+mov    eax, [endy]             ; calculate Y length
+sub    eax, [starty]
+cmp    eax, 0
+jle    emu
+mov    [lengthy], eax
+
+mov    eax, [endx]             ; calculate X length
+sub    eax, [startx]
+cmp    eax, 0
+jle    emu
+mov    [lengthx], eax
+
+mov    eax, [starty]           ; calculate img1 start address
+mov    ebx, [img1x]
+sub    edx, edx
+mul    ebx
+add    eax, [img1a]
+add    eax, [startx]
+mov    [img1start], eax
+
+mov    eax, [cory]             ; calculate img2 start address
+add    eax, [starty]
+mov    ebx, [img2x]
+sub    edx, edx
+mul    ebx
+add    eax, [img2a]
+add    eax, [corx]
+add    eax, [startx]
+mov    [img2start], eax
+
+tvidl9:
+mov    ebx, [img1start]
+mov    ecx, [lengthx]
+mov    edx, [img2start]
+
+tmemmove:               ; ebx - from, edx - to, ecx - amount
+cmp    ecx, 0
+je     tl11
+mov    al, [es:ebx]
+cmp    al, 255
+je     tl12
+mov    [es:edx], al
+tl12:
+inc    ebx
+inc    edx
+dec    ecx
+jmp    tmemmove
+tl11:
+
+mov    eax, [img1x]
+add    [img1start], eax
+mov    eax, [img2x]
+add    [img2start], eax
+dec    dword [lengthy]
+cmp    [lengthy], 0
+jg     tvidl9
+
+jmp    emu

diff --git a/emulator/vidput.inc b/emulator/vidput.inc
index 7e7e793..091f87a 100644 (file)
--- a/emulator/vidput.inc
+++ b/emulator/vidput.inc
@@ -1,146 +1,177 @@
-; part of virtual processor, emulator for FIFTH\r
-\r
-\r
-xvidput:\r
-mov    ebx, edi      ; read data from stack, and save it to variables\r
-mov    eax, [es:ebx]\r
-mov    [cory], eax\r
-add    ebx, 4\r
-mov    eax, [es:ebx]\r
-mov    [corx], eax\r
-\r
-add    ebx, 4\r
-mov    eax, [es:ebx]\r
-add    eax, [xms_addr]\r
-mov    ecx, [es:eax]\r
-mov    [img2x], ecx\r
-add    eax, 4\r
-mov    ecx, [es:eax]\r
-mov    [img2y], ecx\r
-add    eax, 4\r
-mov    [img2a], eax\r
-\r
-add    ebx, 4\r
-mov    eax, [es:ebx]\r
-add    eax, [xms_addr]\r
-mov    ecx, [es:eax]\r
-mov    [img1x], ecx\r
-add    eax, 4\r
-mov    ecx, [es:eax]\r
-mov    [img1y], ecx\r
-add    eax, 4\r
-mov    [img1a], eax\r
-\r
-add    ebx, 4\r
-mov    edi, ebx\r
-\r
-cmp    dword [cory] , 0        ; calculate Y start\r
-jl     vidl1\r
-mov    dword [starty], 0\r
-jmp    vidl2\r
-vidl1:\r
-mov    eax, [cory]\r
-neg    eax\r
-mov    [starty], eax\r
-vidl2:\r
-\r
-cmp    dword [corx] , 0        ; calculate X start\r
-jl     vidl3\r
-mov    dword [startx], 0\r
-jmp    vidl4\r
-vidl3:\r
-mov    eax, [corx]\r
-neg    eax\r
-mov    [startx], eax\r
-vidl4:\r
-\r
-mov    eax, [cory]             ; calculate Y end\r
-add    eax, [img1y]\r
-cmp    eax, [img2y]\r
-jg     vidl5\r
-mov    eax, [img1y]\r
-mov    [endy], eax\r
-jmp    vidl6\r
-vidl5:\r
-mov    eax, [img2y]\r
-sub    eax, [cory]\r
-mov    [endy], eax\r
-vidl6:\r
-\r
-mov    eax, [corx]             ; calculate X end\r
-add    eax, [img1x]\r
-cmp    eax, [img2x]\r
-jg     vidl7\r
-mov    eax, [img1x]\r
-mov    [endx], eax\r
-jmp    vidl8\r
-vidl7:\r
-mov    eax, [img2x]\r
-sub    eax, [corx]\r
-mov    [endx], eax\r
-vidl8:\r
-\r
-mov    eax, [endy]             ; calculate Y length\r
-sub    eax, [starty]\r
-cmp    eax, 0\r
-jle    emu\r
-mov    [lengthy], eax\r
-\r
-mov    eax, [endx]             ; calculate X length\r
-sub    eax, [startx]\r
-cmp    eax, 0\r
-jle    emu\r
-mov    [lengthx], eax\r
-\r
-mov    eax, [starty]           ; calculate img1 start address\r
-mov    ebx, [img1x]\r
-sub    edx, edx\r
-mul    ebx\r
-add    eax, [img1a]\r
-add    eax, [startx]\r
-mov    [img1start], eax\r
-\r
-mov    eax, [cory]             ; calculate img2 start address\r
-add    eax, [starty]\r
-mov    ebx, [img2x]\r
-sub    edx, edx\r
-mul    ebx\r
-add    eax, [img2a]\r
-add    eax, [corx]\r
-add    eax, [startx]\r
-mov    [img2start], eax\r
-\r
-vidl9:\r
-mov    ebx, [img1start]\r
-mov    ecx, [lengthx]\r
-mov    edx, [img2start]\r
-call   memmove\r
-\r
-mov    eax, [img1x]\r
-add    [img1start], eax\r
-mov    eax, [img2x]\r
-add    [img2start], eax\r
-dec    dword [lengthy]\r
-cmp    [lengthy], 0\r
-jg     vidl9\r
-\r
-jmp    emu\r
-\r
-cory   dd 0\r
-corx   dd 0\r
-img2x  dd 0\r
-img2y  dd 0\r
-img2a  dd 0\r
-img1x  dd 0\r
-img1y  dd 0\r
-img1a  dd 0\r
-\r
-starty dd 0\r
-startx dd 0\r
-endy   dd 0\r
-endx   dd 0\r
-lengthx dd 0\r
-lengthy dd 0\r
-\r
-img1start dd 0\r
-img2start dd 0\r
+; Blit image without transparency
+;
+; Stack Effect: addr1 addr2 x y --
+;
+; Copies a portion of image1 to image2 at the specified (x, y)
+; coordinates with clipping. Every pixel is copied regardless of value.
+;
+; Parameters:
+; - addr1: Address of the source image structure (width, height, data)
+; - addr2: Address of the destination image structure
+; - x: X-coordinate in destination where to start copying
+; - y: Y-coordinate in destination where to start copying
+;
+; Image Structure Format:
+; - Offset 0: Image width (32-bit)
+; - Offset 4: Image height (32-bit)
+; - Offset 8: Base address of image data (32-bit pointer)
+;
+; Example:
+;   0x1000  ; Source image structure
+;   0x2000  ; Destination image structure
+;   50      ; x
+;   50      ; y
+;   vidput
+;
+; Memory layout before execution:
+;   [es:edi] = y
+;   [es:edi+4] = x
+;   [es:edi+8] = addr2
+;   [es:edi+12] = addr1
+;
+; Memory layout after execution:
+;   Destination image updated with source image data
+
+xvidput:
+mov    ebx, edi      ; read data from stack, and save it to variables
+mov    eax, [es:ebx]
+mov    [cory], eax
+add    ebx, 4
+mov    eax, [es:ebx]
+mov    [corx], eax
+
+add    ebx, 4
+mov    eax, [es:ebx]
+add    eax, [xms_addr]
+mov    ecx, [es:eax]
+mov    [img2x], ecx
+add    eax, 4
+mov    ecx, [es:eax]
+mov    [img2y], ecx
+add    eax, 4
+mov    [img2a], eax
+
+add    ebx, 4
+mov    eax, [es:ebx]
+add    eax, [xms_addr]
+mov    ecx, [es:eax]
+mov    [img1x], ecx
+add    eax, 4
+mov    ecx, [es:eax]
+mov    [img1y], ecx
+add    eax, 4
+mov    [img1a], eax
+
+add    ebx, 4
+mov    edi, ebx
+
+cmp    dword [cory] , 0        ; calculate Y start
+jl     vidl1
+mov    dword [starty], 0
+jmp    vidl2
+vidl1:
+mov    eax, [cory]
+neg    eax
+mov    [starty], eax
+vidl2:
+
+cmp    dword [corx] , 0        ; calculate X start
+jl     vidl3
+mov    dword [startx], 0
+jmp    vidl4
+vidl3:
+mov    eax, [corx]
+neg    eax
+mov    [startx], eax
+vidl4:
+
+mov    eax, [cory]             ; calculate Y end
+add    eax, [img1y]
+cmp    eax, [img2y]
+jg     vidl5
+mov    eax, [img1y]
+mov    [endy], eax
+jmp    vidl6
+vidl5:
+mov    eax, [img2y]
+sub    eax, [cory]
+mov    [endy], eax
+vidl6:
+
+mov    eax, [corx]             ; calculate X end
+add    eax, [img1x]
+cmp    eax, [img2x]
+jg     vidl7
+mov    eax, [img1x]
+mov    [endx], eax
+jmp    vidl8
+vidl7:
+mov    eax, [img2x]
+sub    eax, [corx]
+mov    [endx], eax
+vidl8:
+
+mov    eax, [endy]             ; calculate Y length
+sub    eax, [starty]
+cmp    eax, 0
+jle    emu
+mov    [lengthy], eax
+
+mov    eax, [endx]             ; calculate X length
+sub    eax, [startx]
+cmp    eax, 0
+jle    emu
+mov    [lengthx], eax
+
+mov    eax, [starty]           ; calculate img1 start address
+mov    ebx, [img1x]
+sub    edx, edx
+mul    ebx
+add    eax, [img1a]
+add    eax, [startx]
+mov    [img1start], eax
+
+mov    eax, [cory]             ; calculate img2 start address
+add    eax, [starty]
+mov    ebx, [img2x]
+sub    edx, edx
+mul    ebx
+add    eax, [img2a]
+add    eax, [corx]
+add    eax, [startx]
+mov    [img2start], eax
+
+vidl9:
+mov    ebx, [img1start]
+mov    ecx, [lengthx]
+mov    edx, [img2start]
+call   memmove
+
+mov    eax, [img1x]
+add    [img1start], eax
+mov    eax, [img2x]
+add    [img2start], eax
+dec    dword [lengthy]
+cmp    [lengthy], 0
+jg     vidl9
+
+jmp    emu
+
+cory   dd 0
+corx   dd 0
+img2x  dd 0
+img2y  dd 0
+img2a  dd 0
+img1x  dd 0
+img1y  dd 0
+img1a  dd 0
+
+starty dd 0
+startx dd 0
+endy   dd 0
+endx   dd 0
+lengthx dd 0
+lengthy dd 0
+
+img1start dd 0
+img2start dd 0