Struct Device

pub struct Device(/* private fields */);

Logical device, representation one or multiple physical devices (hardware or software).

This wraps an existing GL context and acts as the main API interface. It’s the responsibility of the user to keep the context alive.

Implementations

impl Device

pub unsafe fn create_buffer( &self, size: u64, memory: MemoryFlags, ) -> Result<Buffer>

Create a new empty buffer.

Parameters

• size: Length in bytes of the associated storage memory.
• memory: Properties of the internal memory slice. Indicating the usage and locality of the allocation.

pub unsafe fn create_buffer_from_host( &self, data: &[u8], memory: MemoryFlags, ) -> Result<Buffer>

Create a new buffer from host memory data.

Parameters

• data: Host data, which will copied into the buffer on creation.
• memory: Properties of the internal memory slice. Indicating the usage and locality of the allocation.

pub unsafe fn map_buffer<T>( &self, buffer: Buffer, range: Range<u64>, mapping: MappingFlags, ) -> &mut [T]

Persistently map memory to host accessible virtual memory.

Valid usage

• range.end may not be larger than the size of the buffer.
• range.start must be smaller than range.end
• buffer must be created with CPU_MAP_READ or CPU_MAP_WRITE flags.
• range.end - range.start must be a multiple of the size of T
• If the buffer has not been created with CPU_MAP_READ the host should not read from the returned slice.
• If the buffer has not been created with CPU_MAP_WRITE the host should not write to the returned slice.
• A buffer can not be mapped multiple times.

Return

Returns a typed slice of the mapped memory range.

pub unsafe fn unmap_buffer(&self, buffer: Buffer) -> bool

Unmap a buffer from virtual host memory.

Valid usage

• The buffer must be currently mapped.

Return

Returns if the unmapping operation was successfull.

pub unsafe fn delete_buffer(&self, buffer: Buffer)

Delete a buffer.

pub unsafe fn delete_buffers(&self, buffers: &[Buffer])

Delete multiple buffers.

pub unsafe fn copy_host_to_buffer( &self, buffer: Buffer, offset: isize, data: &[u8], )

Copy memory from the host into the buffer memory.

pub unsafe fn bind_uniform_buffers(&self, first: u32, ranges: &[BufferRange])

Bind buffer ranges as uniform buffers.

Shader can access the buffer memory as readonly.

pub unsafe fn bind_storage_buffers(&self, first: u32, ranges: &[BufferRange])

Bind buffer ranges as shader storage buffers.

Shaders can access the buffer memory as readwrite.

pub unsafe fn bind_draw_indirect_buffer(&self, buffer: Buffer)

Bind indirect buffer for draw commands.

pub unsafe fn unbind_draw_indirect_buffer(&self)

Unbind indirect buffer for draw commands.

pub unsafe fn bind_dispatch_indirect_buffer(&self, buffer: Buffer)

Bind indirect buffer for dispatch commands.

pub unsafe fn unbind_dispatch_indirect_buffer(&self)

Unbind indirect buffer for draw commands.

pub unsafe fn bind_parameter_buffer(&self, buffer: Buffer)

Bind parameter buffer for indirect commands.

Requires GL 4.6

impl Device

pub unsafe fn bind_uniform_constants( &self, pipeline: Pipeline, first: u32, constants: &[Constant], )

Set uniform constants for a pipeline.

pub unsafe fn set_viewport(&self, first: u32, viewports: &[Viewport])

Set viewport transformation parameters.

The viewport determines the mapping from NDC (normalized device coordinates) into framebuffer coordinates.

See Viewport for more information about the viewport transformation.

pub unsafe fn set_scissor(&self, first: u32, scissors: &[Region])

Set scissor rectangles for viewports.

Valid usage

• Every active viewport needs an associated scissor.

pub unsafe fn set_depth_bias(&self, constant_factor: f32, slope_factor: f32)

Set depth bias factors.

