ImageSearchDLL v1.19.5.2025

[Trong]

Overview of Functionality

The DLL (commonly named ImageSearchDLL) is written in modern C++ (using C++23 features and c++14 for XP version) and makes extensive use of Windows APIs such as GDI+ for image loading and drawing. It is designed to perform the following major operations:

• Initialization and Resource Management: The DLL initializes GDI+ when loaded (using functions such as GdiplusStartup()) and releases it when no longer needed. Classes such as AutoReleaseDC, AutoDeleteDC, AutoHBITMAP, and AutoSelectObject rely on RAII (Resource Acquisition Is Initialization) to manage GDI objects safely. This design helps prevent resource leaks—even if exceptions occur.

• CPU Feature Check: A function CpuSupportsSSE2() checks if the CPU supports SSE2 instructions by using the __cpuid() intrinsic. This check could be used to determine whether to enable optimized image-processing routines.

• Loading an Image & Extracting Pixel Data: The function LoadPictureEx() is responsible for converting a provided file path (from a UTF-8 string) into a wide-character array and then using GDI+ to load the image. If the desired dimensions (width/height) are not provided, the function defaults to the image’s native dimensions. Then, GetBitmapPixels() extracts pixel data from the image (an HBITMAP) into an array (stored as a vector of DWORD values) via functions like GetDIBits(). This pixel data is later used to match against screen contents.

• Screen Capture: The DLL contains a function CaptureScreenRegion() that grabs a portion of the screen defined by a RECT (left, top, right, bottom). It creates a compatible HDC and HBITMAP, uses BitBlt() to copy the screen data into the bitmap, and then extracts pixel information. This image buffer is used as the search area.

• Pixel Comparison: The ColorsMatch() function compares two pixel color values. It extracts the individual red, green, and blue channels from the DWORD values and compares them within a user-specified tolerance. This permits a partial match rather than an exact pixel comparison—which is useful to handle slight variations due to anti-aliasing or compression artifacts.

• Image Search Operation: The exported function, ImageSearch(), is the primary interface. Its parameters are:

  • The coordinates for the screen region (left, top, right, bottom) to perform the search.

  • A string (testImage) that contains the file path(s) for one or more images. These paths can be delimited by the | character, allowing multiple candidate images to be compared within one call.

  • An integer tolerance to specify the allowable pixel-distance/difference.

  • A flag called centerpos that, if set, causes the function to return the center coordinates of the discovered match rather than the top‐left corner.

  The DLL’s search routine works as follows:

  1. Parameter Normalization: The coordinate values are clamped to the current screen dimensions using GetSystemMetrics() to ensure that the region is valid.

  2. Screen Capture: The given screen region is captured, and its pixel data is stored.

  3. Candidate Image Handling: The function splits the testImage string by the | delimiter into a list of candidate image file paths and attempts to load each image.

  4. Pixel-by-Pixel Comparison: For each candidate image, its pixel buffer is compared against the corresponding region in the captured screen. If every pixel in the candidate image matches the corresponding pixel in the screen (within the specified tolerance), the match is recorded.

  5. Return Format: The results are then summarized and returned as a formatted string. If the centerpos flag is nonzero, the coordinates returned will be adjusted from the top-left position to the center of the image region.

• Error Handling: Throughout the code, specific error conditions are flagged. For example:

  • {-1}[] indicates that no candidate image could be loaded,

  • {-2}[] means failure obtaining the screen’s device context,

  • {-3}[] signifies an error in extracting the image pixel data,

  • {-4}[] represents a screen capture failure, and

  • {-5}[] denotes a general fallback error.

Feature Introduction and Use Cases

a. Key Features

• Image Template Search: The DLL is built to locate one or more images within a user-defined region of the screen. It does this via a pixel-by-pixel search with a configurable tolerance level.

• Multiple Candidate Support: By using a delimiter (the pipe symbol |), users can input several image paths for simultaneous matching. This is particularly useful for error handling or when multiple similar templates might be valid.

• Tolerance-Based Matching: Tolerance in pixel matching means that the search will work even if there are minor differences between the template image and what appears on screen—accounting for differences caused by variations in display or anti-aliasing.

• Return Format Flexibility: The function can return either the top-left coordinates or the center position of the found image. The result is structured in a standard format, making it easy to parse.

