Struct GraphicsContextDescriptor 

pub struct GraphicsContextDescriptor {
    pub backends: Backends,
    pub power_preference: PowerPreference,
    pub force_fallback_adapter: bool,
    pub required_gpu_features: GpuFeatures,
    pub requested_gpu_features: GpuFeatures,
    pub additional_wgpu_features: Features,
    pub limits: Limits,
    pub label: Option<&'static str>,
}

Descriptor for configuring graphics context creation.

Fields

backends: Backends

GPU backends to use

power_preference: PowerPreference

Power preference for adapter selection

force_fallback_adapter: bool

Whether to force fallback adapter

required_gpu_features: GpuFeatures

Required GPU features (panics if not available).

Use this for features that your application cannot function without.

requested_gpu_features: GpuFeatures

Requested GPU features (best-effort, logs warning if unavailable).

Use this for features that would be nice to have but are not essential.

additional_wgpu_features: Features

Additional raw wgpu features to enable (for features not covered by GpuFeatures).

limits: Limits

Required device limits

label: Option<&'static str>

Optional label for debugging

Implementations

impl GraphicsContextDescriptor

pub fn new() -> Self

Create a new descriptor with default settings.

Examples found in repository

examples/batched_renderer.rs (line 288)

fn main() {
    logging::init();

    run_app(|ctx| {
        let tier_override = parse_tier();

        // Use the capability API to configure GPU requirements.
        // For auto-detect, request the best capability (graceful degradation).
        // For a specific tier, require that tier's capability.
        let descriptor = match tier_override {
            None => GraphicsContextDescriptor::new().request_capability::<BestBatchCapability2D>(),
            Some(RenderTier::Direct) => {
                GraphicsContextDescriptor::new().require_capability::<DirectBatchCapability2D>()
            }
            Some(RenderTier::Indirect) => {
                GraphicsContextDescriptor::new().require_capability::<IndirectBatchCapability2D>()
            }
            Some(RenderTier::Bindless) => {
                GraphicsContextDescriptor::new().require_capability::<BindlessBatchCapability2D>()
            }
        };
        let graphics_ctx =
            pollster::block_on(GraphicsContext::new_owned_with_descriptor(descriptor))
                .expect("Failed to create graphics context");

        let window = ctx
            .create_window(WindowDescriptor {
                title: "Batched Renderer Example".to_string(),
                size: Some(WinitPhysicalSize::new(800.0, 600.0)),
                ..Default::default()
            })
            .expect("Failed to create window");

        let surface_format = wgpu::TextureFormat::Bgra8UnormSrgb;

        let renderable_window = RenderWindowBuilder::new()
            .color_format(surface_format)
            .with_depth_default()
            .build(window, graphics_ctx.clone())
            .expect("Failed to create render window");

        let window_id = renderable_window.id();

        let renderer =
            create_batch_renderer_2d(graphics_ctx.clone(), surface_format, tier_override);

        tracing::info!("Using render tier: {}", renderer.tier());

        // Create initial depth buffer
        let depth_texture = graphics_ctx
            .device()
            .create_texture(&wgpu::TextureDescriptor {
                label: Some("example_depth"),
                size: wgpu::Extent3d {
                    width: 1,
                    height: 1,
                    depth_or_array_layers: 1,
                },
                mip_level_count: 1,
                sample_count: 1,
                dimension: wgpu::TextureDimension::D2,
                format: DEPTH_FORMAT,
                usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
                view_formats: &[],
            });
        let depth_view = depth_texture.create_view(&wgpu::TextureViewDescriptor::default());

        let mut windows = HashMap::new();
        windows.insert(window_id, renderable_window);

        Box::new(App {
            context: graphics_ctx,
            windows,
            renderer,
            depth_texture,
            depth_view,
            depth_width: 1,
            depth_height: 1,
            frame_count: 0,
        })
    });
}

examples/profiling_demo.rs (line 49)

