Struct fna3d::Device

pub struct Device { /* fields omitted */ }

FNA3D device

Functionalities

See the sidebar as a list of methods.

• Init/Quit
• Presentation
• Drawing
• Mutable render states
• Immutable render states
• Render targets
• Textures
• Renderbuffers
• Vertex buffers
• Index buffers
• Effects
• Queries
• Feature queries

Resource management

Device is reference counted and it destories the FNA3D device when they go out of scope. NOTE: This is cheating the borrow rules.

Resource types have to be disposed with corresponding methods in Device:

• Buffer
• Renderbuffer
• Effect
• Query
• Texture

Initialization

It's required to set viewport/rasterizer/blend state. If this is skipped, we can't draw anything (we only can clear the screen):

• FNA3D_SetViewport
• FNA3D_ApplyRasterizerState
• FNA3D_SetBlendState

We also have to setup our shader used in the renderling pipeline. See crate::mojo for example.

Rendering cycle

For each frame:

• FNA3D_Clear
• for each draw call:
  • (set shader matrix)
  • FNA3D_ApplyEffect
  • FNA3D_SetVertexBufferData
  • FNA3D_VerifySampler
  • FNA3D_ApplyVertexBufferBindings
  • FNA3D_DrawIndexedPrimitives
• FNA3D_SwapBuffers

Remarks

You may have to mark your vertex struct as #[repr(C)].

Implementations

impl Device

pub fn raw(&self) -> *mut FNA3D_Device

impl Device

Init/Quit

pub fn from_params(params: PresentationParameters, do_debug: bool) -> Self

Creates a rendering context for use on the calling thread.

• params: The initial device/backbuffer settings.
• do_debug: Enable debugging and backend validation features at the cost of reduced overall performance.

Returns a device ready for use. Be sure to only call device functions from the thread that it was created on!

See initialization

impl Device

Presentation

pub fn swap_buffers(
    &self,
    src: Option<Rect>,
    dest: Option<Rect>,
    override_window_handle: *mut c_void
)

Presents the backbuffer to the window. None represents the full region

• override_window_handle: The OS window handle (not really "overridden").

Be sure to pass non-null window pointer. It may work well with e.g. Metal but not with OpenGL.

impl Device

Drawing

A "draw call" is actually a call of a drawing function, which is often FNA3D_DrawIndexedPrimitives in FNA3D.

Set vertex/index data and sampler state before making draw calls.

See rendering cycle

pub fn clear(
    &self,
    options: ClearOptions,
    color: Vec4,
    depth: f32,
    stencil: i32
)

Clears the active draw buffers of any previous contents.

• options: Bitflags to specify color/depth/stencil buffers for clearing.
• color: The new value of the cleared color buffer.
• depth: The new value of the cleared depth buffer.
• stencil: The new value of the cleared stencil buffer.

Example

fn just_clear(device: &fna3d::Device) {
    device.clear(
        fna3d::ClearOptions::TARGET,
        fna3d::Color::cornflower_blue().to_vec4(),
        0.0,
        0,
    );
}

pub fn draw_indexed_primitives(
    &self,
    type_: PrimitiveType,
    base_vtx: u32,
    min_vert_idx: u32,
    n_verts: u32,
    base_idx: u32,
    n_primitives: u32,
    ibuf: *mut Buffer,
    index_elem_size: IndexElementSize
)

Draws data from vertex/index buffers

• min_vert_idx: A hint of the lowest vertex indexed relative to baseVertex.
• n_verts: A hint of the maximum vertex indexed.

pub fn draw_instanced_primitives(
    &self,
    type_: PrimitiveType,
    base_vtx: u32,
    min_vertex_index: u32,
    num_vertices: u32,
    start_index: u32,
    prim_count: u32,
    instance_count: u32,
    ibuf: *mut Buffer,
    index_elem_size: IndexElementSize
)

Draws data from vertex/index buffers with instancing enabled.

• instance_count: The number of instances that will be drawn.

• TODO: what is this

pub fn draw_primitives(
    &self,
    type_: PrimitiveType,
    base_vtx: u32,
    n_primitives: u32
)

