Blitz3D+ Command Reference

CopyPixelFast 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 with no safety checks at all.

This is the unchecked twin of CopyPixel. It ignores Origin and Viewport and does not clip, so it is the one to use inside a tight per-pixel loop - a plasma effect, a fire routine, a software scaler - where you already know every coordinate is inside the buffer.

Lock both buffers with LockBuffer before the loop and unlock them with UnlockBuffer afterwards. That is not just an optimisation here: the fast pixel commands are only valid on a locked buffer.

Because nothing is range-checked, a coordinate that strays outside the buffer writes over memory that does not belong to the image, which will corrupt other data or crash the program outright. Clamp your loop bounds yourself, and while you are still getting the maths right, develop with CopyPixel and only swap in the fast version once it works.

See also: CopyPixel, ReadPixelFast, WritePixelFast, LockBuffer, UnlockBuffer.

Example

; CopyPixelFast 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

    ; CopyPixelFast MUST be used on locked buffers, and every coordinate
    ; must be in range - that is why it can skip the safety checks
    If row<197 Then
        LockBuffer ImageBuffer(logo)
        LockBuffer ImageBuffer(dest)
        ; Eight rows per frame - notice how much faster it fills in
        For n=1 To 8
            If row<197 Then
                For x=0 To 399
                    CopyPixelFast x,row,ImageBuffer(logo),x,row,ImageBuffer(dest)
                Next
                row=row+1
            End If
        Next
        UnlockBuffer ImageBuffer(dest)
        UnlockBuffer ImageBuffer(logo)
    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,"CopyPixelFast has copied "+row+" of 197 rows so far"

    Flip

Wend

End

Index