pixels

The following routines can be used on individual pixels:

putDibPixel(a32Dib dib, integer x, integer y, colour bgr)
fastPutDibPixel(a32Dib dib, integer x, integer y, colour bgr)
a32Colour0 c3 = getDibPixel(a32Dib dib, integer x, integer y)
a32Colour c3 = fastGetDibPixel(a32Dib dib, integer x, integer y)
clearDib(a32Dib dib, a32Colour bgr)

To set a specific pixel on a bitmap, use the putDibPixel procedure.
To get the color of a pixel on the bitmap, use the getDibPixel function.
To clear the bitmap, use the clearDib procedure.
Instead of putDibPixel and getDibPixel, you can also use the faster fastPutDibPixel and fastGetDibPixel, but these do not check if the coordinates of the pixel are within the boundaries of the bitmap, so only use them if you are sure the coordinates are valid (0 <= x < width and 0 <= y < height).

Example:

    a32Dib dib
    a32Colour white, black, color

    dib = newDib(300, 200)             -- create a bitmap

    white = dibColor(255, 255, 255)    -- create the color white
    black = dibColor(  0,   0,   0)    -- create the color black

    clearDib(dib, white)               -- clear the bitmap with the color white
    putDibPixel(dib, 100, 100, black)  -- make the pixel at position (100, 100) black
    color = getDibPixel(dib, 200, 150) -- get the color of the pixel at position (200, 150)

    killDib(dib)                       -- delete the bitmap

If you have to put or get a lot of pixels, there is a much faster way than using putDibPixel and getDibPixel: poke and peek.

The 2nd element of the bitmap-sequence [DibMemory] is the address of the memory block allocated by the bitmap.
To calculate the address of the pixel (x, y), use the formula:

    integer bytes_per_line
    atom memory, address
    memory = dib[DibMemory]
    bytes_per_line = dib[DibBytesPerLine]
    address = memory + 3*x + y*bytes_per_line

which you can of course simplify to:

    atom address = dib[DibMemory] + 3*x + y*dib[DibBytesPerLine]

To get the color of that pixel:

    a32Colour color = peek({address, 3}) -- each pixel is 3 bytes

To set the color of that pixel:

    poke(address, color)

A very fast way to loop over the entire bitmap goes like this:

    atom address = dib[DibMemory]
    for y=0 to height - 1 do
        for x=0 to width - 1 do
            -- do something with the current pixel:
            -- address is the address, x and y are the coordinates.

            address += 3 -- 1 pixel = 3 bytes
        end for
        address += padding -- padding is the integer dib[DibPadding]
    end for

If you only want to loop over a region (x1, y1) -> (x2, y2), you can try:

    atom address = dib[DibMemory] + x1 * 3 + y1 * bytes_per_line
    integer line_jump = bytes_per_line + (x1 - x2) * 3 + 3
    for y = y1 to y2 do
        for x = x1 to x2 do
            -- do something with the current pixel:
            -- address is the address, x and y are the coordinates.

            address += 3
        end for
        address += line_jump -- line_jump is the amount of bytes to jump forward after each line
    end for