pub unsafe fn draw( &self, primitive: Primitive, vertices: Range<u32>, instance: Range<u32>, )

Submit a (non-indexed) draw call.

Valid usage

• There must be a valid graphics pipeline currently bound.
• There must be a valid vertex array currently bound.
• For each attribute in the bound vertex array there must be a vertex buffer bound at the specified binding slot.
• For each attribute in the bound vertex array there must be a vertex attribute specified in the shader with matching format and location.
• The access vertices must be in bound of the vertex buffers bound.
• vertices.end must be larger than vertices.start.
• vertices.end - vertices.start must be allow assembling complete primitives.
• instances.end must be larger than instances.start.

pub unsafe fn draw_indexed( &self, primitive: Primitive, index_ty: IndexTy, indices: Range<u32>, instance: Range<u32>, base_vertex: i32, )

Submit an indexed draw call.

Valid usage

• There must be a valid graphics pipeline currently bound.
• There must be a valid vertex array currently bound.
• For each attribute in the bound vertex array there must be a vertex buffer bound at the specified binding slot.
• For each attribute in the bound vertex array there must be a vertex attribute specified in the shader with matching format and location.
• The access vertices must be in bound of the vertex buffers bound.
• indices.end must be larger than indices.start.
• indices.end - indices.start must allow to assemble complete primitives.
• instances.end must be larger than instances.start.

pub unsafe fn draw_indirect( &self, primitive: Primitive, offset: u64, count: u32, stride: u32, )

Submit an indirect draw call.

Valid Usage

• There must be a valid graphics pipeline currently bound.
• There must be a valid draw indirect buffer currently bound.

pub unsafe fn draw_indirect_from_host( &self, primitive: Primitive, data: &[DrawIndirectCmd], )

Submit an indirect draw call.

pub unsafe fn draw_indexed_indirect( &self, primitive: Primitive, index_ty: IndexTy, offset: u64, count: u32, stride: u32, )

Indirect draw call.

pub unsafe fn draw_indexed_indirect_from_host( &self, primitive: Primitive, index_ty: IndexTy, data: &[DrawIndexedIndirectCmd], )

Indirect (indexed) draw call.

pub unsafe fn dispatch(&self, x: u32, y: u32, z: u32)

Dispatch a workgroup for computation.

Valid usage

• There must be a valid compute shader currently bound.

pub unsafe fn dispatch_indirect(&self, offset: u64)

pub unsafe fn blit( &self, src: Framebuffer, src_region: Region, dst: Framebuffer, dst_region: Region, filter: Filter, )

pub unsafe fn draw_mesh_tasks_nv(&self, task_count: u32, first_task: u32)

pub unsafe fn draw_mesh_tasks_indirect_nv( &self, offset: u64, draw_count: u32, stride: u32, )

pub unsafe fn draw_mesh_tasks_indirect_count_nv( &self, offset: u64, count_buffer_offset: u64, max_draw_count: u32, stride: u32, )

impl Device

pub unsafe fn object_name<T: Object>(&self, object: T, name: &str)

Associate a name with an object.

pub unsafe fn enable_debug_message( &self, src: MsgFilter<DebugSource>, ty: MsgFilter<DebugType>, flags: DebugReport, ids: Option<&[u32]>, )

pub unsafe fn disable_debug_message( &self, src: MsgFilter<DebugSource>, ty: MsgFilter<DebugType>, flags: DebugReport, ids: Option<&[u32]>, )

pub unsafe fn begin_debug_marker(&self, src: DebugSource, id: u32, msg: &str)

pub unsafe fn end_debug_marker(&self)

impl Device

pub unsafe fn new<F>(loader: F, debug: Debug<DebugCallback>) -> Self

where F: FnMut(&str) -> *const c_void,

Create a new device from an existing context.

The context must be initialized with GL 4.5+ core profile. The passed loader is used to obtain the function pointers from the context.

pub unsafe fn context(&self) -> &Gl