Draws data from vertex buffers.

This may require duplicate vertices so prefer draw_indexed_primitives basically.

impl Device

Mutable render states

• TODO: what does mutable here mean

pub fn set_viewport(&self, viewport: &Viewport)

Sets the view dimensions for rendering, relative to the active render target. It is required to call this at least once after calling set_render_targets, as the renderer may need to adjust these dimensions to fit the backend's potentially goofy coordinate systems.

pub fn set_scissor_rect(&self, scissor: &Rect)

Sets the scissor box for rendering, relative to the active render target. It is required to call this at least once after calling set_render_targets, as the renderer may need to adjust these dimensions to fit the backend's potentially goofy coordinate systems.

pub fn blend_factor(&self, blend_factor: Color)

Gets the blending factor used for current draw calls.

• blend_factor: Filled with color being used as the device blend factor.

pub fn set_blend_factor(&self, blend_factor: Color)

Sets the blending factor used for future draw calls.

• blend_factor: The color to use as the device blend factor.

pub fn multi_sample_mask(&self) -> i32

Gets the mask from which multisample fragment data is sampled from.

Returns the coverage mask used to determine sample locations.

pub fn set_multi_sample_mask(&self, mask: i32)

Sets the reference value used for certain types of stencil testing.

• ref: The new stencil reference value.

pub fn reference_stencil(&self) -> i32

Gets the reference value used for certain types of stencil testing.

Returns the stencil reference value.

pub fn set_reference_stencil(&self, ref_: i32)

Sets the reference value used for certain types of stencil testing.

• ref: The new stencil reference value.

impl Device

Immutable render states

• TODO: what does immutable mean. fixed length?

pub fn set_blend_state(&self, blend_state: &BlendState)

Applies a blending state to use for future draw calls. This only needs to be called when the state actually changes. Redundant calls may negatively affect performance!

pub fn set_depth_stencil_state(&self, depth_stencil_state: &DepthStencilState)

Applies depth/stencil states to use for future draw calls. This only needs to be called when the states actually change. Redundant calls may negatively affect performance!

pub fn apply_rasterizer_state(&self, rst: &RasterizerState)

Applies the rasterizing state to use for future draw calls. It's generally a good idea to call this for each draw call, but if you really wanted to you could try reducing it to when the state changes and when the render target state changes.

pub fn verify_sampler(
    &self,
    index: u32,
    texture: *mut Texture,
    sampler: &SamplerState
)

Updates a sampler slot with new texture/sampler data for future draw calls. This should only be called on slots that have modified texture/sampler state. Redundant calls may negatively affect performance!

• index: The sampler slot to update.

pub fn verify_vertex_sampler(
    &self,
    index: u32,
    texture: *mut Texture,
    sampler: &SamplerState
)

Updates a vertex sampler slot with new texture/sampler data for future draw calls. This should only be called on slots that have modified texture/sampler state. Redundant calls may negatively affect performance!

• index: The vertex sampler slot to update.

pub fn apply_vertex_buffer_bindings(
    &self,
    bindings: &[VertexBufferBinding],
    is_bindings_updated: bool,
    base_vertex: u32
)

Updates the vertex attribute state to read from a set of vertex buffers. This should be the very last thing you call before making a draw call, as this does all the final prep work for the shader program before it's ready to use.

• bindings: The vertex buffers and their attribute data.
• is_bindings_updated: If the bindings array hasn't changed since the last update, this can be false. We'll only update the shader state, updating vertex attribute data only if we 100% have to, for a tiny performance improvement.
• base_vertex: This should be the same as the base_vertex parameter from your draw*primitives call, if applicable. Not every rendering backend has native base vertex support, so we work around it by passing this here.

impl Device

Render targets

• back buffer = frame buffer = screen

pub fn set_render_targets(
    &self,
    render_targets: Option<&mut RenderTargetBinding>,
    n_render_targets: u32,
    depth_stencil_buffer: Option<&mut Renderbuffer>,
    depth_format: DepthFormat,
    preserve_target_contents: bool
)

