Struct Context 

pub struct Context { /* private fields */ }

An imgui context.

A context needs to be created to access most library functions. Due to current Dear ImGui design choices, at most one active Context can exist at any time. This limitation will likely be removed in a future Dear ImGui version.

If you need more than one context, you can use suspended contexts. As long as only one context is active at a time, it’s possible to have multiple independent contexts.

Examples

Creating a new active context:

let ctx = dear_imgui_rs::Context::create();
// ctx is dropped naturally when it goes out of scope, which deactivates and destroys the
// context

Never try to create an active context when another one is active:

let ctx1 = dear_imgui_rs::Context::create();

let ctx2 = dear_imgui_rs::Context::create(); // PANIC

Implementations

impl Context

pub fn clipboard_text(&self) -> Option<String>

Returns the current clipboard text, if available.

This calls Dear ImGui’s clipboard callbacks (configured via Context::set_clipboard_backend). When no backend is installed, this returns None.

Note: returned data is copied into a new String.

pub fn set_clipboard_text(&self, text: impl AsRef<str>)

Sets the clipboard text.

This calls Dear ImGui’s clipboard callbacks (configured via Context::set_clipboard_backend). If no backend is installed, this is a no-op.

Interior NUL bytes are sanitized to ? to match other scratch-string helpers.

pub fn set_clipboard_backend<T>(&mut self, backend: T)

where T: ClipboardBackend,

Sets the clipboard backend used for clipboard operations

impl Context

pub fn try_create() -> Result<Context, ImGuiError>

Tries to create a new active Dear ImGui context.

Returns an error if another context is already active or creation fails.

pub fn try_create_with_shared_font_atlas( shared_font_atlas: SharedFontAtlas, ) -> Result<Context, ImGuiError>

Tries to create a new active Dear ImGui context with a shared font atlas.

Multiple contexts may share the atlas while using legacy renderer-managed texture handling. Once a managed renderer claims the atlas, registering another context returns ImGuiError::SharedFontAtlasManaged. If its prior managed Context was dropped without a committed renderer reset, this returns ImGuiError::SharedFontAtlasRendererReleasePending.

pub fn create() -> Context

Creates a new active Dear ImGui context (panics on error).

This aligns with imgui-rs behavior. For fallible creation use try_create().

pub fn create_with_shared_font_atlas( shared_font_atlas: SharedFontAtlas, ) -> Context

Creates a new active Dear ImGui context with a shared font atlas (panics on error).

This panics if a managed renderer has already claimed the atlas. Use Context::try_create_with_shared_font_atlas to handle ownership and pending-release errors.

pub fn as_raw(&self) -> *mut ImGuiContext

Returns the raw ImGuiContext* for FFI integrations.

pub fn id(&self) -> ContextId

Returns the process-unique identity of this Context.

pub fn binding(&self) -> ContextBinding

Returns a persistent capability for calling against this Context while it is alive.

pub fn alive_token(&self) -> ContextAliveToken

Returns a token that can be used to check whether this context is still alive.

Useful for extension crates that store raw pointers and need to avoid calling into FFI after the owning Context has been dropped.

pub fn register_attachment<Marker>( &mut self, role: ContextAttachmentRole, attachment: Rc<dyn ContextAttachment>, ) -> Result<ContextAttachmentLease, ContextAttachmentError>

where Marker: 'static,

Registers a typed lifecycle attachment owned by this Context.

The marker type identifies the attachment independently of its erased implementation. Platform and renderer roles are exclusive, and a renderer requires an active platform.

pub fn preflight_attachment_registration<Marker>( &self, role: ContextAttachmentRole, ) -> Result<(), ContextAttachmentError>

where Marker: 'static,

Validate a typed lifecycle attachment registration without mutating the registry.

Backends use this to preflight a multi-Context transaction before registering any attachment. A successful result remains valid until the attachment registry or Context lifecycle changes.

pub fn prepare_platform_attachment_release( &mut self, handle: &ContextAttachmentHandle, ) -> Result<ContextPlatformAttachmentRelease<'_>, ContextPlatformAttachmentReleaseError>

Prepares an explicit release of this Context’s exact platform attachment generation.

Preparation fails while a renderer attachment is active. No frame, callback, or native state is changed on failure. The returned permit exclusively borrows this Context; perform any fallible platform cleanup through ContextPlatformAttachmentRelease::context_mut and call ContextPlatformAttachmentRelease::commit only after native cleanup succeeds.

pub fn io_mut(&mut self) -> &mut Io

Returns a mutable reference to this context’s IO object.

pub fn io(&self) -> &Io

Get shared access to this context’s IO object.

pub fn style(&self) -> &Style

Get access to the Style structure

pub fn style_mut(&mut self) -> &mut Style

Get mutable access to the Style structure

impl Context

pub fn font_atlas(&self) -> &FontAtlas

Borrow the font atlas from the IO structure.

