Renamed convertCoords to mapPixelToCoords, and added its inverse mapCoordsToPixel

include/SFML/Graphics/RenderTexture.h

@@ -137,16 +137,57 @@ CSFML_GRAPHICS_API const sfView* sfRenderTexture_getDefaultView(const sfRenderTe
 CSFML_GRAPHICS_API sfIntRect sfRenderTexture_getViewport(const sfRenderTexture* renderTexture, const sfView* view);
 
 ////////////////////////////////////////////////////////////
-/// \brief Convert a point in texture coordinates into view coordinates
+/// \brief Convert a point from texture coordinates to world coordinates
+///
+/// This function finds the 2D position that matches the
+/// given pixel of the render-texture. In other words, it does
+/// the inverse of what the graphics card does, to find the
+/// initial position of a rendered pixel.
+///
+/// Initially, both coordinate systems (world units and target pixels)
+/// match perfectly. But if you define a custom view or resize your
+/// render-texture, this assertion is not true anymore, ie. a point
+/// located at (10, 50) in your render-texture may map to the point
+/// (150, 75) in your 2D world -- if the view is translated by (140, 25).
+///
+/// This version uses a custom view for calculations, see the other
+/// overload of the function if you want to use the current view of the
+/// render-texture.
 ///
 /// \param renderTexture Render texture object
-/// \param point         Point to convert, relative to the texture
-/// \param targetView    Target view to convert the point to (pass NULL to use the current view)
+/// \param point Pixel to convert
+/// \param view The view to use for converting the point
 ///
 /// \return The converted point, in "world" units
 ///
 ////////////////////////////////////////////////////////////
-CSFML_GRAPHICS_API sfVector2f sfRenderTexture_convertCoords(const sfRenderTexture* renderTexture, sfVector2i point, const sfView* targetView);
+CSFML_GRAPHICS_API sfVector2f sfRenderTexture_mapPixelToCoords(const sfRenderTexture* renderTexture, sfVector2i point, const sfView* view);
+
+////////////////////////////////////////////////////////////
+/// \brief Convert a point from world coordinates to texture coordinates
+///
+/// This function finds the pixel of the render-texture that matches
+/// the given 2D point. In other words, it goes through the same process
+/// as the graphics card, to compute the final position of a rendered point.
+///
+/// Initially, both coordinate systems (world units and target pixels)
+/// match perfectly. But if you define a custom view or resize your
+/// render-texture, this assertion is not true anymore, ie. a point
+/// located at (150, 75) in your 2D world may map to the pixel
+/// (10, 50) of your render-texture -- if the view is translated by (140, 25).
+///
+/// This version uses a custom view for calculations, see the other
+/// overload of the function if you want to use the current view of the
+/// render-texture.
+///
+/// \param renderTexture Render texture object
+/// \param point Point to convert
+/// \param view The view to use for converting the point
+///
+/// \return The converted point, in target coordinates (pixels)
+///
+////////////////////////////////////////////////////////////
+CSFML_GRAPHICS_API sfVector2i sfRenderTexture_mapCoordsToPixel(const sfRenderTexture* renderTexture, sfVector2f point, const sfView* view);
 
 ////////////////////////////////////////////////////////////
 /// \brief Draw a drawable object to the render-target

include/SFML/Graphics/RenderWindow.h

@@ -313,16 +313,60 @@ CSFML_GRAPHICS_API const sfView* sfRenderWindow_getDefaultView(const sfRenderWin
 CSFML_GRAPHICS_API sfIntRect sfRenderWindow_getViewport(const sfRenderWindow* renderWindow, const sfView* view);
 
 ////////////////////////////////////////////////////////////
-/// \brief Convert a point in window coordinates into view coordinates
+/// \brief Convert a point from window coordinates to world coordinates
+///
+/// This function finds the 2D position that matches the
+/// given pixel of the render-window. In other words, it does
+/// the inverse of what the graphics card does, to find the
+/// initial position of a rendered pixel.
+///
+/// Initially, both coordinate systems (world units and target pixels)
+/// match perfectly. But if you define a custom view or resize your
+/// render-window, this assertion is not true anymore, ie. a point
+/// located at (10, 50) in your render-window may map to the point
+/// (150, 75) in your 2D world -- if the view is translated by (140, 25).
+///
+/// This function is typically used to find which point (or object) is
+/// located below the mouse cursor.
+///
+/// This version uses a custom view for calculations, see the other
+/// overload of the function if you want to use the current view of the
+/// render-window.
 ///
 /// \param renderWindow Render window object
-/// \param point        Point to convert, relative to the window
-/// \param targetView   Target view to convert the point to (pass NULL to use the current view)
+/// \param point Pixel to convert
+/// \param view The view to use for converting the point
 ///
 /// \return The converted point, in "world" units
 ///
 ////////////////////////////////////////////////////////////
-CSFML_GRAPHICS_API sfVector2f sfRenderWindow_convertCoords(const sfRenderWindow* renderWindow, sfVector2i point, const sfView* targetView);
+CSFML_GRAPHICS_API sfVector2f sfRenderWindow_mapPixelToCoords(const sfRenderWindow* renderWindow, sfVector2i point, const sfView* view);
+
+////////////////////////////////////////////////////////////
+/// \brief Convert a point from world coordinates to window coordinates
+///
+/// This function finds the pixel of the render-window that matches
+/// the given 2D point. In other words, it goes through the same process
+/// as the graphics card, to compute the final position of a rendered point.
+///
+/// Initially, both coordinate systems (world units and target pixels)
+/// match perfectly. But if you define a custom view or resize your
+/// render-window, this assertion is not true anymore, ie. a point
+/// located at (150, 75) in your 2D world may map to the pixel
+/// (10, 50) of your render-window -- if the view is translated by (140, 25).
+///
+/// This version uses a custom view for calculations, see the other
+/// overload of the function if you want to use the current view of the
+/// render-window.
+///
+/// \param renderWindow Render window object
+/// \param point Point to convert
+/// \param view The view to use for converting the point
+///
+/// \return The converted point, in target coordinates (pixels)
+///
+////////////////////////////////////////////////////////////
+CSFML_GRAPHICS_API sfVector2i sfRenderWindow_mapCoordsToPixel(const sfRenderWindow* renderWindow, sfVector2f point, const sfView* view);
 
 ////////////////////////////////////////////////////////////
 /// \brief Draw a drawable object to the render-target

src/SFML/Graphics/RenderTexture.cpp

@@ -141,16 +141,35 @@ sfIntRect sfRenderTexture_getViewport(const sfRenderTexture* renderTexture, cons
 
 
 ////////////////////////////////////////////////////////////
-sfVector2f sfRenderTexture_convertCoords(const sfRenderTexture* renderTexture, sfVector2i point, const sfView* targetView)
+sfVector2f sfRenderTexture_mapPixelToCoords(const sfRenderTexture* renderTexture, sfVector2i point, const sfView* targetView)
 {
     sfVector2f result = {0, 0};
     CSFML_CHECK_RETURN(renderTexture, result);
 
     sf::Vector2f sfmlPoint;
     if (targetView)
-        sfmlPoint = renderTexture->This.convertCoords(sf::Vector2i(point.x, point.y), targetView->This);
+        sfmlPoint = renderTexture->This.mapPixelToCoords(sf::Vector2i(point.x, point.y), targetView->This);
     else
-        sfmlPoint = renderTexture->This.convertCoords(sf::Vector2i(point.x, point.y));
+        sfmlPoint = renderTexture->This.mapPixelToCoords(sf::Vector2i(point.x, point.y));
+
+    result.x = sfmlPoint.x;
+    result.y = sfmlPoint.y;
+
+    return result;
+}
+
+
+////////////////////////////////////////////////////////////
+sfVector2i sfRenderTexture_mapCoordsToPixel(const sfRenderTexture* renderTexture, sfVector2f point, const sfView* targetView)
+{
+    sfVector2i result = {0, 0};
+    CSFML_CHECK_RETURN(renderTexture, result);
+
+    sf::Vector2i sfmlPoint;
+    if (targetView)
+        sfmlPoint = renderTexture->This.mapCoordsToPixel(sf::Vector2f(point.x, point.y), targetView->This);
+    else
+        sfmlPoint = renderTexture->This.mapCoordsToPixel(sf::Vector2f(point.x, point.y));
 
     result.x = sfmlPoint.x;
     result.y = sfmlPoint.y;

src/SFML/Graphics/RenderWindow.cpp

@@ -346,16 +346,35 @@ sfIntRect sfRenderWindow_getViewport(const sfRenderWindow* renderWindow, const s
 
 
 ////////////////////////////////////////////////////////////
-sfVector2f sfRenderWindow_convertCoords(const sfRenderWindow* renderWindow, sfVector2i point, const sfView* targetView)
+sfVector2f sfRenderWindow_mapPixelToCoords(const sfRenderWindow* renderWindow, sfVector2i point, const sfView* targetView)
 {
     sfVector2f result = {0, 0};
     CSFML_CHECK_RETURN(renderWindow, result);
 
     sf::Vector2f sfmlPoint;
     if (targetView)
-        sfmlPoint = renderWindow->This.convertCoords(sf::Vector2i(point.x, point.y), targetView->This);
+        sfmlPoint = renderWindow->This.mapPixelToCoords(sf::Vector2i(point.x, point.y), targetView->This);
     else
-        sfmlPoint = renderWindow->This.convertCoords(sf::Vector2i(point.x, point.y));
+        sfmlPoint = renderWindow->This.mapPixelToCoords(sf::Vector2i(point.x, point.y));
+
+    result.x = sfmlPoint.x;
+    result.y = sfmlPoint.y;
+
+    return result;
+}
+
+
+////////////////////////////////////////////////////////////
+sfVector2i sfRenderWindow_mapCoordsToPixel(const sfRenderWindow* renderWindow, sfVector2f point, const sfView* targetView)
+{
+    sfVector2i result = {0, 0};
+    CSFML_CHECK_RETURN(renderWindow, result);
+
+    sf::Vector2i sfmlPoint;
+    if (targetView)
+        sfmlPoint = renderWindow->This.mapCoordsToPixel(sf::Vector2f(point.x, point.y), targetView->This);
+    else
+        sfmlPoint = renderWindow->This.mapCoordsToPixel(sf::Vector2f(point.x, point.y));
 
     result.x = sfmlPoint.x;
     result.y = sfmlPoint.y;