Sets the color/depth/stencil buffers to write future draw calls to.

• render_targets: The targets to write to, or None for the backbuffer (screen).
• n_render_targets: The size of the renderTargets array (can be 0).
• depth_stencil_buffer: The depth/stencil renderbuffer (can be None).
• depth_format: The format of the depth/stencil renderbuffer.
• preserve_depth_stencil_contents: true to store the color/depth/stencil contents for future use. Most of the time you'll want to keep this at 0 to not waste GPU bandwidth.

pub fn resolve_target(&self, target: &mut RenderTargetBinding)

After unsetting a render target, call this to resolve multisample targets or generate mipmap data for the final texture.

• target: The render target to resolve once rendering is complete.

pub fn reset_backbuffer(&self, params: &PresentationParameters)

After modifying the OS window state, call this to reset the backbuffer to match your window changes.

• params: The new settings for the backbuffer.

pub fn read_backbuffer(&self, x: u32, y: u32, w: u32, h: u32, data: &mut [u8])

Read the backbuffer's contents directly into client memory. This function is basically one giant CPU/GPU sync point, do NOT ever call this during any performance-critical situation! Just use it for screenshots.

pub fn get_backbuffer_size(&self) -> (u32, u32)

pub fn get_backbuffer_surface_format(&self) -> SurfaceFormat

pub fn get_backbuffer_depth_format(&self) -> DepthFormat

pub fn get_backbuffer_multi_sample_count(&self) -> u32

impl Device

Textures

pub fn create_texture_2d(
    &self,
    fmt: SurfaceFormat,
    w: u32,
    h: u32,
    level_count: u32,
    is_render_target: bool
) -> *mut Texture

Creates a 2D texture to be applied to verify_sampler

• fmt: The pixel format of the texture data.
• level_count: The NUMBER of mipmap levels to allocate (> 0).
• is_render_target: Set this to 1 when using this with set_render_targets.

Returns an allocated Texture* object. Note that the contents of the texture are undefined, so you must call set_texture_data_2d at least once before drawing!

pub fn create_texture_3d(
    &self,
    fmt: SurfaceFormat,
    w: u32,
    h: u32,
    depth: u32,
    level_count: u32
) -> *mut Texture

Creates a 3D texture to be applied to verify_sampler.

• fmt: The pixel format of the texture data.
• depth: The depth of the texture image.
• level_count: The NUMBER of mipmap levels to allocate (> 0).

Returns an allocated FNA3D_Texture* object. Note that the contents of the texture are undefined, so you must call SetData at least once before drawing!

pub fn create_texture_cube(
    &self,
    fmt: SurfaceFormat,
    size: u32,
    level_count: u32,
    is_render_target: bool
) -> *mut Texture

Creates a texture cube to be applied to verify_sampler.

• fmt: The pixel format of the texture data.
• size: The length of a single edge of the texture cube.
• level_count: The NUMBER of mipmap levels to allocate (> 0).
• is_render_target: Set this to 1 when using this with set_render_targets.

Returns an allocated FNA3D_Texture* object. Note that the contents of the texture are undefined, so you must call SetData at least once before drawing!

pub fn add_dispose_texture(&self, texture: *mut Texture)

Sends a texture to be destroyed by the renderer. Note that we call it "AddDispose" because it may not be immediately destroyed by the renderer if this is not called from the main thread (for example, if a garbage collector deletes the resource instead of the programmer).

• texture: The FNA3D_Texture to be destroyed.

pub fn set_texture_data_2d(
    &self,
    texture: *mut Texture,
    x: u32,
    y: u32,
    w: u32,
    h: u32,
    target_level: u32,
    data: &[u8]
)

Uploads image data to a 2D texture object.

• target_level: The mipmap level being updated (>= 0).

pub fn set_texture_data_3d(
    &self,
    texture: &mut Texture,
    x: u32,
    y: u32,
    z: u32,
    w: u32,
    h: u32,
    depth: u32,
    target_level: u32,
    data: &mut [u8]
)

