diff --git a/docs/design/designdoc.rst b/docs/design/designdoc.rst index a97b182..357ecd7 100644 --- a/docs/design/designdoc.rst +++ b/docs/design/designdoc.rst @@ -336,6 +336,128 @@ Tile Rendering ============== .. Covers the placement of chunk images on a tile +So now that we know how to draw a single chunk, we can move on to placing them +on an image. + +For the diagrams in this section, we are positioning an entire chunk, but +frequently, only the top face of the chunk is drawn (shown in green below). + +.. image:: tilerendering/topofchunk.png + :alt: The top of a chunk is highlighted + +This makes it easier and less cumbersome to describe chunk positionings. Just +remember that chunks extend down for 1536 more pixels. + +Chunk Addressing +---------------- + +Chunks in Minecraft have an X,Z address, starting at 0,0 and extending to +positive and negative infinity on both axes. Since we're looking at things +diagonally, however, we need a way of addressing these chunks in the final +image. For that, we refer to them in rows and columns. Consider this grid +showing the tops of a five by five region of chunks, labeled with their in-game +addresses. + +.. image:: tilerendering/chunkgrid.png + :alt: A grid of 5x5 chunks showing how chunks are addressed. + +Now, we want to transform each chunk to a row/column address as shown here: + +.. image:: tilerendering/chunkgridwithrowcol.png + :alt: A grid of 5x5 chunks showing how chunks are addressed. + +So the chunk at address 0,0 would be at col 0, row 0; while the chunk at address +1,1 would be at col 2, row 0. The intersection of the red and green lines +addresses the chunk in col,row format. + +Notice that as a consequence of this addressing scheme, there is no chunk at +e.g. column 1 row 0. There are some col,row addresses that lie between chunks +(as can be seen where the red/green lines intersect at a chunk boundary instead +of the middle of a chunk). Something to keep in mind. + +So how does one translate between them? It turns out that a chunk's column +address is simply the sum of the X and the Z coordinate, while the row is the +difference. Try it! + +:: + + col = X + Z + row = Z - X + + X = (col - row) / 2 + Z = (col + row) / 2 + +Chunk Positioning +----------------- +Again just looking at the top of a chunk, we can work out how to position them +relative to each other. This is similar to how to position blocks relative to +each other, but this time, for chunks. + +A chunk's top face is 384 pixels wide by 192 pixels tall. Similar to the block, +neighboring chunks have these relationships: + +.. image:: tilerendering/chunkpositioning.png + :alt: Chunk positioning diagram + +But that's all pretty trivial. With this knowledge, we could draw the chunks at +the above offsets in one large image, but for large worlds, that would quickly +become too much to handle. (Early versions of the Overviewer did this, but the +large, unwieldy images quickly motivated the development of rendering to +individual tiles) + +Tile Layout +----------- + +Instead of rendering to one large image, chunks are rendered to small tiles. +Only a handful of chunks need to be rendered into each tile. The downside is +that chunks must be rendered multiple times for each tile they appear in, but +the upside is that arbitrarily sized maps can be viewed. + +The Overviewer uses a tile size of 384 by 384 pixels. This is the same as a +width of a chunk and is no coincidence. Just considering the top face of a +chunk, 8 chunks get rendered into a tile in this configuration: + +.. image:: tilerendering/chunksintile.png + :alt: The 8 chunks that get rendered into a tile + +So the overall strategy is to convert all chunks into diagonal col,row +coordinates, then for each tile decide which chunks belong in it, then render +them in the appropriate place on the tile. + +The rendering routines are actually passed a range of chunks to render, e.g. +rows 4-6, cols 20-24. The lower bound col,row chunk given in the range is +rendered at position 0,0 in the diagram above. That is, at offset -192,-96 +pixels. + +The rendering routines takes the given range of columns and rows, converts it +back into chunk coordinates, and renders the given 8 chunks plus all chunks from +the 16 rows above the given range (see the note below). The chunks are +positioned correctly with the above positioning rules, so any chunks that are +out of the bounds get rendered off the tile and don't affect the final image. +(There is therefore no penalty for rendering out-of-bounds chunks for a tile +except increased processing) + +.. note:: + + Remember that chunks are actually very tall, so there are actually several + rows above 0 in the above diagram that are rendered into the tile. Since the + chunk outlines in the diagrams are only the top face of the chunk, they most + likely don't contribute to the image since chunks usually don't have + anything to render way up at the top near the sky. + +Since every other column of chunks is half-way in two tiles, they must be +rendered twice. Each neighboring tile is therefore only 2 columns over, not 3 as +one may suspect at first. Same goes for the rows: The next tile down is 4 rows +down, not 5. + +Quadtrees +========= +.. About the tile output + +get_range_by_path +----------------- +.. Explain the quadtree.QuadtreeGen._get_range_by_path method + Reading the Data Files ====================== .. diff --git a/docs/design/tilerendering/chunkgrid.png b/docs/design/tilerendering/chunkgrid.png new file mode 100644 index 0000000..53f793d Binary files /dev/null and b/docs/design/tilerendering/chunkgrid.png differ diff --git a/docs/design/tilerendering/chunkgrid.svg b/docs/design/tilerendering/chunkgrid.svg new file mode 100644 index 0000000..1b53af5 --- /dev/null +++ b/docs/design/tilerendering/chunkgrid.svg @@ -0,0 +1,529 @@ + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + 0,0 + 1,1 + 2,2 + -1,-1 + -2,-2 + 1,-1 + 2,-2 + -1,1 + -2,2 + 0,1 + 0,2 + -1,2 + 1,0 + 2,-1 + 2,0 + 2,1 + 1,2 + -2,1 + -1,0 + -2,0 + 0,-1 + 0,-2 + 1,-2 + -1,-2 + -2,-1 + X + Z + + + + diff --git a/docs/design/tilerendering/chunkgridwithrowcol.png b/docs/design/tilerendering/chunkgridwithrowcol.png new file mode 100644 index 0000000..6f23725 Binary files /dev/null and b/docs/design/tilerendering/chunkgridwithrowcol.png differ diff --git a/docs/design/tilerendering/chunkgridwithrowcol.svg b/docs/design/tilerendering/chunkgridwithrowcol.svg new file mode 100644 index 0000000..0b94f76 --- /dev/null +++ b/docs/design/tilerendering/chunkgridwithrowcol.svg @@ -0,0 +1,786 @@ + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + 0,0 + + 1,1 + + 2,2 + + -1,-1 + + -2,-2 + + 1,-1 + + 2,-2 + -1,1 + -2,2 + 0,1 + 0,2 + -1,2 + 1,0 + 2,-1 + 2,0 + 2,1 + 1,2 + -2,1 + -1,0 + + -2,0 + + 0,-1 + + 1,-2 + + -1,-2 + + -2,-1 + Col 0 + Col 1 + Col 2 + Col 3 + Col 4 + Col -4 + Col -3 + Col -2 + Col -1 + Row 0 + Row 1 + Row 2 + Row 3 + Row 4 + + Row -1 + + Row -2 + + Row -3 + Row -4 + 0,-2 + + diff --git a/docs/design/tilerendering/chunkpositioning.png b/docs/design/tilerendering/chunkpositioning.png new file mode 100644 index 0000000..da21b39 Binary files /dev/null and b/docs/design/tilerendering/chunkpositioning.png differ diff --git a/docs/design/tilerendering/chunkpositioning.svg b/docs/design/tilerendering/chunkpositioning.svg new file mode 100644 index 0000000..9b608b9 --- /dev/null +++ b/docs/design/tilerendering/chunkpositioning.svg @@ -0,0 +1,366 @@ + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + 384 + 192 + + + + + + + + + + + (1536) + + + + 192 + 96 + + + + + + + + + + 384 + + + + + + + + 192 + + + + + + diff --git a/docs/design/tilerendering/chunksintile.png b/docs/design/tilerendering/chunksintile.png new file mode 100644 index 0000000..9dc9cce Binary files /dev/null and b/docs/design/tilerendering/chunksintile.png differ diff --git a/docs/design/tilerendering/chunksintile.svg b/docs/design/tilerendering/chunksintile.svg new file mode 100644 index 0000000..1fbd5d0 --- /dev/null +++ b/docs/design/tilerendering/chunksintile.svg @@ -0,0 +1,326 @@ + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + Cols: + 0 + 1 + 2 + Rows: + 0 + 1 + 2 + 3 + 4 + 384 + + + + + 384 + + + + + + + + diff --git a/docs/design/tilerendering/topofchunk.png b/docs/design/tilerendering/topofchunk.png new file mode 100644 index 0000000..c67978c Binary files /dev/null and b/docs/design/tilerendering/topofchunk.png differ diff --git a/docs/design/tilerendering/topofchunk.svg b/docs/design/tilerendering/topofchunk.svg new file mode 100644 index 0000000..5cbeb24 --- /dev/null +++ b/docs/design/tilerendering/topofchunk.svg @@ -0,0 +1,4258 @@ + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + (Actual ChunkProportions) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + (DiagramFrom above) + + + +