Pixel Operations

Macro: Pix

• Introduction
• Command Summary
• Reading Mouse Position
• Reading Screen Pixel Color
• Setting Screen Pixel Color
• Line Drawing
• Reading Clipboard Bitmaps

Introduction:

Important: These pixel (Pix) operations only apply in Spectrogram mode.

There are two types of Pix functions: Those that deal with the Spectrogram display area, and those that read pixels of an unseen bitmap image on the Windows Clipboard. You can see examples of these in the _Music_Mouse and _Music_Clipboard subroutines, respectively, of the Music_from_Anything macro mini-app.

The display functions allow you to read mouse position, pixel color number at that position or any specified position, or the palette values for a given color number. You can also set pixel color at the mouse position, or any specified position.

The Clipboard functions allow reading parameters of the bitmap image, including pixel color at any position in the bitmap.

The Pix functions that deal with screen positions use a coordinate system defined with 0,0 at the lower left corner of the Spectrogram display area. The upper right corner is 511,255. Note that this is quite different from the Posn functions Posn?X and Posn?Y that read relative to the entire Windows screen with 0,0 at the upper left, or Posn?x and Posn?y that are in "dialog units" relative to 0,0 at the upper left corner of the Averager button on the main Daqarta toolbar.

The Clipboard Pix functions use Windows Device-Independent Bitmap coordinates, as in the .BMP file format, which are typically relative to 0,0 at the bottom left of the image, or sometimes relative to the top left.

Command Summary:

