introducing screen_to_world and world_to_screen in scrolling

ccanepa · ccanepa · commit a84999bc1196 · 2016-05-15T19:51:00.000-03:00
diff --git a/cocos/layer/scrolling.py b/cocos/layer/scrolling.py
@@ -65,6 +65,8 @@
 
 __docformat__ = 'restructuredtext'
 
+import warnings
+
 from cocos.director import director
 from .base_layers import Layer
 import pyglet
@@ -74,10 +76,12 @@
 class ScrollableLayer(Layer):
     """Layer that supports scrolling.
 
-    If ``px_width`` (resp ``px_height``) is defined, scrolling will be limited 
-    to only show areas with origin_x <= x < = px_width (resp 
+    If ``px_width`` is defined, then ``px_height`` must also be defined; scrolling
+    will be limited to only show areas with origin_x <= x < = px_width and
     origin_y <= y <= px_height).
 
+    If ``px_width`` is not defined, then the layer will not limit the scrolling.
+
     A layer may have a ``parallax`` value which is used to scale the position
     (and not the dimensions) of the view for the layer - the layer's view
     (x, y) coordinates are calculated as::
@@ -291,7 +295,14 @@ def add(self, child, z=0, name=None):
         self.set_focus(self.fx, self.fy, force=True)
 
     def pixel_from_screen(self, x, y):
-        """Look up the Layer-space pixel matching the screen-space pixel.
+        """deprecated, was renamed as screen_to_world"""
+        warnings.warn("Cocos Deprecation Warning: ScrollingManager.pixel_from_screen "
+                      "was renamed to Scrolling Manager.screen_to_world; the"
+                      " former will disappear in future cocos releases")
+        return self.screen_to_world(x, y)
+
+    def screen_to_world(self, x, y):
+        """Translates screen coordinates to world coordinates.
 
         Account for viewport, layer and screen transformations.
 
@@ -300,7 +311,7 @@ def pixel_from_screen(self, x, y):
             y (int): y coordinate in screen space
 
         Returns:
-            tuple[int, int]: coordinates in map-space
+            tuple[int, int]: coordinates in world-space
         """
         # director display scaling
         if director.autoscale:
@@ -322,13 +333,20 @@ def pixel_from_screen(self, x, y):
         return int(vx + sx * w), int(vy + sy * h)
 
     def pixel_to_screen(self, x, y):
-        """Look up the screen-space pixel matching the Layer-space pixel.
+        """deprecated, was renamed as world_to_screen"""
+        warnings.warn("Cocos Deprecation Warning: ScrollingManager.pixel_to_screen "
+                      "was renamed to Scrolling Manager.world_to_screen; the"
+                      " former will disappear in future cocos releases")
+        return self.world_to_screen(x, y)
+
+    def world_to_screen(self, x, y):
+        """Translates world coordinates to screen coordinates.
 
         Account for viewport, layer and screen transformations.
 
         Arguments:
-            x (int): x coordinate in map space
-            y (int): y coordinate in map space
+            x (int): x coordinate in world space
+            y (int): y coordinate in world space
 
         Returns:
             tuple[int, int]: coordinates in screen space
@@ -338,12 +356,11 @@ def pixel_to_screen(self, x, y):
         return int(screen_x), int(screen_y)
 
     def set_focus(self, fx, fy, force=False):
-        """Determine the viewport based on a desired focus pixel in the
-        Layer space (fx, fy) and honoring any bounding restrictions of
-        child layers.
+        """Makes the point (fx, fy) show as near the view's center as possible.
 
-        The focus will always be shifted to ensure no child layers display
-        out-of-bounds data, as defined by their dimensions ``px_width`` and ``px_height``.
+        Changes his children so that the point (fx, fy) in world coordinates
+        will be seen as near the view center as possible, while at the
+        same time not displaying out-of-bounds areas in the children.
 
         Args:
             fx (int): the focus point x coordinate