fn main() {
    logging::init();
    init_profiling(ProfilingBackend::PuffinHttp);

    run_app(|ctx| {
        profile_function!();

        // Request TIMESTAMP_QUERY for GPU profiling (best-effort, won't fail if unavailable)
        let graphics_ctx = pollster::block_on(GraphicsContext::new_owned_with_descriptor(
            GraphicsContextDescriptor::new()
                .request_capability::<astrelis_render::gpu_profiling::GpuFrameProfiler>(),
        ))
        .expect("Failed to create graphics context");

        let window = ctx
            .create_window(WindowDescriptor {
                title: "Profiling Demo — CPU + GPU".to_string(),
                size: Some(WinitPhysicalSize::new(800.0, 600.0)),
                ..Default::default()
            })
            .expect("Failed to create window");

        #[allow(unused_mut)]
        let mut window = RenderWindowBuilder::new()
            .color_format(wgpu::TextureFormat::Bgra8UnormSrgb)
            .with_depth_default()
            .build(window, graphics_ctx.clone())
            .expect("Failed to create render window");

        let window_id = window.id();

        // Attach GPU profiler to the window — all frames will be automatically profiled
        let has_gpu_profiling;
        #[cfg(feature = "gpu-profiling")]
        {
            match astrelis_render::gpu_profiling::GpuFrameProfiler::new(&graphics_ctx) {
                Ok(profiler) => {
                    let has_timestamps = profiler.has_timestamp_queries();
                    window.set_gpu_profiler(Arc::new(profiler));
                    has_gpu_profiling = true;
                    if has_timestamps {
                        println!("  GPU profiling: enabled with TIMESTAMP_QUERY (full timing)");
                    } else {
                        println!("  GPU profiling: enabled (debug groups only, no timing data)");
                        println!("                 TIMESTAMP_QUERY not supported by this GPU");
                    }
                }
                Err(e) => {
                    has_gpu_profiling = false;
                    tracing::warn!("Failed to create GPU profiler: {e}. GPU profiling disabled.");
                    println!("  GPU profiling: failed to create profiler");
                }
            }
        }
        #[cfg(not(feature = "gpu-profiling"))]
        {
            has_gpu_profiling = false;
        }

        println!();
        println!("═══════════════════════════════════════════════════");
        println!("  PROFILING DEMO — CPU + GPU");
        println!("═══════════════════════════════════════════════════");
        println!();
        println!("  CPU profiling: enabled (puffin)");
        if !has_gpu_profiling {
            #[cfg(not(feature = "gpu-profiling"))]
            println!("  GPU profiling: disabled (compile with --features gpu-profiling)");
        }
        println!();
        println!("  Open puffin_viewer at 127.0.0.1:8585 to see the flame graph.");
        println!("  Install with: cargo install puffin_viewer");
        println!("═══════════════════════════════════════════════════");
        println!();

        Box::new(ProfilingDemo {
            context: graphics_ctx,
            window,
            window_id,
            frame_count: 0,
        })
    });
}

pub fn require_features(self, features: GpuFeatures) -> Self

Set required GPU features (panics if not available).

pub fn request_features(self, features: GpuFeatures) -> Self

Set requested GPU features (best-effort, warns if unavailable).

pub fn with_required_features(self, features: GpuFeatures) -> Self

Add additional required features.

pub fn with_requested_features(self, features: GpuFeatures) -> Self

Add additional requested features.

pub fn with_wgpu_features(self, features: Features) -> Self

Set additional raw wgpu features (for features not covered by GpuFeatures).

pub fn power_preference(self, preference: PowerPreference) -> Self

Set the power preference.

pub fn backends(self, backends: Backends) -> Self

Set the backends to use.

pub fn limits(self, limits: Limits) -> Self

Set the device limits.

