Skip to main content

​
Rendering and Display

The libghostty rendering API provides functions for managing terminal surface rendering, sizing, and display properties.

​
Surface Management

​
ghostty_surface_new

Creates a new terminal surface. 
ghostty_surface_t ghostty_surface_new(
    ghostty_app_t app,
    const ghostty_surface_config_s* config
);
​
app
ghostty_app_t
required
The app instance that will own this surface.
​
config
const ghostty_surface_config_s*
required
Configuration for the new surface.
Returns: A new surface, or NULL on failure. Example: 
ghostty_surface_config_s config = ghostty_surface_config_new();
config.platform_tag = GHOSTTY_PLATFORM_MACOS;
config.platform.macos.nsview = (__bridge void*)myView;
config.scale_factor = 2.0;
config.font_size = 13.0;

ghostty_surface_t surface = ghostty_surface_new(app, &config);

​
ghostty_surface_free

Frees a surface and its resources. 
void ghostty_surface_free(ghostty_surface_t surface);
​
surface
ghostty_surface_t
required
The surface to free.

​
ghostty_surface_config_new

Creates a default surface configuration. 
ghostty_surface_config_s ghostty_surface_config_new();
Returns: A configuration struct with default values.

​
ghostty_surface_inherited_config

Gets configuration for creating a derived surface (e.g., split). 
ghostty_surface_config_s ghostty_surface_inherited_config(
    ghostty_surface_t surface,
    ghostty_surface_context_e context
);
​
surface
ghostty_surface_t
required
The parent surface.
​
context
ghostty_surface_context_e
required
The context for the new surface (tab, split, etc.).
Returns: Configuration that inherits settings from the parent surface.

​
Rendering

​
ghostty_surface_draw

Draws the surface to its render target. 
void ghostty_surface_draw(ghostty_surface_t surface);
​
surface
ghostty_surface_t
required
The surface to draw.
This function renders the terminal content using the platform’s native rendering backend (Metal on macOS/iOS, OpenGL on Linux). Example: 
// In your render loop
void render_frame() {
    ghostty_app_tick(app);
    ghostty_surface_draw(surface);
}

​
ghostty_surface_refresh

Marks the surface as needing a redraw. 
void ghostty_surface_refresh(ghostty_surface_t surface);
​
surface
ghostty_surface_t
required
The surface to refresh.
Call this when you want to force a redraw (e.g., after the view is uncovered).

​
Size and Scale

​
ghostty_surface_set_size

Sets the surface size in pixels. 
void ghostty_surface_set_size(
    ghostty_surface_t surface,
    uint32_t width,
    uint32_t height
);
​
surface
ghostty_surface_t
required
The surface to resize.
​
width
uint32_t
required
New width in pixels.
​
height
uint32_t
required
New height in pixels.
Example: 
// Handle window resize
void on_window_resize(int width, int height) {
    ghostty_surface_set_size(surface, width, height);
}

​
ghostty_surface_size

Gets the current surface size. 
ghostty_surface_size_s ghostty_surface_size(ghostty_surface_t surface);
​
surface
ghostty_surface_t
required
The surface to query.
Returns: Surface size information including dimensions and cell size. Example: 
ghostty_surface_size_s size = ghostty_surface_size(surface);
printf("Terminal: %dx%d cells (%dx%d px)\n",
       size.columns, size.rows,
       size.width_px, size.height_px);
printf("Cell size: %dx%d px\n",
       size.cell_width_px, size.cell_height_px);

​
ghostty_surface_set_content_scale

Sets the content scale factor (for high-DPI displays). 
void ghostty_surface_set_content_scale(
    ghostty_surface_t surface,
    double scale_x,
    double scale_y
);
​
surface
ghostty_surface_t
required
The surface.
​
scale_x
double
required
Horizontal scale factor (e.g., 2.0 for Retina).
​
scale_y
double
required
Vertical scale factor.
Example: 
// Handle display change
void on_display_change(double scale) {
    ghostty_surface_set_content_scale(surface, scale, scale);
}

​
Focus and Occlusion

​
ghostty_surface_set_focus