Font-atlas mutation is exposed through this shared view because Dear ImGui permits one native atlas to be registered with multiple contexts. Mutating methods validate the native atlas lock before entering FFI.

pub fn clone_shared_font_atlas(&self) -> Option<SharedFontAtlas>

Attempts to clone the interior shared font atlas if it exists.

impl Context

pub fn prepare_frame(&mut self, options: FramePrepareOptions)

Prepare IO values commonly needed before starting a frame.

This does not call NewFrame(). Engine backends can call it from their input/window update stage and then open the actual Dear ImGui frame later in the schedule with Context::begin_frame.

pub fn frame_lifecycle_state(&self) -> FrameLifecycleState

Return the current frame lifecycle state for this context.

pub fn end_frame(&mut self) -> bool

End an open frame without producing render data.

Returns true when an open native frame was closed and false when the Context was already idle or rendered. The operation is idempotent so engine teardown can revoke UI access before detaching platform and renderer state.

pub fn begin_frame(&mut self) -> FrameToken<'_>

Begin a Dear ImGui frame and return an explicit frame token.

Engine integrations should prefer this when the frame is owned by a schedule rather than a single function. Draw UI through FrameToken::ui and then consume the token with FrameToken::render or FrameToken::render_snapshot.

pub fn frame(&mut self) -> &mut Ui

Creates a new frame and returns a Ui object for building the interface.

Note: you must update io.DisplaySize (and usually io.DeltaTime) before calling this, unless you are using a platform backend that does it for you (e.g. dear-imgui-winit).

pub fn frame_with_result<F, R>(&mut self, f: F) -> FrameResult<'_, R>

where F: FnOnce(&Ui) -> R,

Begin a frame, run a UI-building closure, render the frame, and return both values.

This is a convenience for callers that want the old callback style but also want the draw data produced by closing the frame. Use Context::begin_frame when the UI is built across several engine systems.

pub fn render(&mut self) -> RenderedFrame<'_>

Render the frame and return a Context-borrowed synchronous lease.

This finalizes the Dear ImGui frame and prepares all draw data for rendering. The returned draw data contains all the information needed to render the frame.

pub fn render_snapshot( &mut self, consumer: &RendererConsumer, ) -> Result<FrameSnapshot, SnapshotError>

Render the current frame and build a thread-safe main-viewport snapshot.

This Context-level entry point supports engine schedules that open and close the native frame in separate systems and therefore cannot retain a FrameToken. The snapshot is still bound to the supplied renderer consumer, Context, generation, and ordered epoch.

impl Context

pub fn platform_io(&self) -> &PlatformIo

Get shared access to the platform IO.

Note: ImGuiPlatformIO exists even when multi-viewport is disabled. We expose it unconditionally so callers can use ImGui 1.92+ texture management via PlatformIO.Textures[].

pub fn platform_io_mut(&mut self) -> &mut PlatformIo

Get mutable access to the platform IO.

Note: ImGuiPlatformIO exists even when multi-viewport is disabled. We expose it unconditionally so callers can use ImGui 1.92+ texture management via PlatformIO.Textures[].

pub fn main_viewport(&mut self) -> &mut Viewport

Returns a reference to the main Dear ImGui viewport.

The returned reference is owned by this ImGui context and must not be used after the context is destroyed.

impl Context

pub fn ini_settings_retention( &self, ) -> Result<IniSettingsRetention, IniSettingsRetentionError>

Returns the Context-owned .ini retention configuration.

Native state modified through unsafe FFI is validated before it is returned.

pub fn set_ini_settings_retention( &mut self, retention: IniSettingsRetention, ) -> Result<(), IniSettingsRetentionError>

Atomically configures the session date and .ini retention behavior.

This must be called before loading settings and before the first Dear ImGui frame. Automatic cleanup runs while settings are loaded, and Dear ImGui copies the platform session date at frame start. Mutating the policy after either boundary would silently produce mixed state.

Enabling IniSettingsRetention::AutoDiscard removes supported settings that have no LastUsed field on the next load, including settings written before date recording was enabled.

let mut context = Context::create();
context.io_mut().set_ini_settings_auto_discard_months(None);
let _ = IniSettingsRetention::disabled();

let mut context = Context::create();
context.platform_io_mut().set_session_date(None);

pub fn set_ini_filename<P>( &mut self, filename: Option<P>, ) -> Result<(), ImGuiError>

where P: Into<PathBuf>,

Sets the INI filename for settings persistence

Errors

Returns an error if the filename contains null bytes

pub fn set_log_filename<P>( &mut self, filename: Option<P>, ) -> Result<(), ImGuiError>

where P: Into<PathBuf>,

Sets the log filename

Errors

Returns an error if the filename contains null bytes

pub fn set_platform_name<S>( &mut self, name: Option<S>, ) -> Result<(), ImGuiError>

where S: Into<String>,

Sets the platform name

Errors

