sdl3/lib.rs
1//! # Getting started
2//!
3//! ```rust,no_run
4//! extern crate sdl3;
5//!
6//! use sdl3::pixels::Color;
7//! use sdl3::event::Event;
8//! use sdl3::keyboard::Keycode;
9//! use std::time::Duration;
10//!
11//! pub fn main() {
12//! let sdl_context = sdl3::init().unwrap();
13//! let video_subsystem = sdl_context.video().unwrap();
14//!
15//! let window = video_subsystem.window("rust-sdl3 demo", 800, 600)
16//! .position_centered()
17//! .build()
18//! .unwrap();
19//!
20//! let mut canvas = window.into_canvas();
21//!
22//! canvas.set_draw_color(Color::RGB(0, 255, 255));
23//! canvas.clear();
24//! canvas.present();
25//! let mut event_pump = sdl_context.event_pump().unwrap();
26//! let mut i = 0;
27//! 'running: loop {
28//! i = (i + 1) % 255;
29//! canvas.set_draw_color(Color::RGB(i, 64, 255 - i));
30//! canvas.clear();
31//! for event in event_pump.poll_iter() {
32//! match event {
33//! Event::Quit {..} |
34//! Event::KeyDown { keycode: Some(Keycode::Escape), .. } => {
35//! break 'running
36//! },
37//! _ => {}
38//! }
39//! }
40//! // The rest of the game loop goes here...
41//!
42//! canvas.present();
43//! ::std::thread::sleep(Duration::new(0, 1_000_000_000u32 / 60));
44//! }
45//! }
46//! ```
47//!
48//! # Feature Flags
49//!
50//! ## Linking to `libsdl3`
51//!
52//! This crate requires the SDL3 library to link and run.
53//!
54//! By default without any of these features enabled, it will try to link a system SDL3 library as a dynamic/shared library
55//! using the default library search paths.
56//!
57//! If you don't have `libsdl3` installed on your system and just want it to work, we recommend using `build-from-source`.
58//! Also see the different build configurations that `sdl3-sys` provides: <https://github.com/maia-s/sdl3-sys-rs/tree/main/sdl3-sys#usage>
59//!
60//! | Name | Description |
61//! |----------------------------------|----------------------------------------------------------------|
62//! | `build-from-source` | Fetch and build the library from source |
63//! | `build-from-source-static` | Fetch and build the library from source and link it statically |
64//! | `build-from-source-unix-console` | Build SDL3 from source but skip the X11/Wayland dependencies for console targets |
65//! | `use-pkg-config` | Use `pkg-config` to find the library |
66//! | `use-vcpkg` | Use `vcpkg` to find the library |
67//! | `static-link` | Link the library statically |
68//! | `link-framework` | Link the library as a framework on macOS |
69//!
70//! ## Optional Features
71//!
72//! Note that since `sdl3` is still in the progress of migrating to and integrating the new
73//! features of `libsdl3`, some features might be not yet, or only partially implemented.
74//!
75//! | Name | Description | Implementation Status |
76//! |---------------------|------------------------------------------------------------------------|-----------------------|
77//! | `ash` | Use Vulkan types from the ash crate | Implemented |
78//! | `unsafe_textures` | Skip lifetime tracking for textures; you must manage destruction safety yourself | Implemented (unsafe opt-in) |
79//! | `gfx` | Legacy SDL_gfx drawing helpers; blocked on an SDL3_gfx C library | Blocked |
80//! | `mixer` | SDL_mixer bindings (needs upstream SDL3_mixer and `sdl3-mixer-sys`) | Blocked |
81//! | `image` | Enable SDL_image helpers for loading/saving surfaces and textures | Implemented |
82//! | `ttf` | Enable SDL_ttf font/text rendering APIs | Implemented |
83//! | `hidapi` | Use SDL's hidapi backend for sensors and controllers | Implemented |
84//! | `test-mode` | Allows SDL to be initialised from a thread that is not the main thread | Implemented |
85//! | `raw-window-handle` | Enables integrations with the [`wgpu`] crate | Implemented |
86//! | `main` | Enables integrations with the [`sdl3-main`] crate (main callbacks api) | Implemented |
87//!
88//! [`wgpu`]: https://docs.rs/wgpu/latest/wgpu/
89//! [`sdl3-main`]: https://docs.rs/sdl3-main/latest/sdl3_main/
90
91#![crate_name = "sdl3"]
92#![crate_type = "lib"]
93#![allow(
94 clippy::cast_lossless,
95 clippy::transmute_ptr_to_ref,
96 clippy::missing_transmute_annotations,
97 clippy::missing_safety_doc
98)]
99
100#[macro_use]
101extern crate bitflags;
102#[cfg(feature = "gfx")]
103extern crate c_vec;
104#[macro_use]
105extern crate lazy_static;
106pub extern crate libc;
107pub extern crate sdl3_sys as sys;
108// use sdl3_sys as sys;
109
110pub use crate::sdl::*;
111
112pub mod clipboard;
113pub mod cpuinfo;
114#[macro_use]
115mod macros;
116pub mod audio;
117pub mod dialog;
118pub mod event;
119pub mod filesystem;
120pub mod gamepad;
121pub mod gpu;
122pub mod haptic;
123pub mod hint;
124pub mod iostream;
125pub mod joystick;
126pub mod keyboard;
127pub mod log;
128pub mod messagebox;
129pub mod mouse;
130pub mod pen;
131pub mod pixels;
132pub mod properties;
133pub mod rect;
134pub mod render;
135mod sdl;
136#[cfg(feature = "hidapi")]
137pub mod sensor;
138pub mod surface;
139pub mod timer;
140pub mod touch;
141pub mod url;
142pub mod version;
143pub mod video;
144
145// modules
146#[cfg(feature = "gfx")]
147pub mod gfx;
148#[cfg(feature = "image")]
149pub mod image;
150#[cfg(feature = "mixer")]
151pub mod mixer;
152#[cfg(feature = "ttf")]
153pub mod ttf;
154
155#[cfg(feature = "main")]
156mod sdlmain; // this just implements traits, so it doesn't have to be public
157
158mod common;
159// Export return types and such from the common module.
160pub use crate::common::IntegerOrSdlError;
161
162mod guid;
163#[cfg(feature = "raw-window-handle")]
164pub mod raw_window_handle;
165mod util;