diff --git a/samples/mouse_elastic_box_selection.py b/samples/mouse_elastic_box_selection.py
@@ -1,4 +1,4 @@
-# -*- coding: cp1252 -*-
+# -*- coding: utf-8 -*-
 """
 Interactive test for CollisionManager.objs_into_box
 Implements click selection plus elastic box selection
@@ -601,8 +601,8 @@ def on_enter(self):
 scene.add(scrolling_manager)
 playview = Worldview(**consts['world'])
 scrolling_manager.add(playview, z=0)
-world_to_screen = scrolling_manager.pixel_to_screen
-screen_to_world = scrolling_manager.pixel_from_screen
+world_to_screen = scrolling_manager.world_to_screen
+screen_to_world = scrolling_manager.screen_to_world
 editor = EditLayer(scrolling_manager, playview, **consts['edit'])
 scene.add(editor)
 director.run(scene)
diff --git a/test/test_scrolling_manager_without_tiles.py b/test/test_scrolling_manager_without_tiles.py
@@ -137,8 +137,8 @@ def on_key_release(self, k, m ):
     def on_mouse_press(self,x,y,button,modifiers):
         # test from screen coords
         print('on_mouse_press:')
-        vx, vy = self.scroller.pixel_from_screen(x,y)
-        print('\tpixel_from_screen(x, y):', vx, vy)
+        vx, vy = self.scroller.screen_to_world(x,y)
+        print('\tscreen_to_world(x, y):', vx, vy)
 
     def clamp(self, actor, new_pos):
         x,y = new_pos
@@ -182,7 +182,7 @@ def update_after_change(self):
 
     def refresh_marks(self):
         for mark, position in zip(self.scene.marks, self.marks_positions):
-            screen_pos = self.scroller.pixel_to_screen(*position)
+            screen_pos = self.scroller.world_to_screen(*position)
             mark.position = screen_pos
 
     def teleport_player(self, x, y):
@@ -220,11 +220,6 @@ def show_common_text():
 use arrows to move, +- in the main keyboard (not the keypad) for zoom,
 ctrl-f to toggle fullscreen status.
 
-You will need grossinis_sister1.png , to be found in the test directory.
-
-You will need cocos r966+ ( for 'cocos_on_resize' event and supresion of
-NotImplementedError in pixel_to_screen)
-
 For clarity set view_width, view_height to respect your desktop aspect
 ratio; look near the script begin
 
@@ -253,17 +248,17 @@ def show_mode_1_text():
     zoom in or out using key '+' or '-', not so much that all the world shows
     in a single screen, then repeat 1), 2)
 
-4. consistency screen to world coordinates conversion(aka pixel_from_screen):
+4. consistency screen to world coordinates conversion:
     a. restart the script, mouse click the inner bottom left corner, do ctrl-f
     click again over the inner bottom left corner, zoom a little, click again
     over the the inner bottom left corner.
-    Now look at the console: the pixel_from_screen values must all be near a
+    Now look at the console: the screen_to_world values must all be near a
     common value.
 
     b. restart the script, scroll to the top right corner, repeat a. replacing
     'botton left' by 'top left'
 
-5. world to screen coordinate changes (aka pixel_to_screen) correctness:
+5. world to screen coordinate changes correctness:
     restart the script; move a bit. Look at the lower left corners in the lower
     row of squares; you should see a small square in the shades of green.
     moving, zomming, resizing (ctrl-f) should not alter the relative position of
@@ -303,17 +298,17 @@ def show_mode_2_text():
     zoom in or out using key '+' or '-', not so much that all the world shows
     in a single screen, then repeat 1), 2)
 
-4. consistency screen to world coordinates conversion(aka pixel_from_screen):
+4. consistency screen to world coordinates conversion:
     a. restart the script, mouse click the inner bottom left corner, do ctrl-f
     click again over the inner bottom left corner, zoom a litle, click again
     over the the inner bottom left corner.
-    Now look at the console: the pixel_from_screen values must all be near a
+    Now look at the console: the screen_to_world values must all be near a
     common value.
 
     b. restart the script, scroll to the top right corner, repeat a. replacing
     'botton left' by 'top left'
 
-5. world to screen coordinate changes (aka pixel_to_screen) correctness:
+5. world to screen coordinate changes correctness:
     restart the script; move a bit. Look at the lower left corners in the lower
     row of squares; you should see a small square in the shades of green.
     moving, zomming, resizing (ctrl-f) should not alter the relative position of
diff --git a/test/test_scrolling_manager_without_tiles_autoscale.py b/test/test_scrolling_manager_without_tiles_autoscale.py
@@ -136,8 +136,8 @@ def on_key_release(self, k, m ):
     def on_mouse_press(self,x,y,button,modifiers):
         # test from screen coords
         print('on_mouse_press:')
-        vx, vy = self.scroller.pixel_from_screen(x,y)
-        print('\tpixel_from_screen(x, y):', vx, vy)
+        vx, vy = self.scroller.screen_to_world(x,y)
+        print('\tscreen_to_world(x, y):', vx, vy)
 
     def clamp(self, actor, new_pos):
         x,y = new_pos
@@ -181,7 +181,7 @@ def update_after_change(self):
 
     def refresh_marks(self):
         for mark, position in zip(self.scene.marks, self.marks_positions):
-            screen_pos = self.scroller.pixel_to_screen(*position)
+            screen_pos = self.scroller.world_to_screen(*position)
             mark.position = screen_pos
 
     def teleport_player(self, x, y):
@@ -219,11 +219,6 @@ def show_common_text():
 use arrows to move, +- in the main keyboard (not the keypad) for zoom,
 ctrl-f to toggle fullscreen status.
 
-You will need grossinis_sister1.png , to be found in the test directory.
-
-You will need cocos r966+ ( for 'cocos_on_resize' event and supresion of
-NotImplementedError in pixel_to_screen)
-
 For clarity set view_width, view_height to respect your desktop aspect
 ratio; look near the script begin
 
@@ -252,17 +247,17 @@ def show_mode_1_text():
     zoom in or out using key '+' or '-', not so much that all the world shows
     in a single screen, then repeat 1), 2)
 
-4. consistency screen to world coordinates conversion(aka pixel_from_screen):
+4. consistency screen to world coordinates conversion:
     a. restart the script, mouse click the inner bottom left corner, do ctrl-f
     click again over the inner bottom left corner, zoom a little, click again
     over the the inner bottom left corner.
-    Now look at the console: the pixel_from_screen values must all be near a
+    Now look at the console: the screen_to_world values must all be near a
     common value.
 
     b. restart the script, scroll to the top right corner, repeat a. replacing
     'botton left' by 'top left'
 
-5. world to screen coordinate changes (aka pixel_to_screen) correctness:
+5. world to screen coordinate changes correctness:
     restart the script; move a bit. Look at the lower left corners in the lower
     row of squares; you should see a small square in the shades of green.
     moving, zomming, resizing (ctrl-f) should not alter the relative position of
@@ -302,17 +297,17 @@ def show_mode_2_text():
     zoom in or out using key '+' or '-', not so much that all the world shows
     in a single screen, then repeat 1), 2)
 
-4. consistency screen to world coordinates conversion(aka pixel_from_screen):
+4. consistency screen to world coordinates conversion:
     a. restart the script, mouse click the inner bottom left corner, do ctrl-f
     click again over the inner bottom left corner, zoom a litle, click again
     over the the inner bottom left corner.
-    Now look at the console: the pixel_from_screen values must all be near a
+    Now look at the console: the screen_to_world values must all be near a
     common value.
 
     b. restart the script, scroll to the top right corner, repeat a. replacing
     'botton left' by 'top left'
 
-5. world to screen coordinate changes (aka pixel_to_screen) correctness:
+5. world to screen coordinate changes correctness:
     restart the script; move a bit. Look at the lower left corners in the lower
     row of squares; you should see a small square in the shades of green.
     moving, zomming, resizing (ctrl-f) should not alter the relative position of
diff --git a/test/test_tmx_hexmap.py b/test/test_tmx_hexmap.py
@@ -83,7 +83,7 @@ def on_key_press(key, modifier):
     def on_mouse_motion(x, y, dx, dy ):
         global scroller, old_ij, old_cell, old_highlighted_color
         #vh, vy = director.get_virtual_coordinates(x, y)
-        vx, vy = scroller.pixel_from_screen(x,y)
+        vx, vy = scroller.screen_to_world(x,y)
         ij = test_layer.get_key_at_pixel(vx, vy)
         if ij == old_ij:
             return
diff --git a/tools/editor.py b/tools/editor.py
@@ -104,7 +104,7 @@ def on_mouse_release(self, x, y, buttons, modifiers):
         m = self.selector.map_layer
 
         # get the cell and cell coordinate
-        x, y = self.manager.pixel_from_screen(x, y)
+        x, y = self.manager.screen_to_world(x, y)
         cell = m.get_at_pixel(x, y)
         if not cell:
             # click not in map
@@ -121,7 +121,7 @@ def on_mouse_release(self, x, y, buttons, modifiers):
 
     def on_mouse_motion(self, x, y, dx, dy):
         m = self.selector.map_layer
-        cell = m.get_at_pixel(*self.manager.pixel_from_screen(x, y))
+        cell = m.get_at_pixel(*self.manager.screen_to_world(x, y))
         if not cell:
             self.highlight = None
             return True
