From e074b6775e0bc5ed3e85bea3b1610d0e155d0a05 Mon Sep 17 00:00:00 2001
From: Jan Haller <bromeon@gmail.com>
Date: Wed, 5 Feb 2014 10:27:59 +0100
Subject: [PATCH] Added documentation note on coordinates and undistorted
 rendering

---
 include/SFML/Graphics/Sprite.hpp        |  2 ++
 include/SFML/Graphics/Text.hpp          |  2 ++
 include/SFML/Graphics/Transformable.hpp | 12 ++++++++++++
 include/SFML/Graphics/View.hpp          |  2 ++
 4 files changed, 18 insertions(+)

diff --git a/include/SFML/Graphics/Sprite.hpp b/include/SFML/Graphics/Sprite.hpp
index 954881d8..eda67608 100644
--- a/include/SFML/Graphics/Sprite.hpp
+++ b/include/SFML/Graphics/Sprite.hpp
@@ -255,6 +255,8 @@ private :
 /// used by a sf::Sprite (i.e. never write a function that
 /// uses a local sf::Texture instance for creating a sprite).
 ///
+/// See also the note on coordinates and undistorted rendering in sf::Transformable.
+///
 /// Usage example:
 /// \code
 /// // Declare and load a texture
diff --git a/include/SFML/Graphics/Text.hpp b/include/SFML/Graphics/Text.hpp
index 04abd243..aea83ecf 100644
--- a/include/SFML/Graphics/Text.hpp
+++ b/include/SFML/Graphics/Text.hpp
@@ -330,6 +330,8 @@ private :
 /// used by a sf::Text (i.e. never write a function that
 /// uses a local sf::Font instance for creating a text).
 ///
+/// See also the note on coordinates and undistorted rendering in sf::Transformable.
+///
 /// Usage example:
 /// \code
 /// // Declare and load a font
diff --git a/include/SFML/Graphics/Transformable.hpp b/include/SFML/Graphics/Transformable.hpp
index 28fb3863..fccf8f1e 100644
--- a/include/SFML/Graphics/Transformable.hpp
+++ b/include/SFML/Graphics/Transformable.hpp
@@ -412,6 +412,18 @@ private :
 /// };
 /// \endcode
 ///
+/// A note on coordinates and undistorted rendering: \n
+/// By default, SFML (or more exactly, OpenGL) may interpolate drawable objects  
+/// such as sprites or texts when rendering. While this allows transitions
+/// like slow movements or rotations to appear smoothly, it can lead to
+/// unwanted results in some cases, for example blurred or distorted objects.
+/// In order to render a sf::Drawable object pixel-perfectly, make sure
+/// the involved coordinates allow a 1:1 mapping of pixels in the window
+/// to texels (pixels in the texture). More specifically, this means:
+/// * The object's position, origin and scale have no fractional part
+/// * The object's and the view's rotation are a multiple of 90 degrees
+/// * The view's center and size have no fractional part
+/// 
 /// \see sf::Transform
 ///
 ////////////////////////////////////////////////////////////
diff --git a/include/SFML/Graphics/View.hpp b/include/SFML/Graphics/View.hpp
index 7713aef6..0004a5b5 100644
--- a/include/SFML/Graphics/View.hpp
+++ b/include/SFML/Graphics/View.hpp
@@ -336,6 +336,8 @@ private :
 /// window.draw(someText);
 /// \endcode
 ///
+/// See also the note on coordinates and undistorted rendering in sf::Transformable.
+///
 /// \see sf::RenderWindow, sf::RenderTexture
 ///
 ////////////////////////////////////////////////////////////