From 72cc824502dfdba13b7566c1afe9228f968c03f9 Mon Sep 17 00:00:00 2001
From: Andreas Hocevar <andreas.hocevar@gmail.com>
Date: Fri, 12 Jun 2015 09:47:43 +0200
Subject: [PATCH] Explain changes in upgrade notes

---
 changelog/upgrade-notes.md | 47 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/changelog/upgrade-notes.md b/changelog/upgrade-notes.md
index 15c957ec08..5d3abb73d9 100644
--- a/changelog/upgrade-notes.md
+++ b/changelog/upgrade-notes.md
@@ -34,6 +34,53 @@ With the removal of `ol.FeatureOverlay`, `zIndex` symbolizer properties of overl
 
 Note that `ol.FeatureOverlay#getFeatures()` returned an `{ol.Collection.<ol.Feature>}`, whereas `ol.source.Vector#getFeatures()` returns an `{Array.<ol.Feature>}`.
 
+#### `ol.TileCoord` changes
+
+Until now, the API exposed two different types of `ol.TileCoord` tile coordinates: the internal ones with bottom-left origin, and transformed ones with an origin that is determined by the tile grid configuration. With this change, the API now only exposes the transformed tile coordinates.
+
+The first `tileCoord` argument of `ol.TileUrlFunctionType` now expects transformed tile coordinates instead of internal OpenLayers tile coordinates. Accordingly, `ol.tilegrid.TileGrid#getTileCoordForCoordAndZ` and `ol.tilegrid.TileGrid#getTileCoordForCoordAndResolution` now return transformed tile coordinates.
+
+This change affects applications that configure a custom `tileUrlFunction` for an `ol.source.Tile`. Previously, the `tileUrlFunction` was called with bottom-left origin tile coordinates that OpenLayers uses internally. To transform these into tile coordinates supported by the tile source, a custom `tileUrlFunction` had to change the `y` value of the `ol.TileCoord`. Now the `y` value can be used unaltered.
+
+To make it easier for application developers to perform this transform, the API provided an `ol.tilegrid.TileGrid#createTileCoordTransform()` function. This function is no longer available and no longer needed.
+
+The code snippets below show how your application code needs to be changed:
+
+Old application code (with `ol.tilegrid.TileGrid#createTileCoordTransform()`):
+```js
+var transform = source.getTileGrid().createTileCoordTransform();
+var tileUrlFunction = function(tileCoord, pixelRatio, projection) {
+  tileCoord = transform(tileCoord, projection);
+  return 'http://mytiles.com/' +
+      tileCoord[0] + '/' + tileCoord[1] + '/' + tileCoord[2] + '.png';
+};
+```
+Old application code (with custom `y` transform):
+```js
+var tileUrlFunction = function(tileCoord, pixelRatio, projection) {
+  var z = tileCoord[0];
+  var yFromBottom = tileCoord[2];
+  var resolution = tileGrid.getResolution(z);
+  var tileHeight = ol.size.toSize(tileSize)[1];
+  var matrixHeight =
+      Math.floor(ol.extent.getHeight(extent) / tileHeight / resolution);
+  return 'http://mytiles.com/' +
+      tileCoord[0] + '/' + tileCoord[1] + '/' +
+      (matrixHeight - yFromBottom - 1) + '.png';
+
+};
+```
+New application code (no transform needed):
+```js
+var tileUrlFunction = function(tileCoord, pixelRatio, projection) {
+  return 'http://mytiles.com/' +
+      tileCoord[0] + '/' + tileCoord[1] + '/' + tileCoord[2] + '.png';
+};
+```
+For easier debugging, `ol.source.DebugTile` was changed to display the transformed tile coordinates as well.
+
+Also watch out for sections in your code where you used `ol.tilegrid.TileGrid#getTileCoordForCoordAndZ()` or `ol.tilegrid.TileGrid#getTileCoordForCoordAndResolution()`. When working with the returned tile coordinates, changes equivalent to the ones shown in the above snippets are required.
+
 ### v3.6.0
 
 #### `ol.interaction.Draw` changes