gget (int_x1, int_y1, int_x2, int_y2, ref_sint32_var);
Get defined rectangular area from the screen into a referred variable. The variable is must be a one-dimensional or multi-dimensional array with total number of elements equal or greater than the needed minimum which is calculated as:
needed_bytes = (x2-x1+1) * (y2-y1+1) * 3
The formula above assumes the following conditions are met: (x2 ≥ x1), (y2 ≥ y1)
The function automatically reorders internally the input parameter in order to meet the conditions above for proper calculation.
If the size of the referred variable does not have enough number of elements, the function will terminate its work once the entire array has been processed.
The last multiplication in the formula above is needed because the colour of every pixel on the screen is stored in three consecutive bytes for red, green, and blue, respectively. Since the “sint32” type (also defined as “int”) is 32-bit, its size is enough for a single pixel colour. Although it also creates a 25% redundancy in the occupied bytes in memory, using the sint32 type offers backward compatibility with the function, and allows further manipulation of the pixel colours and conversion into transparent without need for additional buffers.
After execution, the referred variable contains a copy of the screen area with the colour of every pixel stored in a separate 32-bit array element.
The gget() function requires reading from the display memory. Some cheap displays on the market don’t have the relevant data pins exposed and available for use. The function will be unable to operate normally with those displays.