pub fn label(self, label: &'static str) -> Self

Set the debug label.

pub fn require_capability<T: RenderCapability>(self) -> Self

Require a capability — its features become required, limits are merged.

If the adapter doesn’t support the capability’s required features, device creation will fail with GraphicsError::MissingRequiredFeatures.

Example

use astrelis_render::{GraphicsContextDescriptor, GpuProfiler};

let desc = GraphicsContextDescriptor::new()
    .require_capability::<GpuProfiler>();

Examples found in repository

examples/batched_renderer.rs (line 290)

fn main() {
    logging::init();

    run_app(|ctx| {
        let tier_override = parse_tier();

        // Use the capability API to configure GPU requirements.
        // For auto-detect, request the best capability (graceful degradation).
        // For a specific tier, require that tier's capability.
        let descriptor = match tier_override {
            None => GraphicsContextDescriptor::new().request_capability::<BestBatchCapability2D>(),
            Some(RenderTier::Direct) => {
                GraphicsContextDescriptor::new().require_capability::<DirectBatchCapability2D>()
            }
            Some(RenderTier::Indirect) => {
                GraphicsContextDescriptor::new().require_capability::<IndirectBatchCapability2D>()
            }
            Some(RenderTier::Bindless) => {
                GraphicsContextDescriptor::new().require_capability::<BindlessBatchCapability2D>()
            }
        };
        let graphics_ctx =
            pollster::block_on(GraphicsContext::new_owned_with_descriptor(descriptor))
                .expect("Failed to create graphics context");

        let window = ctx
            .create_window(WindowDescriptor {
                title: "Batched Renderer Example".to_string(),
                size: Some(WinitPhysicalSize::new(800.0, 600.0)),
                ..Default::default()
            })
            .expect("Failed to create window");

        let surface_format = wgpu::TextureFormat::Bgra8UnormSrgb;

        let renderable_window = RenderWindowBuilder::new()
            .color_format(surface_format)
            .with_depth_default()
            .build(window, graphics_ctx.clone())
            .expect("Failed to create render window");

        let window_id = renderable_window.id();

        let renderer =
            create_batch_renderer_2d(graphics_ctx.clone(), surface_format, tier_override);

        tracing::info!("Using render tier: {}", renderer.tier());

        // Create initial depth buffer
        let depth_texture = graphics_ctx
            .device()
            .create_texture(&wgpu::TextureDescriptor {
                label: Some("example_depth"),
                size: wgpu::Extent3d {
                    width: 1,
                    height: 1,
                    depth_or_array_layers: 1,
                },
                mip_level_count: 1,
                sample_count: 1,
                dimension: wgpu::TextureDimension::D2,
                format: DEPTH_FORMAT,
                usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
                view_formats: &[],
            });
        let depth_view = depth_texture.create_view(&wgpu::TextureViewDescriptor::default());

        let mut windows = HashMap::new();
        windows.insert(window_id, renderable_window);

        Box::new(App {
            context: graphics_ctx,
            windows,
            renderer,
            depth_texture,
            depth_view,
            depth_width: 1,
            depth_height: 1,
            frame_count: 0,
        })
    });
}

pub fn request_capability<T: RenderCapability>(self) -> Self

Request a capability — required features stay required, requested features stay optional, limits are merged.

The capability’s required features are added as required, and its requested features are added as requested (best-effort). Limits are merged and clamped to adapter capabilities during device creation.

Example

use astrelis_render::GraphicsContextDescriptor;
use astrelis_render::batched::BestBatchCapability;

let desc = GraphicsContextDescriptor::new()
    .request_capability::<BestBatchCapability>();

Examples found in repository

examples/batched_renderer.rs (line 288)

fn main() {
    logging::init();

    run_app(|ctx| {
        let tier_override = parse_tier();

        // Use the capability API to configure GPU requirements.
        // For auto-detect, request the best capability (graceful degradation).
        // For a specific tier, require that tier's capability.
        let descriptor = match tier_override {
            None => GraphicsContextDescriptor::new().request_capability::<BestBatchCapability2D>(),
            Some(RenderTier::Direct) => {
                GraphicsContextDescriptor::new().require_capability::<DirectBatchCapability2D>()
            }
            Some(RenderTier::Indirect) => {
                GraphicsContextDescriptor::new().require_capability::<IndirectBatchCapability2D>()
            }
            Some(RenderTier::Bindless) => {
                GraphicsContextDescriptor::new().require_capability::<BindlessBatchCapability2D>()
            }
        };
        let graphics_ctx =
            pollster::block_on(GraphicsContext::new_owned_with_descriptor(descriptor))
                .expect("Failed to create graphics context");

        let window = ctx
            .create_window(WindowDescriptor {
                title: "Batched Renderer Example".to_string(),
                size: Some(WinitPhysicalSize::new(800.0, 600.0)),
                ..Default::default()
            })
            .expect("Failed to create window");

        let surface_format = wgpu::TextureFormat::Bgra8UnormSrgb;

        let renderable_window = RenderWindowBuilder::new()
            .color_format(surface_format)
            .with_depth_default()
            .build(window, graphics_ctx.clone())
            .expect("Failed to create render window");

        let window_id = renderable_window.id();

        let renderer =
            create_batch_renderer_2d(graphics_ctx.clone(), surface_format, tier_override);

        tracing::info!("Using render tier: {}", renderer.tier());

        // Create initial depth buffer
        let depth_texture = graphics_ctx
            .device()
            .create_texture(&wgpu::TextureDescriptor {
                label: Some("example_depth"),
                size: wgpu::Extent3d {
                    width: 1,
                    height: 1,
                    depth_or_array_layers: 1,
                },
                mip_level_count: 1,
                sample_count: 1,
                dimension: wgpu::TextureDimension::D2,
                format: DEPTH_FORMAT,
                usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
                view_formats: &[],
            });
        let depth_view = depth_texture.create_view(&wgpu::TextureViewDescriptor::default());

        let mut windows = HashMap::new();
        windows.insert(window_id, renderable_window);

        Box::new(App {
            context: graphics_ctx,
            windows,
            renderer,
            depth_texture,
            depth_view,
            depth_width: 1,
            depth_height: 1,
            frame_count: 0,
        })
    });
}

examples/profiling_demo.rs (line 50)

fn main() {
    logging::init();
    init_profiling(ProfilingBackend::PuffinHttp);

    run_app(|ctx| {
        profile_function!();

        // Request TIMESTAMP_QUERY for GPU profiling (best-effort, won't fail if unavailable)
        let graphics_ctx = pollster::block_on(GraphicsContext::new_owned_with_descriptor(
            GraphicsContextDescriptor::new()
                .request_capability::<astrelis_render::gpu_profiling::GpuFrameProfiler>(),
        ))
        .expect("Failed to create graphics context");

        let window = ctx
            .create_window(WindowDescriptor {
                title: "Profiling Demo — CPU + GPU".to_string(),
                size: Some(WinitPhysicalSize::new(800.0, 600.0)),
                ..Default::default()
            })
            .expect("Failed to create window");

        #[allow(unused_mut)]
        let mut window = RenderWindowBuilder::new()
            .color_format(wgpu::TextureFormat::Bgra8UnormSrgb)
            .with_depth_default()
            .build(window, graphics_ctx.clone())
            .expect("Failed to create render window");

        let window_id = window.id();

        // Attach GPU profiler to the window — all frames will be automatically profiled
        let has_gpu_profiling;
        #[cfg(feature = "gpu-profiling")]
        {
            match astrelis_render::gpu_profiling::GpuFrameProfiler::new(&graphics_ctx) {
                Ok(profiler) => {
                    let has_timestamps = profiler.has_timestamp_queries();
                    window.set_gpu_profiler(Arc::new(profiler));
                    has_gpu_profiling = true;
                    if has_timestamps {
                        println!("  GPU profiling: enabled with TIMESTAMP_QUERY (full timing)");
                    } else {
                        println!("  GPU profiling: enabled (debug groups only, no timing data)");
                        println!("                 TIMESTAMP_QUERY not supported by this GPU");
                    }
                }
                Err(e) => {
                    has_gpu_profiling = false;
                    tracing::warn!("Failed to create GPU profiler: {e}. GPU profiling disabled.");
                    println!("  GPU profiling: failed to create profiler");
                }
            }
        }
        #[cfg(not(feature = "gpu-profiling"))]
        {
            has_gpu_profiling = false;
        }

        println!();
        println!("═══════════════════════════════════════════════════");
        println!("  PROFILING DEMO — CPU + GPU");
        println!("═══════════════════════════════════════════════════");
        println!();
        println!("  CPU profiling: enabled (puffin)");
        if !has_gpu_profiling {
            #[cfg(not(feature = "gpu-profiling"))]
            println!("  GPU profiling: disabled (compile with --features gpu-profiling)");
        }
        println!();
        println!("  Open puffin_viewer at 127.0.0.1:8585 to see the flame graph.");
        println!("  Install with: cargo install puffin_viewer");
        println!("═══════════════════════════════════════════════════");
        println!();

        Box::new(ProfilingDemo {
            context: graphics_ctx,
            window,
            window_id,
            frame_count: 0,
        })
    });
}

Trait Implementations

impl Default for GraphicsContextDescriptor

fn default() -> Self

Returns the “default value” for a type.