8.18.1.54. Texture references

Dear ImGui 1.92 reworked texture handling: the raw ImTextureID you used to hand to image() is now an ImTextureRef. This tutorial shows the full path for displaying your own image — decode a PNG, upload it to a GL texture, and pass that texture through an ImTextureRef:

// 1. decode a PNG to RGBA pixels (dasStbImage)
var img : Image
img->load(path, 4)
// 2. upload to a GL texture
glGenTextures(1, safe_addr(g_tex))
glBindTexture(GL_TEXTURE_2D, g_tex)
glTexImage2D(GL_TEXTURE_2D, 0, int(GL_RGBA), img.width, img.height, 0,
             GL_RGBA, GL_UNSIGNED_BYTE, unsafe(addr(img.bytes[0])))
// 3. wrap the GL texture name in an ImTextureRef
var ref : ImTextureRef
ref._TexID = uint64(g_tex)
// 4. draw it
image(TR_PIC, (user_texture_id = ref, size = float2(w, h), ...))

_TexID is the user slot of ImTextureRef (an ImTextureID == the GL texture name here). With _TexData left null, the backend treats it as a user-managed texture and binds the GL id directly — that is how you pass your own texture in 1.92.

The demo loads one of the repo’s icon PNGs as a stand-in for an application texture; point PICTURE_PATH at any image of your own.

Source: modules/dasImgui/examples/tutorial/texture_ref.das.