Returns an error if the name contains null bytes

pub fn set_renderer_name<S>( &mut self, name: Option<S>, ) -> Result<(), ImGuiError>

where S: Into<String>,

Sets the renderer name

Errors

Returns an error if the name contains null bytes

pub fn load_ini_settings(&mut self, data: &str)

Loads settings from a string slice containing settings in .Ini file format

pub fn save_ini_settings(&mut self, buf: &mut String)

Saves settings to a mutable string buffer in .Ini file format

pub fn load_ini_settings_from_disk<P>( &mut self, filename: P, ) -> Result<(), ImGuiError>

where P: Into<PathBuf>,

Loads settings from a .ini file on disk.

This is a convenience wrapper over ImGui::LoadIniSettingsFromDisk.

Note: this is not available on wasm32 targets.

pub fn save_ini_settings_to_disk<P>( &mut self, filename: P, ) -> Result<(), ImGuiError>

where P: Into<PathBuf>,

Saves settings to a .ini file on disk.

This is a convenience wrapper over ImGui::SaveIniSettingsToDisk.

Note: this is not available on wasm32 targets.

impl Context

pub fn preflight_renderer_consumer(&self) -> Result<(), RendererConsumerError>

Validate whether this Context can attach a managed renderer consumer.

This check is non-mutating: it neither reserves a consumer generation nor claims the font atlas for managed rendering. It is intended for integrations that must validate several Contexts before attaching any renderer. A successful preflight is only a snapshot of the current state; Self::create_renderer_consumer repeats the validation when it commits.

Pending detached completions are not polled by this method. Call Self::poll_snapshot_completions first when retrying after a consumer entered its draining phase.

pub fn create_renderer_consumer( &mut self, ) -> Result<RendererConsumer, RendererConsumerError>

Register the sole renderer consumer for this Context.

A consumer generation is claimed by its first synchronous render or detached snapshot and cannot switch modes. Dropping it begins draining any outstanding detached epochs.

A SharedFontAtlas must be registered with exactly one context before it can enter managed renderer mode. If multiple contexts still share the atlas, this returns RendererConsumerError::SharedFontAtlasRequiresExclusiveContext. Multiple-context shared atlases remain available to legacy renderer-managed texture handling.

pub fn poll_snapshot_completions( &mut self, ) -> Result<SnapshotCompletionProgress, RendererConsumerError>

Merge all currently available detached completion messages.

pub fn prepare_renderer_texture_reset<'context, 'consumer>( &'context mut self, consumer: &'consumer RendererConsumer, ) -> Result<RendererTextureReset<'context, 'consumer>, RendererConsumerError>

Validate an idle renderer generation before destroying its complete GPU texture map.

This two-phase transaction is the only safe renderer-reset path. Prepare the reset while the renderer is still intact, release every GPU resource keyed by this consumer, then call RendererTextureReset::commit. If preparation fails, the backend can return without partially destroying its resource map. Dropping the permit without commit does not mutate native texture state.

A single-call reset is intentionally unavailable because the Context cannot prove that an external renderer released its GPU map first:

use dear_imgui_rs::Context;

let mut context = Context::create();
let consumer = context.create_renderer_consumer().unwrap();
let _ = context.reset_renderer_texture_bindings(&consumer);

impl Context

pub fn suspend(self) -> SuspendedContext

Suspends this context so another context can be the active context

impl Context

pub fn register_texture( &mut self, texture: OwnedTextureData, ) -> ManagedTextureId

Transfer an owned user texture into this Context’s managed registry.

pub fn with_texture<R>( &self, id: ManagedTextureId, f: impl for<'texture> FnOnce(ManagedTextureRef<'texture>) -> R, ) -> Result<R, ManagedTextureError>

Read an active managed texture inside a non-escaping closure.

The facade deliberately has no raw-pointer accessor.

use dear_imgui_rs::{Context, ManagedTextureId, sys};

fn leak_native(context: &Context, id: ManagedTextureId) -> *const sys::ImTextureData {
    context.with_texture(id, |texture| texture.as_raw()).unwrap()
}

pub fn with_texture_mut<R>( &mut self, id: ManagedTextureId, f: impl for<'texture> FnOnce(ManagedTextureMut<'texture>) -> R, ) -> Result<R, ManagedTextureError>

Mutate an active managed texture inside a non-escaping closure.

Renderer-owned state can only be changed by request-bound feedback.

use dear_imgui_rs::{Context, ManagedTextureId, TextureStatus};

fn bypass_renderer(context: &mut Context, id: ManagedTextureId) {
    context
        .with_texture_mut(id, |mut texture| texture.set_status(TextureStatus::OK))
        .unwrap();
}

pub fn remove_texture( &mut self, id: ManagedTextureId, ) -> Result<(), ManagedTextureError>

Stop accepting new draw references and retire a managed texture.

Trait Implementations

impl Debug for Context

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Drop for Context

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.