Sets the focus state of the surface. 
void ghostty_surface_set_focus(
    ghostty_surface_t surface,
    bool focused
);
​
surface
ghostty_surface_t
required
The surface.
​
focused
bool
required
Whether the surface has focus.
This affects cursor rendering and keyboard input. Example: 
void on_focus_change(bool has_focus) {
    ghostty_surface_set_focus(surface, has_focus);
}

​
ghostty_surface_set_occlusion

Sets whether the surface is occluded (hidden by other windows). 
void ghostty_surface_set_occlusion(
    ghostty_surface_t surface,
    bool occluded
);
​
surface
ghostty_surface_t
required
The surface.
​
occluded
bool
required
Whether the surface is occluded.
This can be used to reduce CPU/GPU usage when the terminal is not visible.

​
ghostty_surface_set_color_scheme

Sets the color scheme preference. 
void ghostty_surface_set_color_scheme(
    ghostty_surface_t surface,
    ghostty_color_scheme_e scheme
);
​
surface
ghostty_surface_t
required
The surface.
​
scheme
ghostty_color_scheme_e
required
Color scheme (light or dark).
Example: 
void on_system_theme_change(bool is_dark) {
    ghostty_surface_set_color_scheme(
        surface,
        is_dark ? GHOSTTY_COLOR_SCHEME_DARK : GHOSTTY_COLOR_SCHEME_LIGHT
    );
}

​
Configuration

​
ghostty_surface_update_config

Updates the surface configuration. 
void ghostty_surface_update_config(
    ghostty_surface_t surface,
    ghostty_config_t config
);
​
surface
ghostty_surface_t
required
The surface to update.
​
config
ghostty_config_t
required
New configuration to apply.
This allows hot-reloading configuration without recreating the surface.

​
Surface Queries

​
ghostty_surface_userdata

Gets the user data pointer associated with the surface. 
void* ghostty_surface_userdata(ghostty_surface_t surface);
​
surface
ghostty_surface_t
required
The surface.
Returns: The userdata pointer from ghostty_surface_config_s.

​
ghostty_surface_app

Gets the app that owns the surface. 
ghostty_app_t ghostty_surface_app(ghostty_surface_t surface);
​
surface
ghostty_surface_t
required
The surface.
Returns: The parent app instance.

​
ghostty_surface_needs_confirm_quit

Checks if the surface needs confirmation before closing. 
bool ghostty_surface_needs_confirm_quit(ghostty_surface_t surface);
Returns: true if there’s a running process that would be terminated.

​
ghostty_surface_process_exited

Checks if the surface’s shell process has exited. 
bool ghostty_surface_process_exited(ghostty_surface_t surface);
Returns: true if the process has exited.

​
Platform-Specific (macOS)

​
ghostty_surface_set_display_id

Sets the display ID for the surface (for proper font rendering).
void ghostty_surface_set_display_id(
    ghostty_surface_t surface,
    uint32_t display_id
);

​
ghostty_surface_quicklook_font

Gets the CTFont for QuickLook integration.
void* ghostty_surface_quicklook_font(ghostty_surface_t surface);
Returns: A CTFontRef (cast to void*).

​
ghostty_surface_quicklook_word

Gets the word under the cursor for QuickLook.
bool ghostty_surface_quicklook_word(
    ghostty_surface_t surface,
    ghostty_text_s* text
);

​
Text Selection

​
ghostty_surface_has_selection

Checks if the surface has an active selection. 
bool ghostty_surface_has_selection(ghostty_surface_t surface);
Returns: true if text is selected.

​
ghostty_surface_read_selection

Reads the currently selected text. 
bool ghostty_surface_read_selection(
    ghostty_surface_t surface,
    ghostty_text_s* text
);
​
surface
ghostty_surface_t
required
The surface.
​
text
ghostty_text_s*
required
Pointer to store the selected text.
Returns: true if text was read successfully. Must free with ghostty_surface_free_text().

​
ghostty_surface_read_text

Reads text from a specific region. 
bool ghostty_surface_read_text(
    ghostty_surface_t surface,
    ghostty_selection_s selection,
    ghostty_text_s* text
);
​
surface
ghostty_surface_t
required
The surface.
​
selection
ghostty_selection_s
required
The region to read.
​
text
ghostty_text_s*
required
Pointer to store the text.
Returns: true if text was read successfully.

