Understanding the Water Ripple Visual Effect in MDL

The Minimum Drawing Library (MDL) includes a sophisticated "Water Ripple" effect that simulates the realistic appearance of ripples on a water surface. This document explains how this complex visual effect works, its implementation details, and how you can use it in your LiveCode applications.

What is the Water Ripple Effect?

The water ripple effect creates the illusion of waves spreading across an image, similar to what happens when you drop a stone into a pond. It uses displacement mapping and alpha blending to distort the original image, creating a convincing water distortion that reveals a new image underneath.

This effect is part of the enhanced alpha channel effects in MDL version 0.93, which adds support for transparency and sophisticated image transitions.

Key Features of the Water Ripple Effect

Realistic Wave Simulation: Uses sine functions to create authentic wave patterns
Radial Propagation: Ripples spread outward from a center point
Alpha Transparency: Leverages transparency to blend the old and new images
Refractive Distortion: Simulates how light bends through water
Progressive Transition: Gradually transitions from the old image to the new one

The Science Behind Water Ripples

The water ripple effect is based on principles from physics and optics:

Wave Propagation: Water waves spread outward in concentric circles
Sinusoidal Motion: The height of a water wave follows a sine curve
Refraction: Light bends when passing through water at different depths
Displacement Mapping: Pixels are shifted based on a displacement function

The mathematical model for a radial water ripple can be expressed as:

Displacement(r, t) = A × sin(kr - ωt) × e^-αr

Where:

r is the distance from the center
t is time
A is amplitude
k is the wave number (related to wavelength)
ω is the angular frequency
α is the damping factor

Implementation in MDL

The water ripple effect is implemented in the veWaterRipple function. Here's a simplified overview of how it works:

Core Components

on veWaterRipple pImageName, pEffect, pSpeed
   local tNewBuffer, tOldBuffer, tWidth, tHeight, tWait
   local tSteps, tTempBuffer, tCenterX, tCenterY, tMaxRadius
   local tT
   
   put gMdBuffer into tNewBuffer
   put (the imageData of image pImageName) into tOldBuffer
   put MdGetBufferWidth() into tWidth
   put MdGetBufferHeight() into tHeight
   put getVeWait(pSpeed) into tWait
   
   put 20 into tSteps
   put tWidth div 2 into tCenterX
   put tHeight div 2 into tCenterY
   put sqrt(tWidth^2 + tHeight^2) / 2 into tMaxRadius

Key Steps in the Algorithm

Initialize Buffers: The function starts with the old image and the new image to transition to
Calculate Center Point: The ripple originates from the center of the image
Set Animation Parameters: Number of steps, radius, and timing
Iterate Through Animation Frames: For each frame:
1. Calculate current ripple progress and parameters
2. Apply wave displacement to each pixel
3. Blend old and new images based on progress
4. Apply transparency effects
5. Display the intermediate result

The Pixel Displacement Logic

The heart of the ripple effect is the pixel displacement logic:

-- Calculate ripple effect strength (0-1)
local tRippleStrength
put 1 - abs(tDist - tRippleRadius) / tRippleWidth into tRippleStrength

-- Apply sinusoidal distortion based on distance
local tAngle, tDisplacement
put (tDist / 5) * 360 + (tStep * 18) into tAngle
put tRippleStrength * 8 * sin(tAngle) into tDisplacement

-- Calculate direction vector
local tDx, tDy
if tDist > 0 then
    put (tX - tCenterX) / tDist into tDx
    put (tY - tCenterY) / tDist into tDy
else
    put 0 into tDx
    put 0 into tDy
end if

-- Calculate source pixel with displacement
local tSrcX, tSrcY
put tX + tDx * tDisplacement into tSrcX
put tY + tDy * tDisplacement into tSrcY

Note: This code shows how pixels are displaced based on a sine wave function. The displacement is strongest at the ripple's edge and follows a circular pattern outward from the center point.

Visualizing the Pixel Displacement

To understand the ripple effect, it's helpful to visualize how pixels are displaced:

Alpha Channel Integration

What makes the water ripple effect particularly sophisticated is its integration with the alpha channel for transparency effects:

-- Calculate refractive alpha effect
local tRefractiveAlpha
put tSrcAlpha * (0.7 + 0.3 * tRippleStrength) into tRefractiveAlpha

-- Blend with new image alpha based on progress
local tResultAlpha
put tRefractiveAlpha * (1 - tMixRatio) + tNewAlpha * tMixRatio into tResultAlpha
put numToByte(round(tResultAlpha)) into byte tDestIdx of tTempBuffer

This code creates a refractive effect by modulating the alpha (transparency) based on the ripple strength. This simulates how light intensity varies as it passes through rippling water.

Using the Water Ripple Effect in Your Code

To use the water ripple 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 initial content
MdEraseScreen
MdSetPenColor "255,255,0,0"  -- Red
MdDrawRect "50,50,350,250", true
MdPushBuffer  -- Save this state

-- Create new content
MdEraseScreen
MdSetPenColor "255,0,0,255"  -- Blue
MdDrawRect "100,100,300,200", true

-- Apply the water ripple effect when updating
MdUpdate "myImage", "waterRipple", "normal"

Parameters for Water Ripple Effect

Parameter	Description	Options
pImageName	Name of the image object to update	Any valid image name
pEffect	The visual effect to apply	"waterRipple"
pSpeed	The speed of the transition	"slow", "normal", "fast", or empty for default

Performance Considerations

The water ripple effect is computationally intensive because:

It recalculates every pixel position for each frame
It involves trigonometric functions (sine calculations)
It requires vector math for direction calculations
It performs multiple buffer operations

Optimization Tips

Reduce Image Size: Use smaller images when possible
Limit Animation Steps: Reduce tSteps for faster but less smooth animation
Skip Pixels: For very large images, consider processing every other pixel
Pre-calculate Sine Values: For repeated effects, cache common calculations
Use Fast Speed Option: The "fast" parameter reduces wait time between frames

Mathematical and Programming Concepts

The water ripple effect demonstrates several advanced concepts:

Vector Mathematics

The effect uses vector calculations to determine the direction and magnitude of pixel displacement:

Normalizing vectors: (tX - tCenterX) / tDist
Vector scaling: tDx * tDisplacement
Distance calculations: sqrt((tX - tCenterX)^2 + (tY - tCenterY)^2)

Wave Physics

The sine function models the oscillatory nature of water waves:

Wave amplitude: tRippleStrength * 8
Angular frequency: tStep * 18
Wave number: tDist / 5

Alpha Compositing

Alpha blending creates the transparent water effect:

Variable transparency: tSrcAlpha * (0.7 + 0.3 * tRippleStrength)
Composite blending: tResultAlpha * (1 - tMixRatio) + tNewAlpha * tMixRatio

Conclusion

The water ripple effect in MDL showcases how mathematical principles from physics and computer graphics can create realistic visual effects. By understanding the underlying calculations and buffer manipulations, you can not only use this effect effectively but also potentially customize it or create similar advanced effects of your own.

This effect builds upon the basic principles seen in simpler effects like wipe or fade, but adds sophisticated pixel displacement, wave simulation, and transparency handling to create a visually striking transition that mimics natural water behavior.