Display Functions:
UX=Pix?m           Reads X and Y mouse positions, returns X
UY=Pix?y           Returns Y mouse position after Pix#m or Pix?m
UX=Pix?x           Returns X mouse position after Pix#m or Pix?m
UC=Pix?c           Reads color number UC = 0-255 from mouse in color column
UC=Pix[UX,UY]      Reads color number UC = 0-255 at [UX,UY] pixel
UC=Pix?D           Reads color of most-recent Drawn pixel (Pix#D=1 mode)
UQ=Pix?c[UC]       Reads RGB Sgram palette color from color number UC
Pix#m=UC           Reads mouse position, sets pixel color UC in display
Pix[UX,UY]=UC      Sets [UX,UY] pixel with color number UC = 0-255
Pix#D=n            Toggles smooth line drawing on display area (n=0,1)
Pix#Dw=n           Sets width of drawn lines (n=0-50, 0 same as 1)
Pix#Dc=UC          Sets initial drawing color number UC = 0-255
Pix#Dr=n           Sets rainbow line drawing step +/-20.  0=off.

Clipboard Bitmap Functions:
US=Pix?p           Opens Windows Clipboard, reads BMP header, returns size
UW=Pix?W           Reads BMP Width after Pix?p
UH=Pix?H           Reads BMP Height after Pix?p
UB=Pix?B           Reads BitCount (bits/pixel) after Pix?p
UR=Pix?R           Returns computed bytes/row after Pix?p
US=Pix?S           Reads BMP SizeImage after Pix?p
UP=Pix?p[UX,UY]    Reads BMP pixel at UX,UY coords
U1=Pix?b[UX]       Reads byte at linear index into bitmap
U1=Pix?1[UX]       Reads byte at linear index into bitmap
U2=Pix?w[UX]       Reads word at linear index into bitmap
U2=Pix?2[UX]       Reads word at linear index into bitmap
U3=Pix?t[UX]       Reads 24-bit value at linear index into bitmap
U3=Pix?3[UX]       Reads 24-bit value at linear index into bitmap
U4=Pix?d[UX]       Reads dword at linear index into bitmap
U4=Pix?4[UX]       Reads dword at linear index into bitmap
UQ=Pix?C[U1]       Reads RGB color from palette for 8-bit color index U1
Pix#p=0            Closes Windows Clipboard

Reading Mouse Position:

UX=Pix?m reads both X and Y mouse positions, but only returns the X position. To get the associated Y position use UY=Pix?y. Please note that UY=Pix?y does not read the current mouse position, it only returns the Y value of the most recent UY=Pix?m (or Pix#m=UC, whichever was most recent). The corresponding UX=Pix?x reads the X value of the most recent UY=Pix?m or Pix#m=UC. (See Setting Screen Pixel Color for details of Pix#m=UC.)

The above commands assume the mouse cursor is in the normal Spectrogram display area. If it is in the color bar to the right of that, UC=Pix?c reads the color number 0-255. This is essentially just the Y value of the mouse position in the color bar; the X value is ignored.

After the above UC=Pix?c, you can use UQ=Pix?c[UC] to read the RGB (Red,Green,Blue) values that correspond to the color number in the Spectrogram palette. UQ is a 32-bit value, with the high byte all zeros, then bytes for Red, Green, and Blue components. So, for example, the top of the color bar is 255, and the corresponding color in the defaule palette is pure red. If you display that with Msg=UQ(h) to see it in hexadecimal, it is 00FF0000. Pure green would be 0000FF00 and pure blue 000000FF.

Reading Screen Pixel Color:

UC=Pix[UX,UY] reads the color number (0-255) from the pixel at position [UX,UY], where X may be 0-511 and Y may be 0-255 to read pixels in the normal display area. X values from 512 to 527 are in the color bar to the right of the display area, and will return the associated color number 0-255.

In Line Drawing mode (see below) , use UC=Pix?D to find the color number of the most-recently drawn pixel.

After obtaining the color number, you can convert it to the corresponding RGB Spectrogram palette values using UQ=Pix?c[UC], as described above under Reading Mouse Position.

Setting Screen Pixel Color:

Pix[UX,UY]=UC sets pixel [UX,UY] with color number UC = 0-255. UX may be 0-511 and UY may be 0-255. There will be no effect outside this range; you can only change the Spectrogram display area, not the color bar.

Pix#m=UC reads the mouse position and sets that pixel with color UC. The mouse must be in the display area. You can test the left mouse button state with IF.Posn?m=1 to allow drawing on the screen via click-and-drag as in a Paint-type program. A drawn line will be a series of separate pixels, whose spacing increases with drawing speed. See Line Drawing, below, for smooth lines of adjustable width.

Line Drawing:

Pix#D=1 toggles smooth line drawing on. Before that, however, you should set the line width and color, and optional rainbow color mode.

You should always use Pix#D=0 when you are done drawing to turn off this option.

Pix#Dw=n sets the width of the line to be drawn, where n=0-50. Note that the minimum width is 1 pixel, even if you set 0.

Pix#Dc=UC sets the initial drawing color number 0-255, where 0 is black and 255 is bright red if using the default Spectrogram palette. You can change the color during the drawing by using this command, typically by reading the color selected by a mouse click on the spectrogram color bar to the right of the display using UC=Pix#c, followed by Pix#Dc=UC. See the _Music_Mouse subroutine of the Music_from_Anything macro mini-app for an example.

Pix#Dr=n sets the rainbow drawing mode step size, where n is in the +/-20 range. If it is zero, rainbow drawing is turned off. Every time you move the mouse, the color is changed by adding the step to the current color number. If the step is positive, the drawn color moves higher on the color bar; if negative, the color moves down.

When the draw color reaches the top of the color bar, the step sign is reversed automatically and colors descend. When the drawn color gets down to color number 41 (bright magenta using the default palette) the direction is reversed again and colors ascend.

The above assumes the initial color (set by Pix#Dc before beginning) is 41 or above. Setting a lower number gives "pathological" results, such as very dingy colors or total black. However, setting the initial color lower than the step size (such as 1 with a step size of 5) produces alternating red and black color bands with a very 3-dimensional appearance, like a red-striped licorice candy cane.

In Drawing mode, use UC=Pix?D to find the color number of the most-recently drawn pixel.

Reading Clipboard Bitmaps:

If you open an image file in another program, such as Windows Paint or IrfanView, and select all or part of it and hit CTRL+C, or Copy from the Edit menu, the image will be copied to the Windows Clipboard as a Device Independent Bitmap (DIB). This is equivalent to a .BMP file without the file header, only the bitmap header and data. Even if the original image was a .JPG, the Clipboard will hold a BMP format.

US=Pix?p opens the Clipboard, reads the bitmap header information into Daqarta memory, and sets US with the size of the bitmap, in pixels. Afterward, you can read other bitmap header values:

UW=Pix?W reads the width of the bitmap image, in pixels.

UH=Pix?H reads the height of the image, in pixels. NOTE: This value may be negative if the image is in "top down" format, with its origin is the upper left corner. A positive value indicates the normal "bottom up" convention with its origin at the lower left.

UB=Pix?B reads the BitCount value, bits per pixel. Although the DIB format supports 1 bit per pixel (two colors, typically black and white as in a line drawing) and 4 bits per pixel (16 colors), Pix?p does not not support these and the initial call will return a size of 0.

The standard higher sizes are supported: 8, 16, 24, and 32. 8 bits per pixel uses an indexed color scheme to allow 256 colors. Each pixel of the bitmap holds a byte with a value of 0-255. A 256-color palette holds the actual color that corresponds to each byte. Note that the colors in the palette are almost always different for each image, typically selected by an image-handling program as a "best fit" when reducing an image to 256 colors from higher-color formats, such as from a camera.

16, 24, and 32 bit-per-pixel bitmaps do not use color palettes, but store the actual red, green, and blue color component values at the pixel location in the bitmap.

The 16 bits-per-pixel format can hold up to 2^16 = 65536 colors. Typically, however, it uses only 15 of those bits, 5 each for red, green, and blue color components, for 2^15 = 32768 total possible colors. Bits 0-4 are blue, 5-9 are green, and 10-14 are red, with bit 15 always 0.

24 bits-per-pixel format uses 3 bytes for each pixel, one each for red, green, and blue. This allows up to 2^24 = 16,777,216 possible colors.

32 bits-per-pixel allows 2^32 = 4,294,967,295 possible colors. Typically only 24 bits are used, with the high 8 bits set to 0. This supports simple addressing schemes for 32-bit systems. Alternatively, 10 bits may be allocated to each red, green, blue color for 2^30 = 1,073,741,824 possible colors.

US=Pix?S reads the bitmap size in pixels. This value is the same as that returned when the Clipboard was opened with US=Pix?p.

UR=Pix?R reads the computed bytes per row of the bitmap. This value is used internally by Daqarta in computing the bitmap location of a given pixel; you'll need this if you want to do it manually instead of via UP=Pix?p[UX,UY]. (See below.)

Bitmaps are stored as rows (Y) and columns (X); to find a given pixel you first find the proper row by multiplying the Y value by UR bytes per row, then find the offset into that row by multiplying the X value by the bytes per pixel, which is UB bits-per-pixel divided by 8 bits per byte:

Pixel location = Y * UR + X * UB / 8

You can then read the value at that location, using the proper operation based on the bytes per pixel UB / 8.

IMPORTANT: The UR value takes into account that rows are always multiples of 4 bytes, regardless of the bytes per pixel. If the width in pixels UW times bytes per pixel is not a multiple of 4, it is padded to make it so. (Typically with zeros, but that's not guaranteed.) So you unless UB is 32 (4 bytes per pixel), you can't find the start of the pixel without considering the padding.

UP=Pix?p[UX,UY] reads the pixel at the UX,UY location taking into account the UR value, and returns the UP value of the proper width. If the bitmap uses 8 bits per pixel (256 colors), UP will be the raw byte value 0-255. This is an index into the color palette which holds the actual red, green, blue (RGB) color data. You can retrieve that via UQ=Pix?C[UP]. The color format is as described in Reading Mouse Position, but note that you must use an uppercase ?C to read the Clipboard palette.

For 16, 24, or 32 bits per pixel, the UP value will be the color data in the respective formats discussed above.

If you want to read pixel values manually (or just want to read raw bitmap data of a certain size at certain locations without regard to pixel size), you can use the following operations. These just use a single index UX and treat the bitmap as linear table of bytes. UX tells which byte to start at, and the particular instruction reads the designated number of bytes at that location:

U1=Pix?b[UX] or U1=Pix?1[UX] reads one byte.

U2=Pix?w[UX] or U2=Pix?2[UX] reads one word (2 bytes, or 16 bits.)

U3=Pix?t[UX] U3=Pix?3[UX] reads a triplet of 3 bytes, or 24 bits.

U4=Pix?d[UX] or U4=Pix?4[UX] reads a 4-byte dword (double word), or 32 bits.

See also Macro Overview