Uploads image data to a 3D texture object.

• target_level: The mipmap level being updated (>= 0).

pub fn set_texture_data_cube(
    &self,
    texture: &mut Texture,
    x: u32,
    y: u32,
    w: u32,
    h: u32,
    cube_map_face: CubeMapFace,
    level: i32,
    data: &mut [u8]
)

Uploads image data to a single face of a texture cube object.

• fmt: Should match the format provided to CreateTextureCube.
• cube_map_face: The face of the cube being updated.
• level: The mipmap level being updated.

pub fn set_texture_data_yuv(
    &self,
    y: &mut Texture,
    u: &mut Texture,
    v: &mut Texture,
    y_width: u32,
    y_height: u32,
    uv_width: u32,
    uv_height: u32,
    data: &[u8]
)

Uploads YUV image data to three ALPHA8 texture objects.

• data: A slice of the raw YUV image data.

pub fn get_texture_data_2d(
    &self,
    texture: *mut Texture,
    x: u32,
    y: u32,
    w: u32,
    h: u32,
    level: u32,
    data: &mut [u8]
)

Pulls image data from a 2D texture into client memory. Like any GetData, this is generally asking for a massive CPU/GPU sync point, don't call this unless there's absolutely no other way to use the image data!

• level: The mipmap level being read.

pub fn get_texture_data_3d(
    &self,
    texture: &mut Texture,
    x: u32,
    y: u32,
    z: u32,
    w: u32,
    h: u32,
    depth: u32,
    level: u32,
    data: &mut [u8]
)

Pulls image data from a 3D texture into client memory. Like any GetData, this is generally asking for a massive CPU/GPU sync point, don't call this unless there's absolutely no other way to use the image data!

• level: The mipmap level being read.

pub fn get_texture_data_cube(
    &self,
    texture: *mut Texture,
    x: u32,
    y: u32,
    w: u32,
    h: u32,
    cube_map_face: CubeMapFace,
    level: u32,
    data: &mut [u8]
)

Pulls image data from a single face of a texture cube object into client memory. Like any GetData, this is generally asking for a massive CPU/GPU sync point, don't call this unless there's absolutely no other way to use the image data!

• texture: The texture object being read.
• cube_map_face: The face of the cube being read.
• level: The mipmap level being read.

impl Device

Renderbuffers

pub fn gen_color_renderbuffer(
    &self,
    w: u32,
    h: u32,
    fmt: SurfaceFormat,
    multi_sample_count: u32,
    texture: *mut Texture
) -> *mut Renderbuffer

Creates a color buffer to be used by set_render_targets / resolve_target.

• multi_sample_count: The MSAA value for the color buffer.

Returns a color FNA3D_Renderbuffer object.

pub fn gen_depth_stencil_renderbuffer(
    &self,
    w: u32,
    h: u32,
    fmt: DepthFormat,
    multi_sample_count: i32
) -> *mut Renderbuffer

Creates a depth/stencil buffer to be used by set_render_targets.

• multi_sample_count: The MSAA value for the depth/stencil buffer.

Returns a depth/stencil FNA3D_Renderbuffer object.

pub fn add_dispose_renderbuffer(&self, renderbuffer: &mut Renderbuffer)

Sends a renderbuffer to be destroyed by the renderer. Note that we call it "add_dispose" because it may not be immediately destroyed by the renderer if this is not called from the main thread (for example, if a garbage collector deletes the resource instead of the programmer).

• renderbuffer: The FNA3D_Renderbuffer to be destroyed.

impl Device

Vertex buffers

*mut Buffer is GPU buffer and we need to upload (send, copy) from CPU memory. This is done via FNA3D_SetVertexBufferData or FNA3D_SetIndexBufferData in FNA.

pub fn gen_vertex_buffer(
    &self,
    is_dynamic: bool,
    usage: BufferUsage,
    size_in_bytes: u32
) -> *mut Buffer

Creates a vertex buffer to be used by Draw*Primitives.

• dynamic: Set to true if this buffer will be updated frequently.

