Trait RenderingBackend

pub trait RenderingBackend {
    // Required methods
    fn info(&self) -> ContextInfo;
    fn new_shader(
        &mut self,
        shader: ShaderSource<'_>,
        meta: ShaderMeta,
    ) -> Result<ShaderId, ShaderError> ;
    fn new_texture(
        &mut self,
        access: TextureAccess,
        data: TextureSource<'_>,
        params: TextureParams,
    ) -> TextureId;
    fn texture_params(&self, texture: TextureId) -> TextureParams;
    unsafe fn texture_raw_id(&self, texture: TextureId) -> RawId;
    fn texture_set_min_filter(
        &mut self,
        texture: TextureId,
        filter: FilterMode,
        mipmap_filter: MipmapFilterMode,
    );
    fn texture_set_mag_filter(&mut self, texture: TextureId, filter: FilterMode);
    fn texture_set_wrap(
        &mut self,
        texture: TextureId,
        wrap_x: TextureWrap,
        wrap_y: TextureWrap,
    );
    fn texture_generate_mipmaps(&mut self, texture: TextureId);
    fn texture_resize(
        &mut self,
        texture: TextureId,
        width: u32,
        height: u32,
        bytes: Option<&[u8]>,
    );
    fn texture_read_pixels(&mut self, texture: TextureId, bytes: &mut [u8]);
    fn texture_update_part(
        &mut self,
        texture: TextureId,
        x_offset: i32,
        y_offset: i32,
        width: i32,
        height: i32,
        bytes: &[u8],
    );
    fn new_render_pass_mrt(
        &mut self,
        color_img: &[TextureId],
        resolve_img: Option<&[TextureId]>,
        depth_img: Option<TextureId>,
    ) -> RenderPass;
    fn render_pass_color_attachments(
        &self,
        render_pass: RenderPass,
    ) -> &[TextureId] ;
    fn delete_render_pass(&mut self, render_pass: RenderPass);
    fn new_pipeline(
        &mut self,
        buffer_layout: &[BufferLayout],
        attributes: &[VertexAttribute],
        shader: ShaderId,
        params: PipelineParams,
    ) -> Pipeline;
    fn apply_pipeline(&mut self, pipeline: &Pipeline);
    fn delete_pipeline(&mut self, pipeline: Pipeline);
    fn new_buffer(
        &mut self,
        type_: BufferType,
        usage: BufferUsage,
        data: BufferSource<'_>,
    ) -> BufferId;
    fn buffer_update(&mut self, buffer: BufferId, data: BufferSource<'_>);
    fn buffer_size(&mut self, buffer: BufferId) -> usize ;
    fn delete_buffer(&mut self, buffer: BufferId);
    fn delete_texture(&mut self, texture: TextureId);
    fn delete_shader(&mut self, program: ShaderId);
    fn apply_viewport(&mut self, x: i32, y: i32, w: i32, h: i32);
    fn apply_scissor_rect(&mut self, x: i32, y: i32, w: i32, h: i32);
    fn apply_bindings_from_slice(
        &mut self,
        vertex_buffers: &[BufferId],
        index_buffer: BufferId,
        textures: &[TextureId],
    );
    fn apply_uniforms_from_bytes(&mut self, uniform_ptr: *const u8, size: usize);
    fn clear(
        &mut self,
        color: Option<(f32, f32, f32, f32)>,
        depth: Option<f32>,
        stencil: Option<i32>,
    );
    fn begin_default_pass(&mut self, action: PassAction);
    fn begin_pass(&mut self, pass: Option<RenderPass>, action: PassAction);
    fn end_render_pass(&mut self);
    fn commit_frame(&mut self);
    fn draw(&self, base_element: i32, num_elements: i32, num_instances: i32);

    // Provided methods
    fn new_render_texture(&mut self, params: TextureParams) -> TextureId { ... }
    fn new_texture_from_data_and_format(
        &mut self,
        bytes: &[u8],
        params: TextureParams,
    ) -> TextureId { ... }
    fn new_texture_from_rgba8(
        &mut self,
        width: u16,
        height: u16,
        bytes: &[u8],
    ) -> TextureId { ... }
    fn texture_size(&self, texture: TextureId) -> (u32, u32)  { ... }
    fn texture_update(&mut self, texture: TextureId, bytes: &[u8]) { ... }
    fn texture_set_filter(
        &mut self,
        texture: TextureId,
        filter: FilterMode,
        mipmap_filter: MipmapFilterMode,
    ) { ... }
    fn new_render_pass(
        &mut self,
        color_img: TextureId,
        depth_img: Option<TextureId>,
    ) -> RenderPass { ... }
    fn render_pass_texture(&self, render_pass: RenderPass) -> TextureId { ... }
    fn apply_bindings(&mut self, bindings: &Bindings) { ... }
    fn apply_uniforms(&mut self, uniforms: UniformsSource<'_>) { ... }
}

Available on crate feature dep_miniquad only.

Required Methods

fn info(&self) -> ContextInfo

fn new_shader( &mut self, shader: ShaderSource<'_>, meta: ShaderMeta, ) -> Result<ShaderId, ShaderError>

For metal context’s ShaderSource should contain MSL source string, for GL - glsl. If in doubt, most OpenGL contexts support “#version 100” glsl shaders. So far miniquad never encountered where it can create a rendering context, but version 100 shaders are not supported.

Typical new_shader invocation for an MSL and glsl version 100 sources:

let source = match ctx.info().backend {
   Backend::OpenGl => ShaderSource::Glsl {
       vertex: display_shader::VERTEX,
       fragment: display_shader::FRAGMENT,
   },
   Backend::Metal => ShaderSource::Msl {
       program: display_shader::METAL
   },
};
let shader = ctx.new_shader(source, display_shader::meta()).unwrap();

Or just

let shader = ctx.new_shader(ShaderSource::Glsl {...}, ...);

for GL-only.

fn new_texture( &mut self, access: TextureAccess, data: TextureSource<'_>, params: TextureParams, ) -> TextureId

fn texture_params(&self, texture: TextureId) -> TextureParams

unsafe fn texture_raw_id(&self, texture: TextureId) -> RawId

Get OpenGL’s GLuint texture ID or metals ObjcId

fn texture_set_min_filter( &mut self, texture: TextureId, filter: FilterMode, mipmap_filter: MipmapFilterMode, )

fn texture_set_mag_filter(&mut self, texture: TextureId, filter: FilterMode)

fn texture_set_wrap( &mut self, texture: TextureId, wrap_x: TextureWrap, wrap_y: TextureWrap, )

fn texture_generate_mipmaps(&mut self, texture: TextureId)

Metal-specific note: if texture was created without params.generate_mipmaps generate_mipmaps will do nothing.

Also note that if MipmapFilter is set to None, mipmaps will not be visible, even if generated.

fn texture_resize( &mut self, texture: TextureId, width: u32, height: u32, bytes: Option<&[u8]>, )

fn texture_read_pixels(&mut self, texture: TextureId, bytes: &mut [u8])

fn texture_update_part( &mut self, texture: TextureId, x_offset: i32, y_offset: i32, width: i32, height: i32, bytes: &[u8], )

fn new_render_pass_mrt( &mut self, color_img: &[TextureId], resolve_img: Option<&[TextureId]>, depth_img: Option<TextureId>, ) -> RenderPass

Same as “new_render_pass”, but allows multiple color attachments. if resolve_img is set, MSAA-resolve operation will happen in end_render_pass this operation require color_img to have sample_count > 1,resolve_img have sample_count == 1, and color_img.len() should be equal to resolve_img.len()

Note that resolve attachments may be not supported by current backend! They are only available when ctx.info().features.resolve_attachments is true.

fn render_pass_color_attachments(&self, render_pass: RenderPass) -> &[TextureId]

For depth-only render pass returns empty slice.

fn delete_render_pass(&mut self, render_pass: RenderPass)

fn new_pipeline( &mut self, buffer_layout: &[BufferLayout], attributes: &[VertexAttribute], shader: ShaderId, params: PipelineParams, ) -> Pipeline

fn apply_pipeline(&mut self, pipeline: &Pipeline)

fn delete_pipeline(&mut self, pipeline: Pipeline)

fn new_buffer( &mut self, type_: BufferType, usage: BufferUsage, data: BufferSource<'_>, ) -> BufferId

Create a buffer resource object.

#[repr(C)]
struct Vertex {
    pos: Vec2,
    uv: Vec2,
}
let vertices: [Vertex; 4] = [
    Vertex { pos : Vec2 { x: -0.5, y: -0.5 }, uv: Vec2 { x: 0., y: 0. } },
    Vertex { pos : Vec2 { x:  0.5, y: -0.5 }, uv: Vec2 { x: 1., y: 0. } },
    Vertex { pos : Vec2 { x:  0.5, y:  0.5 }, uv: Vec2 { x: 1., y: 1. } },
    Vertex { pos : Vec2 { x: -0.5, y:  0.5 }, uv: Vec2 { x: 0., y: 1. } },
];
   let buffer = ctx.new_buffer(
       BufferType::VertexBuffer,
       BufferUsage::Immutable,
       BufferSource::slice(&vertices),
   );

fn buffer_update(&mut self, buffer: BufferId, data: BufferSource<'_>)

fn buffer_size(&mut self, buffer: BufferId) -> usize

Size of buffer in bytes. For 1 element, u16 buffer this will return 2.

fn delete_buffer(&mut self, buffer: BufferId)

Delete GPU buffer, leaving handle unmodified.

More high-level code on top of miniquad probably is going to call this in Drop implementation of some more RAII buffer object.

There is no protection against using deleted buffers later. However its not an UB in OpenGl and thats why this function is not marked as unsafe

fn delete_texture(&mut self, texture: TextureId)

Delete GPU texture, leaving handle unmodified.

More high-level code on top of miniquad probably is going to call this in Drop implementation of some more RAII buffer object.

There is no protection against using deleted textures later. However its not a CPU-level UB and thats why this function is not marked as unsafe

fn delete_shader(&mut self, program: ShaderId)

Delete GPU program, leaving handle unmodified.

More high-level code on top of miniquad probably is going to call this in Drop implementation of some more RAII buffer object.

There is no protection against using deleted programs later. However its not a CPU-level Porgram and thats why this function is not marked as unsafe

fn apply_viewport(&mut self, x: i32, y: i32, w: i32, h: i32)

Set a new viewport rectangle. Should be applied after begin_pass.

fn apply_scissor_rect(&mut self, x: i32, y: i32, w: i32, h: i32)

Set a new scissor rectangle. Should be applied after begin_pass.

fn apply_bindings_from_slice( &mut self, vertex_buffers: &[BufferId], index_buffer: BufferId, textures: &[TextureId], )

fn apply_uniforms_from_bytes(&mut self, uniform_ptr: *const u8, size: usize)

fn clear( &mut self, color: Option<(f32, f32, f32, f32)>, depth: Option<f32>, stencil: Option<i32>, )

fn begin_default_pass(&mut self, action: PassAction)

start rendering to the default frame buffer

fn begin_pass(&mut self, pass: Option<RenderPass>, action: PassAction)

start rendering to an offscreen framebuffer

fn end_render_pass(&mut self)

fn commit_frame(&mut self)

fn draw(&self, base_element: i32, num_elements: i32, num_instances: i32)

Draw elements using currently applied bindings and pipeline.

• base_element specifies starting offset in index_buffer.
• num_elements specifies length of the slice of index_buffer to draw.
• num_instances specifies how many instances should be rendered.

NOTE: num_instances > 1 might be not supported by the GPU (gl2.1 and gles2). features.instancing check is required.

Provided Methods

fn new_render_texture(&mut self, params: TextureParams) -> TextureId

fn new_texture_from_data_and_format( &mut self, bytes: &[u8], params: TextureParams, ) -> TextureId

fn new_texture_from_rgba8( &mut self, width: u16, height: u16, bytes: &[u8], ) -> TextureId

fn texture_size(&self, texture: TextureId) -> (u32, u32)

fn texture_update(&mut self, texture: TextureId, bytes: &[u8])

Update whole texture content bytes should be width * height * 4 size - non rgba8 textures are not supported yet anyway

fn texture_set_filter( &mut self, texture: TextureId, filter: FilterMode, mipmap_filter: MipmapFilterMode, )

fn new_render_pass( &mut self, color_img: TextureId, depth_img: Option<TextureId>, ) -> RenderPass

fn render_pass_texture(&self, render_pass: RenderPass) -> TextureId

panics for depth-only or multiple color attachment render pass This function is, mostly, legacy. Using “render_pass_color_attachments” is recommended instead.

fn apply_bindings(&mut self, bindings: &Bindings)

fn apply_uniforms(&mut self, uniforms: UniformsSource<'_>)

Implementors

impl RenderingBackend for GlContext