Returns a specification to start this module under a supervisor.

See Supervisor.

@spec cleanup() :: :ok

Cleans up resources.

@spec clear_graphics(graphics_id()) :: :ok | {:error, term()}

Clears the graphics context.

@spec close_graphics(graphics_id()) :: :ok | {:error, term()}

Closes a graphics context.

@spec convert_and_display(binary(), image_format(), display_options()) ::
  {:ok, graphics_id()} | {:error, term()}

Converts an image from one format to another with display optimization.

Parameters

• image_data - Source image data
• target_format - Target format (:png, :jpeg, :webp, :gif)
• options - Conversion and display options

Returns

• {:ok, graphics_id} - Successfully converted and displayed
• {:error, reason} - Conversion failed

@spec create_animation([binary()], map()) :: {:ok, graphics_id()} | {:error, term()}

Creates an animation from multiple image frames.

Parameters

• frames - List of image data for animation frames
• options - Animation options (frame_delay, loop_count, protocol)

Returns

• {:ok, graphics_id} - Successfully created animation
• {:error, reason} - Error with reason

@spec create_graphics(map()) :: {:ok, graphics_id()} | {:error, term()}

Creates a new graphics context with the given configuration.

@spec display_image(binary() | String.t(), display_options()) ::
  {:ok, graphics_id()} | {:error, term()}

Displays an image using the best available graphics protocol.

Automatically detects the optimal protocol and falls back gracefully if the preferred protocol is not supported.

Parameters

• image_data - Binary image data or file path
• options - Display options including size, position, format

Returns

• {:ok, graphics_id} - Successfully displayed image
• {:error, reason} - Error with reason

Examples

# Display PNG image with automatic protocol detection
{:ok, id} = GraphicsServer.display_image(png_data, %{
  width: 300,
  height: 200,
  format: :png
})

# Display with specific protocol preference
{:ok, id} = GraphicsServer.display_image(image_data, %{
  width: 400,
  height: 300,
  protocol: :kitty,
  fallback_enabled: true
})

@spec display_images(
  [binary() | {binary(), display_options()}],
  display_options()
) :: {:ok, [graphics_id()]} | {:error, term()}

Processes and displays multiple images with optimized format conversion.

Automatically detects image formats, applies appropriate processing, and selects the best display protocol for each image.

Parameters

• images - List of image data or {data, options} tuples
• shared_options - Options applied to all images

Returns

• {:ok, [graphics_id]} - Successfully processed and displayed images
• {:error, reason} - Processing failed

Examples

# Process multiple images with shared settings
{:ok, ids} = GraphicsServer.display_images([
  png_data,
  {jpeg_data, %{quality: 95}},
  svg_data
], %{
  width: 300,
  height: 200,
  optimize_for_terminal: true
})

@spec get_active_graphics() :: {:ok, graphics_id()} | {:error, :no_active_graphics}

Gets the active graphics context ID.

@spec get_graphics() :: [graphics_id()]

Gets the list of all graphics contexts.

@spec get_graphics_info() :: map()

Gets information about available graphics protocols and capabilities.

Returns

A map containing:

• :supported_protocols - List of supported protocols
• :preferred_protocol - Recommended protocol for best performance
• :terminal_info - Detected terminal information
• :capabilities - Protocol-specific capabilities

Examples

iex> GraphicsServer.get_graphics_info()
%{
  supported_protocols: [:kitty, :sixel],
  preferred_protocol: :kitty,
  terminal_info: %{type: :kitty, version: "0.26.5"},
  capabilities: %{
    kitty: %{max_image_size: 100_000_000, supports_animation: true},
    sixel: %{max_image_size: 1_000_000, supports_animation: false}
  }
}

@spec get_graphics_state(graphics_id()) :: {:ok, map()} | {:error, term()}

Gets the state of a specific graphics context.

@spec get_image_info(graphics_id()) :: {:ok, map()} | {:error, term()}

Gets comprehensive information about a processed image.

Parameters

• graphics_id - ID of previously processed image

Returns

• {:ok, image_info} - Image metadata and processing information
• {:error, reason} - Image not found or error

Callback implementation for Raxol.Core.Behaviours.BaseManager.handle_manager_cast/2.

Callback implementation for Raxol.Core.Behaviours.BaseManager.handle_manager_info/2.

@spec manage_cache(atom(), map()) :: term()

Manages the image cache for performance optimization.

Parameters

• action - Cache action (:get_stats, :clear, :configure)
• params - Optional parameters for the action

Returns

• Cache operation result

@spec optimize_and_display(binary(), display_options()) ::
  {:ok, graphics_id()} | {:error, term()}

Creates optimized variants for different terminal capabilities.

Generates multiple versions of an image optimized for different terminal types and automatically selects the best one to display.

Parameters

• image_data - Source image data
• options - Processing and display options

Returns

• {:ok, graphics_id} - Successfully optimized and displayed
• {:error, reason} - Optimization failed

@spec render_graphics(graphics_id(), binary()) :: :ok | {:error, term()}

Renders graphics data to the specified context.

@spec set_active_graphics(graphics_id()) :: :ok | {:error, term()}

Sets the active graphics context.

@spec set_preferred_protocol(graphics_protocol() | :auto, boolean()) ::
  :ok | {:error, term()}

Sets the preferred graphics protocol for future operations.

Parameters

• protocol - Preferred protocol (:kitty, :iterm2, :sixel, :auto)
• fallback_enabled - Whether to enable fallback to other protocols

Returns

• :ok - Protocol preference updated
• {:error, reason} - Error with reason

@spec update_config(map()) :: :ok

Updates the graphics manager configuration.

@spec update_graphics_config(graphics_id(), graphics_config()) ::
  :ok | {:error, term()}

Updates the configuration of a specific graphics context.

@spec update_graphics_properties(graphics_id(), map()) :: :ok | {:error, term()}

Updates properties of an existing graphics element for animation purposes.

Parameters

• graphics_id - ID of the graphics element to update
• properties - Map of properties to update (opacity, position, scale, etc.)

Returns

• :ok - Properties updated successfully
• {:error, reason} - Update failed