MicroTeX: LaTeX formulas rendered as images, natively (MicroTeX and FreeType). The markdown’s math uses it.
The C++ API of MicroTeX as it is bound to Python: the entries of the module imgui_bundle.imgui_microtex, in the same order, with their C++ signatures and the headers’ comments. From the stubs: the functions excluded from the bindings, the typedefs and the macros are absent.
imgui_microtex_amalgamation.h¶
TeX style¶
TexStyle (enum)¶
Selects the layout style used when rendering a formula. This maps directly
to MicroTeX’s TexStyle and corresponds to the four TeX styles defined by
Knuth (D, T, S, SS). Pick Display for centered “display math” (
) and Text for inline math (...).
The style affects symbol size, big-operator appearance, and the spacing around rac (numerator shift-up and denominator shift-down): Display gives generous spacing; Text is compact.
| Member | Value | |
|---|---|---|
Display, Largest size. Big operators (\sum, \int, ...) use their large variants with limits placed above and below. \frac uses generous vertical spacing. This is what LaTeX uses inside $$...$$ and \[...\]. | 0 | |
Text, Default inline size. Big operators use their small variants with limits attached as sub/superscripts. \frac uses compact spacing. This is what LaTeX uses inside $...$ and \(...\). | 1 | |
Script, Smaller size used by LaTeX inside sub/superscripts. Rarely useful at the top level; MicroTeX switches to it automatically where needed. | 2 | |
ScriptScript, } Smallest size, used inside scripts-of-scripts. Same caveat as Script. | 3 |
Initialization and shutdown¶
ImGuiMicroTeX::Init¶
void Init(const std::string& clmFile, const std::string& fontFile);Initialize MicroTeX + FreeType backend.
clmFile: path to the .clm1 font metrics file
fontFile: path to the .otf font file
Safe to call repeatedly: subsequent calls after the first successful
Init() no-op (MicroTeX itself stays initialized for process life; the
underlying MicroTeX::init()/release() pair is not re-entrant, so we
defer the real teardown to std::atexit: see rich_md_latex.cpp).
Init() loads the font files, once. Release() lets the host free the textures it made from formulas,
while its rendering backend is still alive.
ImGuiMicroTeX::IsInitialized¶
bool IsInitialized();Check if initialized.
ImGuiMicroTeX::Release¶
void Release();Drop the cached GPU texture set so the GL context can be torn down cleanly. Call from BeforeExit (or any point where the GL context is about to die). Safe to call multiple times, and safe to call Init() again afterwards: the underlying MicroTeX library stays alive for the whole process and its real teardown runs once at exit via a std::atexit handler installed on first Init().
ImGuiMicroTeX::AddReleaseCallback¶
void AddReleaseCallback(std::function<void()> callback);Registers a callback run by Release(): a host that caches GPU textures made from formulas clears them here, while the rendering backend is still alive.
Rendering¶
RenderedFormula (struct)¶
| Member | |
|---|---|
int Width = 0; | |
int Height = 0; | |
int Depth = 0; | distance below baseline (in pixels, unpadded) |
int BaselineY = 0; |
ImGuiMicroTeX::Render¶
RenderedFormula Render(const std::string& latex, float fontSize, ImU32 color = IM_COL32_BLACK, TexStyle style = TexStyle::Text);RenderedFormula Render(const std::string& latex, float fontSize, const ImVec4& color, TexStyle style = TexStyle::Text);Render a LaTeX string to an RGBA pixel buffer. latex: the LaTeX math string (without ......$)
Level 2: LaTeX -> HelloImGui::TextureGpuPtr¶
FormulaTexture (struct)¶
FormulaTexture owns its GPU texture via a HelloImGui::TextureGpuPtr.
The texture is freed when the last shared reference drops; this happens
at the latest when the imgui_microtex texture cache is cleared (via
ClearTextureCache() or Release()), but a caller may also keep its own
reference to extend the lifetime.
| Member | |
|---|---|
std::shared_ptr<HelloImGui::TextureGpu> Texture; | |
int Width = 0; | |
int Height = 0; | |
int Depth = 0; | |
int BaselineY = 0; | |
int LastUsedFrame = 0; |
FormulaTexture::TextureId¶
ImTextureID TextureId() const;Convenience: returns the GPU texture id, or 0 if no texture is held.
ImGuiMicroTeX::RenderToTexture¶
FormulaTexture RenderToTexture(const std::string& latex, float fontSize, ImU32 color = IM_COL32_BLACK, TexStyle style = TexStyle::Text);FormulaTexture RenderToTexture(const std::string& latex, float fontSize, const ImVec4& color, TexStyle style = TexStyle::Text);Render a LaTeX string to an ImGui texture (cached for the lifetime of imgui_microtex). style: TeX layout style (Display for
, Text for ...).
ImGuiMicroTeX::ToTexture¶
FormulaTexture ToTexture(const RenderedFormula& formula);Convert a previously rendered formula to an ImGui texture (not cached).
ImGuiMicroTeX::ClearTextureCache¶
void ClearTextureCache();Clear the texture cache.
ImGuiMicroTeX::SetEvictionFrames¶
void SetEvictionFrames(int n);Frame-generation eviction for the texture cache
imgui_microtex maintains a texture cache keyed by (latex, fontSize, color)
so that re-rendering the same formula every frame is essentially free.
To prevent unbounded growth in long-running interactive use cases — LaTeX
REPLs, multi-document browsers, notebooks where users page through many
formulas they will never see again — the cache evicts entries that have
not been touched in the last N frames. Static documentation viewers see
no functional change: every formula they render is touched every frame,
so it never falls below the eviction threshold.
SetEvictionFrames(N) configures the threshold:
N > 0: cache entries not touched for N frames are dropped on the next cache insertion (lazy: no insert -> no sweep).
N == 0: eviction disabled, cache grows for the lifetime of the process. Use this for short-lived apps where you do not want any eviction overhead.
The eviction is “lazy on insert” only. If no new formula is ever rendered, no sweep runs — call ClearTextureCache() manually for the rare case where rendering stops entirely and you want to reclaim memory immediately.
Default: N = 60 (~1 second at 60 FPS).
ImGuiMicroTeX::GetCacheSize¶
int GetCacheSize();Returns the current cache size (number of formula entries). Useful for diagnostics, monitoring, and tests.