• Robust Resource Management: With thorough use of RAII and proper error handling, the DLL protects against typical resource leaks, ensuring safe integration into larger automation frameworks.

b. Possible Use Cases

• GUI Automation: Automate repetitive tasks by locating elements (like buttons or icons) on the screen and interacting with them.

• Game Bots: Use image search to detect in-game elements for automated gameplay actions.

• UI Testing: Validate graphical user interfaces by searching for expected visual elements after particular events occur.

• Screen Monitoring: Monitor specific areas of the screen for changes that match predetermined images.

 

3. How to Use the DLL from AutoIt

AutoIt can call external DLL functions using the DllCall() function. Below is an example script that shows how you can use the ImageSearch function:

expandcollapse popup

; === AutoIt Example: Using the ImageSearchDLL ===
Global $sImageSearchDll = @ScriptDir & "\ImageSearchDLL.dll"

; Define the screen search region based on the desktop dimensions.
Global $left = 0
Global $top = 0
Global $right = @DesktopWidth - 1
Global $bottom = @DesktopHeight - 1

; Specify the image(s) to search for. Use "|" to separate multiple candidates if needed.
Global $testImage = @ScriptDir & "\TestImage.png"

; Define the tolerance (allowed color delta) and center flag
Global $tolerance = 10      ; Allows a color difference of up to 10 units per channel
Global $centerpos = 1       ; Set to 1 to return the center point of the matched region

_ImageSearch($testImage, $left, $top, $right, $bottom, $tolerance, $centerpos)


Func _ImageSearch_Raw($sImagePath, $iLeft = 0, $iTop = 0, $iRight = @DesktopWidth, $iBottom = @DesktopHeight, $iTolerance = 0, $iCenterPos = True)
    Local $aDLLResult, $iError = 0
    Local $hDLL = DllOpen($sImageSearchDll)
    If ($hDLL <> -1) Then
        ; Call the ImageSearch function from the DLL.
        $aDLLResult = DllCall($hDLL, "str", "ImageSearch", _
                "int", $iLeft, "int", $iTop, _
                "int", $iRight - 1, "int", $iBottom - 1, _
                "str", $sImagePath, _
                "int", $iTolerance, "int", $iCenterPos)
            $iError = @error
    EndIf
    ; Check whether the call was successful and display the result.
    If Not $iError And IsArray($aDLLResult) Then
        Local $sDLLResult = $aDLLResult[0]
        ; Once all operations are finished, call the CleanUp function to release resources.
        DllCall($hDLL, "", "Cleanup")
        DllClose($hDLL)
        ConsoleWrite("> DLL Return: " & $sDLLResult & @CRLF)
        MsgBox(0, "ImageSearch Result", "Result string: " & $aDLLResult[0])
        Return $aDLLResult[0]
    EndIf
    MsgBox(16, "Error", "DLL call failed or no valid result was returned!")
EndFunc   ;==>_ImageSearch

 

Understanding the Returned Format

When the search is successful, the DLL returns a string with this format:

"{<number_of_matches>}[x1|y1|width1|height1, x2|y2|width2|height2, …]"

For example:

• "{1}[100|200|50|50]" indicates that one match was found at coordinates (100,200) with a width of 50 pixels and a height of 50 pixels.

• If centerpos is enabled, the x and y values represent the center of the matching region instead.

Error conditions are similarly formatted:

• "{-1}[]" might indicate that no candidate image loaded successfully.

• Other error codes ({-2}, {-3}, etc.) signal specific failures, such as inability to get the screen’s DC, extract pixel data, or capture the region.

4. Conclusion

The ImageSearchDLL provides a powerful means of performing pixel-level template matching on screen regions, with flexible options for tolerance and result formatting. Its integration with AutoIt via DllCall() makes it an ideal component for GUI automation, game bots, or UI testing. The clear return format allows your script to quickly verify results and act accordingly, whether it is clicking on a found image or triggering further actions in your automation workflow.

If you need to extend the functionality—such as optimizing the pixel comparison with SSE2 instructions or adding support for additional color formats—the design of the DLL (with its modular RAII-based resource management) lends itself well to further development.

Feel free to experiment further and tailor the example AutoIt code to better fit your specific automation scenarios!

Download Dll & UDF here:  

Edited 11 hours ago by Trong
Finalize UDF and release article