Point

Returns the color attribute of a specified pixel coordinate

Syntax
	result = Point( coord_x, coord_y [,buffer] )
	or
	result = Point( function_index )

Usage
	coord_x
		x coordinate of the pixel
	coord_y
		y coordinate of the pixel
	buffer
		the image buffer to read from
	function_index
		the type of screen coordinate to return: one of the values 0, 1, 2, 3

Return Value
	The return datatype is a KeyPgUlongULong.

	If the x, y coordinates of a pixel are provided Point returns the color 
	attribute at the specified coordinates, as an 8-bit palette index in 8 
	bpp indexed modes, a 24-bit RGB value in 16 bpp modes (upper 8 bits 
	unused, limited precision of R,G,B), and a 32-bit RGB or RGBA value in 
	32 bpp modes (upper 8 bits unused or holding Alpha). Note that it does 
	NOT return a 16-bit value (5 bits R + 6 bits G + 5 bits B).

	If the argument is a function index, Point returns one of the graphics 
	cursor coordinates set by the last graphics command.

		Ŀ
		Argument Value Returned                                                                                                               
		 0      The current physical x coordinate.                                                                                            
		1       The current physical y coordinate.                                                                                            
		 2      The current view x coordinate. This returns the same value as the POINT(0) function if the WINDOW statement has not been used.
		3       The current view y coordinate. This returns the same value as the POINT(1) function if the WINDOW statement has not been used.
		

Description
	GfxLib Function with two different uses.
	If supplied with two coordinates it reads the color of the pixel at the 
	coordinate coord_x, coord_y of the screen, or of the buffer, if 
	supplied.
	The value return is a color index in a 256 or less color 
	KeyPgScreengraphicsScreen (Graphics), and an KeyPgRgbRGB value in true color modes. If the 
	coordinates are off-screen or off-buffer, -1 is returned

	If supplied with a single value it returns the one of the coordinates of 
	the graphics cursor as set by the last graphics command executed. If the 
	last command was executed in a buffer, the values returned will be 
	coordinates in the buffer. Arguments out of the range 0-3 will return 0.

	The function Point does not work in text modes.

	Speed note: while Point provides valid results, it is quite slow to call 
	repeatedly due to the overhead of additional calculations and checks. 
	Much better performance can be achieved by using direct memory access 
	using the results obtained from KeyPgImageInfoImageInfo and KeyPgScreeninfoScreenInfo/KeyPgScreenptrScreenPtr.

Example
	' Set an appropriate screen mode - 320 x 240 x 8bpp indexed color
	ScreenRes 320, 240, 8

	' Draw a line using color 12 (light red)
	Line (20,20)-(100,100), 12

	' Print the color of a point on the line
	Print Point(20,20)

	' Sleep before the program closes
	Sleep
	   

	Output:

	12
			

Version
	Before fbc 1.08.0, the return datatype was an KeyPgIntegerInteger.

Differences from QB
	* buffer is new to FreeBASIC
	* In 16 bpp and 32 bpp modes, a 32-bit value is returned instead of an 
	  8-bit palette index

See also
	* KeyPgPsetPSet - write pixels
	* KeyPgPmapPMap
	* KeyPgColorColor
	* KeyPgViewgraphicsView (Graphics)
	* KeyPgWindowWindow
	* GfxInternalFormatsInternal pixel formats