Return the underlying context for the device

pub unsafe fn limits(&self) -> DeviceLimits

pub unsafe fn features(&self) -> DeviceFeatures

pub unsafe fn submit(&self)

Submit all pending operations for device execution.

This function may return before all operations have finished executing.

pub unsafe fn wait_idle(&self)

Wait on the host for execution of all outstanding device operations.

impl Device

pub unsafe fn create_framebuffer(&self) -> Result<Framebuffer>

Create a new framebuffer.

pub unsafe fn delete_framebuffer(&self, framebuffer: Framebuffer)

Delete a framebuffer.

pub unsafe fn delete_framebuffers(&self, framebuffers: &[Framebuffer])

Delete multiple framebuffers.

pub unsafe fn create_renderbuffer( &self, format: Format, width: u32, height: u32, samples: u32, ) -> Result<Renderbuffer>

Create a new framebuffer.

pub unsafe fn delete_renderbuffer(&self, renderbuffer: Renderbuffer)

Delete a renderbuffer.

pub unsafe fn delete_renderbuffers(&self, renderbuffers: &[Renderbuffer])

Delete multiple renderbuffers.

pub unsafe fn clear_attachment(&self, fb: Framebuffer, cv: ClearAttachment)

Clear framebuffer attachment.

pub unsafe fn invalidate_attachments( &self, framebuffer: Framebuffer, attachments: &[Attachment], region: Region, )

pub unsafe fn bind_framebuffer(&self, framebuffer: Framebuffer)

Bind a framebuffer for draw and read commands.

This will overwrite both (draw and read) binding points.

pub unsafe fn bind_draw_framebuffer(&self, framebuffer: Framebuffer)

Bind a framebuffer for draw commands.

pub unsafe fn bind_read_framebuffer(&self, framebuffer: Framebuffer)

Bind a framebuffer for read commands.

pub unsafe fn bind_attachments( &self, framebuffer: Framebuffer, attachments: &[(Attachment, AttachmentView)], )

Bind attachments to the framebuffer.

All previously bound attachments become invalid.

pub unsafe fn set_color_attachments( &self, framebuffer: Framebuffer, attachments: &[u32], )

Specify color attachments.

Defines the color render targets for the next draw calls. This builds the link between fragment outputs in the fragment shader and attachments bound on the framebuffer.

pub unsafe fn set_read_attachment( &self, framebuffer: Framebuffer, attachment: u32, )

Specify read attachment.

impl Device

pub unsafe fn create_image( &self, ty: ImageType, format: Format, levels: u32, ) -> Result<Image>

pub unsafe fn delete_image(&self, image: Image)

Delete an images.

pub unsafe fn delete_images(&self, images: &[Image])

Delete multiple images.

pub unsafe fn create_image_view( &self, image: Image, ty: ImageViewType, format: Format, range: SubresourceRange, ) -> Result<ImageView>

Create an image view from an image.

pub unsafe fn create_image_and_view( &self, ty: ImageType, format: Format, levels: u32, ) -> Result<(Image, ImageView)>

Create an image and an associated view.

The image view type is derived from the ImageType. It creates either non-arrayed or arrayed view types.

pub unsafe fn delete_image_view(&self, view: ImageView)

Delete an image views.

pub unsafe fn delete_image_views(&self, views: &[ImageView])

Delete multipe image views.

pub unsafe fn bind_image_views(&self, first: u32, views: &[ImageView])

Bind image views to texture units.

pub unsafe fn bind_storage_image_views(&self, first: u32, views: &[ImageView])

Bind image views to storage image units.

pub unsafe fn generate_mipmaps(&self, image: Image)

Generate mipmaps.

This generates the remaining mipmap levels using the base layer via downscaling. The number of levels are determined on resource creation.

The downscaling filter is implementation dependent!

impl Device

pub unsafe fn create_shader( &self, stage: ShaderStage, source: &[u8], flags: ShaderFlags, ) -> Result<Shader>

