draw_getpixel: legacy function; calls
draw_getpixels: populates a buffer with pixel data from the screen and retrieves the pixel at the specified coordinates. FUTURE: returns the fetched pixel data as a flat_matrix.
draw_getpixel_cached: returns the most-recently-read pixel cache at the given coordinate.
This API would be very nice for hit detection. However, I am not so sure if it's that great of an idea to do this for the main screen backbuffer, which is only necessary if surfaces aren't supported. The API would probably be better suited to surfaces, or possibly both since all of the pixel transferring is generic now.
A perhaps better idea to improve the situation for people wanting to read heightmaps is to have a simple
texture_getpixels function. It would return a 2D var array of pixels for textures which includes sprites and backgrounds. It would be the fastest of the methods to read a heightmap since it would not require drawing to the screen first, which is only really useful for hit detection. That's why #1721 is related since it would be a possible way of speeding up the transfer of the texture pixels into the 2D var array.