0
# Integration Backends
1

2
Renderer integrations for various graphics libraries and frameworks including GLFW, SDL2, Pygame, Pyglet, and Cocos2D. These backends handle the platform-specific details of rendering ImGui draw commands and processing user input.
3

4
## Capabilities
5

6
### Base Classes
7

8
Foundation classes that provide common functionality for OpenGL-based renderers.
9

10
```python { .api }
11
class BaseOpenGLRenderer:
12
    """Base class for OpenGL-based ImGui renderers."""
13
    
14
    def __init__(self) -> None:
15
        """Initialize the renderer with current ImGui context."""
16
    
17
    def render(self, draw_data) -> None:
18
        """Render ImGui draw data. Must be implemented by subclasses."""
19
    
20
    def refresh_font_texture(self) -> None:
21
        """Refresh font texture. Must be implemented by subclasses."""
22
    
23
    def shutdown(self) -> None:
24
        """Clean up renderer resources."""
25
```
26

27
### OpenGL Renderers
28

29
Direct OpenGL integration for applications that manage their own OpenGL context.
30

31
```python { .api }
32
class ProgrammablePipelineRenderer(BaseOpenGLRenderer):
33
    """Modern OpenGL renderer using programmable pipeline (OpenGL 3.0+)."""
34
    
35
    def __init__(self) -> None:
36
        """Initialize programmable pipeline renderer."""
37
    
38
    def render(self, draw_data) -> None:
39
        """Render using modern OpenGL shaders."""
40
    
41
    def refresh_font_texture(self) -> None:
42
        """Update font texture using modern OpenGL."""
43

44
class FixedPipelineRenderer(BaseOpenGLRenderer):
45
    """Legacy OpenGL renderer using fixed function pipeline (OpenGL 1.1)."""
46
    
47
    def __init__(self) -> None:
48
        """Initialize fixed pipeline renderer."""
49
    
50
    def render(self, draw_data) -> None:
51
        """Render using legacy OpenGL fixed pipeline."""
52
    
53
    def refresh_font_texture(self) -> None:
54
        """Update font texture using legacy OpenGL."""
55
```
56

57
### GLFW Integration
58

59
Integration with GLFW for cross-platform window management and OpenGL context creation.
60

61
```python { .api }
62
class GlfwRenderer(ProgrammablePipelineRenderer):
63
    """GLFW integration with ImGui using modern OpenGL."""
64
    
65
    def __init__(self, window) -> None:
66
        """Initialize with GLFW window object."""
67
    
68
    def process_inputs(self) -> None:
69
        """Process GLFW input events for ImGui."""
70
    
71
    def render(self, draw_data) -> None:
72
        """Render ImGui draw commands using OpenGL."""
73
    
74
    def keyboard_callback(self, window, key: int, scancode: int, action: int, mods: int) -> None:
75
        """Handle keyboard input callbacks."""
76
    
77
    def char_callback(self, window, char: int) -> None:
78
        """Handle character input callbacks."""
79
    
80
    def mouse_callback(self, window, x: float, y: float) -> None:
81
        """Handle mouse movement callbacks."""
82
    
83
    def scroll_callback(self, window, x_offset: float, y_offset: float) -> None:
84
        """Handle mouse scroll callbacks."""
85
    
86
    def resize_callback(self, window, width: int, height: int) -> None:
87
        """Handle window resize callbacks."""
88
    
89
    def shutdown(self) -> None:
90
        """Clean up GLFW-specific resources."""
91
```
92

93
### SDL2 Integration
94

95
Integration with SDL2 for cross-platform multimedia and input handling.
96

97
```python { .api }
98
class SDL2Renderer(ProgrammablePipelineRenderer):
99
    """SDL2 integration with ImGui using modern OpenGL."""
100
    
101
    def __init__(self, window) -> None:
102
        """Initialize with SDL2 window."""
103
    
104
    def process_inputs(self) -> None:
105
        """Process SDL2 input events for ImGui."""
106
    
107
    def render(self, draw_data) -> None:
108
        """Render ImGui draw commands using OpenGL."""
109
    
110
    def shutdown(self) -> None:
111
        """Clean up SDL2-specific resources."""
112
```
113

114
### Pygame Integration
115

116
Integration with Pygame for game development and multimedia applications.
117

118
```python { .api }
119
class PygameRenderer(FixedPipelineRenderer):
120
    """Pygame integration with ImGui using legacy OpenGL."""
121
    
122
    def __init__(self) -> None:
123
        """Initialize Pygame renderer."""
124
    
125
    def process_inputs(self) -> None:
126
        """Process Pygame input events for ImGui."""
127
    
128
    def render(self, draw_data) -> None:
129
        """Render ImGui draw commands using legacy OpenGL."""
130
```
131