​
ghostty_surface_free_text

Frees text returned by read functions. 
void ghostty_surface_free_text(
    ghostty_surface_t surface,
    ghostty_text_s* text
);

​
Surface Actions

​
ghostty_surface_binding_action

Executes a binding action by name. 
bool ghostty_surface_binding_action(
    ghostty_surface_t surface,
    const char* action,
    uintptr_t len
);
​
surface
ghostty_surface_t
required
The surface.
​
action
const char*
required
Action name.
​
len
uintptr_t
required
Length of action string.
Returns: true if the action was executed. Example: 
// Programmatically trigger copy
ghostty_surface_binding_action(surface, "copy_to_clipboard", 18);

​
ghostty_surface_request_close

Requests the surface to close. 
void ghostty_surface_request_close(ghostty_surface_t surface);
​
surface
ghostty_surface_t
required
The surface to close.
This will trigger the close_surface_cb callback.

​
Split Management

​
ghostty_surface_split

Splits the surface in a direction. 
void ghostty_surface_split(
    ghostty_surface_t surface,
    ghostty_action_split_direction_e direction
);
​
surface
ghostty_surface_t
required
The surface to split.
​
direction
ghostty_action_split_direction_e
required
Split direction (right, down, left, up).

​
ghostty_surface_split_focus

Moves focus to an adjacent split. 
void ghostty_surface_split_focus(
    ghostty_surface_t surface,
    ghostty_action_goto_split_e direction
);

​
ghostty_surface_split_resize

Resizes a split pane. 
void ghostty_surface_split_resize(
    ghostty_surface_t surface,
    ghostty_action_resize_split_direction_e direction,
    uint16_t amount
);

​
ghostty_surface_split_equalize

Equalizes split pane sizes. 
void ghostty_surface_split_equalize(ghostty_surface_t surface);

​
Complete Rendering Example

#include <ghostty.h>

typedef struct {
    ghostty_app_t app;
    ghostty_surface_t surface;
    void* native_view;
} TerminalContext;

// Initialize
TerminalContext* init_terminal(void* native_view) {
    TerminalContext* ctx = malloc(sizeof(TerminalContext));
    
    // Create app
    ghostty_config_t config = ghostty_config_new();
    ghostty_config_load_default_files(config);
    ghostty_config_finalize(config);
    
    ghostty_runtime_config_s runtime = {
        .userdata = ctx,
        .wakeup_cb = wakeup_cb,
        .action_cb = action_cb,
        // ... other callbacks
    };
    
    ctx->app = ghostty_app_new(&runtime, config);
    ghostty_config_free(config);
    
    // Create surface
    ghostty_surface_config_s surf_config = ghostty_surface_config_new();
    surf_config.platform_tag = GHOSTTY_PLATFORM_MACOS;
    surf_config.platform.macos.nsview = native_view;
    surf_config.scale_factor = get_scale_factor(native_view);
    surf_config.userdata = ctx;
    
    ctx->surface = ghostty_surface_new(ctx->app, &surf_config);
    ctx->native_view = native_view;
    
    // Set initial size
    ghostty_surface_set_size(ctx->surface, 800, 600);
    
    return ctx;
}

// Render loop
void render_frame(TerminalContext* ctx) {
    // Process events and timers
    ghostty_app_tick(ctx->app);
    
    // Draw terminal
    ghostty_surface_draw(ctx->surface);
}

// Handle resize
void on_resize(TerminalContext* ctx, uint32_t width, uint32_t height) {
    ghostty_surface_set_size(ctx->surface, width, height);
    render_frame(ctx);
}

// Handle display change
void on_display_change(TerminalContext* ctx, double scale) {
    ghostty_surface_set_content_scale(ctx->surface, scale, scale);
}

// Handle focus change
void on_focus_change(TerminalContext* ctx, bool focused) {
    ghostty_surface_set_focus(ctx->surface, focused);
}

// Cleanup
void cleanup_terminal(TerminalContext* ctx) {
    ghostty_surface_free(ctx->surface);
    ghostty_app_free(ctx->app);
    free(ctx);
}

​
See Also