CopyPixel src_x,src_y,src_buffer,dest_x,dest_y[,dest_buffer]

Parameters

src_x - x coordinate of the pixel to read

src_y - y coordinate of the pixel to read

src_buffer - buffer to read from, for example ImageBuffer(pic)

dest_x - x coordinate to write to

dest_y - y coordinate to write to

dest_buffer (optional) - buffer to write to; 0 means the current drawing buffer (default)

Description

Copies a single pixel from one buffer to another.

This is the safe member of the pixel-copy pair. Both the source and destination coordinates are clipped: they are shifted by each buffer's Origin and tested against its Viewport, and a read or write that lands outside is quietly skipped rather than corrupting anything. That makes it fine to use with coordinates that come from gameplay maths and might wander off the edge.

Use it for the sort of per-pixel effect you cannot get from the drawing commands: melting or dissolving a title screen, a plasma or fire routine, sampling a heightmap image, or hand-rolled scaling and warping. For anything larger than a handful of pixels, though, prefer CopyRect or DrawImageRect, which move whole rectangles in one go.

Pixel-at-a-time work is slow. Wrap the loop in LockBuffer and UnlockBuffer on both buffers and you will get a useful speed-up, and if you have already locked the buffers and you know your coordinates are in range, CopyPixelFast skips the checks entirely.

See also: CopyPixelFast, ReadPixel, WritePixel, CopyRect, LockBuffer.

Example

; CopyPixel Example
; -----------------

Graphics 640,480,0,2
SetBuffer BackBuffer()

; Source photo and a blank destination image of the same size
logo=LoadImage("media/b3dlogo.jpg")     ; 400x197
dest=CreateImage(400,197)

row=0

While Not KeyDown(1)

    Cls

    ; Space restarts the copy from the top
    If KeyHit(57) Then
        row=0
        SetBuffer ImageBuffer(dest) : Cls : SetBuffer BackBuffer()
    End If

    ; Copy two rows per frame, one pixel at a time, image to image
    If row<197 Then
        For n=1 To 2
            If row<197 Then
                For x=0 To 399
                    CopyPixel x,row,ImageBuffer(logo),x,row,ImageBuffer(dest)
                Next
                row=row+1
            End If
        Next
    End If

    ; Source on top, the growing pixel-by-pixel copy below
    DrawImage logo,120,40
    DrawImage dest,120,260
    Color 255,255,0
    Rect 120,260,400,197,False

    Text 0,0,"Space: restart the copy   Esc: exit"
    Text 0,20,"CopyPixel has copied "+row+" of 197 rows so far"

    Flip

Wend

End

Index