skia_safe/gpu/ganesh/context_options.rs
1use std::os::raw;
2
3use skia_bindings::{self as sb, GrContextOptions};
4
5use crate::{gpu::DriverBugWorkarounds, prelude::*};
6
7pub use skia_bindings::GrContextOptions_Enable as Enable;
8variant_name!(Enable::Yes);
9
10pub use skia_bindings::GrContextOptions_ShaderCacheStrategy as ShaderCacheStrategy;
11variant_name!(ShaderCacheStrategy::BackendSource);
12
13#[repr(C)]
14#[derive(Debug)]
15pub struct ContextOptions {
16 /// Optional callback that can be passed into the [`DirectContext`] which will be called when the
17 /// [`DirectContext`] is about to be destroyed. When this call is made, it will be safe for the
18 /// client to delete the GPU backend context that is backing the [`DirectContext`]. The
19 /// [`DirectContextDestroyedContext`] will be passed back to the client in the callback.
20 context_delete_context: sb::GrDirectContextDestroyedContext,
21 context_delete_proc: sb::GrDirectContextDestroyedProc,
22
23 /// Executor to handle threaded work within Ganesh. If this is `None`, then all work will be
24 /// done serially on the main thread. To have worker threads assist with various tasks, set this
25 /// to a valid [`sb::SkExecutor`] instance. Currently, used for software path rendering, but may
26 /// be used for other tasks.
27 executor: *mut sb::SkExecutor,
28
29 /// Cache in which to store compiled shader binaries between runs.
30 persistent_cache: *mut sb::GrContextOptions_PersistentCache,
31
32 /// If present, use this object to report shader compilation failures. If not, report failures
33 /// via [`Debugf`] and assert.
34 shader_error_handler: *mut sb::GrContextOptions_ShaderErrorHandler,
35
36 /// Default minimum size to use when allocating buffers for uploading data to textures. The
37 /// larger the value the more uploads can be packed into one buffer, but at the cost of
38 /// more gpu memory allocated that may not be used. Uploads larger than the minimum will still
39 /// work by allocating a dedicated buffer.
40 pub minimum_staging_buffer_size: usize,
41
42 /// The maximum size of cache textures used for Skia's Glyph cache.
43 pub glyph_cache_texture_maximum_bytes: usize,
44
45 /// Controls whether we check for GL errors after functions that allocate resources (e.g.
46 /// `glTexImage2d`), at the end of a GPU submission, or checking framebuffer completeness. The
47 /// results of shader compilation and program linking are always checked, regardless of this
48 /// option. Ignored on backends other than GL.
49 pub skip_gl_error_checks: Enable,
50
51 /// Can the glyph atlas use multiple textures. If allowed, the each texture's size is bound by
52 /// `glyph_cache_texture_maximum_bytes`.
53 pub allow_multiple_glyph_cache_textures: Enable,
54
55 /// Enables driver workaround to use draws instead of HW clears, e.g. `glClear` on the GL
56 /// backend.
57 pub use_draw_instead_of_clear: Enable,
58
59 /// Allow Ganesh to more aggressively reorder operations to reduce the number of render passes.
60 /// Offscreen draws will be done upfront instead of interrupting the main render pass when
61 /// possible. May increase VRAM usage, but still observes the resource cache limit.
62 ///
63 /// Enabled by default.
64 pub reduce_ops_task_splitting: Enable,
65
66 /// This affects the usage of the PersistentCache. We can cache `SL`, backend source (GLSL), or
67 /// backend binaries (GL program binaries). By default we cache binaries, but if the driver's
68 /// binary loading/storing is believed to have bugs, this can be limited to caching GLSL.
69 /// Caching GLSL strings still saves CPU work when a GL program is created.
70 pub shader_cache_strategy: ShaderCacheStrategy,
71
72 /// Overrides: These options override feature detection using backend API queries. These
73 /// overrides can only reduce the feature set or limits, never increase them beyond the detected
74 /// values.
75 pub max_texture_size_override: raw::c_int,
76
77 /// The threshold in bytes above which we will use a buffer mapping API to map vertex and index
78 /// buffers to CPU memory in order to update them. A value of -1 means the `Context` should
79 /// deduce the optimal value for this platform.
80 pub buffer_map_threshold: raw::c_int,
81
82 /// Maximum number of GPU programs or pipelines to keep active in the runtime cache.
83 pub runtime_program_cache_size: raw::c_int,
84
85 /// Specifies the number of samples Ganesh should use when performing internal draws with MSAA
86 /// (hardware capabilities permitting).
87 ///
88 /// If 0, Ganesh will disable internal code paths that use multisampling.
89 pub internal_multisample_count: raw::c_int,
90
91 /// In Skia's vulkan backend a single `Context` submit equates to the submission of a single
92 /// primary command buffer to the VkQueue. This value specifies how many vulkan secondary command
93 /// buffers we will cache for reuse on a given primary command buffer. A single submit may use
94 /// more than this many secondary command buffers, but after the primary command buffer is
95 /// finished on the GPU it will only hold on to this many secondary command buffers for reuse.
96 ///
97 /// A value of -1 means we will pick a limit value internally.
98 pub max_cached_vulkan_secondary_command_buffers: raw::c_int,
99
100 /// Below this threshold size in device space distance field fonts won't be used. Distance field
101 /// fonts don't support hinting which is more important at smaller sizes.
102 pub min_distance_field_font_size: f32,
103
104 /// Above this threshold size in device space glyphs are drawn as individual paths.
105 pub glyphs_as_paths_font_size: f32,
106
107 pub driver_bug_workarounds: DriverBugWorkarounds,
108
109 /// Construct mipmaps manually, via repeated downsampling draw-calls. This is used when
110 /// the driver's implementation (`gl_generate_mipmap`) contains bugs. This requires mipmap
111 /// level control (ie desktop or ES3).
112 pub do_manual_mipmapping: bool,
113
114 /// Disables the use of coverage counting shortcuts to render paths. Coverage counting can cause
115 /// artifacts along shared edges if care isn't taken to ensure both contours wind in the same
116 /// direction.
117 pub disable_coverage_counting_paths: bool,
118
119 /// Disables distance field rendering for paths. Distance field computation can be expensive,
120 /// and yields no benefit if a path is not rendered multiple times with different transforms.
121 pub disable_distance_field_paths: bool,
122
123 /// If `true` this allows path mask textures to be cached. This is only really useful if paths
124 /// are commonly rendered at the same scale and fractional translation.
125 pub allow_path_mask_caching: bool,
126
127 /// If `true`, the GPU will not be used to perform YUV -> RGB conversion when generating
128 /// textures from codec-backed images.
129 pub disable_gpu_yuv_conversion: bool,
130
131 /// Bugs on certain drivers cause stencil buffers to leak. This flag causes Skia to avoid
132 /// allocating stencil buffers and use alternate rasterization paths, avoiding the leak.
133 pub avoid_stencil_buffers: bool,
134
135 /// If `true`, texture fetches from mip-mapped textures will be biased to read larger MIP levels.
136 /// This has the effect of sharpening those textures, at the cost of some aliasing, and possible
137 /// performance impact.
138 pub sharpen_mipmapped_textures: bool,
139
140 /// Some ES3 contexts report the ES2 external image extension, but not the ES3 version.
141 /// If support for external images is critical, enabling this option will cause Ganesh to limit
142 /// shaders to the ES2 shading language in that situation.
143 pub prefer_external_images_over_es3: bool,
144
145 /// Disables correctness workarounds that are enabled for particular GPUs, OSes, or drivers.
146 /// This does not affect code path choices that are made for performance reasons nor does it
147 /// override other [`ContextOptions`] settings.
148 pub disable_driver_correctness_workarounds: bool,
149
150 /// If `true`, the caps will never support mipmaps.
151 pub suppress_mipmap_support: bool,
152
153 /// If `true`, the TessellationPathRenderer will not be used for path rendering.
154 /// If `false`, will fallback to any driver workarounds, if set.
155 pub disable_tessellation_path_renderer: bool,
156
157 /// If `true`, and if supported, enables hardware tessellation in the caps.
158 /// DEPRECATED: This value is ignored; experimental hardware tessellation is always disabled.
159 pub enable_experimental_hardware_tessellation: bool,
160
161 /// If `true`, then add 1 pixel padding to all glyph masks in the atlas to support bi-lerp
162 /// rendering of all glyphs. This must be set to `true` to use Slugs.
163 pub support_bilerp_from_glyph_atlas: bool,
164
165 /// Uses a reduced variety of shaders. May perform less optimally in steady state but can reduce
166 /// jank due to shader compilations.
167 pub reduced_shader_variations: bool,
168
169 /// If `true`, then allow to enable MSAA on new Intel GPUs.
170 pub allow_msaa_on_new_intel: bool,
171
172 /// Currently on ARM Android we disable the use of GL TexStorage because of memory regressions.
173 /// However, some clients may still want to use TexStorage. For example, TexStorage support is
174 /// required for creating protected textures.
175 ///
176 /// This flag has no impact on non GL backends.
177 pub always_use_text_storage_when_available: bool,
178
179 // Suppress prints for the GrContext.
180 pub suppress_prints: bool,
181}
182unsafe_send_sync!(ContextOptions);
183
184impl Default for ContextOptions {
185 fn default() -> Self {
186 Self::construct(|ptr| unsafe { sb::C_GrContextOptions_Construct(ptr) })
187 }
188}
189
190impl ContextOptions {
191 pub fn new() -> Self {
192 Self::default()
193 }
194}
195
196native_transmutable!(GrContextOptions, ContextOptions);
197
198// TODO: PersistentCache, ShaderErrorHandler