Texture handle docs

docs/en/manuals/render.md

@@ -293,6 +293,41 @@ render.draw(self.my_tile_predicate)
 Defold currently only supports `Materials` and `Render Targets` as referenced render resources, but over time more resource types will be supported by this system.
 :::
 
+## Texture handles
+
+Textures in Defold are represented internally as a handle, which essentially equates to a number that should uniquely identify a texture object anywhere in the engine. This means that you can bridge the gameobject world with the rendering world by passing these handles between the render system and a gameobject script. For example, a script can create a dynamic texture in a script attached to a gameobject and send this to the renderer to be used as a global texture in a draw command.
+
+In a `.script` file:
+
+```lua
+local my_texture_resource = resource.create_texture("/my_texture.texture", tparams)
+-- note: my_texture_resource is a hash to the resource path, which can't be used as a handle!
+local my_texture_handle = resource.get_texture_info(my_texture_resource)
+-- my_texture_handle contains information about the texture, such as width, height and so on
+-- it does also contain the handle, which is what we are after
+msg.post("@render:", "set_texture", { handle = my_texture_handle.handle })
+```
+
+In a .render_script file:
+
+```lua
+function on_message(self, message_id, message)
+    if message_id == hash("set_texture") then
+        self.my_texture = message.handle
+    end
+end
+
+function update(self)
+    -- bind the custom texture to the draw state
+    render.enable_texture(0, self.my_texture)
+    -- do drawing..
+end
+```
+
+::: sidenote
+There is currently no way of changing which texture a resource should point to, you can only use raw handles like this in the render script.
+:::
+
 ## Supported graphics APIs
 The Defold render script API translates render operations into the following graphics APIs: