# Function Reference

# PixelSearch

Searches a rectangle of pixels for the pixel color provided.

PixelSearch ( left, top, right, bottom, color [, shade-variation = 0 [, step = 1 [, hwnd]]] )

## Parameters

left | left coordinate of rectangle.
top | top coordinate of rectangle.
right | right coordinate of rectangle.
bottom | bottom coordinate of rectangle.
color | Color value of pixel to find (in decimal or hex).
shade-variation | [optional] A number between 0 and 255 to indicate the allowed number of shades of variation of the red, green, and blue components of the color. Default is 0 (exact match).
step | [optional] Instead of searching each pixel use a value larger than 1 to skip pixels (for speed). E.g. A value of 2 will only check every other pixel. Default is 1. It is not recommended to use a step value greater than 1.
hwnd | [optional] Window handle to be used. Default is the desktop window. See remark.

## Return Value

Success: | a two-element array of pixel's coordinates. (Array[0] = x, Array[1] = y).
Failure: | sets the @error flag to 1 if the color is not found.

## Remarks

The search direction varies as follows:
Left-to-Right - left < right
Right-to-Left - right < left
Top-to-Bottom - top < bottom
Bottom-to-Top - bottom < top
Changing the search direction can be a useful optimization if the color being searched for frequently appears in a specific quadrant of the search area since less searching is done if the search starts in the most common quadrant.
Remember, a typical display at 1024 x 768 has 786432 pixels. Although PixelSearch() is optimized, narrowing the search area helps speed up the result.
If PixelCoordMode is set to its default SCREEN (1) mode the hwnd parameter is ignored. Only if PixelCoordMode is set to WINDOW (0) or CLIENT (2) will it be honoured.

## Related

PixelChecksum, PixelCoordMode (Option), PixelGetColor

## Example

    #include <MsgBoxConstants.au3>

    ; Find a pure red pixel in the range 0,0-20,300
    Local $aCoord = PixelSearch(0, 0, 20, 300, 0xFF0000)
    If Not @error Then
        MsgBox($MB_SYSTEMMODAL, "", "X and Y are: " & $aCoord[0] & "," & $aCoord[1])
    EndIf

    ; Find a pure red pixel or a red pixel within 10 shades variations of pure red
    $aCoord = PixelSearch(0, 0, 20, 300, 0xFF0000, 10)
    If Not @error Then
        MsgBox($MB_SYSTEMMODAL, "", "X and Y are: " & $aCoord[0] & "," & $aCoord[1])
    EndIf