8.18.1.54.1. Walkthrough

  1options gen2
  2options _comment_hygiene = true
  3
  4require imgui
  5require imgui_app
  6require opengl/opengl_boost
  7require live/glfw_live
  8require live/live_api
  9require live/live_commands
 10require live/live_vars
 11require live_host
 12require imgui/imgui_live
 13require imgui/imgui_boost_runtime
 14require imgui/imgui_boost_v2
 15require imgui/imgui_widgets_builtin
 16require imgui/imgui_containers_builtin
 17require imgui/imgui_visual_aids
 18require stbimage/stbimage_boost
 19require daslib/safe_addr
 20
 21// =============================================================================
 22// TUTORIAL: texture_ref — display YOUR OWN texture via the imgui 1.92 ImTextureRef.
 23//
 24// 1.92 replaced the raw `ImTextureID` handle with `ImTextureRef`. To show a real
 25// image (not the font atlas), the steps are:
 26//
 27//   1. decode a PNG to RGBA pixels      — dasStbImage `Image::load(path, 4)`
 28//   2. upload to a GL texture           — glGenTextures + glTexImage2D
 29//   3. wrap the GL handle               — var ref : ImTextureRef; ref._TexID = handle
 30//   4. draw it                          — image(IDENT, (user_texture_id = ref, ...))
 31//
 32// `_TexID` is the user slot of ImTextureRef (an ImTextureID == the GL texture name
 33// here). With `_TexData` left null, the backend treats it as a user-managed texture
 34// and binds the GL id directly — that is how you pass your own texture in 1.92.
 35//
 36// STANDALONE: daslang.exe modules/dasImgui/examples/tutorial/texture_ref.das
 37// LIVE:       daslang-live modules/dasImgui/examples/tutorial/texture_ref.das
 38// =============================================================================
 39
 40// One of the repo's icon PNGs stands in for an application texture.
 41let PICTURE_PATH = "{get_das_root()}/modules/dasImgui/doc/source/_static/icons/cube.png"
 42
 43var private g_tex : uint = 0u            // GL texture name
 44var private g_tex_w = 0
 45var private g_tex_h = 0
 46var private g_load_err = ""
 47
 48def private upload_picture() {
 49    var img : Image
 50    let (ok, err) = img->load(PICTURE_PATH, 4)   // request 4 channels => RGBA
 51    if (!ok) {
 52        g_load_err = "load failed: {err}"
 53        return
 54    }
 55    g_tex_w = img.width
 56    g_tex_h = img.height
 57    glGenTextures(1, safe_addr(g_tex))
 58    glBindTexture(GL_TEXTURE_2D, g_tex)
 59    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR)
 60    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR)
 61    glTexImage2D(GL_TEXTURE_2D, 0, int(GL_RGBA), img.width, img.height, 0,
 62                 GL_RGBA, GL_UNSIGNED_BYTE, unsafe(addr(img.bytes[0])))
 63}
 64
 65// Build the 1.92 image() handle from the GL texture name. _TexID is the user
 66// slot (ImTextureID == ImU64 == uint64 here); _TexData stays null, so the
 67// backend binds the GL id directly as a user-managed texture.
 68def private texture_ref() : ImTextureRef {
 69    unsafe {
 70        var ref : ImTextureRef
 71        ref._TexID = uint64(g_tex)
 72        return ref
 73    }
 74}
 75
 76[export]
 77def init() {
 78    live_create_window("dasImgui texture_ref tutorial", 820, 520)
 79    live_imgui_init(live_window)
 80    let io & = unsafe(GetIO())
 81    GetStyle().FontScaleMain = 1.3
 82    // GL context is live now — decode + upload the picture once.
 83    upload_picture()
 84}
 85
 86[export]
 87def update() {
 88    if (!live_begin_frame()) return
 89    begin_frame()
 90
 91    ImGui_ImplGlfw_NewFrame()
 92    apply_synth_io_override()
 93    NewFrame()
 94
 95    SetNextWindowPos(ImVec2(40.0f, 40.0f), ImGuiCond.Always)
 96    SetNextWindowSize(ImVec2(740.0f, 440.0f), ImGuiCond.Always)
 97    window(TR_WIN, (text = "texture_ref", closable = false,
 98                    flags = ImGuiWindowFlags.None)) {
 99        if (g_tex == 0u) {
100            text(TR_ERR, (text = "no texture: {g_load_err}"))
101        } else {
102            text("A real PNG, decoded + uploaded to a GL texture, shown through")
103            text("an ImTextureRef whose _TexID is the GL texture name.")
104            separator()
105
106            // Full image, then a tinted + bordered copy — same texture reused.
107            image(TR_PIC, (user_texture_id = texture_ref(),
108                           size = float2(float(g_tex_w), float(g_tex_h)),
109                           uv0 = float2(0.0f, 0.0f),
110                           uv1 = float2(1.0f, 1.0f),
111                           tint_col = float4(1.0f, 1.0f, 1.0f, 1.0f),
112                           border_col = float4(0.6f, 0.6f, 0.6f, 1.0f)))
113            same_line(TR_GAP)
114            image(TR_TINT, (user_texture_id = texture_ref(),
115                            size = float2(float(g_tex_w), float(g_tex_h)),
116                            uv0 = float2(0.0f, 0.0f),
117                            uv1 = float2(1.0f, 1.0f),
118                            tint_col = float4(0.4f, 0.8f, 1.0f, 1.0f),
119                            border_col = float4(1.0f, 1.0f, 1.0f, 1.0f)))
120            separator()
121            text("{g_tex_w}x{g_tex_h}. Swap PICTURE_PATH / _TexID for your own texture.")
122        }
123    }
124
125    end_of_frame()
126    Render()
127    var w, h : int
128    live_get_framebuffer_size(w, h)
129    glViewport(0, 0, w, h)
130    glClearColor(0.10f, 0.10f, 0.12f, 1.0f)
131    glClear(GL_COLOR_BUFFER_BIT)
132    live_imgui_render()
133
134    live_end_frame()
135}
136
137[export]
138def shutdown() {
139    if (g_tex != 0u) {
140        glDeleteTextures(1, safe_addr(g_tex))
141    }
142    live_imgui_shutdown()
143    live_destroy_window()
144}
145
146[export]
147def main() {
148    init()
149    while (!exit_requested()) {
150        update()
151    }
152    shutdown()
153}

8.18.1.54.1.1. Requires

stbimage/stbimage_boost for the PNG decode (the Image type and Image::load), opengl/opengl_boost for the GL upload (already pulled in by the live backend), and daslib/safe_addr for the texture-name address.

8.18.1.54.1.2. Behaviour

The picture is decoded + uploaded once in init (the GL context is live after live_imgui_init), and the texture name is kept in a module global. Each frame image() draws it twice through a freshly built ImTextureRef — once plain, once tinted + bordered — to show the same texture reused while tint_col / border_col vary per call. The texture is freed with glDeleteTextures on shutdown.

8.18.1.54.1.3. Migration note

Pre-1.92 code passed an ImTextureID straight to image(). In 1.92 the argument is an ImTextureRef; put your texture handle in ref._TexID (the user slot) and leave ref._TexData null. The font atlas moved the same way: io.Fonts.TexID → io.Fonts.TexRef (an ImTextureRef), gated on io.Fonts.TexData != null.

See also

Full source: modules/dasImgui/examples/tutorial/texture_ref.das

Related: tree_node_ex + image — image() against the font atlas, alongside tree_node_ex.