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: examples/tutorial/texture_ref.das.

Walkthrough

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

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.

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.

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: examples/tutorial/texture_ref.das

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