Added window_to_world coordinates

README.md

@@ -110,6 +110,16 @@ It is recommended to send the window width and height from the render script to
 NOTE: In order for this to work you need to make sure that the `Shared State` setting in the `Script` section of `game.project` is checked (defaults to checked)
 
 
+### Window vs Screen coordinates
+The camera API allows you to convert to and from world coordinates. This is useful when positioning a game object at the position of the mouse or knowing where in a game world a mouse click was made. The API supports conversion from both window and screen coordinates.
+
+#### Screen coordinates
+This refers to the actual mouse pixel position within the window, scaled to the display size specified in game.project. These are the values from `action.x` and `action.y` in `on_input()``
+
+#### Window coordinates
+This refers to the actual mouse pixel position within the window. These are the values from `action.screen_x` and `action.screen_y` in `on_input()`. Window coordinates should be provided as is, without compensation for High DPI (this will be done automatically).
+
+
 ### Example render script
 The orthographic/render folder contains a render script that does the above mentioned integration of the Orthographic Camera API. Use it as it is or copy it into your project and make whatever modifications that you need.
 
@@ -212,6 +222,17 @@ Translate screen coordinates to world coordinates, based on the view and project
 * ```world_coords``` (vector3) World coordinates
 
 
+### camera.window_to_world(camera_id, window)
+Translate window coordinates to world coordinates, based on the view and projection of the camera.
+
+**PARAMETERS**
+* ```camera_id``` (hash|url)
+* ```window``` (vector3) Window coordinates to convert
+
+**RETURN**
+* ```world_coords``` (vector3) World coordinates
+
+
 ### camera.screen_to_world_bounds(camera_id)
 Translate screen boundaries (corners) to world coordinates, based on the view and projection of the camera.
 

orthographic/camera.lua

@@ -2,6 +2,8 @@
 
 local M = {}
 
+local dpi_ratio = (sys.get_config("display.high_dpi", "0") == "1") and 0.5 or 1.0
+
 M.SHAKE_BOTH = hash("both")
 M.SHAKE_HORIZONTAL = hash("horizontal")
 M.SHAKE_VERTICAL = hash("vertical")
@@ -439,6 +441,8 @@ end
 
 --- Convert screen coordinates to world coordinates based
 -- on a specific camera's view and projection
+-- Screen coordinates are the scaled coordinates provided by action.x and action.y
+-- in on_input()
 -- @param camera_id
 -- @param screen Screen coordinates as a vector3
 -- @return World coordinates
@@ -452,8 +456,27 @@ function M.screen_to_world(camera_id, screen)
 end
 
 
---- Convert world coordinates to screen coordinates based
+--- Convert window coordinates to world coordinates based
 -- on a specific camera's view and projection
+-- Window coordinates are the non-scaled coordinates provided by action.screen_x
+-- and action.screen_y in on_input()
+-- @param camera_id
+-- @param window Window coordinates as a vector3
+-- @return World coordinates
+function M.window_to_world(camera_id, window)
+	assert(camera_id, "You must provide a camera id")
+	assert(window, "You must provide window coordinates to convert")
+	local view = cameras[camera_id].view or MATRIX4
+	local projection = cameras[camera_id].projection or MATRIX4
+	local scale_x = window.x * dpi_ratio * DISPLAY_WIDTH / WINDOW_WIDTH
+	local scale_y = window.y * dpi_ratio * DISPLAY_HEIGHT / WINDOW_HEIGHT
+	local screen = vmath.vector3(scale_x, scale_y, 0)
+	return M.unproject(view, projection, screen)
+end
+
+
+--- Convert world coordinates to screen coordinates based
+-- on a specific camera's view and projection.
 -- @param camera_id
 -- @param world World coordinates as a vector3
 -- @return Screen coordinates