From 421f5597db52dcbc56b6355a5cb2a4e408c94110 Mon Sep 17 00:00:00 2001 From: Eli Clemente Gordillo Foster Date: Fri, 17 Mar 2017 14:47:41 -0700 Subject: [PATCH 1/7] Create tesr.md --- docs/tileentities/tesr.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 docs/tileentities/tesr.md diff --git a/docs/tileentities/tesr.md b/docs/tileentities/tesr.md new file mode 100644 index 00000000..d0601952 --- /dev/null +++ b/docs/tileentities/tesr.md @@ -0,0 +1,20 @@ +TileEntitySpecialRenderer +========================= + +A `TileEntitySpecialRenderer` (TESR) is used for handling additional rendering behavior for tile entities. OpenGL (via `GlStateManager`) is used to handle rendering in a TESR. See the OpenGL documentation to learn more. + +Creating a TESR +--------------- + +To create a TESR, create a class that inherits from `TileEntitySpecialRenderer`. It takes a generic argument, of which the object must inherit from `TileEntity`. The generic argument is used in the TESR's method, `renderTileEntityAt`. + +Only one TESR exists for a given tile entity. Therefore, values that are specific to a single instance in the world should be stored in the tile entity being passed to the renderer rather than in the TESR itself. For example, an integer that increments every frame, if stored in the TESR, will increment every frame for every tile entity of this type in the world. + +### `renderTileEntityAt` + +This method is called every frame in order to render the tile entity. It passes the instance of the tile entity being renderered, its coordinates as doubles at the origin of the block, partialTicks, and the destroy stage of the block if being destroyed. + +Registering a TESR +------------------ + +In order to register a TESR, call `ClientRegistry#bindTileEntitySpecialRenderer` passing the tile entity class to be renderer with this TESR and the instance of the TESR to use to render all TEs of this class. From a979517ea05d43a3907bbd44bfe6538e4b7fc613 Mon Sep 17 00:00:00 2001 From: Eli Clemente Gordillo Foster Date: Fri, 17 Mar 2017 14:48:59 -0700 Subject: [PATCH 2/7] add tesr --- mkdocs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index f083d14c..ffdf2da7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -16,6 +16,8 @@ pages: - Intro to Blockstates: 'blockstates/states.md' - Intro to Blockstate JSONs: 'blockstates/introduction.md' - Forge Blockstate JSON: 'blockstates/forgeBlockstates.md' + - Tile Entities: + - Special Renderer: 'tileentities/tesr.md' - Items: - Home: 'items/items.md' - Events: From dbeaea31a9d27534e338aa671bf2977f96e7ca5b Mon Sep 17 00:00:00 2001 From: Eli Clemente Gordillo Foster Date: Fri, 17 Mar 2017 15:05:00 -0700 Subject: [PATCH 3/7] Expand parameters a bit --- docs/tileentities/tesr.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/tileentities/tesr.md b/docs/tileentities/tesr.md index d0601952..71a58db8 100644 --- a/docs/tileentities/tesr.md +++ b/docs/tileentities/tesr.md @@ -12,7 +12,13 @@ Only one TESR exists for a given tile entity. Therefore, values that are specifi ### `renderTileEntityAt` -This method is called every frame in order to render the tile entity. It passes the instance of the tile entity being renderered, its coordinates as doubles at the origin of the block, partialTicks, and the destroy stage of the block if being destroyed. +This method is called every frame in order to render the tile entity. + +#### Parameters +* `tileentity`: This is the instanceof the tile entity being rendered. It uses the generic argument, so, if the class is being inherited correctly, it will not need to be cast to your tile entity class. +* `x`, `y`, `z`: The coordinates of the tile entity as doubles. They are at the origin of the block. +* `partialTicks`: The amount of times, in fractions of a tick, that have passed since the last full tick. +* `destroyStage`: The destroy stage for the block if it is being broken. Registering a TESR ------------------ From bebb9870f62510f1df896c8deb339bb8520d99f0 Mon Sep 17 00:00:00 2001 From: Eli Clemente Gordillo Foster Date: Sat, 18 Mar 2017 13:07:45 -0700 Subject: [PATCH 4/7] Fix x, y, z params desc --- docs/tileentities/tesr.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tileentities/tesr.md b/docs/tileentities/tesr.md index 71a58db8..0fa629c1 100644 --- a/docs/tileentities/tesr.md +++ b/docs/tileentities/tesr.md @@ -16,7 +16,7 @@ This method is called every frame in order to render the tile entity. #### Parameters * `tileentity`: This is the instanceof the tile entity being rendered. It uses the generic argument, so, if the class is being inherited correctly, it will not need to be cast to your tile entity class. -* `x`, `y`, `z`: The coordinates of the tile entity as doubles. They are at the origin of the block. +* `x`, `y`, `z`: The coordinates at which the tile entity should be rendered. * `partialTicks`: The amount of times, in fractions of a tick, that have passed since the last full tick. * `destroyStage`: The destroy stage for the block if it is being broken. From 1c322aaa817f1b83788b3f8f7750a9017a071394 Mon Sep 17 00:00:00 2001 From: diesieben07 Date: Wed, 22 Mar 2017 15:53:40 +0100 Subject: [PATCH 5/7] Add info about FastTESR and some other improvements --- docs/tileentities/tesr.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/tileentities/tesr.md b/docs/tileentities/tesr.md index 0fa629c1..935e155c 100644 --- a/docs/tileentities/tesr.md +++ b/docs/tileentities/tesr.md @@ -1,12 +1,14 @@ TileEntitySpecialRenderer ========================= -A `TileEntitySpecialRenderer` (TESR) is used for handling additional rendering behavior for tile entities. OpenGL (via `GlStateManager`) is used to handle rendering in a TESR. See the OpenGL documentation to learn more. +A `TileEntitySpecialRenderer` (TESR) is used to render blocks in a way that cannot be represented with a static baked model (JSON, OBJ, B3D, others). A TESR requires the block to have a TileEntity. + +By default OpenGL (via `GlStateManager`) is used to handle rendering in a TESR. See the OpenGL documentation to learn more. It is recommended to use a FastTESR instead whenever possible. Creating a TESR --------------- -To create a TESR, create a class that inherits from `TileEntitySpecialRenderer`. It takes a generic argument, of which the object must inherit from `TileEntity`. The generic argument is used in the TESR's method, `renderTileEntityAt`. +To create a TESR, create a class that inherits from `TileEntitySpecialRenderer`. It takes a generic argument specifying the block's TileEntity class. The generic argument is used in the TESR's `renderTileEntityAt` method. Only one TESR exists for a given tile entity. Therefore, values that are specific to a single instance in the world should be stored in the tile entity being passed to the renderer rather than in the TESR itself. For example, an integer that increments every frame, if stored in the TESR, will increment every frame for every tile entity of this type in the world. @@ -15,12 +17,19 @@ Only one TESR exists for a given tile entity. Therefore, values that are specifi This method is called every frame in order to render the tile entity. #### Parameters -* `tileentity`: This is the instanceof the tile entity being rendered. It uses the generic argument, so, if the class is being inherited correctly, it will not need to be cast to your tile entity class. -* `x`, `y`, `z`: The coordinates at which the tile entity should be rendered. -* `partialTicks`: The amount of times, in fractions of a tick, that have passed since the last full tick. +* `tileentity`: This is the instance of the tile entity being rendered. +* `x`, `y`, `z`: The position at which the tile entity should be rendered. +* `partialTicks`: The amount of time, in fractions of a tick, that has passed since the last full tick. * `destroyStage`: The destroy stage for the block if it is being broken. Registering a TESR ------------------ In order to register a TESR, call `ClientRegistry#bindTileEntitySpecialRenderer` passing the tile entity class to be renderer with this TESR and the instance of the TESR to use to render all TEs of this class. + +`FastTESR` +---------- + +A TESR can opt-in to being a FastTESR by extending the `FastTESR` class instead of `TileEntitySpecialRenderer`. Instead of implementing `renderTileEntityAt`, `renderTileEntityFast` must be implemented. + +A FastTESR can offer performance improvements over a traditional TESR and should be used wherever possible. This is due to the fact that all FastTESR instances are batched together and only issue _one_ combined draw call for all FastTESRs per frame to the GPU. This advantage comes at the cost of making direct OpenGL access via `GlStateManager` or the `GLXX` classes impossible. Instead a FastTESR must only add vertices to the provided `VertexBuffer`, which represents the combined vertex data for all FastTESRs. This allows rendering `IBakedModel`s, an example can be found in Forge's `AnimationTESR`. \ No newline at end of file From 0bd1eb44caef634bd2512fbe2160d0c521b6b798 Mon Sep 17 00:00:00 2001 From: diesieben07 Date: Wed, 22 Mar 2017 18:56:40 +0100 Subject: [PATCH 6/7] add note about hasFastRenderer --- docs/tileentities/tesr.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tileentities/tesr.md b/docs/tileentities/tesr.md index 935e155c..4b91c7da 100644 --- a/docs/tileentities/tesr.md +++ b/docs/tileentities/tesr.md @@ -30,6 +30,6 @@ In order to register a TESR, call `ClientRegistry#bindTileEntitySpecialRenderer` `FastTESR` ---------- -A TESR can opt-in to being a FastTESR by extending the `FastTESR` class instead of `TileEntitySpecialRenderer`. Instead of implementing `renderTileEntityAt`, `renderTileEntityFast` must be implemented. +A TESR can opt-in to being a FastTESR by extending the `FastTESR` class instead of `TileEntitySpecialRenderer` and returning true from `TileEntity#hasFastRenderer`. Instead of implementing `renderTileEntityAt`, `renderTileEntityFast` must be implemented. A FastTESR can offer performance improvements over a traditional TESR and should be used wherever possible. This is due to the fact that all FastTESR instances are batched together and only issue _one_ combined draw call for all FastTESRs per frame to the GPU. This advantage comes at the cost of making direct OpenGL access via `GlStateManager` or the `GLXX` classes impossible. Instead a FastTESR must only add vertices to the provided `VertexBuffer`, which represents the combined vertex data for all FastTESRs. This allows rendering `IBakedModel`s, an example can be found in Forge's `AnimationTESR`. \ No newline at end of file From 8ccec5f475ea3acb0205b9cdb1eb84538b23d5cf Mon Sep 17 00:00:00 2001 From: Eli Clemente Gordillo Foster Date: Wed, 22 Mar 2017 11:03:39 -0700 Subject: [PATCH 7/7] Fix last sentence comma splice --- docs/tileentities/tesr.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tileentities/tesr.md b/docs/tileentities/tesr.md index 4b91c7da..5c746c1d 100644 --- a/docs/tileentities/tesr.md +++ b/docs/tileentities/tesr.md @@ -32,4 +32,4 @@ In order to register a TESR, call `ClientRegistry#bindTileEntitySpecialRenderer` A TESR can opt-in to being a FastTESR by extending the `FastTESR` class instead of `TileEntitySpecialRenderer` and returning true from `TileEntity#hasFastRenderer`. Instead of implementing `renderTileEntityAt`, `renderTileEntityFast` must be implemented. -A FastTESR can offer performance improvements over a traditional TESR and should be used wherever possible. This is due to the fact that all FastTESR instances are batched together and only issue _one_ combined draw call for all FastTESRs per frame to the GPU. This advantage comes at the cost of making direct OpenGL access via `GlStateManager` or the `GLXX` classes impossible. Instead a FastTESR must only add vertices to the provided `VertexBuffer`, which represents the combined vertex data for all FastTESRs. This allows rendering `IBakedModel`s, an example can be found in Forge's `AnimationTESR`. \ No newline at end of file +A FastTESR can offer performance improvements over a traditional TESR and should be used wherever possible. This is due to the fact that all FastTESR instances are batched together and only issue _one_ combined draw call for all FastTESRs per frame to the GPU. This advantage comes at the cost of making direct OpenGL access via `GlStateManager` or the `GLXX` classes impossible. Instead a FastTESR must only add vertices to the provided `VertexBuffer`, which represents the combined vertex data for all FastTESRs. This allows rendering `IBakedModel`s. An example can be found in Forge's `AnimationTESR`.