cotis_raylib/

lib.rs

//! Raylib-backed renderer for the [Cotis](https://crates.io/crates/cotis) UI ecosystem.
//!
//! `cotis-raylib` implements Cotis's `CotisRenderer` and `CotisRendererAsync` traits
//! (from `cotis::renders`) on top of [raylib](https://crates.io/crates/raylib) 6.x.
//! It is the primary render backend used by `cotis-layout` examples.
//!
//! # Quick start
//!
//! For interactive applications, create a [`crate::renderer::RaylibRender`] and wire it into
//! `CotisApp` (from `cotis::cotis_app`) with a layout manager and pipe:
//!
//! ```rust,ignore
//! use cotis::cotis_app::CotisApp;
//! use cotis_layout::preamble::CotisLayoutManager;
//! use cotis_pipes::cotis_layout_pipes::CotisLayoutToRenderListPipeForGenerics;
//! use cotis_raylib::prelude::RaylibRender;
//! use cotis_utils::math::Dimensions;
//!
//! let renderer = RaylibRender::auto_start();
//! let manager = CotisLayoutManager::new(Dimensions::new(1000.0, 800.0));
//! let mut app = CotisApp::new(renderer, manager, CotisLayoutToRenderListPipeForGenerics);
//! // app.compute_frame(...);
//! // while !app.render().window_should_close() { ... }
//! ```
//!
//! Shipped examples use [`crate::renderer::RaylibRender`] directly (not `RayTestRender` from the
//! `test_render` module). Run from the repository root:
//!
//! ```text
//! cargo run -p cotis-raylib --example basic_example
//! ```
//!
//! # Recommended imports
//!
//! Use [`prelude`] for the common entry-point types:
//!
//! ```rust,no_run
//! use cotis_raylib::prelude::{PathBasedImage, RaylibRender, RayRenderHandle};
//! ```
//!
//! # Rendering model
//!
//! [`crate::renderer::RaylibRender`] draws two kinds of command streams:
//!
//! - [`cotis_defaults::render_commands::render_t_list::RenderTList`] — typed heterogeneous command lists
//!   produced by layout pipes. Images are preloaded into the renderer cache before drawing.
//! - [`Box<dyn crate::drawables::RaylibDrawable>`] — custom drawables; implement
//!   [`crate::drawables::RaylibDrawable`] for types not covered by `cotis-defaults` commands.
//!
//! Extend drawing with [`crate::drawables::RaylibDrawable::scale_by`] (used by `RayTestRender` when the
//! `test-render` feature is enabled) and [`crate::drawables::RaylibDrawable::preload_generic_images`]
//! for path-based images.
//!
//! # Images
//!
//! Path-based assets use [`crate::cotis_defaults_images::PathBasedImage`] (or `JPEGImage`, `PNGImage`,
//! `SVGImage` from `cotis_defaults::generic_image`).
//! [`crate::renderer::RaylibRender::translate_generic_image`] loads textures into an internal cache
//! keyed by file path. `SVGImage` is a semantic path tag only — raylib loads raster data from the path;
//! true vector SVG rendering is not implemented.
//!
//! # Fonts
//!
//! Call [`crate::renderer::RaylibRender::load_font_and_keep`] or
//! [`crate::renderer::RaylibRender::load_font_ex_and_keep`] at startup.
//! The returned ID (0-based, assigned in load order) is stored in `TextConfig::font_id`
//! (`cotis_defaults::element_configs::text_config::TextConfig`).
//! Additional pixel sizes are loaded lazily at the start of each frame.
//!
//! # Features
//!
//! | Feature | Effect |
//! |---------|--------|
//! | `test-render` | Exposes the `test_render` module for scaled/headless-style testing. |
//! | `complex-color` | Enables gradient and layered fills (requires `cotis-defaults/complex_color`). |
//!
//! # Thread safety
//!
//! The raylib handle is wrapped in `Arc<Mutex<RayRenderHandle>>` ([`crate::renderer::RayRenderHandle`])
//! so it can be shared for input polling. `RaylibThread` (from the `raylib` crate) is owned by
//! [`crate::renderer::RaylibRender`] and must be used for drawing on the thread that created the window.
//! All mutex locks **panic** if the mutex is poisoned.
//!
//! # When to use `RayTestRender`
//!
//! With the `test-render` feature, `RayTestRender` wraps [`crate::renderer::RaylibRender`] to render at a logical resolution while keeping a smaller physical
//! window (`dimensions / scale`). Use it for CI snapshots and headless-style tests — not as the default
//! for interactive applications.

#![cfg_attr(docsrs, feature(doc_cfg))]

pub mod prelude {
    //! Convenient re-exports for application code.
    //!
    //! Typical import:
    //!
    //! ```rust,no_run
    //! use cotis_raylib::prelude::{PathBasedImage, RaylibRender};
    //! ```
    //!
    //! - [`RaylibRender`](crate::renderer::RaylibRender) — main window renderer and `CotisRenderer` implementation.
    //! - [`RayRenderHandle`](crate::renderer::RayRenderHandle) — mutex-guarded raylib handle for input polling.
    //! - [`PathBasedImage`](crate::cotis_defaults_images::PathBasedImage) — unified path-based image enum.
    //! - `JPEGImage`, `PNGImage`, `SVGImage` — per-format path wrappers from `cotis-defaults`.

    pub use crate::cotis_defaults_images::PathBasedImage;
    pub use crate::renderer::RayRenderHandle;
    pub use crate::renderer::RaylibRender;
    pub use cotis_defaults::generic_image::{JPEGImage, PNGImage, SVGImage};
}

pub mod renderer;

pub mod functions_raylib;

pub mod drawables;

pub mod text;

pub mod raylib_images;

pub mod cotis_defaults_images;

pub mod fonts;

#[cfg(feature = "complex-color")]
mod color_paint;

/// Scaled rendering wrapper for tests (requires `test-render` feature).
#[cfg(feature = "test-render")]
pub mod test_render;

pub mod interactivity;

pub mod cotis;