Create a new shader from GLSL.

Valid usage

• source must be a NULL-terminated C-String.
• The GLSL shader version must be 450 core or higher.
• The stage parameter must be a valid stage of the passed shader source.

pub unsafe fn get_shader_log(&self, shader: Shader) -> Option<String>

Return the log, if any, from compiling the shader.

pub unsafe fn delete_shader(&self, shader: Shader)

Delete a shader.

pub unsafe fn delete_shaders(&self, shaders: &[Shader])

Delete multiple shaders.

pub unsafe fn get_pipeline_log(&self, pipeline: Pipeline) -> Option<String>

Retrieve the log from the most recent program link.

Returns

• Ok(log) if the link was successful.
• Err(log) if the link failed.

pub unsafe fn create_graphics_pipeline<D>( &self, desc: D, flags: PipelineFlags, ) -> Result<Pipeline>

where D: Into<GraphicsPipelineDesc>,

Create a graphics pipeline.

This equals a Program in GL terminology.

Valid usage

• The vertex shader in desc must be valid and created with ShaderStage::Vertex.
• The tessellation control shader in desc must be valid and created with ShaderStage::TessellationControl if specified.
• The tessellation evaluation shader in desc must be valid and created with ShaderStage::TessellationEvalution if specified.
• The geometry shader in desc must be valid and created with ShaderStage::Geometry if specified.
• The fragment shader in desc must be valid and created with ShaderStage::Fragment if specified.

pub unsafe fn create_compute_pipeline( &self, compute_shader: Shader, flags: PipelineFlags, ) -> Result<Pipeline>

Create a compute pipeline.

This equals a Program in GL terminology.

Valid usage

• The compute shader in must be valid and created with ShaderStage::Compute.

pub unsafe fn create_pipeline( &self, shaders: &[Shader], flags: PipelineFlags, ) -> Result<Pipeline>

Create a generic pipeline with an arbitrary list of shaders.

This equals a Program in GL terminology.

Valid usage

• The shaders must all be valid.
• The shader stages must be mutually compatible.

pub unsafe fn delete_pipeline(&self, pipeline: Pipeline)

Delete a pipeline.

pub unsafe fn delete_pipelines(&self, pipelines: &[Pipeline])

Delete multiple pipelines.

pub unsafe fn get_work_group_size(&self, pipeline: Pipeline) -> Option<[i32; 3]>

For a compute pipeline, return the size of the work group defined in the main shader.

pub unsafe fn bind_input_assembly_state(&self, state: InputAssembly)

Bind input assembly pipeline state.

pub unsafe fn bind_color_blend_state(&self, state: &ColorBlend)

Bind color blending pipeline state.

pub unsafe fn bind_depth_stencil_state(&self, state: &DepthStencil)

Bind depth-stencil pipeline state.

Examples

Basic Less-Equal depth test with write:

grr.bind_depth_stencil_state(&grr::DepthStencil {
    depth_test: true,
    depth_write: true,
    depth_compare_op: grr::Compare::LessEqual,
    stencil_test: false,
    stencil_front: grr::StencilFace::KEEP,
    stencil_back: grr::StencilFace::KEEP,
});

pub unsafe fn bind_rasterization_state(&self, state: &Rasterization)

Bind rasterization pipeline state.

pub unsafe fn bind_multisample_state(&self, state: Option<&Multisample>)

pub unsafe fn bind_pipeline(&self, pipeline: Pipeline)

Bind a pipeline for usage.

impl Device

pub unsafe fn create_query(&self, ty: QueryType) -> Query

pub unsafe fn begin_query(&self, query: Query)

pub unsafe fn end_query(&self, query: Query)

pub unsafe fn write_timestamp(&self, query: Query)

pub unsafe fn get_query_result_u32( &self, query: Query, flags: QueryResultFlags, ) -> u32

pub unsafe fn get_query_result_u64( &self, query: Query, flags: QueryResultFlags, ) -> u64

