Understanding the Wipe Visual Effect in MDL

The Minimum Drawing Library (MDL) provides a set of powerful visual effects for image transitions. One of the simplest and most effective effects is the Wipe effect. This document explains how the wipe effect works, its implementation, and how to use it in your LiveCode applications.

What is the Wipe Effect?

The wipe effect creates a transition where a new image gradually replaces an old image by "wiping" across the screen in a specific direction. It's similar to a window blind or curtain being pulled across to reveal what's behind it.

MDL supports several wipe directions:

Visual Demonstration

Here's a simple animation demonstrating the wipeRight effect:

How It Works

The wipe effect is implemented in the veWipe function in MDL. Here's a breakdown of how it works:

Core Concepts

1. Buffers: MDL works with two image data buffers:
   • The tOldBuffer containing the current image
   • The tNewBuffer containing the image to transition to
2. Step-by-Step Replacement: The effect gradually replaces portions of the old buffer with data from the new buffer
3. Direction Control: The replacement direction is determined by the specified effect parameter

Implementation Details

Let's look at how the wipeRight effect is implemented:

if (pEffect is "wipeRight") then -- wipeRight
    put (tWidth div 40) into tStep
    put (4 * tStep) into tByte
    repeat with X = 0 to (tWidth - tStep) step tStep
        put (the ticks) into tT
        put (X * 4) into tOfsX
        repeat with Y = 0 to (tHeight - 1)
            put (tOfsX + tOneLineByte * Y + 1) into tStartByte
            put (byte tStartByte to (tStartByte + tByte) of tNewBuffer) \
                into byte tStartByte to (tStartByte + tByte) of tOldBuffer
        end repeat --//Y
        set the imageData of image pImageName to tOldBuffer
        wait tWait - (the ticks - tT)
    end repeat --// X
end if --// wipeRight

Step-by-Step Explanation

1. Calculate Step Size: The code divides the width by 40 to determine how many pixels to wipe in each iteration
2. Memory Calculation: tByte represents the memory size for each step (4 bytes per pixel * number of pixels in step)
3. Horizontal Iteration: The outer loop moves from left to right across the image
4. Vertical Processing: For each horizontal position, the inner loop processes every row (Y coordinate)
5. Buffer Replacement: For each position, a small vertical strip of the old image is replaced with data from the new image
6. Display Update: After each step, the modified buffer is displayed
7. Timing Control: A short wait ensures smooth animation speed

Pixel Data Organization

Understanding how pixel data is organized in the buffer is crucial to comprehending the wipe effect:

• Each pixel uses 4 bytes in ARGB format (Alpha, Red, Green, Blue)
• Pixels are stored row by row (all pixels in row 0, then row 1, etc.)
• To access a specific pixel at coordinates (x,y):
  • Starting byte position = (y * imageWidth * 4) + (x * 4) + 1

ARGB structure of a single pixel (4 bytes)

Memory layout of pixels in the buffer

Using the Wipe Effect in Your Code

To use the wipe effect in your LiveCode application:

-- Create an image object
create image "myImage"
set the rect of image "myImage" to 0,0,400,300

-- Initialize the drawing buffer
MdMakeBuffer "myImage"

-- Draw your content
MdEraseScreen  -- Clear with background color
MdSetPenColor "255,255,0,0"  -- Red
MdDrawRect "50,50,350,250", true

-- Apply the wipe effect when updating
MdUpdate "myImage", "wipeRight", "normal"

Parameters for MdUpdate

Optimizing Wipe Effects

For better performance when using wipe effects:

• Pre-calculate your image content before starting the transition
• Use smaller images for faster transitions
• Consider the "fast" speed option for large images
• For complex scenes, use MdPushBuffer/MdPopBuffer to store intermediate states

Implementation Insights

The wipe effect demonstrates several key programming techniques:

1. Buffer Manipulation: Direct memory manipulation for efficient image processing
2. Progressive Updates: Updating the display incrementally for smooth animations
3. Time Management: Using tick counting to ensure consistent animation timing
4. Direction Variants: Similar code structure with parametric variations to handle multiple directions

Conclusion

The wipe effect in MDL provides a simple yet powerful way to create professional transitions between images. By understanding how it works internally, you can better utilize it in your LiveCode applications and potentially create your own custom visual effects.