Returns an allocated FNA3D_Buffer* object. Note that the contents of the buffer are undefined, so you must call SetData at least once before drawing!

pub fn add_dispose_vertex_buffer(&self, buffer: *mut Buffer)

Sends a vertex buffer to be destroyed by the renderer. Note that we call it "AddDispose" because it may not be immediately destroyed by the renderer if this is not called from the main thread (for example, if a garbage collector deletes the resource instead of the programmer).

• buffer: The FNA3D_Buffer to be destroyed.

pub fn set_vertex_buffer_data<T>(
    &self,
    buf: *mut Buffer,
    buf_offset_in_bytes: u32,
    data: &[T],
    opts: SetDataOptions
)

Sets a region of the vertex buffer with client data.

• opts: Try not to call NONE if this is a dynamic buffer!

pub fn get_vertex_buffer_data(
    &self,
    buffer: *mut Buffer,
    buf_offset_in_bytes: u32,
    data: *mut c_void,
    elem_size_in_bytes: u32
)

Pulls data from a region of the vertex buffer into a client pointer.

impl Device

Index buffers

*mut Buffer is GPU buffer and we need to upload (send, copy) from CPU memory. This is done via FNA3D_SetVertexBufferData or FNA3D_SetIndexBufferData in FNA.

pub fn gen_index_buffer(
    &self,
    is_dynamic: bool,
    usage: BufferUsage,
    size_in_bytes: u32
) -> *mut Buffer

Creates an index buffer to be used by Draw*Primitives.

• dynamic: Set to 1 if this buffer will be updated frequently.
• usage: Set to WRITEONLY if you do not intend to call GetData.
• size_in_bytes: The length of the vertex buffer.

Returns an allocated FNA3D_Buffer* object. Note that the contents of the buffer are undefined, so you must call SetData at least once before drawing!

pub fn add_dispose_index_buffer(&self, buf: *mut Buffer)

Sends an index buffer to be destroyed by the renderer. Note that we call it "AddDispose" because it may not be immediately destroyed by the renderer if this is not called from the main thread (for example, if a garbage collector deletes the resource instead of the programmer).

• buffer: The FNA3D_Buffer to be destroyed.

pub fn set_index_buffer_data<T>(
    &self,
    buf: *mut Buffer,
    buf_offset_in_bytes: u32,
    data: &[T],
    opts: SetDataOptions
)

Sets a region of the GPU index buffer with client data.

• buf: The index buffer to be updated.
• buf_offset_in_bytes: The starting offset of the buffer to write into.
• data: The client data to write into the buffer.
• opts: Try not to call NONE if this is a dynamic buffer!

pub fn get_index_buffer_data<T>(
    &self,
    buf: *mut Buffer,
    buf_offset_in_bytes: u32,
    data: &[T]
)

Pulls data from a region of the index buffer into a client pointer.

• buf: The index buffer to be read from.
• buf_offset_in_bytes: The starting offset of the buffer to read from.
• data: The pointer to read buffer data into.

impl Device

Effects

See crate::mojo module for more information and some helpers.

pub fn create_effect(
    &self,
    effect_code: *mut u8,
    effect_code_len: u32
) -> (*mut Effect, *mut Effect)

Parses and compiles a Direct3D 9 Effects Framework binary.

Returns (effect, effect_data). You have to detect errors by looking into error_count field of the second return value.

• effect_code: The D3D9 Effect binary blob.
• effect_code_length: The size (in bytes) of the blob.

pub fn clone_effect(
    &self,
    clone_source: *mut Effect
) -> (*mut Effect, *mut Effect)

Copies a compiled Effect, including its current technique/parameter data.

• clone_source: The FNA3D_Effect to copy.
• effect: Filled with the new compiled FNA3D_Effect*.
• effect_data: Filled with the copied Effect Framework data.

pub fn add_dispose_effect(&self, effect: *mut Effect)

Sends an Effect to be destroyed by the renderer. Note that we call it "AddDispose" because it may not be immediately destroyed by the renderer if this is not called from the main thread (for example, if a garbage collector deletes the resource instead of the programmer).

