# 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