132
### Pyglet Integration
133

134
Integration with Pyglet for multimedia applications and game development.
135

136
```python { .api }
137
class PygletRenderer(ProgrammablePipelineRenderer):
138
    """Pyglet integration with ImGui using modern OpenGL."""
139
    
140
    def __init__(self, window) -> None:
141
        """Initialize with Pyglet window."""
142
    
143
    def process_inputs(self) -> None:
144
        """Process Pyglet input events for ImGui."""
145

146
class PygletMixin:
147
    """Mixin class for Pyglet integration functionality."""
148

149
class PygletFixedPipelineRenderer(FixedPipelineRenderer, PygletMixin):
150
    """Pyglet renderer using fixed function pipeline."""
151

152
class PygletProgrammablePipelineRenderer(ProgrammablePipelineRenderer, PygletMixin):
153
    """Pyglet renderer using programmable pipeline."""
154
```
155

156
### Cocos2D Integration
157

158
Integration with Cocos2D Python game development framework.
159

160
```python { .api }
161
class ImguiLayer:
162
    """Cocos2D layer for ImGui integration."""
163
    
164
    def __init__(self) -> None:
165
        """Initialize ImGui layer for Cocos2D."""
166
    
167
    def on_enter(self) -> None:
168
        """Called when layer becomes active."""
169
    
170
    def on_exit(self) -> None:
171
        """Called when layer becomes inactive."""
172
    
173
    def draw(self) -> None:
174
        """Draw ImGui interface in Cocos2D."""
175
```
176

177
### Glumpy Integration
178

179
Integration with Glumpy for scientific visualization applications.
180

181
```python { .api }
182
class GlumpyRenderer(ProgrammablePipelineRenderer):
183
    """Glumpy integration with ImGui."""
184
    
185
    def __init__(self) -> None:
186
        """Initialize Glumpy renderer."""
187
```
188

189
### Utility Functions
190

191
Helper functions for integration backends.
192

193
```python { .api }
194
def compute_fb_scale(window_size: tuple[int, int], frame_buffer_size: tuple[int, int]) -> tuple[float, float]:
195
    """Compute framebuffer scale for high-DPI displays."""
196
```
197

198
## Usage Examples
199

200
### GLFW Integration
201

202
```python
203
import glfw
204
import OpenGL.GL as gl
205
import imgui
206
from imgui.integrations.glfw import GlfwRenderer
207

208
def main():
209
    # Initialize GLFW
210
    if not glfw.init():
211
        return
212
    
213
    # Create window
214
    window = glfw.create_window(800, 600, "ImGui GLFW Example", None, None)
215
    if not window:
216
        glfw.terminate()
217
        return
218
    
219
    glfw.make_context_current(window)
220
    glfw.swap_interval(1)  # Enable vsync
221
    
222
    # Initialize ImGui
223
    imgui.create_context()
224
    impl = GlfwRenderer(window)
225
    
226
    # Main loop
227
    while not glfw.window_should_close(window):
228
        glfw.poll_events()
229
        impl.process_inputs()
230
        
231
        # Start new frame
232
        imgui.new_frame()
233
        
234
        # Create UI
235
        if imgui.begin("Hello, GLFW!"):
236
            imgui.text("This is rendered with GLFW backend")
237
            if imgui.button("Click me!"):
238
                print("Button clicked!")
239
        imgui.end()
240
        
241
        # Render
242
        gl.glClear(gl.GL_COLOR_BUFFER_BIT)
243
        imgui.render()
244
        impl.render(imgui.get_draw_data())
245
        glfw.swap_buffers(window)
246
    
247
    # Cleanup
248
    impl.shutdown()
249
    glfw.terminate()
250

251
if __name__ == "__main__":
252
    main()
253
```
254

255
### SDL2 Integration
256