• effect: The FNA3D_Effect to be destroyed.

pub fn set_effect_technique(
    &self,
    effect: *mut Effect,
    technique: *mut EffectTechnique
)

Sets the active technique on the Effect.

• effect: The Effect to be modified.
• technique: The technique to be used by future apply_effect calls.

pub fn apply_effect(
    &self,
    effect: *mut Effect,
    pass: u32,
    state_changes: &EffectStateChanges
)

Applies an effect pass from a given Effect, setting the active shader program and committing any parameter data changes to be used by future draw calls.

• effect: The Effect to be applied.
• pass: The current technique's pass index to be applied.
• state_changes: Structure to be filled with any render state changes made by the Effect. This must be valid for the entire duration that this Effect is being applied.

pub fn begin_pass_restore(
    &self,
    effect: *mut Effect,
    state_changes: *mut EffectStateChanges
)

Applies an effect pass from a given Effect, setting the active shader program and committing and parameter data changes to be used by future draw calls, while also caching the current program object to be stored once this Effect's pass has been completed.

• effect: The Effect to be applied.
• state_changes: Structure to be filled with any render state changes made by the Effect. This must be valid for the entire duration that this Effect is being applied.

pub fn end_pass_restore(&self, effect: *mut Effect)

Ends a pass started by BeginPassRestore, unsetting the current Effect and restoring the previous shader state from before BeginPassRestore was called.

• effect: The Effect that was applied at BeginPassRestore.

impl Device

Queries

pub fn create_query(&self) -> *mut Query

Creates an object used to run occlusion queries.

Returns an FNA3D_Query object.

pub fn add_dispose_query(&self, query: *mut Query)

Sends a query object to be destroyed by the renderer. Note that we call it "AddDispose" because it may not be immediately destroyed by the renderer if this is not called from the main thread (for example, if a garbage collector deletes the resource instead of the programmer).

• query: The FNA3D_Query to be destroyed.

pub fn query_begin(&self, query: *mut Query)

Marks the start of when a query object should count pixels written.

• query: The FNA3D_Query to start.

pub fn query_end(&self, query: *mut Query)

Marks the end of when a query object should count pixels written. Note that this does NOT mean the query has finished executing, you will need to poll QueryComplete before checking the pixel count.

• query: The FNA3D_Query to stop.

pub fn query_complete(&self, query: *mut Query) -> bool

Call this until the function returns 1 to safely query for pixel counts.

• query: The FNA3D_Query to sync with.

Returns 1 when complete, 0 when still in execution.

pub fn query_pixel_count(&self, query: *mut Query) -> i32

Query the pixels counted between the begin/end markers set for the object.

query: The FNA3D_Query to poll for pixel count

Returns the pixels written during the begin/end period.

impl Device

Feature queries

pub fn supports_dxt1(&self) -> bool

True if the renderer natively supports DXT1 texture data.

pub fn supports_s3_tc(&self) -> bool

True if the renderer natively supports S3TC texture data.

pub fn supports_hardware_instancing(&self) -> bool

True if the renderer natively supports hardware instancing.

pub fn supports_no_overwrite(&self) -> bool

True if the renderer natively supports asynchronous buffer writing.

pub fn get_max_texture_slots(&self) -> (u32, u32)

(n_max_textures, n_max_vertex_texture)

Returns the number of sampler slots supported by the renderer

pub fn get_max_multi_sample_count(
    &self,
    fmt: SurfaceFormat,
    multi_sample_count: u32
) -> i32

Returns the highest multisample count supported for anti-aliasing.

• fmt: The pixel format to query for MSAA support.
• multi_sample_count: The max MSAA value requested for this format.

Returns a hardware-specific version of min(preferred, possible).

impl Device

Debug

pub fn set_string_marker(&self, text: *const c_char)

Sets an arbitrary string constant to be stored in a rendering API trace, useful for labeling call streams for debugging purposes.

• text: The string constant to mark in the API call stream.

Trait Implementations

impl Clone for Device

pub fn clone(&self) -> Device

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Device

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.