pub unsafe fn begin_conditional_rendering( &self, query: Query, mode: ConditionalMode, )

pub unsafe fn end_conditional_rendering(&self)

impl Device

pub unsafe fn create_sampler(&self, desc: SamplerDesc) -> Result<Sampler>

Create a sampler object.

pub unsafe fn bind_samplers(&self, first: u32, samplers: &[Sampler])

Bind samplers to specific texture units.

pub unsafe fn delete_sampler(&self, sampler: Sampler)

pub unsafe fn delete_samplers(&self, samplers: &[Sampler])

Delete multiple samplers.

impl Device

pub unsafe fn memory_barrier(&self, flags: Barrier)

pub unsafe fn memory_barrier_by_region(&self, flags: RegionBarrier)

impl Device

pub unsafe fn copy_host_to_image<T>( &self, src_host: &[T], dst_image: Image, region: HostImageCopy, )

Copy image data from host memory to device memory.

pub unsafe fn copy_buffer_to_image( &self, src_buffer: Buffer, dst_image: Image, region: BufferImageCopy, )

Copy image data from buffer to device memory.

pub unsafe fn copy_image_to_host<T>( &self, src_image: Image, dst_host: &mut [T], region: HostImageCopy, )

Copy image data from device memory to a host array.

pub unsafe fn copy_image_to_buffer( &self, src_image: Image, dst_buffer: Buffer, region: BufferImageCopy, )

Copy image data from device memory to a buffer object.

pub unsafe fn copy_attachment_to_host<T: Sized>( &self, region: Region, layout: MemoryLayout, data: &mut [T], )

Read a region of pixel data from the current read framebuffer into the provided storage slice.

Remarks:

The transfer in copy_attachement_to_host is done synchronously; the method won’t return until the transfer is complete.

See also

• copy_attachement_to_buffer for an asynchronous alternative.

pub unsafe fn copy_attachment_to_buffer( &self, region: Region, layout: MemoryLayout, buffer_range: BufferRange, )

Read a region of pixel data from the current read framebuffer into a buffer object.

Remarks:

The transfer for copy_attachment_to_buffer is asynchronous.

pub unsafe fn copy_image( &self, src_image: Image, dst_image: Image, region: ImageCopy, )

pub unsafe fn copy_buffer( &self, src_buffer: Buffer, src_offset: u64, dst_buffer: Buffer, dst_offset: u64, size: u64, )

Copy data from one buffer into another buffer.

Valid usage

• src_buffer and dst_buffer must be valid handles.
• src_offset must be less than the size of src_buffer.
• dst_offset must be less than the size of dst_buffer.
• size must be less than or equal the size of src_buffer minus src_offset.
• size must be less than or equal the size of dst_buffer minus dst_offset.
• The source and destination region must not overlap in memory.

pub unsafe fn fill_buffer( &self, buffer: BufferRange, buffer_format: Format, base_format: BaseFormat, format_layout: FormatLayout, value: &[u8], )

Fill buffer with data.

impl Device

pub unsafe fn create_vertex_array( &self, attributes: &[VertexAttributeDesc], ) -> Result<VertexArray>

Create a new vertex array, storing information for the input assembler.

The vertex array specified the vertex attributes and their binding to vertex buffer objects.

pub unsafe fn delete_vertex_array(&self, vao: VertexArray)

Delete a vertex array.

pub unsafe fn delete_vertex_arrays(&self, vao: &[VertexArray])

Delete multiple vertex arrays.

pub unsafe fn bind_vertex_array(&self, vao: VertexArray)

Bind a vertex array for usage.

pub unsafe fn bind_vertex_buffers( &self, vao: VertexArray, first: u32, views: &[VertexBufferView], )

Bind vertex buffers to a vertex array.

pub unsafe fn bind_index_buffer(&self, vao: VertexArray, buffer: Buffer)

Bind a index buffer to a vertex array.