257
```python
258
import sys
259
import sdl2
260
import OpenGL.GL as gl
261
import imgui
262
from imgui.integrations.sdl2 import SDL2Renderer
263

264
def main():
265
    # Initialize SDL2
266
    if sdl2.SDL_Init(sdl2.SDL_INIT_VIDEO) < 0:
267
        return
268
    
269
    # Create window
270
    window = sdl2.SDL_CreateWindow(
271
        b"ImGui SDL2 Example",
272
        sdl2.SDL_WINDOWPOS_CENTERED,
273
        sdl2.SDL_WINDOWPOS_CENTERED,
274
        800, 600,
275
        sdl2.SDL_WINDOW_OPENGL | sdl2.SDL_WINDOW_RESIZABLE
276
    )
277
    
278
    # Create OpenGL context
279
    gl_context = sdl2.SDL_GL_CreateContext(window)
280
    sdl2.SDL_GL_SetSwapInterval(1)  # Enable vsync
281
    
282
    # Initialize ImGui
283
    imgui.create_context()
284
    impl = SDL2Renderer(window)
285
    
286
    # Main loop
287
    running = True
288
    while running:
289
        event = sdl2.SDL_Event()
290
        while sdl2.SDL_PollEvent(event):
291
            if event.type == sdl2.SDL_QUIT:
292
                running = False
293
        
294
        impl.process_inputs()
295
        
296
        # Start new frame
297
        imgui.new_frame()
298
        
299
        # Create UI
300
        if imgui.begin("Hello, SDL2!"):
301
            imgui.text("This is rendered with SDL2 backend")
302
            if imgui.button("Quit"):
303
                running = False
304
        imgui.end()
305
        
306
        # Render
307
        gl.glClear(gl.GL_COLOR_BUFFER_BIT)
308
        imgui.render()
309
        impl.render(imgui.get_draw_data())
310
        sdl2.SDL_GL_SwapWindow(window)
311
    
312
    # Cleanup
313
    impl.shutdown()
314
    sdl2.SDL_GL_DeleteContext(gl_context)
315
    sdl2.SDL_DestroyWindow(window)
316
    sdl2.SDL_Quit()
317

318
if __name__ == "__main__":
319
    main()
320
```
321

322
### Pygame Integration
323

324
```python
325
import pygame
326
import OpenGL.GL as gl
327
import imgui
328
from imgui.integrations.pygame import PygameRenderer
329

330
def main():
331
    # Initialize Pygame
332
    pygame.init()
333
    size = (800, 600)
334
    pygame.display.set_mode(size, pygame.DOUBLEBUF | pygame.OPENGL)
335
    pygame.display.set_caption("ImGui Pygame Example")
336
    
337
    # Initialize ImGui
338
    imgui.create_context()
339
    impl = PygameRenderer()
340
    
341
    clock = pygame.time.Clock()
342
    running = True
343
    
344
    while running:
345
        # Handle events
346
        for event in pygame.event.get():
347
            if event.type == pygame.QUIT:
348
                running = False
349
        
350
        impl.process_inputs()
351
        
352
        # Start new frame
353
        imgui.new_frame()
354
        
355
        # Create UI
356
        if imgui.begin("Hello, Pygame!"):
357
            imgui.text("This is rendered with Pygame backend")
358
            fps = clock.get_fps()
359
            imgui.text(f"FPS: {fps:.1f}")
360
        imgui.end()
361
        
362
        # Render
363
        gl.glClear(gl.GL_COLOR_BUFFER_BIT)
364
        imgui.render()
365
        impl.render(imgui.get_draw_data())
366
        pygame.display.flip()
367
        clock.tick(60)
368
    
369
    # Cleanup
370
    pygame.quit()
371

372
if __name__ == "__main__":
373
    main()
374
```
375

376
### Pyglet Integration
377

378
```python
379
import pyglet
380
import imgui
381
from imgui.integrations.pyglet import PygletRenderer
382

383
class ImGuiWindow(pyglet.window.Window):
384
    def __init__(self):
385
        super().__init__(800, 600, "ImGui Pyglet Example", resizable=True)
386
        
387
        # Initialize ImGui
388
        imgui.create_context()
389
        self.impl = PygletRenderer(self)
390
        
391
        # Schedule frame updates
392
        pyglet.clock.schedule_interval(self.update, 1/60.0)
393
    
394
    def on_draw(self):
395
        self.clear()
396
        
397
        # Start new frame
398
        imgui.new_frame()
399
        
400
        # Create UI
401
        if imgui.begin("Hello, Pyglet!"):
402
            imgui.text("This is rendered with Pyglet backend")
403
            if imgui.button("Toggle Fullscreen"):
404
                self.set_fullscreen(not self.fullscreen)
405
        imgui.end()
406
        
407
        # Render
408
        imgui.render()
409
        self.impl.render(imgui.get_draw_data())
410
    
411
    def update(self, dt):
412
        pass
413
    
414
    def on_close(self):
415
        self.impl.shutdown()
416
        super().on_close()
417

418
def main():
419
    window = ImGuiWindow()
420
    pyglet.app.run()
421

422
if __name__ == "__main__":
423
    main()
424
```
425

426
### Basic Backend Selection
427

428
```python
429
import imgui
430

431
# Choose backend based on availability
432
try:
433
    import glfw
434
    from imgui.integrations.glfw import GlfwRenderer
435
    print("Using GLFW backend")
436
except ImportError:
437
    try:
438
        import pygame
439
        from imgui.integrations.pygame import PygameRenderer
440
        print("Using Pygame backend")
441
    except ImportError:
442
        print("No supported backend found")
443
        sys.exit(1)
444

445
# Initialize ImGui context (required for all backends)
446
imgui.create_context()
447
```